@sayknow-cli/coding-agent 0.3.12 → 0.3.15

package/src/coordinator-mcp/session-reaper.ts

@@ -0,0 +1,129 @@
+import { logger } from "@sayknow-cli/utils";
+
+/**
+ * Idle reaper for coordinator-managed SKC worker sessions.
+ *
+ * Every `skc_delegate_*` call that omits `session_id` starts a fresh tmux worker
+ * session. Nothing in the coordinator ever tore those down, so completed/crashed
+ * sessions accumulated (RAM + worktrees) until something killed them by hand.
+ *
+ * This is the automatic backstop (defense-in-depth): a periodic sweep force-closes
+ * sessions that are (a) ephemeral — coordinator delegate-created, never a user's
+ * registered resident session, (b) not mid-turn, and (c) idle past a TTL.
+ *
+ * The controller is pure + fully injectable (clock / list / reap side-effects) so
+ * it is unit-testable without tmux, the filesystem, or wall-clock waits. The
+ * scheduling mirrors the proven resource-gc controller: a recursive setTimeout
+ * with a generation guard so a stop()+start() can never leak a duplicate timer.
+ */
+
+export const DEFAULT_SESSION_IDLE_TTL_MS = 30 * 60_000; // 30 min idle → reap
+export const DEFAULT_SESSION_SWEEP_INTERVAL_MS = 5 * 60_000; // sweep every 5 min
+export const MIN_SESSION_IDLE_TTL_MS = 60_000; // never reap a <1min-idle session
+export const MIN_SESSION_SWEEP_INTERVAL_MS = 30_000;
+
+/** Minimal projection of a coordinator session the reaper needs to decide. */
+export interface ReapableSession {
+	sessionId: string;
+	/** True only for coordinator delegate-created sessions. User-registered resident sessions are false and never reaped. */
+	ephemeral: boolean;
+	/** Epoch ms of last observed activity (turn update / session-state write / session creation). */
+	lastActivityMs: number;
+	/** True while a turn is active — never reap mid-turn. */
+	hasActiveTurn: boolean;
+}
+
+export interface SessionReaperPolicy {
+	idleTtlMs: number;
+	sweepIntervalMs: number;
+}
+
+/**
+ * Pure selection: which sessions are safe to reap at `now`.
+ * A session is reapable iff ephemeral AND not mid-turn AND idle ≥ (clamped) TTL.
+ */
+export function selectReapableSessions(
+	sessions: readonly ReapableSession[],
+	now: number,
+	idleTtlMs: number,
+): ReapableSession[] {
+	const ttl = Math.max(MIN_SESSION_IDLE_TTL_MS, idleTtlMs);
+	return sessions.filter(s => s.ephemeral && !s.hasActiveTurn && now - s.lastActivityMs >= ttl);
+}
+
+/** Injectable side-effects so the controller runs in tests without tmux/fs/real time. */
+export interface SessionReaperDeps {
+	listSessions: () => Promise<ReapableSession[]>;
+	reapSession: (sessionId: string) => Promise<void>;
+	now: () => number;
+}
+
+export interface SessionReaper {
+	/** Run one sweep; returns the number of sessions successfully reaped. */
+	sweepOnce: () => Promise<number>;
+	start: () => void;
+	stop: () => void;
+	readonly running: boolean;
+}
+
+export function createSessionReaper(deps: SessionReaperDeps, policy: SessionReaperPolicy): SessionReaper {
+	const idleTtlMs = Math.max(MIN_SESSION_IDLE_TTL_MS, policy.idleTtlMs);
+	const sweepIntervalMs = Math.max(MIN_SESSION_SWEEP_INTERVAL_MS, policy.sweepIntervalMs);
+	let timer: ReturnType<typeof setTimeout> | null = null;
+	let generation = 0;
+	let inProgress = false;
+
+	async function sweepOnce(): Promise<number> {
+		if (inProgress) return 0; // never overlap sweeps
+		inProgress = true;
+		try {
+			const sessions = await deps.listSessions();
+			const targets = selectReapableSessions(sessions, deps.now(), idleTtlMs);
+			let reaped = 0;
+			for (const session of targets) {
+				try {
+					await deps.reapSession(session.sessionId);
+					reaped += 1;
+				} catch (err) {
+					// One wedged session must not abort the rest of the sweep.
+					logger.warn(
+						`session-reaper: failed to reap ${session.sessionId}: ${err instanceof Error ? err.message : String(err)}`,
+					);
+				}
+			}
+			return reaped;
+		} finally {
+			inProgress = false;
+		}
+	}
+
+	function schedule(gen: number): void {
+		timer = setTimeout(() => {
+			if (gen !== generation) return; // stale timer from a prior start()
+			void sweepOnce().finally(() => {
+				if (gen === generation) schedule(gen);
+			});
+		}, sweepIntervalMs);
+		// The reaper must never keep the coordinator process alive by itself.
+		(timer as { unref?: () => void }).unref?.();
+	}
+
+	return {
+		sweepOnce,
+		start(): void {
+			if (timer) return; // already running
+			generation += 1;
+			schedule(generation);
+		},
+		stop(): void {
+			generation += 1; // invalidate any in-flight scheduled tick
+			if (timer) {
+				clearTimeout(timer);
+				timer = null;
+			}
+		},
+		get running(): boolean {
+			return timer !== null;
+		},
+	};
+}

