@sayknow-cli/coding-agent 0.3.5 → 0.3.7

package/README.md

@@ -11,6 +11,82 @@ Package-specific references:
 - [DEVELOPMENT](./DEVELOPMENT.md)
 - [RenderMermaid guide](../../docs/render-mermaid.md)
 
+## External lifecycle notifications
+
+SKC already exposes public lifecycle events through the extension/hook event contract. External notification integrations for Discord, Hermes, clawhip, or similar channels should be opt-in and subscribe to these events instead of scraping transcripts or logs:
+
+- `turn_end` — a model/tool turn finished. The public payload is `{ type: "turn_end", turnIndex, message, toolResults }`.
+- `agent_end` — the agent loop for a submitted prompt reached a terminal boundary. The public payload is `{ type: "agent_end", messages }`.
+
+For simple local side effects that do not need a full extension, set the user-level `completion.notifyCommand`. SKC runs it on completed agent turns with `SKC_NOTIFICATION_*` environment variables (`SKC_NOTIFICATION_TITLE`, `SKC_NOTIFICATION_BODY`, `SKC_NOTIFICATION_JSON`, etc.); project settings cannot activate this command hook.
+
+```sh
+skc config set completion.notifyCommand 'cmux notify --title "$SKC_NOTIFICATION_TITLE" --body "$SKC_NOTIFICATION_BODY"'
+```
+
+When SKC runs inside a cmux terminal (`CMUX_WORKSPACE_ID` is set), SKC best-effort renames that cmux workspace to the current SKC session name (with a `SKC: ` prefix) — but only when the workspace still has its default title, so a name you pinned (or one set by a peer session sharing the workspace) is never overwritten. Opt out with `SKC_NO_CMUX_RENAME=1`.
+
+Windows Terminal may keep BEL (`[Console]::Write([char]7)`) silent depending on profile and system sound settings even when `notifications.terminalBell` is enabled. For an audible Windows completion beep, configure a user-level PowerShell command hook instead:
+
+```powershell
+skc config set completion.notifyCommand 'powershell.exe -NoProfile -Command "[Console]::Beep(880, 300)"'
+```
+
+`cmux notify` returning successfully means SKC handed the completion event to cmux. cmux may still suppress the native desktop banner when the app/window is focused, the emitting workspace is active, or the notification panel is open. In those cases, check cmux's notification panel or unread workspace state instead of treating the missing banner as a SKC delivery failure.
+
+Recommended external mapping:
+
+| Notification | Public event | Status guidance |
+|---|---|---|
+| Turn finished | `turn_end` | Use the handler's own sanitized status such as `"finished"`. |
+| Agent stopped/finished | `agent_end` | Treat as terminal for the prompt. |
+| Waiting/blocked/failed | `agent_end` plus a caller-supplied safe summary | Current lifecycle events do not expose a separate structured waiting/blocked reason; inspect only public-safe, integration-owned state. |
+
+Forward only a minimal, caller-sanitized payload. Do not include raw prompts, assistant transcripts, hidden prompts, tool outputs, raw logs, host paths, private config, webhook URLs, channel IDs, tokens, or secrets. A safe notification payload should be built by the extension/hook itself, for example:
+
+```ts
+import type { ExtensionAPI } from "@sayknow-cli/coding-agent";
+
+type PublicLifecycleNotification = {
+	type: "turn_end" | "agent_end";
+	status: "finished" | "stopped" | "failed" | "blocked" | "waiting";
+	turnIndex?: number;
+	timestamp: string;
+	summary: string;
+};
+
+export default function lifecycleNotifier(pi: ExtensionAPI) {
+	const enabled = process.env.SKC_LIFECYCLE_NOTIFY === "1";
+	if (!enabled) return;
+
+	const send = async (payload: PublicLifecycleNotification) => {
+		// POST to Discord/Hermes/clawhip here. Keep target URLs and channel IDs in
+		// private config or environment variables; never include them in payloads.
+	};
+
+	pi.on("turn_end", event =>
+		send({
+			type: "turn_end",
+			status: "finished",
+			turnIndex: event.turnIndex,
+			timestamp: new Date().toISOString(),
+			summary: "SKC turn finished",
+		}),
+	);
+
+	pi.on("agent_end", () =>
+		send({
+			type: "agent_end",
+			status: "stopped",
+			timestamp: new Date().toISOString(),
+			summary: "SKC prompt reached a terminal lifecycle boundary",
+		}),
+	);
+}
+```
+
+This is the supported repo-native lifecycle notification path. It is not Claude Code hook compatibility, and it remains disabled unless the user configures an extension/hook handler and private delivery target.
+
 ## Memory backends
 
 The agent supports three mutually-exclusive memory backends, selected via the `memory.backend` setting (Settings → Memory tab, or `~/.skc/config.yml`):

