@aeondave/pi-persona 1.17.1 → 1.17.4

package/src/tools/delegate.ts

@@ -1,28 +1,14 @@
 /**
- * The `delegate` tool's core logic — pure, engine-injected, testable. Maps params
- * to engine runs (single + bounded parallel), formats the result, and emits live
- * per-task "views" (running → done/failed) so the UI can show each sub-agent as
- * it runs. A task may carry `skills`/`model`/`tools` to spawn a *dynamic* sub-agent
- * (e.g. the generic `operator` specialised by the skills it loads). Capability
- * gating happens upstream in the `tool_call` hook.
+ * The `delegate` tool's pure core: parameter coercion and validation, the task → run-spec mapping,
+ * and the anti-loop ledger. A task may carry `skills`/`model`/`tools` to spawn a *dynamic* sub-agent
+ * (e.g. the generic `operator` specialised by the skills it loads). Capability gating happens
+ * upstream in the `tool_call` hook; launching and settling live in `delegate-tool.ts`.
  */
 
-import { type ChildUsage, emptyUsage, type ToolEvent } from "../engine/stream.ts";
-import { mapWithConcurrency } from "../orchestration/parallel.ts";
 import { cappedList } from "../core/format.ts";
+import { isThinkingLevel, THINKING_LEVELS, type ThinkingLevel } from "../core/types.ts";
 import { sanitizeDisplayLabel } from "../core/display-label.ts";
