@iowarp/clio-coder 0.5.1 → 0.5.2

package/src/tools/context/surface.ts

@@ -12,22 +12,26 @@ import type { ToolSurface } from "../lazy-tool.js";
 export const contextToolSurface = {
 	name: ToolNames.Context,
 	description:
-		"Environment context: scope=settings explains current effective settings, autonomy, configured limits, and exact UI commands without exposing credentials; scope=workspace returns the git/project snapshot, scope=skills lists ready skills, installed package states and marketplace options, or loads a ready skill by name, scope=recall returns an exact persisted evicted or summarized tool result by ref; omit ref to discover historical results by query with bounded limit/offset pages. Clio's documentation and the recipe catalog are gateway capabilities (clio_docs, clio_library). For repository code and the repo's generated wiki use code_nav (mode=wiki).",
+		"Environment context: scope=settings explains effective settings, autonomy, limits and UI commands without credentials; workspace returns the git/project snapshot; budget inspects the native session's live request budget (read-only, shadow policy); skills lists ready skills, installed states and marketplace options, or loads a ready skill by name; recall retrieves persisted evicted/summarized tool results by ref, or discovers them by query with limit/offset pages. Clio docs and recipes: gateway capabilities clio_docs and clio_library. Repository code/wiki: code_nav (mode=wiki).",
 	parameters: Type.Object({
-		scope: StringEnum(["workspace", "settings", "skills", "recall"], { description: "Context source." }),
+		scope: StringEnum(["workspace", "settings", "skills", "recall", "budget"], { description: "Context source." }),
+		// These three carry three scopes each. The attached-schema byte budget in
+		// tests/contracts/gateway-prompt.test.ts had 18 bytes of headroom, so
+		// naming scope=skills here is paid for by compressing the wording rather
+		// than by widening a budget that exists to keep the prompt small.
 		query: Type.Optional(
 			Type.String({
 				description:
-					"scope=settings: settings path, section, or terms; scope=recall without ref: path, tool, or ref terms.",
+					"scope=settings: path/section/terms; scope=recall (no ref): path/tool/ref terms; scope=skills: narrow the list.",
 			}),
 		),
 		name: Type.Optional(Type.String({ description: "scope=skills: skill name to load; omit to list." })),
-		limit: Type.Optional(Type.Number({ description: "scope=settings or recall: bounded page size (max 12)." })),
+		limit: Type.Optional(
+			Type.Number({ description: "scope=settings/recall: page size (max 12); scope=skills: rows (max 200)." }),
+		),
 		ref: Type.Optional(Type.String({ description: "scope=recall: exact persisted result ref; omit for discovery." })),
 		offset: Type.Optional(
-			Type.Number({
-				description: "scope=settings or recall discovery: zero-based offset; follow nextOffset (default 0).",
-			}),
+			Type.Number({ description: "scope=settings, recall, or skills: 0-based offset; follow nextOffset." }),
 		),
 		include_tree: Type.Optional(Type.Boolean({ description: "scope=skills: list files under the skill base_dir." })),
 	}),

package/src/tools/core-bootstrap.ts

@@ -1,6 +1,7 @@
 import type { ContextRecalledPayload } from "../core/bus-events.js";
 import type { ClioSettings } from "../core/config.js";
 import { ToolNames } from "../core/tool-names.js";
+import type { BudgetProvider } from "../domains/context/budget/inspection.js";
 import type { WorkerRecall } from "../domains/context/worker/recall.js";
 import type { LoadSkillsInput } from "../domains/resources/index.js";
 import type { SessionContract } from "../domains/session/contract.js";
@@ -40,6 +41,8 @@ import { webFetchToolSurface, webReadToolSurface } from "./web-fetch-surface.js"
 import { writeTool } from "./write.js";
 
 export interface CoreToolBootstrapDeps {
+	/** Native session accounting only. Worker registries do not inherit it. */
+	getContextBudget?: BudgetProvider;
 	getSettings?: () => Readonly<ClioSettings>;
 	workerRecall?: WorkerRecall;
 	session?: SessionContract;
@@ -164,6 +167,7 @@ export function registerCoreTools(registry: ToolRegistry, deps: CoreToolBootstra
 		),
 	});
 	const skillToolDeps = {
+		...(deps.getContextBudget ? { getContextBudget: deps.getContextBudget } : {}),
 		...(deps.getSettings ? { getSettings: deps.getSettings } : {}),
 		...(deps.workerRecall ? { workerRecall: deps.workerRecall } : {}),
 		getCwd: () => deps.session?.current()?.cwd ?? process.cwd(),

package/src/tools/observation.ts

@@ -306,6 +306,8 @@ function bumpExhaustedStreak(key: string | null): number {
 export function observationBudgetExhausted(input: {
 	tool: string;
 	unit: ObservationUnit;
+	/** Preserve parseable JSON for structured inspection tools, without offloading. */
+	format?: ObservationFormat;
 	reservation: ObservationReservation;
 	subject: string;
 	hint: string;
@@ -322,7 +324,11 @@ export function observationBudgetExhausted(input: {
 		recordSpentBytes(reservation, byteLength(message));
 		return { kind: "error", message };
 	}
-	const output = `[observation budget exhausted for this turn before ${tool} ${subject}: ${spent}. ${hint}]`;
+	const message = `observation budget exhausted for this turn before ${tool} ${subject}: ${spent}. ${hint}`;
+	const output =
+		input.format === "json"
+			? JSON.stringify({ status: "unavailable", reason: "observation-budget-exhausted", message })
+			: `[${message}]`;
 	const shownBytes = byteLength(output);
 	recordSpentBytes(reservation, shownBytes);
 	const budget = budgetDetails(reservation);
@@ -336,7 +342,7 @@ export function observationBudgetExhausted(input: {
 		// the full size is the message itself; keep totalBytes >= shownBytes.
 		totalBytes: shownBytes,
 		truncated: true,
-		format: "text",
+		format: input.format ?? "text",
 		...(budget !== null ? { budget } : {}),
 	};
 	return { kind: "ok", output, details: { observation } };

package/src/tools/policy.ts

@@ -36,6 +36,7 @@ export const TOOL_PLANES: Readonly<Record<BuiltinToolName, PlaneExpectation>> =
 	[ToolNames.Find]: { plane: "observe", actionClass: "read", executionMode: "parallel" },
 	[ToolNames.Ls]: { plane: "observe", actionClass: "read", executionMode: "parallel" },
 	[ToolNames.CodeNav]: { plane: "observe", actionClass: "read", executionMode: "parallel" },
+	[ToolNames.SelfCompact]: { plane: "orchestrate", actionClass: "read", executionMode: "sequential" },
 	[ToolNames.Context]: { plane: "observe", actionClass: "read", executionMode: "parallel" },
 	[ToolNames.CredentialPresent]: { plane: "observe", actionClass: "read", executionMode: "parallel" },
 	// clio_docs and clio_library are the bundled-documentation and recipe-catalog
@@ -191,6 +192,8 @@ export function validateBuiltinToolPolicy(
 	const includeLedgerTools = options.includeLedgerTools ?? false;
 	const includeNetworkTools = options.includeNetworkTools ?? true;
 	const required = new Set<ToolName>(Object.values(ToolNames));
+	// The native interactive host alone supplies the durable continuity port.
+	required.delete(ToolNames.SelfCompact);
 	for (const tool of [...required]) {
 		if (!includeSessionTools && SESSION_BOUND_TOOLS.has(tool)) required.delete(tool);
 		if (!includeDispatchTools && DISPATCH_BOUND_TOOLS.has(tool)) required.delete(tool);

package/src/tools/self-compact.ts

@@ -0,0 +1,31 @@
+import { Type } from "typebox";
+import { ToolNames } from "../core/tool-names.js";
+import type { ToolSpec } from "./registry.js";
+
+export type RequestSelfCompact = (note: unknown, toolCallId: string, signal?: AbortSignal) => Promise<string>;
+
+/** Admission only. The native host owns reduction after this receipt settles. */
+export function createSelfCompactTool(request: RequestSelfCompact): ToolSpec {
+	return {
+		name: ToolNames.SelfCompact,
+		description:
+			"Save an exact handoff note and compact context before continuing this task. Call alone, with no sibling tools. Include current objective, decisions, evidence, paths, and next steps. A pending receipt is not proof of completion.",
+		parameters: Type.Object({
+			note_to_self: Type.String({
+				maxLength: 8192,
+				description: "Assistant-authored handoff text; nonblank, at most 8192 UTF-8 bytes. Preserved exactly.",
+			}),
+		}),
+		baseActionClass: "read",
+		executionMode: "sequential",
+		async run(args, options) {
+			try {
+				const note = (args as { note_to_self?: unknown }).note_to_self;
+				const output = await request(note, options?.toolCallId ?? "", options?.signal);
+				return { kind: "ok", output };
+			} catch (error) {
+				return { kind: "error", message: error instanceof Error ? error.message : String(error) };
+			}
+		},
+	};
+}

package/src/tools/surface.ts

@@ -39,6 +39,7 @@ export const TOOL_PLACEMENT: Readonly<Record<BuiltinToolName, ToolPlacement>> =
 	[ToolNames.Ls]: "direct",
 	[ToolNames.CodeNav]: "direct",
 	[ToolNames.Context]: "direct",
+	[ToolNames.SelfCompact]: "direct",
 	[ToolNames.CredentialPresent]: "gateway",
 	[ToolNames.ClioDocs]: "gateway",
 	[ToolNames.ClioLibrary]: "gateway",

package/src/tools/tasks.ts

@@ -174,7 +174,7 @@ export function createTasksTool(deps: TasksToolDeps): ToolSpec {
 			"pick moves one operator task uN onto the board; start marks one task active (the current focus); " +
 			"done completes a task (started or still pending) and requires note as the " +
 			"evidence the work actually finished; block parks it with a required reason; drop cancels it; list shows the board. " +
-			"For operator handoff, pick the intended uN and use its linked tN; CLI hand does not pick it. Never pick unrelated tasks. " +
+			"For operator handoff, pick the intended uN before work and use its linked tN; CLI hand alone does not pick it. Never pick unrelated tasks. " +
 			"Before claiming completion, list: the linked row must be completed and the operator task done on the same session/board link; report IDs and states. " +
 			"Work that did not happen is blocked or dropped, never done. A self-created plan is not operator authorization. " +
 			"For proposal-only work, plan/add with initialStatus=blocked and note naming the pending operator decision; " +