@tiny-fish/cli 0.41.2-next.327 → 0.41.2-next.329

package/README.md

@@ -97,6 +97,18 @@ Hermes completes OAuth while adding the MCP server. `hermes mcp add` accepts no
 interactively. After setup, the command starts the walkthrough in a Hermes session and leaves that
 session open for your replies.
 
+### Connect Command Code
+
+Register TinyFish user-wide with your API key:
+
+```bash
+npx -y @tiny-fish/cli@latest connect command-code --api-key sk-tinyfish-...
+```
+
+Command Code takes an API key only. `cmd mcp add` opens a browser sign-in even when a header is
+passed, so TinyFish registers through `mcp add-json`, which writes `~/.commandcode/mcp.json`
+without an auth probe. Without a key the command refuses rather than falling back to a sign-in.
+
 ### Connect OpenClaw
 
 Install the TinyFish skill, sign in with an API key, and start an interactive walkthrough with one

package/dist/commands/connect.js

@@ -836,7 +836,7 @@ export function registerConnect(program) {
     program
         .command('connect')
         .description('Connect TinyFish to an AI agent')
-        .argument('[client]', 'Agent client to connect (claude-code, codex, cursor, grok, hermes, omp, openclaw, or opencode); omit to pick from the agents detected on this machine')
+        .argument('[client]', `Agent client to connect (${ALL_HARNESSES.join(', ')}); omit to pick from the agents detected on this machine`)
         .option('--all', 'Detect and connect every supported harness found on this machine')
         .option('--dry-run', 'Print planned writes per harness without touching anything (--all only)')
         .option('--uninstall', 'Remove TinyFish entries written by connect --all')

package/dist/lib/bundled-skill.d.ts

@@ -0,0 +1,2 @@
+/** Two levels up from dist/lib/ is the package root; tsc mirrors src/. */
+export declare function bundledSkillDir(): string;

package/dist/lib/bundled-skill.js

@@ -0,0 +1,8 @@
+import * as path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { WEB_SKILL_NAME } from './constants.js';
+/** Two levels up from dist/lib/ is the package root; tsc mirrors src/. */
+export function bundledSkillDir() {
+    const packageRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..', '..');
+    return path.join(packageRoot, 'skill', WEB_SKILL_NAME);
+}

package/dist/lib/command-code-config.d.ts

@@ -0,0 +1,3 @@
+import { type McpJsonServerEntry } from './mcp-json-config.js';
+/** Reports the header's shape, never its value. */
+export declare function readCommandCodeTinyfishEntry(): McpJsonServerEntry;

package/dist/lib/command-code-config.js

@@ -0,0 +1,14 @@
+import * as os from 'os';
+import * as path from 'path';
+import { readTinyfishEntry, } from './mcp-json-config.js';
+// Read-only: Command Code writes this file itself, through `cmd mcp add-json --scope user`.
+const COMMAND_CODE_TARGET = {
+    serverKey: 'tinyfish',
+    dir: () => path.join(os.homedir(), '.commandcode'),
+    file: () => path.join(os.homedir(), '.commandcode', 'mcp.json'),
+    keyHeader: { name: 'Authorization', valuePrefix: 'Bearer ' },
+};
+/** Reports the header's shape, never its value. */
+export function readCommandCodeTinyfishEntry() {
+    return readTinyfishEntry(COMMAND_CODE_TARGET);
+}

package/dist/lib/connect-clients.d.ts

@@ -99,7 +99,7 @@ export declare function hermesRegistrationEnabled(home: string): {
 };
 export declare const NATIVE_MCP_CLIENTS: readonly NativeMcpClient[];
 /** Native descriptor by harness id; Cursor and OpenClaw have none. */
-export declare const NATIVE_BY_HARNESS: Map<"openclaw" | "omp" | "grok" | "cursor" | "codex" | "hermes" | "opencode" | "pi" | "claude-code", NativeMcpClient>;
+export declare const NATIVE_BY_HARNESS: Map<"openclaw" | "omp" | "grok" | "cursor" | "codex" | "hermes" | "command-code" | "opencode" | "pi" | "claude-code", NativeMcpClient>;
 export declare const OPENCLAW: SupportedCommand;
 /** "printed" = handed to the user to paste; the walkthrough was never started for them. */
 export type WalkthroughOutcome = 'launched' | 'printed';

package/dist/lib/connect-clients.js

@@ -206,8 +206,21 @@ function specAddArgs(spec, mcpUrl) {
         ? ['mcp', 'add', ...flags, 'tinyfish', mcpUrl]
         : ['mcp', 'add', 'tinyfish', '--url', mcpUrl, ...flags];
 }
+/** `mcp add` probes the server and runs OAuth; add-json only writes config. */
+function jsonAddArgs(spec, mcpUrl, apiKey) {
+    const { header } = spec;
+    const body = {
+        transport: 'http',
+        url: mcpUrl,
+        ...(header ? { headers: { [header.name]: `${header.valuePrefix ?? ''}${apiKey}` } } : {}),
+    };
+    return ['mcp', 'add-json', ...(spec.keyedAddJsonFlags ?? []), 'tinyfish', JSON.stringify(body)];
+}
 function specKeyAuth(spec) {
     const { header, keyEnvFlag, keyAddFlags } = spec;
+    if (spec.keyedAddJsonFlags) {
+        return { addArgs: (mcpUrl, apiKey) => jsonAddArgs(spec, mcpUrl, apiKey) };
+    }
     if (keyEnvFlag) {
         return {
             envVar: TINYFISH_API_KEY_VAR,

package/dist/lib/constants.d.ts

@@ -4,6 +4,8 @@ export declare const CLI_INVOCATION_ID: string;
 /** Unversioned: the install site appends `@latest`, the version read must not. */
 export declare const TINYFISH_CLI_PACKAGE = "@tiny-fish/cli";
 export declare const CLI_AGENT_IDENTITY = "tinyfish-cli";
+/** Names the bundled dir, every install target dir, and the lock entry. */
+export declare const WEB_SKILL_NAME = "use-tinyfish";
 /** The descriptor hands this name to harnesses; the probes resolve it. */
 export declare const TINYFISH_API_KEY_VAR = "TINYFISH_API_KEY";
 export declare const BASE_URL: string;

package/dist/lib/constants.js

@@ -9,6 +9,8 @@ export const CLI_INVOCATION_ID = randomUUID();
 export const TINYFISH_CLI_PACKAGE = '@tiny-fish/cli';
 // How we identify ourselves to other tools; `skills` echoes it back.
 export const CLI_AGENT_IDENTITY = 'tinyfish-cli';
+/** Names the bundled dir, every install target dir, and the lock entry. */
+export const WEB_SKILL_NAME = 'use-tinyfish';
 /** The descriptor hands this name to harnesses; the probes resolve it. */
 export const TINYFISH_API_KEY_VAR = 'TINYFISH_API_KEY';
 /** Base URL for the TinyFish API. Override with TINYFISH_API_URL for staging/self-hosted. */

package/dist/lib/doctor-report.d.ts

@@ -30,6 +30,7 @@ declare const doctorCheckSchema: z.ZodObject<{
         cursor: "cursor";
         codex: "codex";
         hermes: "hermes";
+        "command-code": "command-code";
         opencode: "opencode";
         pi: "pi";
         "claude-code": "claude-code";
@@ -48,6 +49,7 @@ declare const doctorHarnessSchema: z.ZodObject<{
         cursor: "cursor";
         codex: "codex";
         hermes: "hermes";
+        "command-code": "command-code";
         opencode: "opencode";
         pi: "pi";
         "claude-code": "claude-code";
@@ -75,6 +77,7 @@ declare const doctorRepairSchema: z.ZodObject<{
         cursor: "cursor";
         codex: "codex";
         hermes: "hermes";
+        "command-code": "command-code";
         opencode: "opencode";
         pi: "pi";
         "claude-code": "claude-code";
@@ -104,6 +107,7 @@ export declare const doctorReportSchema: z.ZodObject<{
             cursor: "cursor";
             codex: "codex";
             hermes: "hermes";
+            "command-code": "command-code";
             opencode: "opencode";
             pi: "pi";
             "claude-code": "claude-code";
@@ -122,6 +126,7 @@ export declare const doctorReportSchema: z.ZodObject<{
             cursor: "cursor";
             codex: "codex";
             hermes: "hermes";
+            "command-code": "command-code";
             opencode: "opencode";
             pi: "pi";
             "claude-code": "claude-code";
@@ -149,6 +154,7 @@ export declare const doctorReportSchema: z.ZodObject<{
             cursor: "cursor";
             codex: "codex";
             hermes: "hermes";
+            "command-code": "command-code";
             opencode: "opencode";
             pi: "pi";
             "claude-code": "claude-code";

package/dist/lib/harness-spec.d.ts

@@ -44,6 +44,8 @@ export interface HarnessSpec {
     keyEnvFlag?: string;
     /** Keyed adds append these flags; the key itself is seeded elsewhere (Hermes). */
     keyAddFlags?: string[];
+    /** Keyed adds go through `mcp add-json`, which takes the URL and header in its body. */
+    keyedAddJsonFlags?: string[];
     /** No sign-in exists here, so connect refuses a keyless install (Hermes). */
     keyRequired?: true;
     loginArgs?: string[];
@@ -133,6 +135,29 @@ export declare const HARNESS_SPECS: {
         loginArgs: string[];
         authDeferredAtInstall: true;
     };
+    'command-code': {
+        command: string;
+        displayName: string;
+        configDir: string;
+        reloadAction: string;
+        supportCheck: {
+            args: string[];
+            patterns: RegExp[];
+            timeoutMs: number;
+            unavailableMessage: string;
+        };
+        keyRequired: true;
+        header: {
+            name: string;
+            sep: ": ";
+            valuePrefix: string;
+        };
+        keyedAddJsonFlags: string[];
+        removals: {
+            args: string[];
+            label: string;
+        }[];
+    };
     cursor: {
         command: string;
         displayName: string;
@@ -253,7 +278,7 @@ export declare const ALL_HARNESSES: readonly Harness[];
 export declare function harnessSpec(harness: Harness): HarnessSpec;
 /** The rest of the union: every one of these must supply a connect and launch override. */
 export type NonNativeHarness = {
-    [K in Harness]: 'urlStyle' extends keyof (typeof HARNESS_SPECS)[K] ? never : K;
+    [K in Harness]: 'urlStyle' extends keyof (typeof HARNESS_SPECS)[K] ? never : 'keyRequired' extends keyof (typeof HARNESS_SPECS)[K] ? never : K;
 }[Harness];
-/** Native MCP harnesses carry add-generation fields; the rest override connect. */
-export declare const NATIVE_HARNESSES: ("openclaw" | "omp" | "grok" | "cursor" | "codex" | "hermes" | "opencode" | "pi" | "claude-code")[];
+/** Native MCP harnesses generate an add; key-only ones generate only the keyed form. */
+export declare const NATIVE_HARNESSES: ("openclaw" | "omp" | "grok" | "cursor" | "codex" | "hermes" | "command-code" | "opencode" | "pi" | "claude-code")[];

package/dist/lib/harness-spec.js

@@ -46,7 +46,11 @@ const OPENCODE_MODEL_NOTE = 'Note: TinyFish runs on tool calls, so OpenCode need
     'models (e.g. Nano Banana Pro) will show "No endpoints found that support tool use" — switch ' +
     "OpenCode's model if the walkthrough can't start.";
 const HERMES_RESTART_NOTE = 'Restart your Hermes session to pick up TinyFish — Hermes discovers MCP servers at startup.';
+const COMMAND_CODE_ADD_JSON_UNAVAILABLE_MESSAGE = 'Could not confirm this Command Code installation supports keyed MCP setup: `commandcode mcp ' +
+    '--help` did not list `add-json`. Run `commandcode update` and retry.' +
+    SUPPORT_CHECK_DEBUG_HINT;
 const HEADER_FLAG = /(?:^|\s)--header(?:[\s<=]|$)/m;
+const ADD_JSON_COMMAND = /^\s*add-json(?:\s|\[)/m;
 /** One entry per harness; every per-harness list derives from it. */
 export const HARNESS_SPECS = {
     'claude-code': {
@@ -108,6 +112,32 @@ export const HARNESS_SPECS = {
         // TODO(PF-3580): connect now probes Codex sign-in, so this over-warns a signed-in install.
         authDeferredAtInstall: true,
     },
+    'command-code': {
+        // Same package ships `cmd`, but that is cmd.exe on Windows; this alias collides with nothing.
+        command: 'commandcode',
+        displayName: 'Command Code',
+        configDir: '.commandcode',
+        reloadAction: 'restart it',
+        // add-json is the only command this harness uses, so it is what must exist.
+        supportCheck: {
+            args: ['mcp', '--help'],
+            patterns: [ADD_JSON_COMMAND],
+            // Command Code self-updates inside the probe, which outlasts the default budget.
+            timeoutMs: 30_000,
+            unavailableMessage: COMMAND_CODE_ADD_JSON_UNAVAILABLE_MESSAGE,
+        },
+        // Key-only: `cmd mcp add` runs browser OAuth even when a header is supplied.
+        keyRequired: true,
+        header: { name: 'Authorization', sep: ': ', valuePrefix: 'Bearer ' },
+        // Default scope is `local`, which writes a per-project entry instead of the user's.
+        keyedAddJsonFlags: ['--scope', 'user'],
+        removals: [
+            {
+                args: ['mcp', 'remove', 'tinyfish', '--scope', 'user'],
+                label: 'user TinyFish registration',
+            },
+        ],
+    },
     cursor: {
         command: 'cursor-agent',
         displayName: 'Cursor',
@@ -228,5 +258,8 @@ export const ALL_HARNESSES = Object.keys(HARNESS_SPECS);
 export function harnessSpec(harness) {
     return HARNESS_SPECS[harness];
 }
-/** Native MCP harnesses carry add-generation fields; the rest override connect. */
-export const NATIVE_HARNESSES = ALL_HARNESSES.filter((harness) => harnessSpec(harness).urlStyle !== undefined);
+/** Native MCP harnesses generate an add; key-only ones generate only the keyed form. */
+export const NATIVE_HARNESSES = ALL_HARNESSES.filter((harness) => {
+    const spec = harnessSpec(harness);
+    return spec.urlStyle !== undefined || spec.keyRequired === true;
+});

package/dist/lib/harness.js

@@ -26,6 +26,8 @@ const HARNESS_FINGERPRINTS = [
     // prefix so we catch a Codex run regardless of which of its vars are set.
     { name: 'codex', matches: (env) => hasVarWithPrefix(env, 'CODEX_') },
     { name: 'hermes', matches: (env) => hasVarWithPrefix(env, 'HERMES_') },
+    // COMMANDCODE_SCRATCHPAD lands on every child; a disabled scratchpad leaves no marker.
+    { name: 'command-code', matches: (env) => hasVarWithPrefix(env, 'COMMANDCODE_') },
     // Exact key, not a prefix: opencode writes OPENCODE=1 at startup, reads every OPENCODE_* as config.
     { name: 'opencode', matches: (env) => Boolean(env['OPENCODE']) },
     // Observed: pi launched from Claude Code inherits CLAUDECODE=1.

package/dist/lib/mcp-json-config.d.ts

@@ -3,6 +3,11 @@ export interface McpJsonTarget {
     /** Functions so paths resolve at call time. */
     dir(): string;
     file(): string;
+    /** Read-side only; defaults to what the write path emits (Command Code writes its own). */
+    keyHeader?: {
+        name: string;
+        valuePrefix?: string;
+    };
 }
 export interface McpJsonWriteResult {
     status: 'written' | 'unchanged' | 'corrupt_skip';
@@ -17,6 +22,8 @@ export declare function planWrite(target: McpJsonTarget, mcpUrl: string, apiKey?
 export interface McpJsonServerEntry {
     present: boolean;
     hasApiKeyHeader: boolean;
+    /** Only ever false: harnesses with a disable toggle write it, the rest omit it. */
+    enabled?: false;
     /** Registered endpoint, so a caller can tell "registered" from "registered at the right place". */
     url?: string;
     keyMatchesCliKey?: boolean;

package/dist/lib/mcp-json-config.js

@@ -67,21 +67,31 @@ export function readTinyfishEntry(target) {
     const entry = isPlainRecord(servers) ? servers[target.serverKey] : undefined;
     if (!isPlainRecord(entry))
         return { present: false, hasApiKeyHeader: false };
-    const headers = entry.headers;
-    // Header names are case-insensitive, and this file is hand-editable — matching only the
-    // casing we write would understate auth mode for a user who typed it differently.
-    const keyHeader = isPlainRecord(headers)
-        ? Object.entries(headers).find((entry) => entry[0].toLowerCase() === 'x-api-key' && typeof entry[1] === 'string')
-        : undefined;
-    const templateVar = keyHeader ? ENV_TEMPLATE_VALUE.exec(keyHeader[1])?.[1] : undefined;
+    const key = readKeyHeader(entry.headers, target.keyHeader);
+    const templateVar = key ? ENV_TEMPLATE_VALUE.exec(key.value)?.[1] : undefined;
     return {
         present: true,
-        hasApiKeyHeader: keyHeader !== undefined,
-        ...(matchesCliKey(keyHeader?.[1]) ? { keyMatchesCliKey: true } : {}),
+        hasApiKeyHeader: key !== undefined,
+        ...(entry.enabled === false ? { enabled: false } : {}),
+        ...(matchesCliKey(key?.value) ? { keyMatchesCliKey: true } : {}),
         ...(templateVar ? { keyTemplateVar: templateVar } : {}),
         ...(typeof entry.url === 'string' ? { url: entry.url } : {}),
     };
 }
+/** Reports the key header's shape, never its value. */
+function readKeyHeader(headers, keyHeader) {
+    const { name = 'x-api-key', valuePrefix = '' } = keyHeader ?? {};
+    // Header names are case-insensitive, and this file is hand-editable — matching only the
+    // casing we write would understate auth mode for a user who typed it differently.
+    const found = isPlainRecord(headers)
+        ? Object.entries(headers).find((entry) => entry[0].toLowerCase() === name.toLowerCase() && typeof entry[1] === 'string')
+        : undefined;
+    if (!found)
+        return undefined;
+    // The scheme is case-insensitive too, and a hand-edited header may omit it entirely.
+    const hasPrefix = found[1].toLowerCase().startsWith(valuePrefix.toLowerCase());
+    return { value: hasPrefix ? found[1].slice(valuePrefix.length) : found[1] };
+}
 // Backup, then atomic temp+rename; pid avoids same-millisecond backup collisions.
 function commitServers(target, existing, servers) {
     const filePath = target.file();

package/dist/lib/registration-detect.js

@@ -6,6 +6,7 @@ import { loadConfig, matchesCliKey } from './auth.js';
 import { NATIVE_BY_HARNESS } from './connect-clients.js';
 import { HARNESS_PROBE_TIMEOUT_MS } from './constants.js';
 import { errLine } from './output.js';
+import { readCommandCodeTinyfishEntry } from './command-code-config.js';
 import { readCursorTinyfishEntry } from './cursor-config.js';
 import { readOmpTinyfishEntry } from './omp-config.js';
 import { readPiTinyfishEntry } from './pi-config.js';
@@ -278,6 +279,22 @@ function probeCodex() {
         ...(envVar ? envKeyVerdict(envVar) : {}),
     };
 }
+function probeCommandCode() {
+    const entry = readCommandCodeTinyfishEntry();
+    if (entry.error)
+        return unverified('mcp.json exists but could not be read or parsed');
+    if (!entry.present)
+        return NOT_REGISTERED;
+    // The /mcp toggle disables an entry in place, and Command Code then ignores it.
+    return {
+        registered: Registered.Yes,
+        authMode: entry.hasApiKeyHeader ? AuthMode.ApiKey : AuthMode.Unknown,
+        // connect only ever writes a keyed entry here, so a headerless one was not written by us.
+        ...(entry.enabled === false ? { connected: false } : {}),
+        ...(entry.url ? { registeredUrl: entry.url } : {}),
+        ...(entry.keyMatchesCliKey ? { keyMatchesCliKey: true } : {}),
+    };
+}
 function probeCursor() {
     const entry = readCursorTinyfishEntry();
     if (entry.error) {
@@ -499,6 +516,7 @@ function probeGrok() {
 const PROBES = {
     'claude-code': () => fromMcpGet('claude'),
     codex: probeCodex,
+    'command-code': probeCommandCode,
     cursor: probeCursor,
     grok: probeGrok,
     hermes: probeHermes,

package/dist/lib/setup-telemetry.d.ts

@@ -28,6 +28,7 @@ declare const harnessResultSchema: z.ZodObject<{
         cursor: "cursor";
         codex: "codex";
         hermes: "hermes";
+        "command-code": "command-code";
         opencode: "opencode";
         pi: "pi";
         "claude-code": "claude-code";
@@ -63,6 +64,7 @@ export declare const setupCompletedPayloadSchema: z.ZodObject<{
             cursor: "cursor";
             codex: "codex";
             hermes: "hermes";
+            "command-code": "command-code";
             opencode: "opencode";
             pi: "pi";
             "claude-code": "claude-code";
@@ -125,6 +127,7 @@ declare const doctorCompletedPayloadSchema: z.ZodObject<{
         cursor: "cursor";
         codex: "codex";
         hermes: "hermes";
+        "command-code": "command-code";
         opencode: "opencode";
         pi: "pi";
         "claude-code": "claude-code";
@@ -139,6 +142,7 @@ declare const doctorCompletedPayloadSchema: z.ZodObject<{
         cursor: "cursor";
         codex: "codex";
         hermes: "hermes";
+        "command-code": "command-code";
         opencode: "opencode";
         pi: "pi";
         "claude-code": "claude-code";
@@ -151,6 +155,7 @@ declare const doctorCompletedPayloadSchema: z.ZodObject<{
             cursor: "cursor";
             codex: "codex";
             hermes: "hermes";
+            "command-code": "command-code";
             opencode: "opencode";
             pi: "pi";
             "claude-code": "claude-code";
@@ -187,6 +192,7 @@ declare const doctorCouldNotRunPayloadSchema: z.ZodObject<{
         cursor: "cursor";
         codex: "codex";
         hermes: "hermes";
+        "command-code": "command-code";
         opencode: "opencode";
         pi: "pi";
         "claude-code": "claude-code";
@@ -224,6 +230,7 @@ declare const doctorPayloadSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
         cursor: "cursor";
         codex: "codex";
         hermes: "hermes";
+        "command-code": "command-code";
         opencode: "opencode";
         pi: "pi";
         "claude-code": "claude-code";
@@ -238,6 +245,7 @@ declare const doctorPayloadSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
         cursor: "cursor";
         codex: "codex";
         hermes: "hermes";
+        "command-code": "command-code";
         opencode: "opencode";
         pi: "pi";
         "claude-code": "claude-code";
@@ -250,6 +258,7 @@ declare const doctorPayloadSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
             cursor: "cursor";
             codex: "codex";
             hermes: "hermes";
+            "command-code": "command-code";
             opencode: "opencode";
             pi: "pi";
             "claude-code": "claude-code";
@@ -285,6 +294,7 @@ declare const doctorPayloadSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
         cursor: "cursor";
         codex: "codex";
         hermes: "hermes";
+        "command-code": "command-code";
         opencode: "opencode";
         pi: "pi";
         "claude-code": "claude-code";

package/dist/lib/skill-install.js

@@ -1,5 +1,4 @@
 import * as fs from 'node:fs';
-import * as os from 'node:os';
 import * as path from 'node:path';
 import spawn from 'cross-spawn';
 import { loadConfig } from './auth.js';
@@ -8,6 +7,7 @@ import { CURSOR_SKILL_TARGET, NATIVE_MCP_CLIENTS, OPENCLAW, openclawSkillInstall
 import { ConnectInterruptedError, ConnectStepError, probeSupportVariant, spawnStepError, throwIfInterrupted, } from './connect-runtime.js';
 import { CLI_AGENT_IDENTITY } from './constants.js';
 import { errLine, sanitizeLine } from './output.js';
+import { skillTargetDir } from './skill-paths.js';
 // Supports Hermes without node:util.styleText, so the installer still runs on Node 20.11.
 export const SKILLS_CLI_PACKAGE = 'skills@1.5.15';
 const TINYFISH_WEB_SKILL_SOURCE = 'tinyfish-io/tinyfish-cookbook';
@@ -45,28 +45,10 @@ const SKILL_ALREADY_CURRENT_PATTERN = /All global skills are up to date/;
 // A lock entry with no recorded hash is untrackable, so `skills` reports it as skipped rather
 // than failed. Left undetected that reads as "up to date" while nothing was refreshed.
 const SKILL_UNCHECKABLE_PATTERN = /cannot be checked automatically/;
-// `skills` writes here for the universal agents, whose own config dirs it never touches.
-function canonicalSkillsDir() {
-    return path.join(os.homedir(), '.agents', 'skills'); // nosemgrep: path-join-resolve-traversal -- fixed dir names under os.homedir()
-}
-// Where the harness reads. Both of the modes `add` picks land the skill here.
-const SKILL_DIR_BY_AGENT = {
-    'claude-code': () => path.join(agentHome('CLAUDE_CONFIG_DIR', '.claude'), 'skills'),
-    // The env value, not resolveHermesHome(): the child we spawn reads the env.
-    'hermes-agent': () => path.join(agentHome('HERMES_HOME', '.hermes'), 'skills'),
-    codex: canonicalSkillsDir,
-    cursor: canonicalSkillsDir,
-    opencode: canonicalSkillsDir,
-    // `skills` writes pi's here whatever PI_CODING_AGENT_DIR says.
-    pi: () => path.join(os.homedir(), '.pi', 'agent', 'skills'), // nosemgrep: path-join-resolve-traversal -- fixed dir names under os.homedir()
-};
-function agentHome(override, fallback) {
-    return process.env[override]?.trim() || path.join(os.homedir(), fallback); // nosemgrep: path-join-resolve-traversal -- fixed dir names under os.homedir()
-}
 /** `add` exits 0 on per-agent failure, so the file it should have written is the verdict. */
 function skillOnDisk(agent) {
     // SKILL.md, not the dir: `skills` mkdirs before it copies, so a failed copy leaves one.
-    return fs.existsSync(path.join(SKILL_DIR_BY_AGENT[agent](), TINYFISH_WEB_SKILL, 'SKILL.md'));
+    return fs.existsSync(path.join(skillTargetDir(agent), 'SKILL.md'));
 }
 // The route tail-slices to 500, so an over-long tail would cut the tag off the front.
 const SKILL_DETAIL_TAIL_MAX_CHARS = 425;

package/dist/lib/skill-paths.d.ts

@@ -0,0 +1,5 @@
+import type { SkillAgent } from './harness-spec.js';
+/** The skill's own dir under where skills@1.5.15 wrote for this agent. */
+export declare function skillTargetDir(agent: SkillAgent): string;
+/** Mirrors skills@1.5.15 getSkillLockPath(); missing the XDG branch strands entries. */
+export declare function skillLockPath(): string;

package/dist/lib/skill-paths.js

@@ -0,0 +1,33 @@
+import * as os from 'node:os';
+import * as path from 'node:path';
+import { WEB_SKILL_NAME } from './constants.js';
+// Mirrors skills@1.5.15 exactly: it trims and falls back on empty values.
+function agentHome(override, fallback) {
+    return process.env[override]?.trim() || path.join(os.homedir(), fallback); // nosemgrep: path-join-resolve-traversal -- fixed dir names under os.homedir()
+}
+// `skills` writes here for the universal agents, whose own config dirs it never touches.
+function canonicalSkillsDir() {
+    return path.join(os.homedir(), '.agents', 'skills'); // nosemgrep: path-join-resolve-traversal -- fixed dir names under os.homedir()
+}
+// Where the harness reads. Both of the modes `add` picks land the skill here.
+const SKILL_DIR_BY_AGENT = {
+    'claude-code': () => path.join(agentHome('CLAUDE_CONFIG_DIR', '.claude'), 'skills'),
+    // The env value, not resolveHermesHome(): skills@1.5.15 reads $HERMES_HOME directly.
+    'hermes-agent': () => path.join(agentHome('HERMES_HOME', '.hermes'), 'skills'),
+    codex: canonicalSkillsDir,
+    cursor: canonicalSkillsDir,
+    opencode: canonicalSkillsDir,
+    // `skills` writes pi's here whatever PI_CODING_AGENT_DIR says.
+    pi: () => path.join(os.homedir(), '.pi', 'agent', 'skills'), // nosemgrep: path-join-resolve-traversal -- fixed dir names under os.homedir()
+};
+/** The skill's own dir under where skills@1.5.15 wrote for this agent. */
+export function skillTargetDir(agent) {
+    return path.join(SKILL_DIR_BY_AGENT[agent](), WEB_SKILL_NAME);
+}
+/** Mirrors skills@1.5.15 getSkillLockPath(); missing the XDG branch strands entries. */
+export function skillLockPath() {
+    const xdgStateHome = process.env.XDG_STATE_HOME?.trim();
+    if (xdgStateHome)
+        return path.join(xdgStateHome, 'skills', '.skill-lock.json');
+    return path.join(os.homedir(), '.agents', '.skill-lock.json');
+}

package/dist/lib/skill-vendor.d.ts

@@ -0,0 +1,13 @@
+import type { SkillAgent } from './harness-spec.js';
+/**
+ * Writes the bundled skill where each agent reads it; true iff bytes changed.
+ *
+ * Synchronous on purpose: connect flows are sync, a new await breaks them.
+ */
+export declare function writeWebSkill(agents: SkillAgent[], opts?: {
+    sourceDir?: string;
+}): boolean;
+/** Best effort: a lock cleanup failure must never fail an install. */
+export declare function clearSkillLockEntry(opts?: {
+    verbose?: boolean;
+}): void;

package/dist/lib/skill-vendor.js

@@ -0,0 +1,187 @@
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import { bundledSkillDir } from './bundled-skill.js';
+import { WEB_SKILL_NAME } from './constants.js';
+import { ConnectStepError } from './connect-runtime.js';
+import { errLine } from './output.js';
+import { skillLockPath, skillTargetDir } from './skill-paths.js';
+// A younger staging dir may belong to a live concurrent connect.
+const STAGING_SWEEP_MIN_AGE_MS = 5 * 60_000;
+// Under the route's 500-char tail-slice; margin for caller prefixes.
+const FAILURE_DETAIL_MAX_CHARS = 425;
+/**
+ * Writes the bundled skill where each agent reads it; true iff bytes changed.
+ *
+ * Synchronous on purpose: connect flows are sync, a new await breaks them.
+ */
+export function writeWebSkill(agents, opts) {
+    const sourceDir = opts?.sourceDir ?? bundledSkillDir();
+    const targetDirs = [...new Set(agents.map(skillTargetDir))];
+    let changed = false;
+    for (const targetDir of targetDirs) {
+        try {
+            changed = writeSkillDir(sourceDir, targetDir) || changed;
+        }
+        catch (error) {
+            throw skillWriteError(error, targetDir);
+        }
+    }
+    return changed;
+}
+function writeSkillDir(sourceDir, targetDir) {
+    const parent = path.dirname(targetDir);
+    fs.mkdirSync(parent, { recursive: true });
+    sweepStaleStaging(parent);
+    if (matchesSource(sourceDir, targetDir))
+        return false;
+    // Stage-then-swap: an early rm would strand the user skill-less on failure.
+    const stagingDir = path.join(parent, `${WEB_SKILL_NAME}.tmp-${process.pid}`);
+    fs.rmSync(stagingDir, { recursive: true, force: true });
+    fs.mkdirSync(stagingDir);
+    for (const name of fs.readdirSync(sourceDir)) {
+        fs.copyFileSync(path.join(sourceDir, name), path.join(stagingDir, name));
+    }
+    swapIntoPlace(stagingDir, targetDir, sourceDir);
+    return true;
+}
+// The old copy survives as a sibling backup until the new dir lands.
+function swapIntoPlace(stagingDir, targetDir, sourceDir) {
+    const backupDir = moveAsideExisting(targetDir);
+    try {
+        try {
+            fs.renameSync(stagingDir, targetDir);
+        }
+        catch (error) {
+            // A concurrent connect can recreate the target mid-swap.
+            if (!isErrnoCode(error, 'ENOTEMPTY') && !isErrnoCode(error, 'EEXIST'))
+                throw error;
+            if (matchesSource(sourceDir, targetDir)) {
+                // The concurrent writer already landed these bytes; ours can go.
+                fs.rmSync(stagingDir, { recursive: true, force: true });
+            }
+            else {
+                removeExistingEntry(targetDir);
+                fs.renameSync(stagingDir, targetDir);
+            }
+        }
+    }
+    catch (error) {
+        fs.rmSync(stagingDir, { recursive: true, force: true });
+        restoreBackup(backupDir, targetDir);
+        throw error;
+    }
+    if (backupDir)
+        removeExistingEntry(backupDir);
+}
+// Sweep-prefixed name, so an orphaned backup is eventually cleaned.
+function moveAsideExisting(targetDir) {
+    try {
+        fs.lstatSync(targetDir);
+    }
+    catch {
+        return null;
+    }
+    const backupDir = `${targetDir}.tmp-${process.pid}-prev`;
+    removeExistingEntry(backupDir);
+    fs.renameSync(targetDir, backupDir);
+    return backupDir;
+}
+function restoreBackup(backupDir, targetDir) {
+    if (!backupDir)
+        return;
+    try {
+        fs.renameSync(backupDir, targetDir);
+    }
+    catch {
+        // A concurrent writer owns the target now; leave its copy in place.
+    }
+}
+/** Only a real dir with the bundle's exact file set and bytes skips. */
+function matchesSource(sourceDir, targetDir) {
+    let stat;
+    try {
+        stat = fs.lstatSync(targetDir);
+    }
+    catch {
+        return false;
+    }
+    if (!stat.isDirectory())
+        return false;
+    const sourceFiles = fs.readdirSync(sourceDir).sort();
+    const targetFiles = fs.readdirSync(targetDir).sort();
+    if (sourceFiles.join('\n') !== targetFiles.join('\n'))
+        return false;
+    return sourceFiles.every((name) => fs.readFileSync(path.join(sourceDir, name)).equals(fs.readFileSync(path.join(targetDir, name))));
+}
+/** lstat first: a skills-CLI symlink must be unlinked, never followed. */
+function removeExistingEntry(targetDir) {
+    let stat;
+    try {
+        stat = fs.lstatSync(targetDir);
+    }
+    catch {
+        return;
+    }
+    if (stat.isDirectory()) {
+        fs.rmSync(targetDir, { recursive: true });
+        return;
+    }
+    try {
+        fs.unlinkSync(targetDir);
+    }
+    catch (error) {
+        // Windows junctions: unlink is EPERM there, rmdir removes the link.
+        if (isErrnoCode(error, 'EPERM') || isErrnoCode(error, 'EISDIR'))
+            fs.rmdirSync(targetDir);
+        else
+            throw error;
+    }
+}
+function sweepStaleStaging(parent) {
+    let entries;
+    try {
+        entries = fs.readdirSync(parent);
+    }
+    catch {
+        return;
+    }
+    for (const name of entries) {
+        if (!name.startsWith(`${WEB_SKILL_NAME}.tmp-`))
+            continue;
+        try {
+            const staged = path.join(parent, name);
+            if (Date.now() - fs.lstatSync(staged).mtimeMs < STAGING_SWEEP_MIN_AGE_MS)
+                continue;
+            fs.rmSync(staged, { recursive: true, force: true });
+        }
+        catch {
+            // Best effort; a sweep failure must never fail the install.
+        }
+    }
+}
+// Reason stays in the closed enum; the errno rides failure_detail instead.
+function skillWriteError(error, targetDir) {
+    const code = error?.code ?? 'unknown';
+    return new ConnectStepError('Could not write the TinyFish web skill', 'unexpected_error', {
+        cause: error,
+        failureDetail: `skill_write_failed ${code} ${targetDir}`.slice(0, FAILURE_DETAIL_MAX_CHARS),
+    });
+}
+function isErrnoCode(error, code) {
+    return error?.code === code;
+}
+/** Best effort: a lock cleanup failure must never fail an install. */
+export function clearSkillLockEntry(opts) {
+    const lockPath = skillLockPath();
+    try {
+        const lock = JSON.parse(fs.readFileSync(lockPath, 'utf8'));
+        if (!lock.skills || !(WEB_SKILL_NAME in lock.skills))
+            return;
+        delete lock.skills[WEB_SKILL_NAME];
+        fs.writeFileSync(lockPath, `${JSON.stringify(lock, null, 2)}\n`);
+    }
+    catch {
+        if (opts?.verbose)
+            errLine('Skipped cleaning the skills lock file.');
+    }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tiny-fish/cli",
-  "version": "0.41.2-next.327",
+  "version": "0.41.2-next.329",
   "description": "TinyFish CLI — run web automations from your terminal",
   "type": "module",
   "bin": {
@@ -8,6 +8,7 @@
   },
   "files": [
     "dist/",
+    "skill/",
     "README.md",
     "LICENSE"
   ],

package/skill/.source-commit

@@ -0,0 +1 @@
+8615317f6db58ae776dd53817ac30668c1db5ef8

package/skill/use-tinyfish/SKILL.md

@@ -0,0 +1,216 @@
+---
+name: use-tinyfish
+description: Use TinyFish for web search, fetching URLs, reading pages, current information, source-backed answers, research, docs, pricing/product pages, extraction, scraping, and browser automation. Use whenever the user asks to search, find, look up, research, compare, get information from the web, summarize a URL, fetch page content, or automate a website.
+---
+
+# TinyFish CLI
+
+You have access to the TinyFish CLI (`tinyfish`) — a suite of web tools you can call from the terminal.
+
+If not installed: `npm install -g @tiny-fish/cli`
+If not authenticated: `tinyfish auth login --source openclaw` or set `TINYFISH_API_KEY` env var.
+
+---
+
+## When This Skill Should Trigger
+
+Use TinyFish whenever a request depends on live web information or page content. Do not wait for the user to say "TinyFish" or "scrape".
+
+Strong triggers include:
+
+- Search or discovery: search, find, look up, research, compare, latest, current, news, docs, pricing, product details, best options.
+- URL/page reading: fetch, read, summarize, extract from this page, inspect this URL, get the content, pull links or metadata.
+- Source-backed answers: answer using web sources, verify a fact, check whether something changed, gather information from the web.
+- Website work: interact with a site, click through pages, fill forms, log in, collect structured data, handle bot-protected pages.
+
+Default to the lightest tool that can answer:
+
+- No URL and the user needs web information: `search`, then `fetch` the best result(s) if more detail is needed.
+- URL provided and only content is needed: `fetch`.
+- Page interaction or dynamic extraction is needed: `agent`.
+- Raw CDP/Playwright-style control is needed: `browser`.
+
+---
+
+## Picking the Right Tool
+
+TinyFish has four tools. Start with the lightest one that can do the job and escalate only when needed.
+
+```
+search  →  fetch  →  agent  →  browser
+lightest                        heaviest
+```
+
+| Tool | When to use | Speed | Cost |
+|------|-------------|-------|------|
+| **search** | You need to find URLs, current facts, docs, pricing, product details, or a quick source-backed answer | Fastest | Lowest |
+| **fetch** | You have URLs and need clean page content, summaries, article text, docs, product pages, links, or metadata | Fast | Low |
+| **agent** | You need to interact with a page — click, fill forms, navigate, extract structured data from dynamic sites | Slower | Higher |
+| **browser** | Agent isn't enough — you need raw programmatic browser control via CDP | Slowest | Highest |
+
+### Common Patterns
+
+**Research: search → fetch**
+Search for a topic, then fetch the best results to read their full content.
+
+```bash
+# 1. Find URLs
+tinyfish search query "best React state management libraries 2026"
+
+# 2. Read the top results
+tinyfish fetch content get --format markdown "https://result1.com" "https://result2.com"
+```
+
+**Deep extraction: search → agent**
+Search to find the right site, then use agent to interact with it and extract structured data.
+
+```bash
+# 1. Find the site
+tinyfish search query "Nike running shoes official store"
+
+# 2. Automate extraction on it
+tinyfish agent run --url "https://nike.com/running" \
+  "Extract all running shoes as JSON: [{\"name\": str, \"price\": str, \"colors\": [str]}]"
+```
+
+**Escalation: fetch → agent**
+Try fetch first. If the page is dynamic/JS-heavy and fetch returns empty or incomplete content, escalate to agent.
+
+**Full control: agent → browser**
+If agent can't handle a complex multi-step workflow, spin up a raw browser session and automate it yourself via CDP.
+
+---
+
+## Commands
+
+### `tinyfish search query`
+
+Web search. Returns ranked results with titles, URLs, and snippets.
+
+```bash
+tinyfish search query "<query>" [--location <hint>] [--language <hint>] [--pretty]
+```
+
+- Returns 10 results by default
+- Use `--location` and `--language` for geo-targeted results
+- Default output is JSON; `--pretty` for human-readable
+
+```bash
+tinyfish search query "best pho in Ho Chi Minh City" --location "Vietnam" --language "en"
+```
+
+---
+
+### `tinyfish fetch content get`
+
+Fetch clean, extracted content from one or more URLs. Strips ads, nav, boilerplate — returns just the content.
+
+```bash
+tinyfish fetch content get <urls...> [--format markdown|html|json] [--links] [--image-links] [--pretty]
+```
+
+- Accepts **multiple URLs** in a single call — they are fetched in parallel server-side
+- `--format markdown` (default) — clean readable text
+- `--format json` — structured document tree
+- `--links` — include all extracted links from the page
+- `--image-links` — include extracted image URLs
+- Response includes: `url`, `final_url`, `title`, `language`, `author`, `published_date`, `text`, `latency_ms`
+
+```bash
+# Fetch one page as markdown
+tinyfish fetch content get --format markdown "https://example.com/article"
+
+# Fetch multiple pages with links
+tinyfish fetch content get --links "https://site-a.com" "https://site-b.com" "https://site-c.com"
+```
+
+---
+
+### `tinyfish agent run`
+
+Run a browser automation using a natural language goal. The agent opens a real browser, navigates, clicks, fills forms, and extracts data.
+
+```bash
+tinyfish agent run --url <url> "<goal>" [--sync] [--async] [--pretty]
+```
+
+| Flag | Purpose |
+|------|---------|
+| `--url <url>` | Target URL (bare hostnames get `https://` auto-prepended) |
+| `--sync` | Wait for full result without streaming steps |
+| `--async` | Submit and return immediately |
+| `--pretty` | Human-readable output |
+
+**Output:** Default streams `data: {...}` SSE lines. The final result is the event where `type == "COMPLETE"` and `status == "COMPLETED"` — the extracted data is in the `resultJson` field. Read the raw output directly; no script-side parsing is needed.
+
+**Always specify the JSON structure you want in the goal:**
+
+```bash
+tinyfish agent run --url "https://example.com/products" \
+  "Extract all products as JSON array: [{\"name\": str, \"price\": str, \"url\": str}]"
+
+tinyfish agent run --url "https://example.com/search" \
+  "Search for 'wireless headphones', filter under $50, extract top 5 as JSON: [{\"name\": str, \"price\": str, \"rating\": str}]"
+```
+
+**Parallel extraction — when hitting multiple independent sites, make separate calls. Do NOT combine into one goal.**
+
+Good — parallel calls (run simultaneously):
+```bash
+tinyfish agent run --url "https://pizzahut.com" \
+  "Extract pizza prices as JSON: [{\"name\": str, \"price\": str}]"
+
+tinyfish agent run --url "https://dominos.com" \
+  "Extract pizza prices as JSON: [{\"name\": str, \"price\": str}]"
+```
+
+Bad — single combined call:
+```bash
+# Don't do this — less reliable and slower
+tinyfish agent run --url "https://pizzahut.com" \
+  "Extract prices from Pizza Hut and also go to Dominos..."
+```
+
+**Managing runs:**
+
+```bash
+tinyfish agent run list [--status PENDING|RUNNING|COMPLETED|FAILED|CANCELLED] [--limit N]
+tinyfish agent run get <run_id>
+tinyfish agent run cancel <run_id>
+```
+
+**Batch operations** — submit many runs from a CSV file (`url,goal` columns):
+
+```bash
+tinyfish agent batch run --input runs.csv
+tinyfish agent batch list
+tinyfish agent batch get <batch_id>
+tinyfish agent batch cancel <batch_id>
+```
+
+---
+
+### `tinyfish browser session create`
+
+Spin up a remote browser instance. Returns a CDP WebSocket URL for programmatic control.
+
+```bash
+tinyfish browser session create [--url <url>] [--pretty]
+```
+
+- `--url` optionally navigates to a page after creation
+- Returns `session_id`, `cdp_url` (WebSocket), and `base_url`
+- Use the `cdp_url` with Playwright, Puppeteer, or any CDP client
+
+```bash
+tinyfish browser session create --url "https://example.com"
+# Returns: { session_id, cdp_url: "wss://...", base_url: "https://..." }
+```
+
+---
+
+## General Notes
+
+- **Match the user's language**: Respond in whatever language the user writes in.
+- All commands support `--pretty` for human-readable output. Default is JSON.
+- Use `--debug` on the root command or set `TINYFISH_DEBUG=1` to log HTTP requests to stderr.