@sayknow-cli/coding-agent 0.3.1 → 0.3.4

package/dist/types/web/search/index.d.ts

@@ -111,5 +111,6 @@ export declare class WebSearchTool implements AgentTool<typeof webSearchSchema,
 export declare const webSearchCustomTool: CustomTool<typeof webSearchSchema, SearchRenderDetails>;
 export declare function getSearchTools(): CustomTool<any, any>[];
 export { getSearchProvider, setPreferredSearchProvider, setSearchFallbackProviders } from "./provider";
+export { setSearchHardTimeoutMs } from "./providers/utils";
 export type { SearchProviderId as SearchProvider, SearchResponse } from "./types";
 export { isConfigurableSearchProviderId, isSearchProviderPreference } from "./types";

package/dist/types/web/search/providers/utils.d.ts

@@ -15,16 +15,23 @@ import { SearchProviderError, type SearchProviderId, type SearchSource } from ".
  */
 export declare function findCredential(storage: AgentStorage | null | undefined, envKey: string | null | undefined, ...storageProviders: string[]): string | null;
 /**
- * Default hard ceiling for a single web-search round-trip. 60s tolerates
+ * Default hard ceiling for a single web-search round-trip. 300s tolerates
  * legitimate slow LLM-mediated responses (anthropic web_search_20250305,
  * perplexity, gemini, OpenAI code backend) while still guaranteeing the session unfreezes
- * within a minute if Bun's `AbortSignal` fails to propagate on Windows.
+ * if Bun's `AbortSignal` fails to propagate on Windows.
  *
  * Pure search APIs (brave, exa, jina, tavily, searxng, synthetic, zai)
  * settle far faster in practice; reusing the same ceiling keeps the wiring
  * uniform without compromising correctness.
  */