package/src/daemon/control-types.ts

@@ -47,6 +47,15 @@ export interface DaemonOperationOptions {
 	spawnIfStopped?: boolean;
 }
 
+export interface DaemonRecovery {
+	/** Machine-readable recovery category for automation branching. */
+	reason: "ownership_mismatch";
+	/** One-line human summary of why the operation could not proceed. */
+	summary: string;
+	/** Ordered, copy-pasteable remediation steps. */
+	steps: string[];
+}
+
 export interface DaemonOperationResult {
 	kind: DaemonKind;
 	action: Exclude<DaemonAction, "list">;
@@ -55,6 +64,8 @@ export interface DaemonOperationResult {
 	after?: DaemonStatus;
 	warnings: string[];
 	message: string;
+	/** Present when the operation was refused with an actionable recovery path (e.g. ownership mismatch). */
+	recovery?: DaemonRecovery;
 }
 
 export interface BuiltInDaemonController {

package/src/daemon/operator-contract.ts

@@ -0,0 +1,121 @@
+/**
+ * Shared operator contract for the `skc daemon` command surface.
+ *
+ * One source of truth for the beginner-safe operational vocabulary so the
+ * guided human surface and the machine-readable JSON never drift:
+ * - the terse action verbs plus operator aliases (e.g. `restart` -> `reload`),
+ * - process exit codes,
+ * - concise vs. `--verbose` human rendering of statuses and results, and
+ * - actionable recovery guidance for a token/chat ownership mismatch.
+ *
+ * The full roots/debug payload lives behind `--verbose` (human) or `--json`
+ * (automation); the default human output stays a concise per-daemon result.
+ */
+
+import type { DaemonAction, DaemonOperationResult, DaemonRecovery, DaemonStatus } from "./control-types";
+
+/** Canonical daemon actions accepted as the leading verb. */
+export const DAEMON_CANONICAL_ACTIONS: readonly DaemonAction[] = ["list", "status", "stop", "reload"];
+
+/**
+ * Operator-friendly aliases resolved to a canonical action. `restart` is the
+ * routine "reload if running, otherwise start" verb; it maps onto `reload`,
+ * whose default already spawns a fresh owner when none is running.
+ */
+export const DAEMON_ACTION_ALIASES: Readonly<Record<string, DaemonAction>> = {
+	restart: "reload",
+};
+
+/** Every token accepted in the leading action position (canonical + aliases). */
+export const DAEMON_ACTION_TOKENS: readonly string[] = [
+	...DAEMON_CANONICAL_ACTIONS,
+	...Object.keys(DAEMON_ACTION_ALIASES),
+];
+
+/** Resolve a leading verb (canonical or alias) to its canonical action. */
+export function resolveDaemonAction(token: string | undefined): DaemonAction | undefined {
+	if (token === undefined) return undefined;
+	if ((DAEMON_CANONICAL_ACTIONS as readonly string[]).includes(token)) return token as DaemonAction;
+	return DAEMON_ACTION_ALIASES[token];
+}
+
+/** Exit codes for `skc daemon`. Backward compatible: success 0, any failure 1. */
+export const DAEMON_EXIT = { ok: 0, failure: 1 } as const;
+
+/** Human-facing headline when a spawn/reload is refused by a live foreign identity. */
+export const OWNERSHIP_MISMATCH_MESSAGE =
+	"refused: a live Telegram daemon with a different bot token or chat already owns this workspace";
+
+/** Structured, actionable recovery for a token/chat ownership mismatch. */
+export function ownershipMismatchRecovery(): DaemonRecovery {
+	return {
+		reason: "ownership_mismatch",
+		summary: "A live Telegram daemon owned by a different bot token or chat already holds this workspace.",
+		steps: [
+			"Confirm the intended bot token and chat with `skc notify` (or edit notifications.telegram in your config).",
+			"If the running daemon is stale or unwanted, stop it with `skc daemon stop --force`, then rerun `skc daemon restart`.",
+			"If it is the correct daemon, no action is needed — this workspace attaches automatically once the identities match.",
+		],
+	};
+}
+
+function timestamp(ms: number | undefined): string | undefined {
+	if (ms === undefined) return undefined;
+	const date = new Date(ms);
+	return Number.isNaN(date.getTime()) ? undefined : date.toISOString();
+}
+
+/**
+ * Render one daemon status. Concise by default (single head line + any
+ * actionable warning); `--verbose` adds runtime detail and the full roots list.
+ */
+export function formatDaemonStatus(status: DaemonStatus, opts: { verbose?: boolean } = {}): string {
+	const lines: string[] = [];
+	if (!status.configured) {
+		lines.push(`${status.kind}: not configured`);
+		if (status.runtime.warning) lines.push(`  warning: ${status.runtime.warning}`);
+		return lines.join("\n");
+	}
+
+	const meta: string[] = [];
+	if (status.pid !== undefined) meta.push(`pid ${status.pid}`);
+	if (status.ownerId) meta.push(`owner ${status.ownerId}`);
+	const rootCount = status.rootCount ?? status.roots?.length ?? 0;
+	if (rootCount > 0) meta.push(`${rootCount} root${rootCount === 1 ? "" : "s"}`);
+
+	let head = `${status.kind}: ${status.health}`;
+	if (meta.length > 0) head += ` (${meta.join(", ")})`;
+	if (status.detail) head += ` — ${status.detail}`;
+	lines.push(head);
+	if (status.runtime.warning) lines.push(`  warning: ${status.runtime.warning}`);
+
+	if (opts.verbose) {
+		lines.push(`  runtime: ${status.runtime.mode} (${status.runtime.execPath})`);
+		const started = timestamp(status.startedAt);
+		if (started) lines.push(`  started: ${started}`);
+		const heartbeat = timestamp(status.heartbeatAt);
+		if (heartbeat) lines.push(`  heartbeat: ${heartbeat}`);
+		const roots = status.roots ?? [];
+		lines.push(`  roots: ${rootCount}`);
+		for (const root of roots) lines.push(`    - ${root}`);
+	}
+
+	return lines.join("\n");
+}
+
+/**
+ * Render one operation result. Keeps the stable `<kind> <action>: ok|failed —
+ * <message>` head line, then any warnings, then actionable recovery steps.
+ */
+export function formatDaemonResult(result: DaemonOperationResult): string {
+	const lines = [`${result.kind} ${result.action}: ${result.ok ? "ok" : "failed"} — ${result.message}`];
+	for (const warning of result.warnings) lines.push(`  warning: ${warning}`);
+	if (result.recovery) {
+		lines.push(`  ${result.recovery.summary}`);
+		lines.push("  to recover:");
+		result.recovery.steps.forEach((step, i) => {
+			lines.push(`    ${i + 1}. ${step}`);
+		});
+	}
+	return lines.join("\n");
+}

package/src/defaults/skc/extensions/grok-cli-vendor/src/models/catalog.ts

@@ -1,12 +1,14 @@
 /**
  * Model definitions for Grok CLI's API.
  */
+import { Effort } from '@sayknow-cli/ai/model-thinking';
 
 // ─── Cost constants ($/M tokens) ──────────────────────────────────────────────
 
 const COST_BUILD = { input: 1, output: 2, cacheRead: 0.2, cacheWrite: 0.2 };
 const COST_COMPOSER_FAST = { input: 3, output: 15, cacheRead: 0.5, cacheWrite: 0 };
 const COST_43 = { input: 1.25, output: 2.5, cacheRead: 0.2, cacheWrite: 0 };
+const COST_45 = { input: 2, output: 6, cacheRead: 0.5, cacheWrite: 0 };
 const COST_420 = { input: 2, output: 6, cacheRead: 0.2, cacheWrite: 0 };
 
 // ─── Model type ───────────────────────────────────────────────────────────────
@@ -24,6 +26,8 @@ export interface GrokCliModelConfig {
   };
   contextWindow: number;
   maxTokens: number;
+  /** Highest reasoning effort supported by this model. */
+  maxReasoningEffort?: Effort;
   /** Models that don't support reasoning.effort get a thinkingLevelMap. */
   thinkingLevelMap?: Record<string, string | null>;
 }
@@ -69,6 +73,18 @@ const FALLBACK_MODELS: GrokCliModelConfig[] = [
     contextWindow: 1_000_000,
     maxTokens: 30_000,
   },
+  {
+    // Official metadata and pricing: https://docs.x.ai/developers/models/grok-4.5
+    id: 'grok-4.5',
+    name: 'Grok 4.5',
+    reasoning: true,
+    input: ['text', 'image'],
+    cost: COST_45,
+    contextWindow: 500_000,
+    maxTokens: 30_000,
+    // https://docs.x.ai/developers/model-capabilities/text/reasoning caps Grok 4.5 at high.
+    maxReasoningEffort: Effort.High,
+  },
   {
     id: 'grok-4.20-0309-reasoning',
     name: 'Grok 4.20 Reasoning',
@@ -106,15 +122,37 @@ const FALLBACK_MODELS: GrokCliModelConfig[] = [
   },
 ];
 
-const EFFORT_CAPABLE_PREFIXES = ['grok-3-mini', 'grok-4.20-multi-agent', 'grok-4.3'];
+// Official aliases: https://docs.x.ai/developers/models/grok-4.5
+const MODEL_ALIASES: Readonly<Record<string, string>> = {
+  'grok-4.5-latest': 'grok-4.5',
+  'grok-build-latest': 'grok-4.5',
+};
 
-export function supportsReasoningEffort(modelId: string): boolean {
+function getModelName(modelId: string): string {
   const parts = modelId.split('/');
-  const name = (parts.at(-1) ?? modelId).toLowerCase();
+  return (parts.at(-1) ?? modelId).toLowerCase();
+}
+
+function getCanonicalModelName(modelId: string): string {
+  const name = getModelName(modelId);
+  return MODEL_ALIASES[name] ?? name;
+}
+
+export function getMaxReasoningEffort(modelId: string): Effort | undefined {
+  const name = getCanonicalModelName(modelId);
+  return FALLBACK_MODELS.find(
+    (model) => name === model.id.toLowerCase() || name.startsWith(`${model.id.toLowerCase()}-`),
+  )?.maxReasoningEffort;
+}
+
+const EFFORT_CAPABLE_PREFIXES = ['grok-3-mini', 'grok-4.20-multi-agent', 'grok-4.3', 'grok-4.5'];
+
+export function supportsReasoningEffort(modelId: string): boolean {
+  const name = getCanonicalModelName(modelId);
   if (!EFFORT_CAPABLE_PREFIXES.some((prefix) => name.startsWith(prefix))) {
     return false;
   }
-  const model = resolveModels().find((entry) => entry.id.toLowerCase() === name);
+  const model = resolveModels().find((entry) => getCanonicalModelName(entry.id) === name);
   if (model) {
     if (!model.reasoning) return false;
     if (!model.thinkingLevelMap) return true;
@@ -139,17 +177,19 @@ export function resolveModels(): GrokCliModelConfig[] {
     .filter(Boolean);
   if (env.length === 0) return FALLBACK_MODELS;
 
-  const byId = new Map(FALLBACK_MODELS.map((m) => [m.id, m]));
-  return env.map(
-    (id) =>
-      byId.get(id) ?? {
-        id,
-        name: id,
-        reasoning: true,
-        input: ['text'] as ('text' | 'image')[],
-        cost: COST_BUILD,
-        contextWindow: 1_000_000,
-        maxTokens: 30_000,
-      },
-  );
+  const byId = new Map(FALLBACK_MODELS.map((model) => [model.id.toLowerCase(), model]));
+  return env.map((id) => {
+    const model = byId.get(getCanonicalModelName(id));
+    if (model) return model.id === id ? model : { ...model, id };
+
+    return {
+      id,
+      name: id,
+      reasoning: true,
+      input: ['text'] as ('text' | 'image')[],
+      cost: COST_BUILD,
+      contextWindow: 1_000_000,
+      maxTokens: 30_000,
+    };
+  });
 }

package/src/defaults/skc/extensions/grok-cli-vendor/src/payload/sanitize.ts

@@ -22,7 +22,8 @@
 import { existsSync, readFileSync, realpathSync } from 'node:fs';
 import { extname, isAbsolute, resolve, sep } from 'node:path';
 import { fileURLToPath } from 'node:url';
-import { supportsReasoningEffort } from '../models/catalog.js';
+import { Effort, THINKING_EFFORTS } from '@sayknow-cli/ai/model-thinking';
+import { getMaxReasoningEffort, supportsReasoningEffort } from '../models/catalog.js';
 
 // ─── Content text extraction ─────────────────────────────────────────────────
 
@@ -266,6 +267,18 @@ function stripUnsupportedTopLevelFields(next: Record<string, unknown>): void {
   delete next.truncation;
 }
 
+function normalizeReasoningEffort(modelId: string, value: unknown): unknown {
+  const effort = value === Effort.Minimal ? Effort.Low : value;
+  if (typeof effort !== 'string') return effort;
+
+  const maxEffort = getMaxReasoningEffort(modelId);
+  if (maxEffort === undefined) return effort;
+
+  const effortIndex = THINKING_EFFORTS.indexOf(effort as Effort);
+  const maxEffortIndex = THINKING_EFFORTS.indexOf(maxEffort);
+  return effortIndex > maxEffortIndex ? maxEffort : effort;
+}
+
 // ─── Main sanitization ────────────────────────────────────────────────────────
 
 /**
@@ -334,7 +347,7 @@ export function sanitizePayload(
   if (supportsReasoningEffort(modelId)) {
     const reasoning = next.reasoning as Record<string, unknown> | undefined;
     if (reasoning) {
-      const effort = reasoning.effort === 'minimal' ? 'low' : reasoning.effort;
+      const effort = normalizeReasoningEffort(modelId, reasoning.effort);
       next.reasoning = reasoning.summary !== undefined ? { effort } : { ...reasoning, effort };
     }
   } else {

package/src/defaults/skc/extensions/grok-cli-vendor/src/provider/register.ts

@@ -36,7 +36,11 @@ export default function registerGrokCli(api: ExtensionAPI) {
       name: m.name,
       reasoning: m.reasoning,
       thinking: m.reasoning
-        ? { minLevel: Effort.Low, maxLevel: Effort.XHigh, mode: 'effort' }
+        ? {
+            minLevel: Effort.Low,
+            maxLevel: m.maxReasoningEffort ?? Effort.XHigh,
+            mode: 'effort',
+          }
         : undefined,
       input: m.input,
       cost: m.cost,

package/src/extensibility/extensions/runner.ts

@@ -484,7 +484,7 @@ export class ExtensionRunner {
 			abort: () => this.#abortFn(),
 			hasPendingMessages: () => this.#hasPendingMessagesFn(),
 			shutdown: () => this.#shutdownHandler(),
-			getSystemPrompt: () => this.#getSystemPromptFn(),
+			getSystemPrompt: () => [...this.#getSystemPromptFn()],
 			hasQueuedMessages: () => this.#hasPendingMessagesFn(), // deprecated alias
 			workflowGate: this.#getWorkflowGateFn(),
 		};

package/src/extensibility/extensions/types.ts

@@ -273,11 +273,13 @@ export interface ExtensionUIContext {
 // ============================================================================
 
 export interface ContextUsage {
-	/** Estimated context tokens, or null if unknown (e.g. right after compaction, before next LLM response). */
+	/** Context tokens, or null if unknown (e.g. right after compaction, before next LLM response). */
 	tokens: number | null;
 	contextWindow: number;
 	/** Context usage as percentage of context window, or null if tokens is unknown. */
 	percent: number | null;
+	/** Provenance: "provider_anchor" = anchored on provider-reported usage (+ heuristic trailing delta); "heuristic" = no provider anchor available, full estimate; "unknown" = post-compaction, no post-compaction provider response yet. */
+	source: "provider_anchor" | "heuristic" | "unknown";
 }
 
 export interface CompactOptions {