agentleFS
ai-ecoverseai-ecoverse/slicc/.agents/skills/adding-slicc-features/SKILL.md

adding-slicc-features

Skill37 starsChanged 20 days agoApache-2.0View on GitHub

Use when adding a SLICC shell command, dedicated tool, provider, scoop capability, UI panel, interactive approval, or runtime skill wiring; when `command not found`, a tool/skill is undiscovered, a follower action is dropped, OAuth reports `session expired` or `401 invalid x-api-key`, or `playwright-cli-sync` reports a command gap. Covers exact file paths, code interfaces, registration patterns, and the cross-reference checklist (test, SKILL.md update, follower handler, AGENTS.md).

  • Reads credentials

The file

Show its rules and text

We split this skill into the rules it gives an agent

21 rules. About 0 are common, 5 are distinctive, and 16 are very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈5

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 16

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Very specific:

    Use this procedure to extend SLICC.

    line 9
  2. Distinctive:

    Use these common extension points:

    line 33
  3. Very specific:

    If the command dispatches on a subcommand verb (my-command list|create|delete), answer --help before dispatching — use isHelpRequest() and …

    line 84
  4. Very specific:

    Add a handler under packages/webapp/src/shell/supplemental-commands/playwright/handlers/ (one module per subcommand family) and register it …

    line 413
  5. Very specific:

    Keep browser automation shell-first through playwright-cli / playwright / puppeteer.

    line 421
  6. Very specific:

    Document the subcommand in playwright/help.ts as a two-space-indented entry — the dispatcher extracts that entry for playwright-cli …

    line 424
  7. Very specific:

    Use serve <dir> for app directories (default index.html, optional --entry) and open for single files, URLs, downloads, or inline image …

    line 425
  8. Very specific:

    Add tests in packages/webapp/tests/ mirroring the command's src/ path (for example …

    line 430
  9. Very specific:

    Put pure helper coverage in shared.test.ts.

    line 431
  10. Distinctive:

    Prefer focused command-level assertions over large integration fixtures.

    line 432
  11. Very specific:

    When adding a new playwright-cli subcommand, also update packages/webapp/src/shell/supplemental-commands/playwright/slicc-commands.json and …

    line 436
  12. Very specific:

    Create: packages/webcomponents/src/my-panel.ts (web component)

    line 589
  13. Very specific:

    Only native /workspace/skills/ entries are install-managed by SLICC.

    line 680
  14. Very specific:

    Base URL validation: When requiresBaseUrl: true is set on an OAuth provider and no build-time default exists (empty proxyEndpoint in …

    line 982
  15. Distinctive:

    When adding a feature:

    line 1006
  16. Very specific:

    Use data-action="actionName" on buttons for click handling

    line 1110
  17. Very specific:

    Use data-action-data='{"key":"value"}' for additional data (JSON)

    line 1111
  18. Very specific:

    Logging: Import createLogger('namespace') from packages/webapp/src/core/logger.js.

    line 1151
  19. Distinctive:

    VFS access: All core layers have access to VirtualFS.

    line 1153
  20. Distinctive:

    Shell commands: Prefer shell commands (bash tool) for new capabilities.

    line 1155
  21. Very specific:

    Browser automation: Use playwright-cli / playwright / puppeteer for tab control.

    line 1157

≈ “Common” is an estimate: at least 1 in 5 of the 372,429 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

adding-slicc-features

Use this procedure to extend SLICC. Prefer shell commands over dedicated tools, preserve CLI and extension parity, and update every agent-facing reference that exposes changed behavior.

For non-procedural system and protocol background, see docs/architecture.md, docs/shell-reference.md, and docs/tools-reference.md.

Quick Reference

# Validate TypeScript and behavior
npm run typecheck
npm test

# Validate all repository and skill lint gates
npm run lint

# Check playwright-cli command parity after adding/changing a subcommand
node packages/dev-tools/tools/playwright-cli-sync.mjs

The Chrome extension is built and tested in ai-ecoverse/slicc-extension. For dual-mode verification, run it against your local webapp from there; an extension-protocol change here needs a matching PR there.

Use these common extension points:

CapabilityPrimary path
Supplemental shell commandpackages/webapp/src/shell/supplemental-commands/
Executable .jsh skill commandpackages/vfs-root/workspace/skills/<skill>/
Core agent toolpackages/webapp/src/tools/ and packages/webapp/src/scoops/scoop-context.ts
Scoop-management toolpackages/webapp/src/scoops/scoop-management-tools.ts
Providerpackages/webapp/src/providers/built-in/ or packages/webapp/providers/
Runtime agent skillpackages/vfs-root/workspace/skills/<skill>/SKILL.md

1. Add a Supplemental Shell Command

webhook rotate is a leader-panel RPC operation (tray-webhook-rotate): wire it through ui/boot/setup-standalone-panel-rpc.ts, never expose the home's rebind secret in shell output or follower status. Rotation replaces both delivery and management hashes atomically in the existing home. Persist fresh random replacements in private pending intent before HTTP; exact receipt retries must present both replacements, not just the old identity. Old management credentials cannot authorize new mutations. Legacy pending intents without replacements fail closed without clearing storage. A non-2xx home response must never report success.

For tray webhook lifecycle changes, management credentials belong only to LeaderTrayManager's private IndexedDB identity store, scoped to the worker URL. Persist before create; never put rebind secrets on LeaderTraySession, public status, localStorage mirrors, follower messages, or the VFS. coneId names a leader-session lineage shared by WorkUnits, not per-agent isolation. Reset callers must use the manager's resumable reset() rather than clear-and-start: failed preview transfer retains the same source/target pair across reloads. See docs/cloudflare-worker-details.md.

webhook delete uses tray-webhook-revoke before local removal. The private leader manager sends management identity to POST /webhooks/:coneId/:webhookId/revoke; the home authenticates the rebind secret plus current tray/controller. Revoked IDs have permanent hashed per-registration tombstones (constant-size each, never TTL-evicted); queue drain checks them even after interrupted cleanup. Total authorized metadata grows with deleted registrations until home retirement; bounding the total requires a coordinated lifetime registration quota, not eviction that resurrects IDs. Failed/lost revocation responses retain the local retry handle.

When: To register a new bash command (e.g., convert, webhook, crontask).

Files to modify:

  • Create: packages/webapp/src/shell/supplemental-commands/my-command.ts
  • Modify: packages/webapp/src/shell/supplemental-commands/index.ts

Implementation:

If the command dispatches on a subcommand verb (my-command list|create|delete), answer --help before dispatching — use isHelpRequest() and subcommandHelpText() from supplemental-commands/subcommand-help.ts, and register the command in DISPATCHERS in tests/shell/supplemental-commands/subcommand-help.test.ts (its coverage test fails if you don't). An args[0] === '--help' check answers only the bare command: my-command delete --help then runs delete. See review pattern 14 in docs/review-patterns.md.

Define a command using just-bash's defineCommand:

// packages/webapp/src/shell/supplemental-commands/my-command.ts
import { defineCommand } from 'just-bash';
import type { Command, CommandContext } from 'just-bash';

export function createMyCommand(): Command {
  return defineCommand('mycommand', async (args, ctx) => {
    // args: string[] of arguments
    // ctx: CommandContext { fs, env, cwd, getRegisteredCommands }

    try {
      // Your logic here
      const result = await ctx.fs.readFile('/some/path');

      return {
        stdout: result,
        stderr: '',
        exitCode: 0,
      };
    } catch (err) {
      return {
        stdout: '',
        stderr: `Error: ${err}`,
        exitCode: 1,
      };
    }
  });
}

Register in createSupplementalCommands():

// packages/webapp/src/shell/supplemental-commands/index.ts
import { createMyCommand } from './my-command.js';

export function createSupplementalCommands(options: SupplementalCommandsConfig = {}): Command[] {
  return [
    // ... existing commands ...
    createMyCommand(),
  ];
}

Type signature (just-bash):

type Command = {
  name: string;
  execute: (args: string[], ctx: CommandContext) => Promise<ShellResult>;
};

type CommandContext = {
  fs: IFileSystem;
  env: Map<string, string>;
  cwd: string;
  getRegisteredCommands?: () => string[];
};

type ShellResult = {
  stdout: string;
  stderr: string;
  exitCode: number;
};

Test pattern:

// packages/webapp/tests/shell/supplemental-commands/my-command.test.ts
import { describe, it, expect, beforeEach } from 'vitest';
import { createMyCommand } from './my-command.js';
import { FakeVirtualFS } from '../../fs/fake-virtual-fs.js';

describe('my-command', () => {
  let fs: FakeVirtualFS;

  beforeEach(() => {
    fs = new FakeVirtualFS();
  });

  it('should execute correctly', async () => {
    const cmd = createMyCommand();
    const result = await cmd.execute(['arg1'], {
      fs,
      env: new Map([['HOME', '/home/user']]),
      cwd: '/',
    });
    expect(result.exitCode).toBe(0);
  });
});

Reference file: packages/webapp/src/shell/supplemental-commands/which-command.ts


2. Add a .jsh Script Command

When: To ship executable scripts as part of a skill (e.g., a custom build tool, data processor).

Files to create:

  • Create: packages/vfs-root/workspace/skills/my-skill/my-script.jsh

Implementation:

// packages/vfs-root/workspace/skills/my-skill/my-script.jsh
// The script has access to:
// - process: { argv, env, cwd(), exit(code), stdout.write(), stderr.write() }
// - console: { log, info, warn, error, debug, assert, … } (19 standard methods)
// - require('fs'): { readFile, writeFile, readDir, mkdir, rm, stat, exists }
// - require('sliccy:<name>'): exec / http / browser / skill / cli / ...

const fs = require('fs');
const args = process.argv.slice(2); // Skip 'node' and script path

if (args.length === 0) {
  console.error('Usage: my-script <input>');
  process.exit(1);
}

const inputFile = args[0];

(async () => {
  try {
    const content = await fs.readFile(inputFile);
    const processed = content.toUpperCase();

    const outputFile = inputFile.replace(/\.txt$/, '.out.txt');
    await fs.writeFile(outputFile, processed);

    console.log(`Processed: ${inputFile} → ${outputFile}`);
  } catch (err) {
    console.error(`Error: ${err.message}`);
    process.exit(1);
  }
})();

Globals API:

Global / moduleMethods
processargv[], env (object), cwd(), exit(code), exitCode (deferred status; honoured after drain), stdout.write(), stderr.write()
console19 standard methods: log/info/debug/dirxml/table/dir → stdout; warn/error/assert/trace → stderr (assert does not throw); group*/time*/count*/clear
require('fs') / require('node:fs')readFile(path), readFileBinary(path), writeFile(path, content), writeFileBinary(path, bytes), appendFile(path, data), readDir(path), mkdir(path), rm(path), stat(path), exists(path), fetchToFile(url, path)
require('sliccy:exec')Callable exec(cmd) + .spawn(argv[]). Shell command bridge.
require('sliccy:<name>')http, browser, skill, cli, color, time, fmt, pool, usb / serial / hid — see packages/vfs-root/workspace/skills/skill-authoring/jsh-runtime-extensions.md.
require(id)Synchronous CJS require (require('sliccy:<name>'), require('fs'), or installed packages).
module, exportsAvailable for CJS module pattern (e.g., a .jsh consumed by require('./helper.jsh')).

Discovery:

The shell auto-discovers *.jsh files from /workspace/skills/ (priority) and anywhere on the VFS. Call by basename:

my-script arg1 arg2

Execution modes:

  • CLI mode: Uses AsyncFunction constructor, full Node.js-like globals
  • Extension mode: Routes through sandbox iframe (CSP-compliant), via postMessage for VFS operations

Test pattern:

JSH scripts cannot be unit-tested in Node because they rely on extension mode detection. Test the logic separately:

// packages/webapp/tests/shell/supplemental-commands/my-command.test.ts
import { describe, it, expect } from 'vitest';
import { executeJshFile } from '../jsh-executor.js';
import { FakeVirtualFS } from '../../fs/fake-virtual-fs.js';

describe('my-script.jsh', () => {
  it('should run the script', async () => {
    const fs = new FakeVirtualFS();
    await fs.writeFile('/test.jsh', 'console.log("hello");');

    const result = await executeJshFile('/test.jsh', [], {
      fs,
      env: new Map(),
      cwd: '/',
    });

    expect(result.stdout).toContain('hello');
    expect(result.exitCode).toBe(0);
  });
});

Reference file: packages/webapp/src/shell/jsh-executor.ts, packages/webapp/src/shell/supplemental-commands/node-command.ts


3. Add a Core Agent Tool

When: To add a tool available to the agent (e.g., a new read_database tool).

Files to create/modify:

  • Create: packages/webapp/src/tools/my-tool.ts
  • Modify: packages/webapp/src/scoops/scoop-context.ts (wiring)

Implementation:

// packages/webapp/src/tools/my-tool.ts
import type { ToolDefinition, ToolResult } from '../core/types.js';
import { createLogger } from '../core/logger.js';

const log = createLogger('tool:my');

export function createMyTool(dependency: SomeDependency): ToolDefinition {
  return {
    name: 'my_tool',
    description: 'Does something useful. Parameters: x (required), y (optional).',
    inputSchema: {
      type: 'object',
      properties: {
        x: {
          type: 'string',
          description: 'The first parameter',
        },
        y: {
          type: 'number',
          description: 'Optional second parameter',
        },
      },
      required: ['x'],
    },
    async execute(input: Record<string, unknown>): Promise<ToolResult> {
      const x = input['x'] as string;
      const y = input['y'] as number | undefined;

      log.debug('Execute', { x, y });

      try {
        // Your logic
        const result = await doSomething(x, y, dependency);

        return {
          content: `Result: ${result}`,
          isError: false,
        };
      } catch (err) {
        const message = err instanceof Error ? err.message : String(err);
        log.error('Error', { x, error: message });
        return {
          content: `Error: ${message}`,
          isError: true,
        };
      }
    },
  };
}

Interface:

interface ToolDefinition {
  name: string;
  description: string;
  inputSchema: ToolInputSchema;
  execute(input: Record<string, unknown>): Promise<ToolResult>;
}

interface ToolInputSchema {
  type: 'object';
  properties?: Record<string, unknown>;
  required?: string[];
  [k: string]: unknown; // Allow additional schema fields
}

interface ToolResult {
  content: string;
  isError?: boolean;
}

Wire into ScoopContext:

// packages/webapp/src/scoops/scoop-context.ts — in the init() method
const legacyTools = [
  // ... existing tools ...
  createMyTool(dependency),
];

Test pattern:

// packages/webapp/tests/tools/my-tool.test.ts
import { describe, it, expect } from 'vitest';
import { createMyTool } from './my-tool.js';

describe('my_tool', () => {
  it('should execute with valid input', async () => {
    const tool = createMyTool(mockDependency);
    const result = await tool.execute({ x: 'test' });
    expect(result.content).toContain('Result');
    expect(result.isError).toBeFalsy();
  });
});

Reference file: packages/webapp/src/tools/bash-tool.ts, packages/webapp/src/tools/file-tools.ts


4. Extend Browser Automation Shell Commands

When: To add or change browser automation behavior, tab workflows, or preview-serving commands.

Files to modify:

  • Add a handler under packages/webapp/src/shell/supplemental-commands/playwright/handlers/ (one module per subcommand family) and register it in playwright/handlers/index.ts.
  • Shared helpers live in playwright/ (state.ts, snapshot.ts, session-log.ts, teleport.ts, teleport-storage.ts, discover.ts, help.ts); playwright-command.ts is just the thin dispatcher + public re-exports.
  • Modify: packages/webapp/src/shell/supplemental-commands/serve-command.ts
  • Modify: packages/webapp/src/shell/supplemental-commands/shared.ts (shared preview/path helpers)
  • Update: packages/vfs-root/workspace/skills/playwright-cli/SKILL.md — this file is injected into the agent's system prompt. Every new or changed command MUST be reflected here or the agent will not know about it.

Implementation:

  • Keep browser automation shell-first through playwright-cli / playwright / puppeteer.
  • A handler is a PlaywrightHandler — (ctx: { browser, fs, state, positional, flags }) => Promise<CmdResult>; add the subcommand name (and any alias) to the playwrightHandlers map.
  • Reuse shared preview helpers for VFS URLs instead of manually constructing /preview/... paths.
  • Document the subcommand in playwright/help.ts as a two-space-indented entry — the dispatcher extracts that entry for playwright-cli <subcommand> --help, and the help path must never reach your handler.
  • Use serve <dir> for app directories (default index.html, optional --entry) and open for single files, URLs, downloads, or inline image viewing.
  • Preserve the current tab + snapshot model (the shared PlaywrightState in playwright/state.ts) when adding stateful browser actions.

Test pattern:

  • Add tests in packages/webapp/tests/ mirroring the command's src/ path (for example tests/shell/supplemental-commands/playwright-command.test.ts).
  • Put pure helper coverage in shared.test.ts.
  • Prefer focused command-level assertions over large integration fixtures.

Alignment with official playwright-cli:

When adding a new playwright-cli subcommand, also update packages/webapp/src/shell/supplemental-commands/playwright/slicc-commands.json and run node packages/dev-tools/tools/playwright-cli-sync.mjs to confirm the gap is closed. That manifest is ENFORCED at runtime by playwright/validate-args.ts: a flag or extra positional it does not declare is rejected with a usage line (#2405), so list every flag your handler actually reads (and "variadic": true when the last positional soaks up the rest) or working invocations will fail. If you're implementing a command that the official CLI already has, cross- reference its args and flags in help.json first. Full workflow: docs/playwright-cli-sync.md.

Reference files: packages/webapp/src/shell/supplemental-commands/playwright-command.ts (dispatcher) and packages/webapp/src/shell/supplemental-commands/playwright/ (handlers + helpers), packages/webapp/src/shell/supplemental-commands/serve-command.ts, packages/webapp/src/shell/supplemental-commands/sprinkle-command.ts


5. Add a Scoop-Management Tool

When: To add a messaging or multi-scoop management tool.

Files to modify:

  • Modify: packages/webapp/src/scoops/scoop-management-tools.ts

Implementation:

// packages/webapp/src/scoops/scoop-management-tools.ts — in createScoopManagementTools()
export function createScoopManagementTools(config: ScoopManagementToolsConfig): ToolDefinition[] {
  const tools: ToolDefinition[] = [];

  // ... existing tools (send_message, feed_scoop, etc.) ...

  // Root-unit only: my_special_tool. `derivePolicy(config.scoop)` turns the
  // ownership edge into capabilities — the record carries no role field.
  if (policy.canManageChildren && config.onMySpecialCallback) {
    tools.push({
      name: 'my_special_tool',
      description: 'Description of what this tool does.',
      inputSchema: {
        type: 'object',
        properties: {
          param1: {
            type: 'string',
            description: 'First parameter',
          },
        },
        required: ['param1'],
      },
      execute: async (input) => {
        const { param1 } = input as { param1: string };
        try {
          const result = await config.onMySpecialCallback(param1);
          return { content: result };
        } catch (err) {
          const msg = err instanceof Error ? err.message : String(err);
          return { content: `Failed: ${msg}`, isError: true };
        }
      },
    });
  }

  return tools;
}

Interface:

interface ScoopManagementToolsConfig {
  scoop: RegisteredScoop;
  onSendMessage: (text: string, sender?: string) => void;
  getScoops: () => RegisteredScoop[];
  // Cone-only callbacks:
  onFeedScoop?: (scoopJid: string, prompt: string) => Promise<void>;
  onScoopScoop?: (scoop: Omit<RegisteredScoop, 'jid'>) => Promise<RegisteredScoop>;
  onDropScoop?: (scoopJid: string) => Promise<void>;
  onSetGlobalMemory?: (content: string) => Promise<void>;
  getGlobalMemory?: () => Promise<string>;
}

interface RegisteredScoop {
  jid: string; // Unique ID
  name: string;
  folder: string;
  parentJid: string | null; // `null` = root unit (a cone); the ONLY role signal
  assistantLabel: string;
}

Cone vs Universal:

  • Cone-only: Guarded by the unit's policy (derivePolicy(scoop).canManageChildren, or isRootUnit(scoop)) — e.g., feed_scoop, scoop_scoop, drop_scoop
  • Universal: Available to all scoops — e.g., send_message

Add callback to ScoopContextCallbacks:

// packages/webapp/src/scoops/scoop-context.ts
export interface ScoopContextCallbacks {
  // ... existing callbacks ...
  onMySpecialCallback?: (param: string) => Promise<string>;
}

Wire in Orchestrator:

// packages/webapp/src/scoops/orchestrator.ts
const scoopManagementConfig: ScoopManagementToolsConfig = {
  // ... existing config ...
  onMySpecialCallback: async (param) => {
    // Implementation
  },
};

Test pattern:

// packages/webapp/tests/scoops/scoop-management-tools.test.ts
import { describe, it, expect, vi } from 'vitest';
import { createScoopManagementTools } from './scoop-management-tools.js';

describe('my_special_tool', () => {
  it('should execute correctly', async () => {
    const mockCallback = vi.fn().mockResolvedValue('result');
    const tools = createScoopManagementTools({
      scoop: { parentJid: null, folder: 'test' },
      onMySpecialCallback: mockCallback,
      // ... other config ...
    });

    const tool = tools.find((t) => t.name === 'my_special_tool');
    expect(tool).toBeDefined();
    const result = await tool!.execute({ param1: 'test' });
    expect(result.content).toContain('result');
  });
});

Reference file: packages/webapp/src/scoops/scoop-management-tools.ts


6. Add a UI Panel

When: To add a new tab or section in the UI (e.g., a settings panel, network monitor).

Architecture note: The legacy Layout/ChatPanel UI was removed during the web-components migration. The current UI shell is built on @slicc/webcomponents (see packages/webcomponents/). New panels are web components mounted via the wc-shell.ts / wc-live.ts controllers in packages/webapp/src/ui/wc/.

Files to create/modify:

  • Create: packages/webcomponents/src/my-panel.ts (web component)
  • Modify: packages/webcomponents/src/index.ts (register the element)
  • Modify: packages/webapp/src/ui/wc/wc-live.ts (mount and wire the panel)

The @slicc/webcomponents library provides the UI primitives (Storybook + @vitest/browser for testing). The packages/webapp/src/ui/wc/ controllers handle mounting, scoop lifecycle events, and leader/follower behavior.

Test pattern: Web component tests use @vitest/browser (real Chromium):

npm test -w @slicc/webcomponents  # browser-mode Vitest

Reference files:

  • packages/webcomponents/src/ — existing web component implementations
  • packages/webapp/src/ui/wc/wc-live.ts — leader UI shell wiring
  • packages/webapp/src/ui/wc/wc-follower.ts — follower UI shell wiring

7. Add a Skill

When: To ship reusable agent instructions as a markdown file.

Files to create:

  • Create: packages/vfs-root/workspace/skills/my-skill/SKILL.md
  • Optional: packages/vfs-root/workspace/skills/my-skill/helper.jsh (executable script)

Implementation:

---
name: my-skill
description: Teaches the agent how to do X
---

# My Skill

You are an expert in [domain]. Your role is to [responsibility].

## Key Principles

1. Always [principle 1]
2. Consider [principle 2]

## Example

When the user asks for X, follow this approach:

- Step 1: [description]
- Step 2: [description]
- Step 3: [description]

Use the `bash` tool to run commands. Use `read_file` to inspect files.

## Output Format

Always provide:

- A brief summary
- Code blocks (when applicable)
- Relevant file paths

How it works:

Skills are auto-discovered from native /workspace/skills/ plus any accessible .agents/skills/*/SKILL.md and .claude/skills/*/SKILL.md directories anywhere in the reachable VFS during scoop initialization. Headers are shown by default; full content is loaded on demand.

With executable script:

# packages/vfs-root/workspace/skills/my-skill/SKILL.md
## Command: my-skill-cmd

Run `my-skill-cmd arg1` to process files:
// packages/vfs-root/workspace/skills/my-skill/my-skill-cmd.jsh
const args = process.argv.slice(2);
console.log(`Processing: ${args.join(', ')}`);

Discovery:

During ScoopContext.init(), SLICC starts from /workspace/skills/ (cone) or /scoops/{folder}/workspace/skills/ (scoop), then also considers any accessible .agents/skills/*/SKILL.md and .claude/skills/*/SKILL.md roots elsewhere in that runtime's reachable VFS. The agent's system prompt includes discovered skill headers and can request full content via read_file.

Only native /workspace/skills/ entries are install-managed by SLICC. Compatibility-discovered .agents and .claude skills remain read-only unless you explicitly copy/package them into the native skills directory.

Test pattern:

Skills are narrative instructions; test by verifying they load correctly:

// packages/webapp/tests/scoops/skills.test.ts
import { describe, it, expect } from 'vitest';
import { loadSkills } from './skills.js';
import { VirtualFS } from '../fs/index.js';

describe('loadSkills', () => {
  it('should load a skill with metadata', async () => {
    const fs = new VirtualFS();
    // Write a skill file
    await fs.writeFile(
      '/workspace/skills/test/SKILL.md',
      '---\nname: test-skill\ndescription: Test\n---\nContent'
    );

    const skills = await loadSkills(fs, '/workspace/skills');
    expect(skills[0].metadata.name).toBe('test-skill');
  });
});

Reference file: packages/webapp/src/scoops/skills.ts, packages/vfs-root/workspace/skills/


8. Add a Provider

Providers come from three sources:

  • Pi-ai auto-discovery: getProviders() returns all pi-ai providers automatically — no files needed. Filtered by packages/dev-tools/providers.build.json (include: ["*"] = all, exclude: ["*"] = none).
  • Built-in extensions: packages/webapp/src/providers/built-in/*.ts — only for providers needing custom register() functions (e.g., bedrock-camp). Also filtered by packages/dev-tools/providers.build.json.
  • External: packages/webapp/providers/*.ts (gitignored within the webapp package) — always included, never filtered. For custom OAuth providers, corporate proxies, etc. Some providers (e.g., adobe.ts) are explicitly un-gitignored and tracked in version control.

Built-in and external modules export config: ProviderConfig and optionally register(): void.

8a. Add an API-Key Provider

When: To support a new LLM provider that uses an API key (e.g., Groq, Hugging Face).

Most providers need no files at all. Pi-ai auto-discovers its providers via getProviders(), and provider-settings.ts generates a fallback config (display name derived from ID, requiresApiKey: true, requiresBaseUrl: false). The provider appears in the Settings UI automatically.

Only create a file in packages/webapp/src/providers/built-in/ if the provider needs a custom register() function (e.g., custom stream functions). See packages/webapp/src/providers/built-in/bedrock-camp.ts for an example.

For external providers (typically gitignored), create packages/webapp/providers/my-provider.ts:

// packages/webapp/providers/my-provider.ts
import type { ProviderConfig } from '../src/providers/types.js';

export const config: ProviderConfig = {
  id: 'my-provider',
  name: 'My Provider',
  description: 'Models via My Provider API',
  requiresApiKey: true,
  apiKeyPlaceholder: 'your-api-key-here',
  apiKeyEnvVar: 'MY_PROVIDER_API_KEY',
  requiresBaseUrl: false,
};

// Optional: register custom stream functions with pi-ai
export function register(): void {
  // registerApiProvider({ api: 'my-provider' as Api, stream: ..., streamSimple: ... });
}

External providers in packages/webapp/providers/ are always included (never filtered by packages/dev-tools/providers.build.json).

8b. Add an OAuth Provider (Corporate Proxy / SSO)

When: To support a provider that authenticates via OAuth (implicit grant or PKCE) — typically a corporate LLM proxy behind SSO.

Files to create:

  • packages/webapp/providers/my-corp.ts (external, gitignored)
  • packages/webapp/providers/my-corp-config.json (optional, for client ID / endpoints)

Implementation:

// packages/webapp/providers/my-corp.ts
import type { ProviderConfig, OAuthLauncher } from '../src/providers/types.js';
import { registerApiProvider, streamAnthropic } from '@earendil-works/pi-ai';
import type { Api, Model, Context } from '@earendil-works/pi-ai';
import { saveOAuthAccount, getAccounts } from '../src/ui/provider-settings.js';

const isExtension = typeof chrome !== 'undefined' && !!(chrome as any)?.runtime?.id;

// Load config from a gitignored JSON file
const configFiles = import.meta.glob('/packages/webapp/providers/my-corp-config.json', {
  eager: true,
  import: 'default',
}) as Record<
  string,
  { clientId: string; proxyEndpoint: string; redirectUri?: string; extensionRedirectUri?: string }
>;
const corpConfig = configFiles['/packages/webapp/providers/my-corp-config.json'] ?? {
  clientId: '',
  proxyEndpoint: '',
};

export const config: ProviderConfig = {
  id: 'my-corp',
  name: 'My Corp',
  description: 'Claude via corporate proxy — login with SSO',
  requiresApiKey: false,
  requiresBaseUrl: false,
  isOAuth: true,

  onOAuthLogin: async (launcher: OAuthLauncher, onSuccess: () => void) => {
    // Build the redirect URI based on runtime
    const redirectUri = isExtension
      ? (corpConfig.extensionRedirectUri ??
        `https://${(chrome as any).runtime.id}.chromiumapp.org/`)
      : (corpConfig.redirectUri ?? `${window.location.origin}/auth/callback`);

    // Generate a cryptographic state nonce to prevent CSRF/token substitution.
    // The launcher round-trips it through the IdP; we reject responses without it.
    const state = crypto.randomUUID();

    const params = new URLSearchParams({
      client_id: corpConfig.clientId,
      response_type: 'token',
      redirect_uri: redirectUri,
      scope: 'openid profile',
      state,
    });
    const authorizeUrl = `https://sso.mycorp.com/authorize?${params}`;

    // Launch the OAuth flow — launcher handles CLI popup vs extension chrome.identity
    const redirectUrl = await launcher(authorizeUrl);
    if (!redirectUrl) return; // User cancelled or timed out

    // Extract token from redirect URL (implicit grant has token in fragment).
    // Verify the state parameter matches to prevent login CSRF.
    const fragment = new URLSearchParams(redirectUrl.slice(redirectUrl.indexOf('#') + 1));
    if (fragment.get('state') !== state) return; // State mismatch — reject
    const accessToken = fragment.get('access_token');
    if (!accessToken) return;

    // Save the OAuth account — this makes the provider "logged in"
    saveOAuthAccount({
      providerId: 'my-corp',
      accessToken,
      tokenExpiresAt: Date.now() + parseInt(fragment.get('expires_in') ?? '86400', 10) * 1000,
    });
    onSuccess(); // Re-render the accounts list
  },

  onOAuthLogout: async () => {
    // Optionally revoke the token with your IdP
    saveOAuthAccount({ providerId: 'my-corp', accessToken: '' });
  },
};

// --- Silent token renewal (optional) ---
// If your IdP supports prompt=none (silent re-auth via session cookie),
// you can implement automatic token renewal in getValidAccessToken():
//
//   1. Check if token is about to expire (e.g., < 60s remaining)
//   2. Build an authorize URL with prompt=none appended
//   3. Call createOAuthLauncher() — it handles CLI popup, extension
//      chrome.identity, and Electron relay automatically
//   4. Extract new token from the redirect URL
//   5. Save via saveOAuthAccount(), return the new token
//
// See packages/webapp/providers/adobe.ts silentRenewToken() for a working example.
// If renewal fails, fall back to throwing "session expired".

// Register custom stream function that proxies through the corporate endpoint
export function register(): void {
  registerApiProvider({
    api: 'my-corp-anthropic' as Api,
    stream: (model: Model<Api>, context: Context, options: any = {}) => {
      const account = getAccounts().find((a) => a.providerId === 'my-corp');
      const proxyModel = {
        ...model,
        baseUrl: corpConfig.proxyEndpoint,
        api: 'anthropic-messages' as Api,
      };
      return streamAnthropic(proxyModel as any, context, {
        ...options,
        apiKey: account?.accessToken,
      });
    },
  });
}

How the OAuth flow works:

  1. User clicks "Login with My Corp" in the Settings dialog
  2. provider-settings.ts calls config.onOAuthLogin(launcher, onSuccess)
  3. The provider builds its authorize URL and calls launcher(authorizeUrl)
  4. The generic OAuthLauncher (from packages/webapp/src/providers/oauth-service.ts) handles transport:
    • CLI: Opens popup → IDP login → redirects to https://www.sliccy.ai/auth/callback → relay page decodes state (port, path, nonce) → redirects to http://localhost:{port}/auth/callback → callback page postMessages the redirect URL back → popup closes
    • Extension: Sends oauth-request to service worker → chrome.identity.launchWebAuthFlow → returns redirect URL with token in fragment
  5. The provider extracts the token from the redirect URL and calls saveOAuthAccount()
  6. onSuccess() re-renders the accounts list showing the logged-in state

Key files:

  • packages/webapp/src/providers/types.ts — ProviderConfig (with onOAuthLogin, onOAuthLogout, onSilentRenew, onValidateToken), OAuthLauncher / OAuthTokenValidation types
  • packages/webapp/src/providers/oauth-service.ts — createOAuthLauncher() factory (CLI popup vs extension chrome.identity)
  • packages/webapp/src/ui/provider-settings.ts — Calls config.onOAuthLogin(launcher, onSuccess) when login button clicked
  • packages/node-server/src/index.ts — /auth/callback route (reads query params + fragment, postMessages to opener)
  • The extension SW's handleOAuthRequest() (generic chrome.identity.launchWebAuthFlow), in ai-ecoverse/slicc-extension

Dual-mode redirect URIs:

ModeRedirect URIRegistration
CLIhttps://www.sliccy.ai/auth/callbackRegister with your OAuth provider/IdP
Extensionhttps://<extension-id>.chromiumapp.org/Register with your OAuth provider/IdP

The CLI redirect URI uses the sliccy.ai relay which decodes the OAuth state parameter to find the localhost port. Encode {port, path, nonce} as base64 JSON in the state param. See packages/webapp/providers/adobe.ts for the pattern.

Type:

interface ProviderConfig {
  id: string;
  name: string;
  description: string;
  requiresApiKey: boolean;
  apiKeyPlaceholder?: string;
  apiKeyEnvVar?: string;
  requiresBaseUrl: boolean; // shown for non-OAuth; also shown for OAuth providers when true
  baseUrlPlaceholder?: string;
  baseUrlDescription?: string;
  isOAuth?: boolean;
  onOAuthLogin?: (launcher: OAuthLauncher, onSuccess: () => void) => Promise<void>;
  onOAuthLogout?: () => Promise<void>;
  /** Refresh silently; null when renewal is impossible OR the call itself failed. */
  onSilentRenew?: () => Promise<string | null>;
  /** Does the provider still accept the stored token? Powers `oauth-token --check`. */
  onValidateToken?: () => Promise<OAuthTokenValidation>;
  /** Static per-model capability overrides. */
  modelOverrides?: Record<string, ModelMetadata>;
  /** Return model IDs with optional metadata (resolved against Anthropic registry). */
  getModelIds?: () => Array<{ id: string; name?: string } & ModelMetadata>;
}

/** Wire format for model capabilities (snake_case, merged into camelCase Model objects). */
interface ModelMetadata {
  api?: 'anthropic' | 'openai'; // stream function routing
  context_window?: number; // context window in tokens
  max_tokens?: number; // max output tokens
  reasoning?: boolean; // supports thinking/reasoning
  input?: string[]; // input modalities (['text', 'image'])
}

type OAuthLauncher = (authorizeUrl: string) => Promise<string | null>;

interface OAuthTokenValidation {
  status: 'accepted' | 'rejected' | 'unknown';
  userName?: string; // identity the token resolved to, when the check returns one
  detail?: string; // e.g. `HTTP 401 Unauthorized`
}

onValidateToken — held is not working (#2695): a stored token inside its recorded expiry can already have been invalidated upstream, so oauth-token --list / --renew only ever report which token is HELD. Implement this hook with ONE cheap authenticated call (GitHub uses GET /user) so oauth-token --check <id> can report whether the provider still accepts it. Rules:

  • Return rejected only when the response proves the credential was refused (401). Statuses a healthy token also produces — GitHub answers 403 for rate limits — must be unknown, or a throttled caller gets sent through a consent window that cannot fix anything.
  • Read the verdict where the provider puts it. Adobe IMS (POST {imsHost}/ims/validate_token/v1) answers HTTP 200 for BOTH verdicts and reports {"valid":false,"reason":"…"} in the body, so treating the status as the answer would call every revoked token valid. A non-2xx there is the check failing, not a refusal — unknown.
  • Return unknown for 5xx, transport failures, and "nothing stored". unknown says nothing about the token; only rejected costs the user a re-login.
  • Bound the request (AbortSignal.timeout) — --check must always answer.
  • onSilentRenew returning null is NOT proof of a lapsed session: most hooks collapse transport failures into null too. The command confirms a decline with onValidateToken before it claims a human is required (exit 3).

requiresBaseUrl for OAuth providers: By default, the base URL field is hidden for OAuth providers. Set requiresBaseUrl: true to show it — useful for providers where the proxy endpoint is configurable at runtime. The base URL is saved to the account before onOAuthLogin is called, so the provider can read it via getBaseUrlForProvider(). The saveOAuthAccount() function preserves the existing baseUrl through re-logins.

getModelIds: When present, getProviderModels() uses this instead of returning all Anthropic models. Each ID is resolved against the Anthropic model registry; unknown IDs get fallback model objects with sensible defaults. Can return optional ModelMetadata fields per model — these override pi-ai defaults. Set api: 'openai' to route a model through streamOpenAICompletions instead of streamAnthropic.

modelOverrides: Static per-model overrides applied to all models for this provider. Useful for config-only providers (like Azure AI Foundry) that can't implement getModelIds() but need custom context windows. Example: modelOverrides: { 'claude-opus-4-6': { context_window: 1000000 } }.

refreshModels (optional, (accessToken?) => Promise<void>): the async populate step for a dynamic model list. getModelIds() is synchronous and only reads caches; refreshModels is where the provider fetches its /v1/models-style list, caches it, and persists the enriched result to localStorage (so cold consumers — notably the cloud cone's kernel worker, which reads localStorage — see the full set + metadata on first resolve). Normally this runs inside onOAuthLogin. Floats that inject an account without an interactive login (the cloud cone, via applyHostedAccounts) must call it explicitly — prewarmHostedModels in ui/hosted-config-apply.ts does this before applying the account (the account write triggers the worker's model resolution, so the list must be warm first). The optional accessToken lets callers pre-warm before the account is persisted. Without it, an OAuth model id pi-ai's registry doesn't know (e.g. claude-opus-4-8) still routes through the provider (see resolution note below) but with default metadata until the list warms.

OAuth-safe resolution: resolveModelById / resolveCurrentModel (ui/provider-settings.ts) never fall back to a native Anthropic model for an OAuth/custom provider. An unknown model id is routed through the provider (api: '${providerId}-anthropic') via buildProviderRoutedModel — otherwise the provider's token (e.g. an Adobe IMS token) would be sent to api.anthropic.com and rejected with 401 invalid x-api-key.

Three-layer merge: Model capabilities resolve as pi-ai registry (defaults) → modelOverrides (static overrides) → getModelIds() metadata (dynamic, highest priority). Each layer only overrides fields it provides.

Model ID pitfall: Use pi-ai alias IDs (e.g., claude-opus-4-6) not dated IDs (e.g., claude-opus-4-6-20250626). In the browser bundle, getModel() returns undefined for unknown IDs instead of throwing, and { ...undefined } silently produces {}. The alias resolves to a full model from the registry with all required fields.

Base URL validation: When requiresBaseUrl: true is set on an OAuth provider and no build-time default exists (empty proxyEndpoint in config), the login button validates that a URL was entered. Users cannot proceed without providing a proxy endpoint.

Test pattern:

OAuth flow is runtime-dependent (browser popups, chrome.identity). Test the provider's token extraction and account saving logic in isolation:

import { describe, it, expect } from 'vitest';

describe('my-corp provider', () => {
  it('extracts token from redirect URL', () => {
    const url = 'https://sso.mycorp.com/callback#access_token=abc123&expires_in=3600';
    const fragment = new URLSearchParams(url.slice(url.indexOf('#') + 1));
    expect(fragment.get('access_token')).toBe('abc123');
  });
});

Reference files: packages/webapp/src/providers/oauth-service.ts, packages/webapp/src/providers/types.ts, packages/webapp/src/ui/provider-settings.ts


Integration Checklist

When adding a feature:

  • Core logic implemented with error handling
  • Test file in packages/*/tests/ mirroring the src/ structure
  • Pure-logic tests added (avoid DOM/chrome.* testing in vitest unless necessary)
  • Extension mode compatibility verified (CSP, chrome.runtime.getURL, sandbox iframe if needed)
  • Dual-mode tested (CLI + extension)
  • Logging added (createLogger('namespace'))
  • Agent-facing SKILL.md updated when a shell command or workflow changes
  • Matching follower handler and UI action added for leader broadcasts
  • Root/package AGENTS.md or CLAUDE.md updated if the architectural pattern is new
  • No sensitive data logged or stored in localStorage unencrypted

Build & Test

# Type-check both browser and CLI
npm run typecheck

# Run tests
npm run test

# Standalone dev
npm run dev

Extension dev happens in ai-ecoverse/slicc-extension.


9. Add Interactive Tool UI (Approval Dialogs, Forms)

When: A shell command or tool needs user interaction before proceeding (e.g., permission approval, file picker, form input). Tool UI solves the "user gesture" problem — browser APIs like showDirectoryPicker() require a user click, but agent-driven tool calls have no gesture context. For the broader gate-pattern context (sudo, device gates, OS capture gates), see docs/approvals.md.

Files to modify:

  • Your command file (e.g., packages/webapp/src/fs/mount-commands.ts)
  • Import from: packages/webapp/src/tools/tool-ui.ts

How it works:

  1. Tool execution sets up a context with onUpdate callback (handled automatically by tool-adapter.ts)
  2. Shell commands call showToolUIFromContext() to render interactive HTML in the chat
  3. User clicks a button → callback runs with user gesture context → can call restricted APIs
  4. Promise resolves with user's action/data

Implementation (from mount command):

import { getToolExecutionContext, showToolUIFromContext } from '../tools/tool-ui.js';

async function execute(args: string[]): Promise<ShellResult> {
  // Check if running in agent context (no user gesture)
  const toolContext = getToolExecutionContext();

  if (toolContext) {
    // Agent-driven: show approval UI.
    // IMPORTANT: escape dynamic values before interpolating into HTML to prevent
    // injection — a crafted path could spoof the approval surface.
    const safePath = targetPath.replace(
      /[&<>"']/g,
      (c) => ({ '&': '&amp;', '<': '&lt;', '>': '&gt;', '"': '&quot;', "'": '&#39;' })[c] ?? c
    );
    const result = await showToolUIFromContext({
      html: `
        <div class="tool-ui">
          <p>The agent wants to access <code>${safePath}</code></p>
          <div class="tool-ui__actions">
            <button class="tool-ui__btn tool-ui__btn--primary" data-action="approve">
              Approve
            </button>
            <button class="tool-ui__btn tool-ui__btn--secondary" data-action="deny">
              Deny
            </button>
          </div>
        </div>
      `,
      onAction: async (action) => {
        if (action === 'approve') {
          // Runs with user gesture! Can call showDirectoryPicker(), etc.
          const handle = await window.showDirectoryPicker();
          return { approved: true, handle };
        }
        return { approved: false };
      },
    });

    if (!result?.approved) {
      return { stdout: '', stderr: 'User denied', exitCode: 1 };
    }
    // Use result.handle...
  } else {
    // Terminal/user-driven: has gesture, call API directly
    const handle = await window.showDirectoryPicker();
  }
}

HTML conventions:

  • Wrap content in <div class="tool-ui">
  • Use data-action="actionName" on buttons for click handling
  • Use data-action-data='{"key":"value"}' for additional data (JSON)
  • Available button classes: .tool-ui__btn--primary, .tool-ui__btn--secondary
  • Forms: add data-action="submit" to form, fields become action data

Key functions (packages/webapp/src/tools/tool-ui.ts):

// Get current tool execution context (null if not in a tool)
getToolExecutionContext(): ToolExecutionContext | null

// Show UI and wait for user action (returns null if no context)
showToolUIFromContext(request: {
  html: string;
  onAction?: (action: string, data?: unknown) => Promise<unknown> | unknown;
}): Promise<unknown | null>

// Lower-level: show UI with explicit onUpdate callback
showToolUI(request: ToolUIRequest, onUpdate: OnUpdateCallback): Promise<unknown>

Lifecycle:

  1. Tool calls showToolUIFromContext() → UI appears in chat (tool call auto-expands)
  2. User clicks button with data-action → onAction callback fires with gesture context
  3. Callback return value resolves the showToolUIFromContext() promise
  4. UI is automatically cleaned up when tool execution ends

Extension vs CLI mode:

  • CLI mode: HTML rendered directly in DOM with click handlers
  • Extension mode: HTML rendered in CSP-exempt sandbox iframe, actions posted via postMessage

Both modes handle data-action clicks and form submissions identically.


Common Patterns

Error handling: Wrap async operations in try/catch. Return { content: errorMsg, isError: true } for tools.

Logging: Import createLogger('namespace') from packages/webapp/src/core/logger.js. Logs are filtered by level (DEBUG in dev, ERROR in prod).

VFS access: All core layers have access to VirtualFS. Scoops get RestrictedFS (path-based ACL).

Shell commands: Prefer shell commands (bash tool) for new capabilities. Dedicated tools only if the capability needs binary data (browser screenshots, network recording).

Browser automation: Use playwright-cli / playwright / puppeteer for tab control. Use serve <dir> for app directories and open for single preview files.


Resources

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.