@sayknow-cli/coding-agent 0.3.2 → 0.3.4

package/src/modes/components/model-selector.ts

@@ -20,6 +20,7 @@ import {
 import type { ModelRegistry, SkcModelAssignmentTargetId } from "../../config/model-registry";
 import {
 	isAuthenticated,
+	kNoAuth,
 	SKC_MODEL_ASSIGNMENT_TARGET_IDS,
 	SKC_MODEL_ASSIGNMENT_TARGETS,
 } from "../../config/model-registry";
@@ -804,7 +805,14 @@ export class ModelSelectorComponent extends Container {
 		const entries = await Promise.all(
 			[...providers].map(async provider => {
 				const apiKey = await this.#modelRegistry.getApiKeyForProvider(provider, this.#authSessionId);
-				return [provider, isAuthenticated(apiKey)] as const;
+				// "Usable" — not "has a real API key". getApiKeyForProvider returns the
+				// kNoAuth ("N/A") sentinel for keyless/no-auth providers (local LLMs,
+				// `--auth none` custom providers), which are usable WITHOUT a key. But
+				// isAuthenticated() deliberately rejects kNoAuth, so using it alone would
+				// flag those providers unauthenticated and silently bail their presets
+				// into a login flow instead of applying. Treat kNoAuth as usable here,
+				// matching setModel()/getApiKey() which already accept it.
+				return [provider, isAuthenticated(apiKey) || apiKey === kNoAuth] as const;
 			}),
 		);
 		this.#providerAuthById = new Map(entries);

package/src/modes/controllers/selector-controller.ts

@@ -51,6 +51,7 @@ import {
 	setPreferredImageProvider,
 	setPreferredSearchProvider,
 	setSearchFallbackProviders,
+	setSearchHardTimeoutMs,
 } from "../../tools";
 import { setSessionTerminalTitle } from "../../utils/title-generator";
 import { AgentDashboard } from "../components/agent-dashboard";
@@ -645,6 +646,11 @@ export class SelectorController {
 					);
 				}
 				break;
+			case "web_search.timeout":
+				if (typeof value === "number" && Number.isFinite(value) && value > 0) {
+					setSearchHardTimeoutMs(value * 1000);
+				}
+				break;
 			case "providers.image":
 				if (
 					value === "auto" ||

package/src/prompts/system/system-prompt.md

@@ -194,9 +194,9 @@ Delegate by default for multi-file changes, refactors, new features, tests, and
 </detached-subagents>
 {{/has}}
 
-{{#has tools "inspect_image"}}
+{{#has tools "read"}}
 <images>
-For image understanding, use `{{toolRefs.inspect_image}}` with a specific question instead of reading raw image metadata only.
+For image understanding, call `{{toolRefs.read}}` on the image path; the image is returned inline for direct visual inspection.
 </images>
 {{/has}}
 

package/src/prompts/tools/cron.md

@@ -1,12 +1,14 @@
 Schedule a prompt to fire on a recurring cron schedule, or one-shot at the next match. Cron tasks let you re-run a prompt automatically on an interval — poll a deployment, babysit a PR, check back on a long-running build, or remind yourself to do something later in the session.
 
-`CronCreate` accepts a standard 5-field cron expression in your local timezone, the prompt to run, and whether the job recurs or fires once. It returns an 8-character job id you can pass to `CronDelete`. Each session can hold up to 50 scheduled tasks. Recurring tasks auto-expire 7 days after creation; one-shot tasks self-delete after firing.
+Use a single `op` field to select the operation:
 
-`CronList` enumerates every scheduled task in the session. `CronDelete` cancels a task by id.
+- `op: "create"` accepts a standard 5-field `cron_expression` in your local timezone, the `prompt` to run, and `recurring` (whether the job recurs or fires once). It returns an 8-character job id you can pass to `op: "delete"`. Each session can hold up to 50 scheduled tasks. Recurring tasks auto-expire 7 days after creation; one-shot tasks self-delete after firing.
+- `op: "list"` enumerates every scheduled task in the session.
+- `op: "delete"` cancels a task by `id`.
 
 ## Cron expressions
 
-`CronCreate` accepts 5-field cron: `minute hour day-of-month month day-of-week`. All fields support `*`, single values (`5`), steps (`*/15`), ranges (`1-5`), and comma lists (`1,15,30`). Day-of-week uses `0`/`7` for Sunday through `6` for Saturday. Extended syntax like `L`, `W`, `?`, or month/weekday names is not supported.
+`op: "create"` accepts 5-field cron: `minute hour day-of-month month day-of-week`. All fields support `*`, single values (`5`), steps (`*/15`), ranges (`1-5`), and comma lists (`1,15,30`). Day-of-week uses `0`/`7` for Sunday through `6` for Saturday. Extended syntax like `L`, `W`, `?`, or month/weekday names is not supported.
 
 | Example       | Meaning                      |
 | :------------ | :--------------------------- |

package/src/prompts/tools/read.md

@@ -46,7 +46,7 @@ Extracts text from PDF, Word, PowerPoint, Excel, RTF, and EPUB. Notebooks (`.ipy
 
 # Images
 
-Reading an image path returns metadata (mime, bytes, dimensions, channels, alpha). For actual visual analysis, call `inspect_image` with the path and a question describing what to inspect.
+Reading an image path returns the image itself for visual inspection by a vision-capable model.
 
 # Archives
 

package/src/sdk.ts

@@ -142,6 +142,7 @@ import {
 	setPreferredImageProvider,
 	setPreferredSearchProvider,
 	setSearchFallbackProviders,
+	setSearchHardTimeoutMs,
 	type Tool,
 	type ToolSession,
 	WebSearchTool,
@@ -943,6 +944,10 @@ export async function createAgentSession(options: CreateAgentSessionOptions = {}
 			webSearchFallback.filter(value => typeof value === "string" && isConfigurableSearchProviderId(value)),
 		);
 	}
+	const webSearchTimeout = settings.get("web_search.timeout");
+	if (typeof webSearchTimeout === "number" && Number.isFinite(webSearchTimeout) && webSearchTimeout > 0) {
+		setSearchHardTimeoutMs(webSearchTimeout * 1000);
+	}
 
 	const imageProvider = settings.get("providers.image");
 	if (

package/src/session/agent-session.ts

@@ -250,6 +250,7 @@ import { releaseTabsForOwner } from "../tools/browser/tab-supervisor";
 import type { CheckpointState } from "../tools/checkpoint";
 import { outputMeta, wrapToolWithMetaNotice } from "../tools/output-meta";
 import { normalizeLocalScheme, resolveToCwd } from "../tools/path-utils";
+import { registerResourceGcSession } from "../tools/resource-gc";
 import { getLatestTodoPhasesFromEntries, type TodoItem, type TodoPhase } from "../tools/todo-write";
 import { ToolAbortError, ToolError } from "../tools/tool-errors";
 import { clampTimeout } from "../tools/tool-timeouts";
@@ -964,6 +965,8 @@ export class AgentSession {
 	// Python execution state
 	#evalAbortControllers = new Set<AbortController>();
 	#evalKernelOwnerId: string;
+	/** Idempotent unregister handle for this session's resource-GC registration. */
+	#unregisterResourceGc?: () => void;
 	/**
 	 * AsyncJobManager owned by this session (top-level only). Subagents leave
 	 * this undefined and **MUST NOT** dispose the global instance on teardown.
@@ -1180,6 +1183,15 @@ export class AgentSession {
 		this.sessionManager = config.sessionManager;
 		this.settings = config.settings;
 		this.taskDepth = config.taskDepth ?? 0;
+		// Register this session with the process-wide resource GC (idle/RSS browser-tab eviction
+		// + stale screenshot cleanup). Session-keyed so concurrent sessions share one timer safely.
+		const resourceGcSessionId = this.sessionManager.getSessionId();
+		if (resourceGcSessionId) {
+			this.#unregisterResourceGc = registerResourceGcSession({
+				sessionId: resourceGcSessionId,
+				settings: this.settings,
+			});
+		}
 		// Power assertions are taken per turn (see #beginInFlight); nothing acquired here.
 		this.#evalKernelOwnerId = config.evalKernelOwnerId ?? `agent-session:${Snowflake.next()}`;
 		this.#ownedAsyncJobManager = config.ownedAsyncJobManager;
@@ -3285,6 +3297,8 @@ export class AgentSession {
 		// browsers disconnect, headless close gracefully). Scoped by the session id the
 		// browser tool tagged tabs with, so other live sessions' tabs are untouched.
 		// No-op when this session opened no tabs. Failure is logged, not thrown.
+		this.#unregisterResourceGc?.();
+		this.#unregisterResourceGc = undefined;
 		await releaseTabsForOwner(this.sessionManager.getSessionId()).catch((error: unknown) =>
 			logger.warn("session dispose: releaseTabsForOwner failed", { error }),
 		);
@@ -3324,6 +3338,8 @@ export class AgentSession {
 	async disposeChildSubprocesses(timeoutMs = SIGNAL_TEARDOWN_TIMEOUT_MS): Promise<void> {
 		const sessionId = this.sessionManager.getSessionId();
 		const kernelOwnerId = this.#evalKernelOwnerId;
+		this.#unregisterResourceGc?.();
+		this.#unregisterResourceGc = undefined;
 		const work = Promise.allSettled([
 			// kill:true so a forced exit also reaps spawned-app Chrome we own (headless
 			// always closes; connected/attached browsers only disconnect — never killed).
@@ -5231,6 +5247,19 @@ export class AgentSession {
 			attribution: "user",
 			timestamp: Date.now(),
 		});
+		// A live agent loop polls the steering queue at every tool/turn boundary
+		// and consumes this message on its own. But when a steer is queued while no
+		// loop is actively running — e.g. the session still reports busy only
+		// because a finished prompt is unwinding (deferred agent_end / post-prompt
+		// work) — nothing delivers it until the next explicit prompt or a
+		// user-interrupt abort, so it stalls until the user presses Esc. Schedule a
+		// continue so the steer is delivered promptly. A live loop (or an
+		// already-drained queue) makes the scheduled continue a no-op.
+		if (this.#canAutoContinueForSteer()) {
+			this.#scheduleAgentContinue({
+				shouldContinue: () => this.#canAutoContinueForSteer() && this.agent.hasQueuedSteering(),
+			});
+		}
 	}
 
 	/**
@@ -5275,6 +5304,21 @@ export class AgentSession {
 		return last?.role === "assistant";
 	}
 
+	/**
+	 * Gate for idle / winding-down steer auto-continue. Unlike the follow-up gate
+	 * this checks `agent.state.isStreaming` (a live agent loop) rather than the
+	 * public `isStreaming` (which stays true while a finished prompt unwinds), so a
+	 * steer queued during the unwind window is still delivered. A live loop returns
+	 * false here because it polls the steering queue itself.
+	 */
+	#canAutoContinueForSteer(): boolean {
+		if (this.agent.state.isStreaming) return false;
+		if (this.isRetrying) return false;
+		const messages = this.agent.state.messages;
+		const last = messages[messages.length - 1];
+		return last?.role === "assistant";
+	}
+
 	queueDeferredMessage(message: CustomMessage): void {
 		this.#queueHiddenNextTurnMessage(message, true);
 	}

package/src/skc-runtime/state-renderer.ts

@@ -256,6 +256,11 @@ export function renderUltragoalStatusMarkdown(summary: {
 	currentGoal?: { id: string; status: string; title?: string; objective?: string };
 	counts: Record<string, number>;
 	goals: unknown[];
+	nudgeBudget?: number;
+	nudgeCount?: number;
+	nudgeRemaining?: number;
+	nudgeGoalId?: string;
+	nudgeTargetKind?: string;
 }): string {
 	if (!summary.exists)
 		return `# ultragoal status\n\n- status: missing\n- No ultragoal plan found at ${summary.paths.goalsPath}. Run \`skc ultragoal create-goals --brief "..."\` first.\n`;
@@ -270,6 +275,14 @@ export function renderUltragoalStatusMarkdown(summary: {
 	];
 	if (summary.skcObjective) lines.push(`- objective: ${summary.skcObjective}`);
 	if (summary.currentGoal) lines.push(`- current: ${summary.currentGoal.id} (${summary.currentGoal.status})`);
+	if (summary.nudgeBudget !== undefined && summary.nudgeGoalId) {
+		const used = summary.nudgeCount ?? 0;
+		const remaining = summary.nudgeRemaining ?? Math.max(0, summary.nudgeBudget - used);
+		const target = summary.nudgeTargetKind ? ` target=${summary.nudgeTargetKind}` : "";
+		lines.push(
+			`- nudge: ${summary.nudgeGoalId} ${used}/${summary.nudgeBudget} used (${remaining} remaining)${target}`,
+		);
+	}
 	lines.push(`- goals_path: ${summary.paths.goalsPath}`);
 	if (summary.paths.ledgerPath) lines.push(`- ledger_path: ${summary.paths.ledgerPath}`);
 	return `${lines.join("\n")}\n`;

package/src/skc-runtime/ultragoal-guard.ts

@@ -8,9 +8,13 @@ import {
 	hashStructuredValue,
 	readUltragoalLedger,
 	readUltragoalPlan,
+	recordUltragoalNudgeIfBudgetRemaining,
+	resolveUltragoalNudgeBudget,
+	selectUltragoalNudgeTarget,
 	type UltragoalCompletionVerification,
 	type UltragoalGoal,
 	type UltragoalLedgerEvent,
+	type UltragoalNudgeSurface,
 	type UltragoalPaths,
 	type UltragoalPlan,
 	type UltragoalReceiptKind,
@@ -494,6 +498,96 @@ export async function isUltragoalAskBlocked(cwd: string): Promise<UltragoalAskBl
 	});
 }
 
+const NUDGE_SURFACE_LABEL: Record<UltragoalNudgeSurface, string> = {
+	pause: "pausing the goal",
+	drop: "dropping the run",
+	ask: "asking the user",
+	premature_complete: "finishing the story early",
+};
+
+const NUDGE_SURFACE_REASON: Record<UltragoalNudgeSurface, string> = {
+	pause: "an active story still has resolvable work",
+	drop: "the aggregate run still has unfinished stories",
+	ask: "the decision can be resolved as durable story work",
+	premature_complete: "story verification is not yet satisfied",
+};
+
+/**
+ * Escalating per-attempt refusal text. Deliberately avoids every
+ * `isUltragoalBypassPrompt` trigger: no `update_goal(`, no "skip/weaken verification",
+ * no "mark ... complete", no "--status complete", and the word "complete" never
+ * appears (so the `goal` ... `complete` proximity rule cannot match).
+ */
+export function formatUltragoalNudgeMessage(input: {
+	surface: UltragoalNudgeSurface;
+	attempt: number;
+	budget: number;
+	goalId: string;
+}): string {
+	const label = NUDGE_SURFACE_LABEL[input.surface];
+	const reason = NUDGE_SURFACE_REASON[input.surface];
+	return [
+		`Ultragoal try-harder nudge (${input.attempt}/${input.budget}) for ${input.goalId}: ${label} was refused before the normal gate.`,
+		`Resolving this is part of the goal, not a reason to stop. Try a different approach first: inspect the failure, run a focused test or replay, find local credentials/config if access is the blocker, split the obstacle with \`skc ultragoal steer --kind add_subgoal\`, delegate an executor, or record concrete review blockers.`,
+		`Reason: ${reason}.`,
+	].join("\n");
+}
+
+/**
+ * Consume one nudge for a guarded give-up attempt. MUST only be called from assert/
+ * consume paths, never from read-style `is...Blocked` diagnostics. Returns a nudge
+ * message while the per-story budget remains; otherwise reports not-nudged so the
+ * caller falls through to today's gate.
+ */
+async function consumeUltragoalNudge(input: {
+	cwd: string;
+	surface: UltragoalNudgeSurface;
+	currentGoal?: CurrentGoalLike | null;
+	sessionId?: string | null;
+}): Promise<{ nudged: true; message: string } | { nudged: false }> {
+	const sessionId = input.sessionId?.trim() || (await ultragoalReadPaths(input.cwd)).sessionId;
+	if (!sessionId) return { nudged: false };
+	const plan = await readUltragoalPlan(input.cwd, sessionId);
+	if (!plan) return { nudged: false };
+	const target = selectUltragoalNudgeTarget(plan, { currentGoalObjective: input.currentGoal?.objective });
+	if (!target) return { nudged: false };
+	const { budget } = await resolveUltragoalNudgeBudget(input.cwd);
+	const outcome = await recordUltragoalNudgeIfBudgetRemaining({
+		cwd: input.cwd,
+		sessionId,
+		target,
+		surface: input.surface,
+		budget,
+		reason: NUDGE_SURFACE_REASON[input.surface],
+		...(input.currentGoal?.objective ? { currentGoalObjective: input.currentGoal.objective } : {}),
+	});
+	if (outcome.nudged) {
+		return {
+			nudged: true,
+			message: formatUltragoalNudgeMessage({
+				surface: input.surface,
+				attempt: outcome.attempt,
+				budget: outcome.budget,
+				goalId: outcome.goalId,
+			}),
+		};
+	}
+	return { nudged: false };
+}
+
+/**
+ * Assert-path entry for the `ask` surface (the ask guard lives in another module).
+ * Resolves the active (leader) Ultragoal session so subagent/headless asks consume
+ * the leader run's budget rather than a fresh child ledger.
+ */
+export async function consumeUltragoalAskNudge(
+	cwd: string,
+	sessionId?: string | null,
+): Promise<{ nudged: true; message: string } | { nudged: false }> {
+	if (!cwd) return { nudged: false };
+	return consumeUltragoalNudge({ cwd, surface: "ask", sessionId });
+}
+
 export async function assertCanCompleteCurrentGoal(input: {
 	cwd: string;
 	currentGoal?: CurrentGoalLike | null;
@@ -502,6 +596,13 @@ export async function assertCanCompleteCurrentGoal(input: {
 	if (!input.cwd) return;
 	const diagnostic = await readUltragoalVerificationState(input);
 	if (["inactive", "unrelated_goal", "active_verified_complete"].includes(diagnostic.state)) return;
+	const nudge = await consumeUltragoalNudge({
+		cwd: input.cwd,
+		surface: "premature_complete",
+		currentGoal: input.currentGoal,
+		sessionId: input.sessionId,
+	});
+	if (nudge.nudged) throw new Error(nudge.message);
 	throw new Error(
 		`${diagnostic.message} Run strict \`skc ultragoal checkpoint --status complete --quality-gate-json <file> --skc-goal-json <file>\` first, or record review blockers and rerun verification.`,
 	);
@@ -558,6 +659,10 @@ export async function isUltragoalPauseBlocked(cwd: string): Promise<UltragoalPau
 }
 
 export async function assertUltragoalPauseAllowed(cwd: string): Promise<void> {
+	if (cwd) {
+		const nudge = await consumeUltragoalNudge({ cwd, surface: "pause" });
+		if (nudge.nudged) throw new Error(nudge.message);
+	}
 	const diagnostic = await isUltragoalPauseBlocked(cwd);
 	if (!diagnostic.blocked) return;
 	throw new Error(
@@ -568,3 +673,65 @@ export async function assertUltragoalPauseAllowed(cwd: string): Promise<void> {
 		].join("\n"),
 	);
 }
+/**
+ * Guard `goal({"op":"drop"})` during an active Ultragoal run. A *real give-up* (an
+ * aggregate run still mid-flight with incomplete required stories) is nudged while
+ * budget remains; once exhausted it falls through to today's drop behavior. Legitimate
+ * aggregate-reset drops — no durable run, unrelated goal, an already dropped/stale
+ * aggregate, or an all-stories-complete run — are never nudged. If durable state
+ * exists but cannot be read to classify the drop, fail closed.
+ */
+export async function assertUltragoalDropAllowed(input: {
+	cwd: string;
+	currentGoal?: CurrentGoalLike | null;
+	sessionId?: string | null;
+}): Promise<void> {
+	if (!input.cwd) return;
+	let paths: UltragoalPaths;
+	let sessionId: string | null;
+	try {
+		({ paths, sessionId } = await ultragoalReadPaths(input.cwd));
+	} catch (error) {
+		throw new Error(
+			`Unable to classify Ultragoal drop (durable state unreadable): ${error instanceof Error ? error.message : String(error)}`,
+		);
+	}
+	if (sessionId === null) return;
+	try {
+		await fs.stat(paths.dir);
+	} catch (error) {
+		if (isEnoent(error)) return;
+		throw new Error(
+			`Unable to classify Ultragoal drop (durable state present but unreadable): ${error instanceof Error ? error.message : String(error)}`,
+		);
+	}
+	let plan: UltragoalPlan | null;
+	try {
+		plan = await readUltragoalPlan(input.cwd, sessionId);
+	} catch (error) {
+		throw new Error(
+			`Unable to classify Ultragoal drop (goals.json unreadable): ${error instanceof Error ? error.message : String(error)}`,
+		);
+	}
+	if (!plan) {
+		throw new Error("Unable to classify Ultragoal drop: durable state exists but goals.json is missing or empty.");
+	}
+	// Out of scope: per-story mode drops keep today's behavior.
+	if (plan.skcGoalMode !== "aggregate") return;
+	// A real give-up requires an active aggregate goal to actually be abandoned. With no
+	// current goal-mode goal (or a non-active one), `drop` is a no-op/reset before a fresh
+	// `create`, never a give-up — so it is left un-nudged.
+	if (!input.currentGoal) return;
+	if (input.currentGoal.status !== "active") return;
+	// Unrelated active goal: not this aggregate run.
+	if (!objectiveMatches(input.currentGoal.objective, plan)) return;
+	// All required stories complete: a legitimate reset, not a give-up.
+	if (getUltragoalRunCompletionState(plan).allComplete) return;
+	const nudge = await consumeUltragoalNudge({
+		cwd: input.cwd,
+		surface: "drop",
+		currentGoal: input.currentGoal,
+		sessionId,
+	});
+	if (nudge.nudged) throw new Error(nudge.message);
+}