-import { validateParallelWriteSets } from "../core/ownership.ts";
-import { aggregateResults } from "../orchestration/reducers.ts";
-import {
-	type AgentRunSpec,
-	type InfrastructureFailure,
-	isInfrastructureFailure,
-	isPositiveFiniteMs,
-	legFailure,
-	type SteerFn,
-	type StrategyEngine,
-} from "../orchestration/sdk.ts";
-import type { AgentResult } from "../orchestration/types.ts";
+import { type AgentRunSpec, type InfrastructureFailure, isInfrastructureFailure, isPositiveFiniteMs } from "../orchestration/sdk.ts";
 
 export interface DelegateTask {
 	agent: string;
@@ -35,6 +21,8 @@ export interface DelegateTask {
 	skills?: string[];
 	/** Model override for this sub-agent. */
 	model?: string;
+	/** Requested effort for this leg; overrides agent and shared child defaults. Pi clamps it. */
+	thinking?: ThinkingLevel;
 	/** Tool allowlist override for this sub-agent. */
 	tools?: string[];
 	/** Extra system-prompt text: an ON-THE-FLY specialist persona, appended to the
@@ -62,6 +50,7 @@ export interface DelegateParams {
 	name?: string;
 	skills?: string[];
 	model?: string;
+	thinking?: ThinkingLevel;
 	tools?: string[];
 	role?: string;
 	isolation?: "none" | "worktree";
@@ -73,8 +62,6 @@ export interface DelegateParams {
 	outputContract?: string;
 	tasks?: DelegateTask[];
 	concurrency?: number;
-	async?: boolean;
-	sync?: boolean;
 }
 
 /** Structured cold-start context that any persona policy may require. */
@@ -150,10 +137,6 @@ export function validateDelegationBrief(params: DelegateParams): string | undefi
 	return undefined;
 }
 
-// Moved to core/ownership.ts (so a strategy can call it without importing a tool module);
-// re-exported here unchanged for this file's own call sites and existing tests.
-export { findWriteSetOverlaps, validateParallelWriteSets, type WriteSetOverlap } from "../core/ownership.ts";
-
 function unwrapJsonish(value: unknown, label: string): { ok: true; value: unknown } | { ok: false; error: string } {
 	let current = value;
 	for (let depth = 0; depth < 2; depth++) {
@@ -222,6 +205,9 @@ function decodedTaskFieldError(bag: Record<string, unknown>, index: number): str
 			return `delegate: ${label}.${field} must be a string.`;
 		}
 	}
+	if (bag.thinking !== undefined && !isThinkingLevel(bag.thinking)) {
+		return `delegate: ${label}.thinking must be one of: ${THINKING_LEVELS.join(", ")}.`;
+	}
 	if (bag.isolation !== undefined && bag.isolation !== "none" && bag.isolation !== "worktree") {
 		return `delegate: ${label}.isolation must be "none" or "worktree".`;
 	}
@@ -281,6 +267,9 @@ export function coerceDelegateParams(raw: unknown): { ok: true; params: Delegate
 		return { ok: false, error: "delegate: arguments must be an object." };
 	}
 	const bag = { ...(raw as Record<string, unknown>) };
+	if (bag.thinking !== undefined && !isThinkingLevel(bag.thinking)) {
+		return { ok: false, error: `delegate: thinking must be one of: ${THINKING_LEVELS.join(", ")}.` };
+	}
 	const tasks = coerceTaskList(bag.tasks);
 	if (!tasks.ok) return tasks;
 	if (tasks.value !== undefined) bag.tasks = tasks.value;
@@ -299,32 +288,16 @@ export function coerceDelegateParams(raw: unknown): { ok: true; params: Delegate
 	return { ok: true, params: bag as DelegateParams };
 }
 
-/** A live per-sub-agent view for the UI (running → done/failed). */
-export interface DelegateView {
-	agent: string;
-	/** Display label: `name · model` (e.g. "kiln-port · sonnet-4-6"). */
-	label: string;
-	running: boolean;
-	ok: boolean;
-	/** Terminal failure classification; `abort` projects as stopped rather than failed in the UI. */
-	failureKind?: AgentResult["failureKind"];
-	output: string;
-	/** The tool the leg is currently running (e.g. "grep src/…"), "" if none. */
-	activity: string;
-	usage: ChildUsage;
-}
-
-/** Short model name for display: drop provider + `claude-` + any `:thinking`. */
+/** Short model name for display: drop provider + `claude-`; model ids remain opaque. */
 export function shortModel(ref: string | undefined): string {
 	if (!ref) return "";
-	const base = ref.split(":")[0]?.split("/").pop() ?? ref;
+	const base = ref.split("/").pop() ?? ref;
 	return base.replace(/^claude-/, "");
 }
 
 /** The bare display NAME for a sub-agent (no model suffix): the loader's name, or a codename
  *  for a generic operator, else the agent's own name. Exported so a caller that folds in the
- *  model itself (e.g. the async tree node, `AsyncRun.label`) doesn't have to strip it back out
- *  of {@link labelFor}'s composite string. */
+ *  model itself (e.g. the async tree node, `AsyncRun.label`). */
 export function nameFor(t: { agent: string; name?: string }, index: number): string {
 	// No catalog of call-signs: an unnamed generic operator stays the agent name, disambiguated
 	// by index. The model is supposed to invent `<call-sign>-<purpose>` itself; this is only the
@@ -333,28 +306,8 @@ export function nameFor(t: { agent: string; name?: string }, index: number): str
 	return sanitizeDisplayLabel(t.name?.trim() || fallback, fallback);
 }
 
-/** Display label for a sub-agent: its bare {@link nameFor} name plus its short model. */
-export function labelFor(t: { agent: string; name?: string; model?: string }, index: number): string {
-	const name = nameFor(t, index);
-	const m = shortModel(t.model);
-	return m ? `${name} · ${m}` : name;
-}
-
-export interface DelegateOutcome {
-	text: string;
-	results: AgentResult[];
-	views: DelegateView[];
-	ok: boolean;
-}
-
-/** Hard ceilings the engine enforces regardless of what the LLM asks for. */
-export interface DelegateLimits {
-	maxConcurrency: number;
-	maxChildren: number;
-}
-
-/** Normalize an LLM-authored concurrency request once for sync scheduling, async scheduling, and
- * policy gates. Fractional/non-finite inputs fail toward serialization instead of rounding up. */
+/** Normalize an LLM-authored concurrency request once for scheduling and policy gates.
+ * Fractional/non-finite inputs fail toward serialization instead of rounding up. */
 export function normalizeDelegateConcurrency(value: number | undefined, maximum: number): number {
 	const ceiling = Math.max(1, Number.isFinite(maximum) ? Math.floor(maximum) : 1);
 	if (value === undefined) return ceiling;
@@ -363,9 +316,8 @@ export function normalizeDelegateConcurrency(value: number | undefined, maximum:
 }
 
 /** Map a task to the run-spec fields the engine accepts — the single source of truth for the
- *  delegate path's field mapping. Exported so the async launch path (extension.ts) routes
- *  through the SAME mapping instead of duplicating it (a duplicated copy is how NP2's
- *  `timeoutMs` could silently miss the async fan-out, which is the interactive default). */
+ *  delegate path's field mapping (a second copy is how a per-leg knob like `timeoutMs` silently
+ *  misses one launch route). */
 export function specOf(t: DelegateTask, index = 0): AgentRunSpec {
 	const renderedBrief = renderDelegationBrief(t.brief);
 	const spec: AgentRunSpec = {
@@ -375,6 +327,7 @@ export function specOf(t: DelegateTask, index = 0): AgentRunSpec {
 	};
 	if (t.skills && t.skills.length > 0) spec.skills = t.skills;
 	if (t.model) spec.model = t.model;
+	if (t.thinking !== undefined) spec.thinking = t.thinking;
 	if (t.tools !== undefined) spec.tools = t.tools;
 	if (t.role?.trim()) spec.role = t.role.trim();
 	if (t.outputContract?.trim()) spec.outputContract = t.outputContract.trim();
@@ -406,6 +359,18 @@ export interface DelegationKeyInput {
 	isolation?: string;
 }
 
+/** The ledger's view of a task or run spec: just the key fields, absent when unset. */
+export function keyInputOf(t: Pick<DelegateTask, "agent" | "task" | "model" | "role" | "tools" | "isolation">): DelegationKeyInput {
+	return {
+		agent: t.agent,
+		task: t.task,
+		...(t.model ? { model: t.model } : {}),
+		...(t.role ? { role: t.role } : {}),
+		...(t.tools !== undefined ? { tools: t.tools } : {}),
+		...(t.isolation ? { isolation: t.isolation } : {}),
+	};
+}
+
 export class DelegationLedger {
 	private readonly failures = new Map<string, number>();
 	private readonly maxKeys = 200;
@@ -469,9 +434,6 @@ export class DelegationLedger {
  * an operator abort is cancellation, and an engine REJECTION is the harness breaking (see
  * {@link isInfrastructureFailure}) — a full disk or a crashed adapter says nothing about whether the
  * delegation was a good idea, and two of them would blacklist a task that was never really attempted.
- * Lives beside the ledger so every path that records feeds it the same notion of evidence: the sync
- * fan-out settles a rejection as `ok:false` while the single and async paths let it propagate, and
- * without this the identical infrastructure crash would count in one path and vanish in the others.
  */
 export function shouldRecordDelegationOutcome(result: Partial<InfrastructureFailure>): boolean {
 	return result.failureKind !== "abort" && !isInfrastructureFailure(result);
@@ -518,146 +480,3 @@ export function unknownContractError(requested: Array<string | undefined>, insta
 		"`outputContract` takes a contract NAME; omit it for free-form output and describe the report shape in `requiredArtifacts`."
 	);
 }
-
-/**
- * Should this `delegate` call run in the BACKGROUND (async)? An explicit `async` always wins;
- * otherwise an interactive session (`hasUI`) defaults to background — the supervisor stays free and
- * results return as follow-ups — unless the call opts out with `sync: true`. A headless run (no UI,
- * e.g. `pi -p`) defaults to SYNC: the single turn must carry the result, and nothing drains a
- * follow-up after the process exits. `renderCall` passes `hasUI: true` (it only ever fires in a UI),
- * so the async tag it shows tracks the exact same default the execute path takes.
- */
-export function wantsAsyncRun(params: { async?: boolean; sync?: boolean }, hasUI: boolean): boolean {
-	return params.async ?? (hasUI && params.sync !== true);
-}
-
-function viewOf(agent: string, label: string, r: AgentResult): DelegateView {
-	return {
-		agent,
-		label,
-		running: false,
-		ok: r.ok,
-		...(r.failureKind !== undefined ? { failureKind: r.failureKind } : {}),
-		output: r.ok ? r.output || "(no output)" : r.error ?? "(failed)",
-		activity: "",
-		usage: r.usage,
-	};
-}
-
-export async function runDelegate(
-	params: DelegateParams,
-	engine: StrategyEngine,
-	limits: DelegateLimits = { maxConcurrency: 4, maxChildren: 8 },
-	onProgress?: (views: DelegateView[]) => void,
-	onLegStart?: (index: number, abort: () => void) => void,
-	onLegSteerable?: (index: number, steer: SteerFn) => void,
-	/** The RUN-level abort signal — the same one the caller baked into its engine. A whole-run
-	 *  cancellation reaches a leg through THIS, never through the per-leg controller below, so
-	 *  without it a cancelled leg whose engine rejects is filed as an agent failure and the user's
-	 *  own stop renders as FAILED. Mirrors `SDKDeps.signal`, which classifies the same way. */
-	signal?: AbortSignal,
-	/** Authoritative per-leg tool lifecycle; arguments and output are intentionally absent. */
-	onLegToolEvent?: (index: number, event: ToolEvent) => void,
-): Promise<DelegateOutcome> {
-	if (params.tasks && params.tasks.length > 0) {
-		// Enforce the hard ceilings: cap the fan-out and clamp the concurrency the
-		// LLM requested — a strategy/tool call cannot exceed the declared limits.
-		const tasks = params.tasks.slice(0, limits.maxChildren);
-		const dropped = params.tasks.length - tasks.length;
-		const concurrency = normalizeDelegateConcurrency(params.concurrency, limits.maxConcurrency);
-		if (concurrency > 1) {
-			const writeSetError = validateParallelWriteSets(tasks);
-			if (writeSetError) return { text: writeSetError, results: [], views: [], ok: false };
-		}
-		const labels = tasks.map((t, i) => labelFor(t, i));
-		const views: DelegateView[] = tasks.map((t, i) => ({
-			agent: t.agent,
-			label: labels[i] as string,
-			running: true,
-			ok: false,
-			output: "",
-			activity: "",
-			usage: emptyUsage(),
-		}));
-		onProgress?.(views.map((v) => ({ ...v })));
-
-		const results = await mapWithConcurrency(tasks, concurrency, async (t, i) => {
-			const ac = new AbortController();
-			onLegStart?.(i, () => ac.abort());
-			// An engine that REJECTS becomes this leg's own ok:false result: the fan-out's completed
-			// siblings (already spawned and billed) must still reach the supervisor. Nothing in here
-			// is run-fatal — the max-children ceiling was applied to `tasks` before anything spawned.
-			let r: AgentResult;
-			try {
-				r = await engine.run(
-					specOf(t, i),
-					(p) => {
-						// Stream the leg's rolling output + current tool activity.
-						if (p.toolEvent) onLegToolEvent?.(i, p.toolEvent);
-						const cur = views[i] as DelegateView;
-						views[i] = { ...cur, output: p.output || cur.output, activity: p.activity ?? "" };
-						onProgress?.(views.map((v) => ({ ...v })));
-					},
-					ac.signal,
-					(steer) => onLegSteerable?.(i, steer),
-				);
-			} catch (err) {
-				r = legFailure(t.agent, err, ac.signal.aborted || (signal?.aborted ?? false));
-			}
-			views[i] = viewOf(t.agent, labels[i] as string, r);
-			onProgress?.(views.map((v) => ({ ...v })));
-			return r;
-		});
-		const agg = aggregateResults(results);
-		const text =
-			dropped > 0
-				? `${agg.output}\n\n[pi-persona] ${dropped} task(s) beyond the max-children limit (${limits.maxChildren}) were dropped.`
-				: agg.output;
-		return { text, results, views, ok: agg.ok };
-	}
-
-	if (params.agent && params.task) {
-		const single: DelegateTask = { agent: params.agent, task: params.task };
-		if (params.name) single.name = params.name;
-		if (params.skills && params.skills.length > 0) single.skills = params.skills;
-		if (params.model) single.model = params.model;
-		if (params.tools !== undefined) single.tools = params.tools;
-		if (params.role?.trim()) single.role = params.role.trim();
-		if (params.isolation !== undefined) single.isolation = params.isolation;
-		if (params.mcp !== undefined) single.mcp = params.mcp;
-		if (params.timeoutMs !== undefined) single.timeoutMs = params.timeoutMs;
-		if (params.brief !== undefined) single.brief = params.brief;
-		if (params.writeSet !== undefined) single.writeSet = params.writeSet;
-		if (params.outputContract !== undefined) single.outputContract = params.outputContract;
-		const label = labelFor(single, 0);
-		const view: DelegateView = {
-			agent: params.agent,
-			label,
-			running: true,
-			ok: false,
-			output: "",
-			activity: "",
-			usage: emptyUsage(),
-		};
-		onProgress?.([{ ...view }]);
-		const ac = new AbortController();
-		onLegStart?.(0, () => ac.abort());
-		const r = await engine.run(
-			specOf(single),
-			(p) => {
-				if (p.toolEvent) onLegToolEvent?.(0, p.toolEvent);
-				if (p.output) view.output = p.output;
-				view.activity = p.activity ?? "";
-				onProgress?.([{ ...view }]);
-			},
-			ac.signal,
-			(steer) => onLegSteerable?.(0, steer),
-		);
-		const text = r.ok ? r.output || "(no output)" : `Agent "${params.agent}" failed: ${r.error ?? "(no detail)"}`;
-		const terminalView = viewOf(params.agent, label, r);
-		onProgress?.([{ ...terminalView }]);
-		return { text, results: [r], views: [terminalView], ok: r.ok };
-	}
-
-	return { text: "delegate: provide either { agent, task } or { tasks: [{ agent, task }, ...] }", results: [], views: [], ok: false };
-}

package/src/tools/exocom-collaboration-input.ts

@@ -0,0 +1,168 @@
+/** Runtime validation and TypeBox schemas for the Exocom collaboration tools. */
+import { type Static, Type } from "typebox";
+
+import { writeSetPathError } from "../core/ownership.ts";
+
+const TOKEN = { minLength: 1, maxLength: 128, pattern: "^[A-Za-z0-9._:-]+$" } as const;
+export const TaskParams = Type.Object({
+	action: Type.Union([Type.Literal("create"), Type.Literal("take"), Type.Literal("progress"), Type.Literal("finish"), Type.Literal("list"), Type.Literal("get")], {
+		description: "Choose list to discover tasks (do not pass work_key or task_id); use get with both identifiers returned by create/list to inspect one exact task generation.",
+	}),
+	work_key: Type.Optional(Type.String({ ...TOKEN, description: "Required for create, take, progress, finish, and get. Omit for list. Pair with task_id for an existing task." })),
+	task_id: Type.Optional(Type.String({ ...TOKEN, description: "Generation id returned by create or list. Required with work_key for take, progress, finish, and get; omit for create and list." })),
+	description: Type.Optional(Type.String({ minLength: 1, maxLength: 2_048 })),
+	write_set: Type.Optional(Type.Array(Type.String({ minLength: 1, maxLength: 256 }), { maxItems: 64 })),
+	note: Type.Optional(Type.String({ minLength: 1, maxLength: 4_096 })),
+	outcome: Type.Optional(Type.Union([Type.Literal("done"), Type.Literal("abandoned")])),
+	offset: Type.Optional(Type.Integer({ minimum: 0, maximum: 64 })),
+	limit: Type.Optional(Type.Integer({ minimum: 1, maximum: 20, description: "Rows per page: defaults to 10 for summaries or 5 when detail=true. Detailed pages allow at most 5." })),
+	detail: Type.Optional(Type.Boolean({ description: "Include peer-authored task/progress prose. Detailed lists default to 5 rows and reject an explicit limit above 5." })),
+});
+export const OfferParams = Type.Object({
+	work_key: Type.String({ ...TOKEN }),
+	task_id: Type.String({ ...TOKEN }),
+	target: Type.Optional(Type.String({ minLength: 1, maxLength: 80 })),
+	expiresInMinutes: Type.Optional(Type.Integer({ minimum: 1, maximum: 1_440 })),
+});
+export const PublishParams = Type.Object({
+	action: Type.Union([Type.Literal("publish"), Type.Literal("read")]),
+	work_key: Type.Optional(Type.String({ ...TOKEN })),
+	task_id: Type.Optional(Type.String({ ...TOKEN })),
+	title: Type.Optional(Type.String({ minLength: 1, maxLength: 160 })),
+	excerpt: Type.Optional(Type.String({ minLength: 1, maxLength: 4_096 })),
+	msg_id: Type.Optional(Type.String({ ...TOKEN })),
+	offset: Type.Optional(Type.Integer({ minimum: 0, maximum: 64 })),
+	limit: Type.Optional(Type.Integer({ minimum: 1, maximum: 20 })),
+});
+
+type RecordValue = Record<string, unknown>;
+const isRecord = (value: unknown): value is RecordValue => !!value && typeof value === "object" && !Array.isArray(value);
+const isToken = (value: unknown): value is string => typeof value === "string" && /^[A-Za-z0-9._:-]{1,128}$/.test(value);
+function invalid(tool: string, field: string, expected: string): never {
+	throw new Error(`${tool}: ${field} ${expected}`);
+}
+function exactKeys(tool: string, value: RecordValue, allowed: readonly string[]): void {
+	const unexpected = Object.keys(value).find((key) => !allowed.includes(key));
+	if (unexpected) invalid(tool, unexpected, "is not a supported parameter");
+}
+function boundedString(tool: string, field: string, value: unknown, max: number): string {
+	if (typeof value !== "string" || value.length < 1 || value.length > max) invalid(tool, field, `must be 1–${max} characters`);
+	return value;
+}
+function tokenField(tool: string, field: string, value: unknown): string {
+	if (!isToken(value)) invalid(tool, field, "must be 1–128 token characters matching [A-Za-z0-9._:-]");
+	return value;
+}
+function objectInput(tool: string, input: unknown): RecordValue {
+	if (!isRecord(input)) invalid(tool, "parameters", "must be an object");
+	return input;
+}
+
+export type TaskInput =
+	| { action: "list"; offset: number; limit: number; detail: boolean }
+	| { action: "get"; work_key: string; task_id: string }
+	| { action: "create"; work_key: string; description: string; write_set: string[] }
+	| { action: "take"; work_key: string; task_id: string }
+	| { action: "progress"; work_key: string; task_id: string; note: string }
+	| { action: "finish"; work_key: string; task_id: string; note: string; outcome: "done" | "abandoned" };
+
+export function parseTaskInput(input: unknown): TaskInput {
+	const tool = "exocom_task";
+	const value = objectInput(tool, input);
+	if (typeof value.action !== "string" || !["create", "take", "progress", "finish", "list", "get"].includes(value.action)) invalid(tool, "action", "must be create, take, progress, finish, list, or get");
+	const action = value.action as "create" | "take" | "progress" | "finish" | "list" | "get";
+	if (action === "list") {
+		exactKeys(tool, value, ["action", "offset", "limit", "detail"]);
+		const offset = value.offset === undefined ? 0 : value.offset;
+		const detail = value.detail === undefined ? false : value.detail;
+		const limit = value.limit === undefined ? (detail ? 5 : 10) : value.limit;
+		if (!Number.isInteger(offset) || (offset as number) < 0 || (offset as number) > 64) invalid(tool, "offset", "must be an integer from 0 to 64");
+		if (!Number.isInteger(limit) || (limit as number) < 1 || (limit as number) > 20) invalid(tool, "limit", "must be an integer from 1 to 20");
+		if (typeof detail !== "boolean") invalid(tool, "detail", "must be a boolean");
+		return { action, offset: offset as number, limit: limit as number, detail };
+	}
+	if (action === "get") {
+		exactKeys(tool, value, ["action", "work_key", "task_id"]);
+		return { action, work_key: tokenField(tool, "work_key", value.work_key), task_id: tokenField(tool, "task_id", value.task_id) };
+	}
+	if (action === "create") {
+		exactKeys(tool, value, ["action", "work_key", "description", "write_set"]);
+		const work_key = tokenField(tool, "work_key", value.work_key);
+		const description = boundedString(tool, "description", value.description, 2_048);
+		const write_set = value.write_set === undefined ? [] : value.write_set;
+		if (!Array.isArray(write_set) || write_set.length > 64 || write_set.some((path) => typeof path !== "string" || path.length < 1 || path.length > 256)) {
+			invalid(tool, "write_set", "must contain at most 64 paths of 1–256 characters");
+		}
+		for (const path of write_set as string[]) {
+			const issue = writeSetPathError(path);
+			if (issue) invalid(tool, "write_set path", `is invalid (${issue})`);
+		}
+		return { action, work_key, description, write_set: write_set as string[] };
+	}
+	const work_key = tokenField(tool, "work_key", value.work_key);
+	if (action === "take") {
+		exactKeys(tool, value, ["action", "work_key", "task_id"]);
+		return { action, work_key, task_id: tokenField(tool, "task_id", value.task_id) };
+	}
+	if (action === "progress") {
+		exactKeys(tool, value, ["action", "work_key", "task_id", "note"]);
+		return { action, work_key, task_id: tokenField(tool, "task_id", value.task_id), note: boundedString(tool, "note", value.note, 4_096) };
+	}
+	exactKeys(tool, value, ["action", "work_key", "task_id", "note", "outcome"]);
+	if (value.outcome !== "done" && value.outcome !== "abandoned") invalid(tool, "outcome", "must be done or abandoned");
+	return { action, work_key, task_id: tokenField(tool, "task_id", value.task_id), note: boundedString(tool, "note", value.note, 4_096), outcome: value.outcome };
+}
+
+export function parseOfferInput(input: unknown) {
+	const value = objectInput("exocom_offer", input);
+	exactKeys("exocom_offer", value, ["work_key", "task_id", "target", "expiresInMinutes"]);
+	const work_key = tokenField("exocom_offer", "work_key", value.work_key);
+	const task_id = tokenField("exocom_offer", "task_id", value.task_id);
+	let target: string | undefined;
+	if (value.target !== undefined) {
+		const raw = boundedString("exocom_offer", "target", value.target, 80);
+		if (raw === "*") invalid("exocom_offer", "target", "must name one peer, never *");
+		if (!/^[^\p{Cc}\p{Zl}\p{Zp}<>]+$/u.test(raw) || raw !== raw.trim()) invalid("exocom_offer", "target", "must exactly match a clean public target from exocom_list");
+		target = raw;
+	}
+	const expiresInMinutes = value.expiresInMinutes === undefined ? 60 : value.expiresInMinutes;
+	if (!Number.isInteger(expiresInMinutes) || (expiresInMinutes as number) < 1 || (expiresInMinutes as number) > 1_440) {
+		invalid("exocom_offer", "expiresInMinutes", "must be an integer from 1 to 1440");
+	}
+	return { work_key, task_id, target, expiresInMinutes: expiresInMinutes as number };
+}
+
+export type PublishInput =
+	| { action: "read"; msg_id: string }
+	| { action: "read"; work_key: string; task_id?: string; offset: number; limit: number }
+	| { action: "publish"; work_key: string; task_id: string; title: string; excerpt: string };
+
+export function parsePublishInput(input: unknown): PublishInput {
+	const value = objectInput("exocom_publish", input);
+	if (value.action === "read") {
+		if (value.msg_id !== undefined) {
+			exactKeys("exocom_publish", value, ["action", "msg_id"]);
+			return { action: "read", msg_id: tokenField("exocom_publish", "msg_id", value.msg_id) };
+		}
+		exactKeys("exocom_publish", value, ["action", "work_key", "task_id", "offset", "limit"]);
+		const work_key = tokenField("exocom_publish", "work_key", value.work_key);
+		const task_id = value.task_id === undefined ? undefined : tokenField("exocom_publish", "task_id", value.task_id);
+		const offset = value.offset === undefined ? 0 : value.offset;
+		const limit = value.limit === undefined ? 10 : value.limit;
+		if (!Number.isInteger(offset) || (offset as number) < 0 || (offset as number) > 64) invalid("exocom_publish", "offset", "must be an integer from 0 to 64");
+		if (!Number.isInteger(limit) || (limit as number) < 1 || (limit as number) > 20) invalid("exocom_publish", "limit", "must be an integer from 1 to 20");
+		return { action: "read", work_key, ...(task_id === undefined ? {} : { task_id }), offset: offset as number, limit: limit as number };
+	}
+	if (value.action !== "publish") invalid("exocom_publish", "action", "must be publish or read");
+	exactKeys("exocom_publish", value, ["action", "work_key", "task_id", "title", "excerpt"]);
+	const work_key = tokenField("exocom_publish", "work_key", value.work_key);
+	const task_id = tokenField("exocom_publish", "task_id", value.task_id);
+	const title = boundedString("exocom_publish", "title", value.title, 160);
+	const excerpt = boundedString("exocom_publish", "excerpt", value.excerpt, 4_096);
+	if (Buffer.byteLength(excerpt, "utf8") > 8_192) invalid("exocom_publish", "excerpt", "must be at most 8192 UTF-8 bytes");
+	return { action: "publish", work_key, task_id, title, excerpt };
+}
+
+export type TaskParamsType = Static<typeof TaskParams>;
+export type OfferParamsType = Static<typeof OfferParams>;
+export type PublishParamsType = Static<typeof PublishParams>;