package/dist/types/capability/mcp.d.ts

@@ -7,6 +7,8 @@ export interface MCPServer {
     name: string;
     /** Whether this server is enabled (default: true) */
     enabled?: boolean;
+    /** Whether to connect automatically at session startup (default: true) */
+    autoload?: boolean;
     /** Connection timeout in milliseconds */
     timeout?: number;
     /** Command to run (for stdio transport) */

package/dist/types/cli/local-provider-smoke.d.ts

@@ -0,0 +1,59 @@
+import type { ModelsConfig } from "../config/models-config-schema";
+export interface LocalProviderSmokeCommandArgs {
+    model?: string;
+    modelsPath?: string;
+    timeoutMs?: number;
+    json?: boolean;
+    smoke?: boolean;
+}
+export interface LocalOpenAICompatConfig {
+    baseUrl: string;
+    apiKey?: string;
+}
+export type LocalProviderDiagnosticCheckName = "config" | "models" | "chat_stream";
+export type LocalProviderDiagnosticStatus = "ok" | "skipped" | "error";
+export type LocalProviderDiagnosticCategory = "auth" | "timeout" | "unreachable" | "not_ready" | "oom" | "malformed_response" | "http_error" | "configuration" | "empty_response";
+export interface LocalProviderDiagnosticCheck {
+    name: LocalProviderDiagnosticCheckName;
+    status: LocalProviderDiagnosticStatus;
+    message: string;
+    action?: string;
+    category?: LocalProviderDiagnosticCategory;
+    error?: string;
+    httpStatus?: number;
+}
+export interface LocalProviderSmokeResult {
+    ok: boolean;
+    baseUrl?: string;
+    model?: string;
+    message: string;
+    error?: string;
+    category?: LocalProviderDiagnosticCategory;
+    action?: string;
+}
+export interface LocalProviderDiscoveryResult {
+    ok: boolean;
+    provider: string;
+    baseUrl?: string;
+    models: string[];
+    message: string;
+    error?: string;
+    category?: LocalProviderDiagnosticCategory;
+    action?: string;
+}
+export interface LocalProviderStatusResult {
+    ok: boolean;
+    provider: "local";
+    baseUrl?: string;
+    model?: string;
+    models: string[];
+    checks: LocalProviderDiagnosticCheck[];
+    message: string;
+}
+export declare function getLocalOpenAICompatConfig(config: ModelsConfig | undefined): LocalOpenAICompatConfig | undefined;
+export declare function runLocalProviderDiscover(cmd: Omit<LocalProviderSmokeCommandArgs, "model" | "smoke">): Promise<LocalProviderDiscoveryResult>;
+export declare function runLocalProviderStatus(cmd: LocalProviderSmokeCommandArgs): Promise<LocalProviderStatusResult>;
+export declare function runLocalProviderSmoke(cmd: LocalProviderSmokeCommandArgs): Promise<LocalProviderSmokeResult>;
+export declare function runLocalProviderDiscoverCommand(cmd: Omit<LocalProviderSmokeCommandArgs, "model" | "smoke">): Promise<void>;
+export declare function runLocalProviderStatusCommand(cmd: LocalProviderSmokeCommandArgs): Promise<void>;
+export declare function runLocalProviderSmokeCommand(cmd: LocalProviderSmokeCommandArgs): Promise<void>;

package/dist/types/cli/notify-cli.d.ts

@@ -1,4 +1,4 @@
-import { Settings } from "../config/settings";
+import type { Settings } from "../config/settings";
 export type NotifyAction = "setup" | "status" | "daemon-internal";
 export interface NotifyCommandArgs {
     action: NotifyAction;

package/dist/types/cli/telegram-cli.d.ts

@@ -0,0 +1,13 @@
+/**
+ * `skc telegram` command handlers — start/status/env for the Telegram Remote
+ * integration, driven entirely by the `telegram.*` settings group.
+ */
+export type TelegramAction = "start" | "status" | "env" | "__gateway";
+export interface TelegramCommandArgs {
+    action: TelegramAction;
+    flags: {
+        json?: boolean;
+    };
+}
+export declare const TELEGRAM_ACTIONS: readonly TelegramAction[];
+export declare function runTelegramCommand(cmd: TelegramCommandArgs): Promise<void>;

package/dist/types/cli/update-cli.d.ts

@@ -5,6 +5,20 @@ export interface InstalledVersionVerification {
     path?: string;
     smokeTestFailed?: boolean;
     smokeTestOutput?: string;
+    cleanupWarning?: string;
+}
+export interface PackageManagerUpdateResult {
+    exitCode: number | null;
+    text: () => string;
+}
+export type PackageManagerUpdateRunner = (expectedVersion: string) => Promise<PackageManagerUpdateResult>;
+export interface PackageManagerUpdateOptions {
+    managerName: string;
+    expectedVersion: string;
+    runInstall: PackageManagerUpdateRunner;
+    verifyInstalledRuntime: (expectedVersion: string) => Promise<InstalledVersionVerification>;
+    printVerificationResult?: (expectedVersion: string) => Promise<void>;
+    printRecoveredVerification?: (expectedVersion: string) => void;
 }
 /** Paths and verifier used while replacing a downloaded binary update. */
 export interface BinaryReplacementOptions {
@@ -22,7 +36,14 @@ export declare function parseUpdateArgs(args: string[]): {
     force: boolean;
     check: boolean;
 } | undefined;
-export declare function resolveUpdateMethodForTest(ompPath: string, bunBinDir: string | undefined): "bun" | "binary";
+type PackageManagerTarget = {
+    manager: "npm";
+    packageName: string;
+};
+type PathPlatform = NodeJS.Platform;
+type PackageExists = (packageName: string, packageRoot: string) => boolean;
+export declare function resolveUpdateMethodForTest(ompPath: string, bunBinDir: string | undefined): "bun" | "npm" | "binary";
+export declare function resolveNpmManagedTargetForTest(ompPath: string, platform: PathPlatform, packageExists: PackageExists): PackageManagerTarget | undefined;
 export declare function formatBinaryDownloadFailureMessageForTest(binaryName: string, url: string, status: string | number, platform?: NodeJS.Platform): string;
 export declare function buildReleaseBinaryUrlForTest(version: string, platform?: NodeJS.Platform, arch?: string): string;
 export declare function formatManualUpdateInstructionsForTest(platform?: NodeJS.Platform): string;
@@ -31,6 +52,7 @@ export declare function formatVerificationFailureForTest(result: InstalledVersio
  * Atomically replace the installed binary and roll back if version verification fails.
  */
 export declare function replaceBinaryForUpdate(options: BinaryReplacementOptions): Promise<InstalledVersionVerification>;
+export declare function runPackageManagerUpdateForTest(options: PackageManagerUpdateOptions): Promise<InstalledVersionVerification>;
 /**
  * Run the update command.
  */
@@ -42,3 +64,4 @@ export declare function runUpdateCommand(opts: {
  * Print update command help.
  */
 export declare function printUpdateHelp(): void;
+export {};

package/dist/types/commands/local-provider.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Test configured local OpenAI-compatible providers.
+ */
+import { Command } from "@sayknow-cli/utils/cli";
+export declare const LOCAL_PROVIDER_ACTIONS: readonly ["status", "diagnose", "discover", "models", "smoke"];
+export declare const LOCAL_PROVIDER_DEFAULT_ACTION = "status";
+export default class LocalProvider extends Command {
+    static description: string;
+    static args: {
+        action: import("@sayknow-cli/utils/cli").ArgDescriptor & {
+            description: string;
+            required: false;
+            options: readonly ["status", "diagnose", "discover", "models", "smoke"];
+        };
+    };
+    static flags: {
+        model: import("@sayknow-cli/utils/cli").FlagDescriptor<"string"> & {
+            description: string;
+        };
+        "models-path": import("@sayknow-cli/utils/cli").FlagDescriptor<"string"> & {
+            description: string;
+        };
+        "timeout-ms": import("@sayknow-cli/utils/cli").FlagDescriptor<"integer"> & {
+            description: string;
+        };
+        smoke: import("@sayknow-cli/utils/cli").FlagDescriptor<"boolean"> & {
+            description: string;
+        };
+        json: import("@sayknow-cli/utils/cli").FlagDescriptor<"boolean"> & {
+            description: string;
+        };
+    };
+    run(): Promise<void>;
+}

package/dist/types/commands/telegram.d.ts

@@ -0,0 +1,22 @@
+/**
+ * `skc telegram` — manage the Telegram Remote integration.
+ */
+import { Command } from "@sayknow-cli/utils/cli";
+import { type TelegramAction } from "../cli/telegram-cli";
+export default class Telegram extends Command {
+    static description: string;
+    static args: {
+        action: import("@sayknow-cli/utils/cli").ArgDescriptor & {
+            description: string;
+            required: false;
+            options: TelegramAction[];
+        };
+    };
+    static flags: {
+        json: import("@sayknow-cli/utils/cli").FlagDescriptor<"boolean"> & {
+            description: string;
+        };
+    };
+    static examples: string[];
+    run(): Promise<void>;
+}

package/dist/types/config/keybindings.d.ts

@@ -10,6 +10,7 @@ interface AppKeybindings {
     "app.suspend": true;
     "app.thinking.cycle": true;
     "app.thinking.toggle": true;
+    "app.commandPalette.open": true;
     "app.model.cycleForward": true;
     "app.model.cycleBackward": true;
     "app.model.select": true;
@@ -45,6 +46,7 @@ declare module "@sayknow-cli/tui" {
     interface Keybindings extends AppKeybindings {
     }
 }
+export declare function defaultMessageQueueKeysForPlatform(platform?: NodeJS.Platform): KeyId;
 /**
  * All keybindings definitions: TUI + app-specific.
  */
@@ -201,12 +203,16 @@ export declare const KEYBINDINGS: {
         readonly defaultKeys: "ctrl+t";
         readonly description: "Toggle thinking mode";
     };
-    readonly "app.model.cycleForward": {
+    readonly "app.commandPalette.open": {
         readonly defaultKeys: "ctrl+p";
+        readonly description: "Open command palette";
+    };
+    readonly "app.model.cycleForward": {
+        readonly defaultKeys: "alt+n";
         readonly description: "Cycle to next model";
     };
     readonly "app.model.cycleBackward": {
-        readonly defaultKeys: "shift+ctrl+p";
+        readonly defaultKeys: "alt+shift+n";
         readonly description: "Cycle to previous model";
     };
     readonly "app.model.select": {
@@ -231,10 +237,10 @@ export declare const KEYBINDINGS: {
     };
     readonly "app.message.followUp": {
         readonly defaultKeys: [];
-        readonly description: "Send follow-up message (no default; Ctrl+Enter inserts a newline)";
+        readonly description: "Send follow-up message (no default; Ctrl+Enter submits)";
     };
     readonly "app.message.queue": {
-        readonly defaultKeys: "alt+enter";
+        readonly defaultKeys: KeyId;
         readonly description: "Queue message for next turn";
     };
     readonly "app.message.dequeue": {
@@ -254,8 +260,8 @@ export declare const KEYBINDINGS: {
         readonly description: "Copy prompt";
     };
     readonly "app.session.new": {
-        readonly defaultKeys: [];
-        readonly description: "Create new session";
+        readonly defaultKeys: "ctrl+n";
+        readonly description: "Start a new session";
     };
     readonly "app.session.tree": {
         readonly defaultKeys: [];

package/dist/types/config/model-registry.d.ts

@@ -256,6 +256,11 @@ export declare const ModelsConfigFile: ConfigFile<{
         disableStrictTools?: boolean | undefined;
         transport?: "pi-native" | undefined;
         cacheRetention?: "long" | "none" | "short" | undefined;
+        openaiCompat?: {
+            baseUrl: string;
+            apiKey?: string | undefined;
+            apiKeyEnv?: string | undefined;
+        } | undefined;
     }> | undefined;
     modelBindings?: {
         modelRoles?: Record<string, string> | undefined;

package/dist/types/config/models-config-schema.d.ts

@@ -669,6 +669,11 @@ export declare const ModelsConfigSchema: z.ZodObject<{
             none: "none";
             short: "short";
         }>>;
+        openaiCompat: z.ZodOptional<z.ZodObject<{
+            baseUrl: z.ZodString;
+            apiKey: z.ZodOptional<z.ZodString>;
+            apiKeyEnv: z.ZodOptional<z.ZodString>;
+        }, z.core.$strict>>;
     }, z.core.$strict>>>;
     modelBindings: z.ZodOptional<z.ZodObject<{
         modelRoles: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;