-export declare const SEARCH_HARD_TIMEOUT_MS = 60000;
+export declare const SEARCH_HARD_TIMEOUT_MS = 300000;
+/**
+ * Override the hard timeout applied to every web-search round-trip.
+ *
+ * @param ms - Hard timeout in milliseconds. Non-finite or non-positive
+ *   values reset the timeout to {@link SEARCH_HARD_TIMEOUT_MS}.
+ */
+export declare function setSearchHardTimeoutMs(ms: number | undefined): void;
 /**
  * Compose a caller-supplied {@link AbortSignal} with a hard timeout so an
  * outbound `fetch()` is guaranteed to settle within `ms` even when the
@@ -36,7 +43,7 @@ export declare const SEARCH_HARD_TIMEOUT_MS = 60000;
  * because the user's Esc is never delivered to the native layer.
  *
  * @param signal - Caller cancellation signal, if any.
- * @param ms - Hard timeout in milliseconds. Defaults to {@link SEARCH_HARD_TIMEOUT_MS}.
+ * @param ms - Hard timeout in milliseconds. Defaults to the configured value.
  */
 export declare function withHardTimeout(signal: AbortSignal | undefined, ms?: number): AbortSignal;
 /**

package/package.json

@@ -1,7 +1,7 @@
 {
 	"type": "module",
 	"name": "@sayknow-cli/coding-agent",
-	"version": "0.3.1",
+	"version": "0.3.4",
 	"description": "Sayknow-CLI CLI with read, bash, edit, write tools and session management",
 	"homepage": "https://github.com/jaybeyond/Sayknow_CLI",
 	"author": "jaybeyond",
@@ -28,7 +28,7 @@
 	"main": "./src/index.ts",
 	"types": "./dist/types/index.d.ts",
 	"bin": {
-		"skc": "src/cli.ts"
+		"skc": "bin/skc.js"
 	},
 	"scripts": {
 		"build": "bun scripts/build-binary.ts",
@@ -52,12 +52,12 @@
 		"@agentclientprotocol/sdk": "0.21.0",
 		"@babel/parser": "^7.29.3",
 		"@mozilla/readability": "^0.6.0",
-		"@sayknow-cli/stats": "0.3.1",
-		"@sayknow-cli/agent-core": "0.3.1",
-		"@sayknow-cli/ai": "0.3.1",
-		"@sayknow-cli/natives": "0.3.1",
-		"@sayknow-cli/tui": "0.3.1",
-		"@sayknow-cli/utils": "0.3.1",
+		"@sayknow-cli/stats": "0.3.4",
+		"@sayknow-cli/agent-core": "0.3.4",
+		"@sayknow-cli/ai": "0.3.4",
+		"@sayknow-cli/natives": "0.3.4",
+		"@sayknow-cli/tui": "0.3.4",
+		"@sayknow-cli/utils": "0.3.4",
 		"@puppeteer/browsers": "^2.13.0",
 		"@types/turndown": "5.0.6",
 		"@xterm/headless": "^6.0.0",
@@ -74,13 +74,15 @@
 		"zod": "4.4.3"
 	},
 	"devDependencies": {
-		"@types/bun": "^1.3.14"
+		"@types/bun": "^1.3.14",
+		"@types/ws": "^8.5.13"
 	},
 	"engines": {
 		"bun": ">=1.3.14"
 	},
 	"files": [
 		"src",
+		"bin",
 		"scripts",
 		"examples",
 		"README.md",

package/scripts/g004-tmux-smoke.ts

@@ -0,0 +1,100 @@
+// G004 real-tmux smoke: exercises forceCloseSkcTmuxSession against LIVE tmux
+// sessions (tmux 3.6a). Proves the wrapper hard-kills SKC-managed live panes
+// (where remove refuses), refuses non-SKC sessions, and enforces session-id
+// matching. Produces durable evidence; not part of the unit suite.
+import assert from "node:assert";
+
+import {
+	buildSkcTmuxExactOptionTarget,
+	buildSkcTmuxProfileCommands,
+	resolveSkcTmuxCommand,
+} from "../src/skc-runtime/tmux-common";
+import { forceCloseSkcTmuxSession, removeSkcTmuxSession, statusSkcTmuxSession } from "../src/skc-runtime/tmux-sessions";
+
+const tmux = resolveSkcTmuxCommand(process.env);
+
+function sh(args: string[]): { code: number; err: string } {
+	const r = Bun.spawnSync([tmux, ...args], { stdout: "pipe", stderr: "pipe" });
+	return { code: r.exitCode, err: r.stderr.toString().trim() };
+}
+
+function makeRawSession(name: string): void {
+	const r = sh(["new-session", "-d", "-s", name, "sleep 600"]);
+	if (r.code !== 0) throw new Error(`failed to create tmux session ${name}: ${r.err}`);
+}
+
+function tagAsSkc(name: string, sessionId?: string): void {
+	const target = buildSkcTmuxExactOptionTarget(name);
+	for (const cmd of buildSkcTmuxProfileCommands(target, process.env, { sessionId })) {
+		const r = sh(cmd.args);
+		if (r.code !== 0) throw new Error(`failed to tag ${name} (${cmd.description}): ${r.err}`);
+	}
+}
+
+function exists(name: string): boolean {
+	return sh(["has-session", "-t", `=${name}`]).code === 0;
+}
+
+function killQuiet(name: string): void {
+	sh(["kill-session", "-t", `=${name}`]);
+}
+
+const suffix = `${process.pid}-${Date.now()}`;
+const live = `skc_g004live_${suffix}`;
+const raw = `g004raw_${suffix}`;
+const mism = `skc_g004mism_${suffix}`;
+const cleanup: string[] = [live, raw, mism];
+
+try {
+	// 1. SKC-managed LIVE session: remove refuses, force-close hard-kills.
+	makeRawSession(live);
+	tagAsSkc(live, "sess-g004");
+	const status = statusSkcTmuxSession(live);
+	assert.equal(status.profile, "1", "session must be recognized as SKC-managed");
+	assert.ok(status.panePids.length > 0, "session must have a live pane (sleep)");
+	console.log(`[g004] live SKC session up: ${live} panePids=${status.panePids.length}`);
+
+	let removeRefused = false;
+	try {
+		removeSkcTmuxSession(live);
+	} catch (e) {
+		removeRefused = /skc_tmux_session_live/.test(String(e));
+	}
+	assert.ok(removeRefused, "removeSkcTmuxSession must REFUSE a live pane");
+	console.log("[g004] remove refused live session (expected)");
+
+	const closed = forceCloseSkcTmuxSession(live, process.env, "sess-g004");
+	assert.equal(closed.name, live);
+	assert.ok(!exists(live), "force-close must hard-kill the live SKC session");
+	console.log("[g004] force-close hard-killed the live SKC session (id-matched)");
+
+	// 2. Non-SKC (untagged) session: force-close must refuse.
+	makeRawSession(raw);
+	let notManaged = false;
+	try {
+		forceCloseSkcTmuxSession(raw, process.env);
+	} catch (e) {
+		notManaged = /skc_tmux_session_(not_managed|not_found)/.test(String(e));
+	}
+	assert.ok(notManaged, "force-close must refuse a non-SKC tmux session");
+	assert.ok(exists(raw), "non-SKC session must be left untouched");
+	killQuiet(raw);
+	console.log("[g004] force-close refused + preserved non-SKC session (expected)");
+
+	// 3. SKC session with a MISMATCHED expected session id: must refuse.
+	makeRawSession(mism);
+	tagAsSkc(mism, "sess-real");
+	let idMismatch = false;
+	try {
+		forceCloseSkcTmuxSession(mism, process.env, "sess-WRONG");
+	} catch (e) {
+		idMismatch = /skc_tmux_session_id_mismatch/.test(String(e));
+	}
+	assert.ok(idMismatch, "force-close must refuse on session-id mismatch");
+	assert.ok(exists(mism), "mismatched session must be left untouched");
+	console.log("[g004] force-close refused on session-id mismatch (expected)");
+
+	console.log("[g004] PASS: forceCloseSkcTmuxSession verified against live tmux");
+} finally {
+	for (const name of cleanup) killQuiet(name);
+}

package/scripts/g005-daemon-smoke.ts

@@ -0,0 +1,180 @@
+// G005 real end-to-end daemon-orchestration smoke.
+//
+// Drives the lifecycle orchestrator's create -> close path with REAL effects:
+// a real fsynced file-backed idempotency ledger, a real audit JSONL, and a real
+// tmux session spawned/closed via the actual tmux helpers. Proves the daemon
+// orchestration turns a `session_create` frame into a genuinely-spawned,
+// SKC-tagged tmux session and a `session_close` frame into a real hard-close,
+// with idempotent re-ack. Not part of the unit suite.
+import assert from "node:assert";
+import * as crypto from "node:crypto";
+import * as fs from "node:fs";
+import * as os from "node:os";
+import * as path from "node:path";
+import type { SessionCloseFrame, SessionCreateFrame } from "../src/notifications/index";
+import {
+	type AuditEvent,
+	handleLifecycleRequest,
+	type LedgerDoc,
+	type LedgerStore,
+	type OrchestratorDeps,
+} from "../src/notifications/lifecycle-orchestrator";
+import {
+	buildSkcTmuxExactOptionTarget,
+	buildSkcTmuxProfileCommands,
+	resolveSkcTmuxCommand,
+} from "../src/skc-runtime/tmux-common";
+import { forceCloseSkcTmuxSession, statusSkcTmuxSession } from "../src/skc-runtime/tmux-sessions";
+
+const tmux = resolveSkcTmuxCommand(process.env);
+const tmpRoot = fs.mkdtempSync(path.join(os.tmpdir(), "skc-g005-"));
+const ledgerPath = path.join(tmpRoot, "idempotency.json");
+const auditPath = path.join(tmpRoot, "audit.jsonl");
+const created: string[] = [];
+
+function sh(args: string[]): number {
+	return Bun.spawnSync([tmux, ...args], { stdout: "pipe", stderr: "pipe" }).exitCode;
+}
+function exists(name: string): boolean {
+	return sh(["has-session", "-t", `=${name}`]) === 0;
+}
+
+// Real fsynced + atomic file ledger store.
+const store: LedgerStore = {
+	async read(): Promise<LedgerDoc> {
+		try {
+			return JSON.parse(fs.readFileSync(ledgerPath, "utf8")) as LedgerDoc;
+		} catch {
+			return { version: 1, entries: {} };
+		}
+	},
+	async write(doc: LedgerDoc): Promise<void> {
+		const tmp = `${ledgerPath}.${process.pid}.tmp`;
+		const fd = fs.openSync(tmp, "w", 0o600);
+		fs.writeSync(fd, JSON.stringify(doc));
+		fs.fsyncSync(fd);
+		fs.closeSync(fd);
+		fs.renameSync(tmp, ledgerPath);
+	},
+};
+
+const auditLines: AuditEvent[] = [];
+const deps: OrchestratorDeps = {
+	pairedChatId: "42",
+	now: () => Date.now(),
+	store,
+	audit: e => {
+		auditLines.push(e);
+		fs.appendFileSync(auditPath, `${JSON.stringify(e)}\n`, { mode: 0o600 });
+	},
+	allowCreate: () => true,
+	writeStartupPrompt: async (requestId, prompt) => {
+		if (prompt === undefined) return undefined;
+		const ref = path.join(tmpRoot, `prompt-${requestId}`);
+		const fd = fs.openSync(ref, "w", 0o600);
+		fs.writeSync(fd, prompt);
+		fs.fsyncSync(fd);
+		fs.closeSync(fd);
+		return ref;
+	},
+	// REAL spawn: create a SKC-tagged tmux session carrying the authoritative id.
+	spawnCreate: async (_frame, ids) => {
+		const name = `skc_g005_${ids.intendedSessionId}`;
+		created.push(name);
+		if (sh(["new-session", "-d", "-s", name, "sleep 600"]) !== 0) {
+			throw new Error(`tmux spawn failed for ${name}`);
+		}
+		const target = buildSkcTmuxExactOptionTarget(name);
+		for (const cmd of buildSkcTmuxProfileCommands(target, process.env, {
+			sessionId: ids.intendedSessionId,
+		})) {
+			if (sh(cmd.args) !== 0) throw new Error(`tag failed for ${name}`);
+		}
+		return {
+			sessionId: ids.intendedSessionId,
+			tmuxSession: name,
+			endpointUrl: "ws://127.0.0.1:0",
+			topicThreadId: "1",
+		};
+	},
+	// REAL close: hard-close the SKC-managed tmux session, id-matched.
+	closeSession: async target => {
+		forceCloseSkcTmuxSession(target.tmuxSession ?? "", process.env, target.sessionId);
+		return { processGone: !exists(target.tmuxSession ?? "") };
+	},
+	resumeSession: async () => ({ ambiguous: [] }),
+	newLifecycleRequestId: () => `lc-${crypto.randomUUID()}`,
+	newSessionId: () => `s${crypto.randomUUID().slice(0, 8)}`,
+};
+
+const createFrame: SessionCreateFrame = {
+	type: "session_create",
+	requestId: "lc_g005",
+	lifecycleRequestId: "lc_g005",
+	intendedSessionId: `g005${Date.now().toString(36)}`,
+	updateId: 100,
+	chatId: "42",
+	token: "control-token",
+	target: { kind: "existing_path", path: tmpRoot },
+};
+
+async function main(): Promise<void> {
+	// 1. CREATE -> real tmux session spawned + SKC-tagged with the authoritative id.
+	const createOut = await handleLifecycleRequest(createFrame, deps);
+	assert.equal(createOut.status, "ok", "create must succeed");
+	const session = createOut.status === "ok" ? createOut.entry.tmuxSession! : "";
+	assert.ok(exists(session), "real tmux session must exist after create");
+	const status = statusSkcTmuxSession(session);
+	assert.equal(status.profile, "1", "spawned session must be SKC-managed");
+	assert.equal(status.sessionId, createFrame.intendedSessionId, "authoritative session id propagated to tmux tag");
+	console.log(`[g005] CREATE -> live tmux session ${session} (id=${status.sessionId})`);
+
+	// 2. Idempotent re-ack: same updateId+body must NOT spawn a second session.
+	const before = created.length;
+	const dupOut = await handleLifecycleRequest(createFrame, deps);
+	assert.equal(dupOut.status, "ok", "duplicate create re-acks ok");
+	assert.equal(created.length, before, "duplicate create must NOT spawn a second session");
+	console.log("[g005] DUPLICATE create re-acked, no second spawn (idempotent)");
+
+	// 3. CLOSE -> real hard-close of the SKC-managed session, id-matched.
+	const closeFrame: SessionCloseFrame = {
+		type: "session_close",
+		requestId: "lc_g005_close",
+		updateId: 101,
+		chatId: "42",
+		token: "control-token",
+		target: { sessionId: createFrame.intendedSessionId, tmuxSession: session },
+		force: true,
+	};
+	const closeOut = await handleLifecycleRequest(closeFrame, deps);
+	assert.equal(closeOut.status, "ok", "close must succeed");
+	assert.ok(!exists(session), "real tmux session must be gone after close");
+	console.log(`[g005] CLOSE -> hard-closed ${session} (id-matched)`);
+
+	// 4. Durable ledger + audit redaction.
+	const doc = JSON.parse(fs.readFileSync(ledgerPath, "utf8")) as LedgerDoc;
+	assert.equal(doc.entries["42:100"]?.state, "success");
+	assert.equal(doc.entries["42:101"]?.state, "success");
+	const auditBlob = fs.readFileSync(auditPath, "utf8");
+	assert.ok(!auditBlob.includes("control-token"), "audit must never contain the control token");
+	assert.ok(
+		auditLines.some(a => a.event === "spawn_started"),
+		"audit records spawn_started",
+	);
+	console.log("[g005] durable fsynced ledger + token-redacted audit verified");
+
+	console.log("[g005] PASS: real create->close daemon orchestration over live tmux");
+}
+
+main()
+	.then(() => {
+		for (const n of created) sh(["kill-session", "-t", `=${n}`]);
+		fs.rmSync(tmpRoot, { recursive: true, force: true });
+		process.exit(0);
+	})
+	.catch(err => {
+		for (const n of created) sh(["kill-session", "-t", `=${n}`]);
+		fs.rmSync(tmpRoot, { recursive: true, force: true });
+		console.error("[g005] FAIL", err);
+		process.exit(1);
+	});

package/scripts/g011-daemon-path-smoke.ts

@@ -0,0 +1,153 @@
+// G011 real daemon-path smoke.
+//
+// Drives a PARSED /session_* command through the LIVE native
+// NotificationControlServer + a real loopback WebSocket client (NO injected/fake
+// seams), wired to the real orchestrator (with stubbed spawn/close effects so the
+// focus is the authenticated wire path, not tmux). Asserts:
+//  - a wrong-token handshake is rejected (control token gates the endpoint);
+//  - a valid frame is forwarded with the control token STRIPPED from payloadJson;
+//  - the host response is routed back to the client by requestId;
+//  - control discovery exists while running and is removed after stop.
+import assert from "node:assert";
+import * as crypto from "node:crypto";
+import * as fs from "node:fs";
+import * as os from "node:os";
+import * as path from "node:path";
+import WebSocket from "ws";
+
+// Import the WORKTREE native build directly (not @sayknow-cli/natives, which can
+// resolve to a different checkout in this dev environment).
+import { NotificationControlServer } from "../../natives/native/index.js";
+import { parseLifecycleCommand } from "../src/notifications/lifecycle-commands";
+import { attachLifecycleControl, fileAudit, fileLedgerStore } from "../src/notifications/lifecycle-control-runtime";
+import type { OrchestratorDeps } from "../src/notifications/lifecycle-orchestrator";
+
+const tmp = fs.mkdtempSync(path.join(os.tmpdir(), "skc-g011-"));
+const token = crypto.randomBytes(32).toString("base64url");
+const ownerId = "daemon-g011";
+const closed: string[] = [];
+
+function deps(): OrchestratorDeps {
+	return {
+		pairedChatId: "42",
+		now: () => Date.now(),
+		store: fileLedgerStore(path.join(tmp, "idempotency.json")),
+		audit: fileAudit(path.join(tmp, "audit.jsonl")),
+		allowCreate: () => true,
+		writeStartupPrompt: async () => undefined,
+		// Stubbed effects: this smoke proves the WIRE path, not tmux (covered by g005).
+		spawnCreate: async (_f, ids) => ({
+			sessionId: ids.intendedSessionId,
+			tmuxSession: `skc-${ids.intendedSessionId}`,
+			endpointUrl: "ws://127.0.0.1:0",
+			topicThreadId: "1",
+		}),
+		closeSession: async t => {
+			closed.push(t.sessionId);
+			return { processGone: true };
+		},
+		resumeSession: async () => ({ ambiguous: [] }),
+		newLifecycleRequestId: () => `lc-${crypto.randomUUID()}`,
+		newSessionId: () => `s${crypto.randomUUID().slice(0, 8)}`,
+	};
+}
+
+function send(ws: WebSocket, frame: unknown): void {
+	ws.send(JSON.stringify(frame));
+}
+
+async function main(): Promise<void> {
+	const server = new NotificationControlServer(token, ownerId, tmp);
+
+	// Wire the real orchestrator to the real native control server.
+	const d = deps();
+	attachLifecycleControl(server as never, d);
+
+	const ep = (await server.start()) as { url: string };
+	assert.ok(ep.url.startsWith("ws://127.0.0.1:"), `loopback url, got ${ep.url}`);
+	const controlJson = path.join(tmp, "notifications", "control.json");
+	assert.ok(fs.existsSync(controlJson), "control discovery must exist while running");
+	// The control discovery file MUST NOT persist the privileged control token:
+	// the daemon holds it in memory and is the only client.
+	const controlRaw = fs.readFileSync(controlJson, "utf8");
+	assert.ok(!controlRaw.includes(token), "control token MUST NOT be persisted in control.json");
+	assert.ok(
+		!("token" in (JSON.parse(controlRaw) as Record<string, unknown>)),
+		"control.json must omit any token field",
+	);
+	console.log(`[g011] live control endpoint ${ep.url}; discovery present, no persisted token`);
+
+	// 1. Wrong-token handshake must be rejected.
+	await new Promise<void>(resolve => {
+		const bad = new WebSocket(`${ep.url}/?token=wrong`);
+		bad.on("open", () => {
+			throw new Error("wrong-token handshake must NOT open");
+		});
+		bad.on("error", () => {
+			console.log("[g011] wrong-token handshake rejected (expected)");
+			resolve();
+		});
+	});
+
+	// 2. Valid client: send a PARSED /session_close command through the real wire.
+	const parsed = parseLifecycleCommand("/session_close sess-g011");
+	assert.equal(parsed.kind, "close", "parser must yield a close command");
+	const requestId = "lc-g011-1";
+	const frame = {
+		type: "session_close",
+		requestId,
+		updateId: 1,
+		chatId: "42",
+		token,
+		target: parsed.kind === "close" ? parsed.target : { sessionId: "sess-g011" },
+		force: true,
+	};
+
+	const response = await new Promise<Record<string, unknown>>((resolve, reject) => {
+		const ws = new WebSocket(`${ep.url}/?token=${token}`);
+		const timer = setTimeout(() => reject(new Error("timed out")), 5000);
+		ws.on("open", () => send(ws, frame));
+		ws.on("message", data => {
+			clearTimeout(timer);
+			ws.close();
+			resolve(JSON.parse(String(data)) as Record<string, unknown>);
+		});
+		ws.on("error", reject);
+	});
+
+	assert.equal(response.type, "session_close_response", "response routed back to client");
+	assert.equal(response.requestId, requestId, "response correlated by requestId");
+	assert.equal(response.sessionId, "sess-g011");
+	assert.deepEqual(closed, ["sess-g011"], "orchestrator close effect ran exactly once");
+	console.log("[g011] parsed command -> real wire -> orchestrator -> routed response OK");
+
+	// 3. The real orchestrator path must NOT leak the control token into its
+	// durable audit log or idempotency ledger (g002 separately proves the native
+	// payloadJson boundary is token-stripped).
+	for (const f of ["audit.jsonl", "idempotency.json"]) {
+		const p = path.join(tmp, f);
+		if (fs.existsSync(p)) {
+			assert.ok(!fs.readFileSync(p, "utf8").includes(token), `control token leaked into ${f}`);
+		}
+	}
+	console.log("[g011] no control-token leak in audit/ledger on the real path");
+
+	// 4. Stop removes control discovery.
+	server.stop();
+	await new Promise(r => setTimeout(r, 50));
+	assert.ok(!fs.existsSync(controlJson), "control discovery removed after stop");
+	console.log("[g011] control discovery removed after stop");
+
+	console.log("[g011] PASS: real daemon-path (parse -> native control endpoint -> orchestrator -> reply)");
+}
+
+main()
+	.then(() => {
+		fs.rmSync(tmp, { recursive: true, force: true });
+		process.exit(0);
+	})
+	.catch(err => {
+		fs.rmSync(tmp, { recursive: true, force: true });
+		console.error("[g011] FAIL", err);
+		process.exit(1);
+	});

package/src/cli/args.ts

@@ -284,7 +284,6 @@ ${chalk.bold("Available Tools (default-enabled unless noted):")}
   lsp           - Language server protocol (code intelligence)
   python        - Execute Python code (requires: ${APP_NAME} setup python)
   notebook      - Edit Jupyter notebooks
-  inspect_image - Analyze images with a vision model
   browser       - Browser automation (Puppeteer)
   task          - Launch sub-agents for parallel tasks
   todo_write    - Manage todo/task lists

package/src/cli/fast-help.ts

@@ -1,7 +1,35 @@
 import { APP_NAME, CONFIG_DIR_NAME } from "@sayknow-cli/utils/dirs";
 
 export function getExtraHelpText(): string {
-	return `Environment Variables:
+	return `Commands:
+  ${APP_NAME} [prompt]             - Start an interactive coding session (default launch command)
+  ${APP_NAME} launch               - Start an explicit launch/session workflow
+  ${APP_NAME} setup                - Install SKC defaults or optional dependencies
+  ${APP_NAME} session              - List, inspect, create, remove, or attach sessions
+  ${APP_NAME} state                - Inspect or manage persisted SKC state
+  ${APP_NAME} harness              - Run harness control-plane commands
+  ${APP_NAME} coordinator          - Manage coordinator/runtime coordination helpers
+  ${APP_NAME} team                 - Run tmux-backed coordinated execution
+  ${APP_NAME} ultragoal            - Run durable goal execution workflow
+  ${APP_NAME} ralplan              - Run consensus planning workflow
+  ${APP_NAME} deep-interview       - Run requirements interview workflow
+  ${APP_NAME} skills               - List/read embedded workflow skills
+  ${APP_NAME} config               - List, get, and set configuration values
+  ${APP_NAME} notify               - Send or test notifications
+  ${APP_NAME} daemon               - Manage background daemon helpers
+  ${APP_NAME} mcp                  - Manage MCP server registrations
+  ${APP_NAME} mcp-serve            - Serve the MCP integration endpoint
+  ${APP_NAME} contribute-pr        - Prepare contribution/PR workflow artifacts
+  ${APP_NAME} migrate              - Run migration helpers
+  ${APP_NAME} rlm                  - Run RLM helpers
+  ${APP_NAME} update               - Update SKC installation artifacts
+  ${APP_NAME} plugin               - Install, remove, and list plugins
+  ${APP_NAME} web-search           - Search the web from the CLI (alias: q)
+  ${APP_NAME} codex-native-hook    - Run Codex native hook integration
+  ${APP_NAME} gc                   - Run garbage-collection/cleanup helpers
+  ${APP_NAME} <command> --help     - Show command-specific help
+
+Environment Variables:
   # Core Providers
   ANTHROPIC_API_KEY          - Anthropic Claude models
   ANTHROPIC_OAUTH_TOKEN      - Anthropic OAuth (takes precedence over API key)
@@ -69,7 +97,6 @@ Available Tools (default-enabled unless noted):
   lsp           - Language server protocol (code intelligence)
   python        - Execute Python code (requires: ${APP_NAME} setup python)
   notebook      - Edit Jupyter notebooks
-  inspect_image - Analyze images with a vision model
   browser       - Browser automation (Puppeteer)
   task          - Launch sub-agents for parallel tasks
   todo_write    - Manage todo/task lists