@fitchmultz/pi-subagents 0.44.7 → 0.45.0

package/dist/extension/parent-runtime.js

@@ -0,0 +1,339 @@
+import { randomUUID } from "node:crypto";
+import { discoverAgents } from "../agents/agents.js";
+import { ARTIFACT_CLEANUP_DAYS, cleanupAllArtifactDirs, cleanupOldArtifacts, getArtifactsDir, } from "../shared/artifacts.js";
+import { resolveCurrentSessionId } from "../shared/session-identity.js";
+import { cleanupOldChainDirs } from "../shared/settings.js";
+import { cleanupOldRunStorage } from "../shared/temp-root.js";
+import { AgentViewController } from "../tui/agent-view.js";
+import { createSubagentExecutor } from "../runs/foreground/subagent-executor.js";
+import { createAsyncJobTracker } from "../runs/background/async-job-tracker.js";
+import { rememberOwnedRun, restoreOwnedRunsAsync } from "../runs/shared/run-records.js";
+import { closeRunHistory, runHistoryIndex, startRunHistory } from "../runs/shared/history-index.js";
+import { registerParentUsage } from "../runs/shared/parent-usage.js";
+import { createCompletionDelivery } from "../runs/background/completion-delivery.js";
+import { isObsoleteIdleNotice } from "../runs/shared/subagent-control.js";
+import { registerSlashCommands } from "../slash/slash-commands.js";
+import { clearSlashSnapshots, restoreSlashFinalSnapshots } from "../slash/slash-live-state.js";
+import { isTuiContext } from "../shared/ui-mode.js";
+import { isRecord } from "../shared/unknown.js";
+import { ASYNC_DIR, RESULTS_DIR, SUBAGENT_ASYNC_COMPLETE_EVENT, SUBAGENT_ASYNC_STARTED_EVENT, SUBAGENT_CONTROL_EVENT, WIDGET_KEY, } from "../shared/types.js";
+import { handleSubagentControlNotice, SUBAGENT_CONTROL_MESSAGE_TYPE, } from "./control-notices.js";
+import { parseControlNotice } from "./control-notice-schema.js";
+import { adaptFinalizedToolResult, registerToolResultAdapter } from "./tool-result.js";
+import { registerCompactSubagentTools } from "./compact-tools.js";
+import { registerParentSubagentTool, SUBAGENT_GUIDELINES } from "./primary-tool.js";
+import { registerMessageRenderers } from "./message-renderers.js";
+import { registerDelegationBridges } from "./delegation-bridges.js";
+import { createRuntimeState, ensureAccessibleDir, expandTilde, getSubagentSessionRoot, } from "./runtime-storage.js";
+import { cleanupStaleSubscriptions, EVENT_UNSUBSCRIBES_KEY, isStaleExtensionContextError, removeSharedRuntimeValue, RUNTIME_CLEANUP_KEY, setSharedRuntimeValue, visibleControlNotices, } from "./runtime-reload.js";
+const TOOL_NAMES = ["subagent", "delegate", "agent_runs"];
+/** Owns one extension runtime's session projection, timers, delivery, subscriptions and UI. */
+export class ParentSubagentRuntime {
+    pi;
+    config;
+    state;
+    tracker;
+    executor;
+    agentView;
+    parentUsage;
+    completionDelivery;
+    adaptToolResult;
+    bridges;
+    visibleNotices = visibleControlNotices();
+    pendingIdleNotices = new Map();
+    pendingReconciliations = new Set();
+    runtimeCleanup = () => this.cleanupRuntime();
+    eventUnsubscribes = [];
+    sessionReset;
+    reconcileTools = () => Promise.resolve();
+    constructor(pi, config) {
+        this.pi = pi;
+        this.config = config;
+        this.state = createRuntimeState(pi);
+        this.tracker = createAsyncJobTracker(pi, this.state, ASYNC_DIR, {
+            render: () => {
+                this.refreshView();
+            },
+        });
+        this.executor = createSubagentExecutor({
+            pi,
+            state: this.state,
+            config,
+            asyncByDefault: config.asyncByDefault !== false,
+            tempArtifactsDir: getArtifactsDir(null),
+            getSubagentSessionRoot,
+            expandTilde,
+            discoverAgents,
+            ensureSessionState: (ctx) => this.ensureSession(ctx),
+        });
+        this.agentView = new AgentViewController(pi, this.state, (params, ctx) => this.executor.execute({ toolCallId: randomUUID(), params, ctx }));
+        this.parentUsage = registerParentUsage(pi, TOOL_NAMES);
+        this.completionDelivery = createCompletionDelivery(pi, this.state, this.parentUsage);
+        this.adaptToolResult = registerToolResultAdapter(pi, TOOL_NAMES);
+        this.bridges = registerDelegationBridges({
+            events: pi.events,
+            getContext: () => this.state.lastUiContext,
+            executor: this.executor,
+        });
+        setSharedRuntimeValue(RUNTIME_CLEANUP_KEY, this.runtimeCleanup);
+    }
+    register() {
+        registerMessageRenderers(this.pi);
+        this.registerTools();
+        registerSlashCommands(this.pi, this.state);
+        this.registerRunEvents();
+        this.registerSessionEvents();
+    }
+    registerTools() {
+        const asyncByDefault = this.config.asyncByDefault !== false;
+        const adapt = (result, ctx) => adaptFinalizedToolResult(result, ctx, this.parentUsage, this.adaptToolResult);
+        this.reconcileTools = registerCompactSubagentTools(this.pi, {
+            executor: this.executor,
+            state: this.state,
+            adapt,
+            guidelines: SUBAGENT_GUIDELINES,
+            asyncByDefault,
+            getHistoryIndex: () => runHistoryIndex(this.state),
+        });
+        this.state.onRunsChanged = () => {
+            this.reconcileInBackground();
+            this.refreshView();
+        };
+        registerParentSubagentTool(this.pi, {
+            executor: this.executor,
+            adapt,
+            config: this.config,
+            asyncByDefault,
+        });
+    }
+    refreshView() {
+        this.agentView.refresh().catch((error) => {
+            console.error("Could not refresh subagent view:", error);
+        });
+    }
+    reconcileInBackground() {
+        const operation = this.reconcileTools();
+        this.pendingReconciliations.add(operation);
+        operation
+            .finally(() => {
+            this.pendingReconciliations.delete(operation);
+        })
+            .catch((error) => {
+            console.error("Could not reconcile subagent run controls:", error);
+        });
+    }
+    deliverControlNotice(details) {
+        handleSubagentControlNotice({
+            pi: this.pi,
+            visibleControlNotices: this.visibleNotices,
+            details,
+        });
+    }
+    controlEvent(data) {
+        const details = parseControlNotice(data);
+        if (!details) {
+            return;
+        }
+        // Keep idle references out of Pi's active turn queue until its native settle boundary.
+        if (details.source === "async" &&
+            details.event.reason === "idle" &&
+            !details.event.supervisorQuestion &&
+            this.state.lastUiContext &&
+            !this.state.lastUiContext.isIdle()) {
+            this.pendingIdleNotices.set(`${details.event.runId}:${details.event.index ?? ""}`, details);
+            return;
+        }
+        this.deliverControlNotice(details);
+    }
+    flushIdleNotices() {
+        for (const details of this.pendingIdleNotices.values()) {
+            this.deliverControlNotice(details);
+        }
+        this.pendingIdleNotices.clear();
+    }
+    startedEvent(data) {
+        this.tracker.handleStarted(data);
+        if (!isRecord(data) || typeof data.id !== "string" || data.id.length === 0) {
+            return;
+        }
+        const run = this.state.ownedRuns?.get(data.id);
+        if (run) {
+            rememberOwnedRun(this.state, {
+                ...run,
+                source: "async",
+                asyncDir: typeof data.asyncDir === "string" ? data.asyncDir : undefined,
+                pid: typeof data.pid === "number" ? data.pid : undefined,
+            });
+        }
+    }
+    subscribeEvents() {
+        this.eventUnsubscribes = [];
+        setSharedRuntimeValue(EVENT_UNSUBSCRIBES_KEY, this.eventUnsubscribes);
+        // Retain each successful subscription even if a later registration fails.
+        this.eventUnsubscribes.push(this.pi.events.on(SUBAGENT_ASYNC_STARTED_EVENT, (data) => this.startedEvent(data)));
+        this.eventUnsubscribes.push(this.pi.events.on(SUBAGENT_ASYNC_COMPLETE_EVENT, this.tracker.handleComplete));
+        this.eventUnsubscribes.push(this.pi.events.on(SUBAGENT_CONTROL_EVENT, (data) => this.controlEvent(data)));
+    }
+    registerRunEvents() {
+        cleanupStaleSubscriptions();
+        this.subscribeEvents();
+        this.pi.on("turn_end", () => this.flushIdleNotices());
+        this.pi.on("agent_before_settle", () => this.flushIdleNotices());
+        this.pi.on("context", (event) => ({
+            messages: event.messages.filter((message) => {
+                if (message.role !== "custom" || message.customType !== SUBAGENT_CONTROL_MESSAGE_TYPE) {
+                    return true;
+                }
+                const notice = parseControlNotice(message.details);
+                return !notice || !isObsoleteIdleNotice(notice);
+            }),
+        }));
+        this.pi.on("tool_result", (event, ctx) => {
+            if (!TOOL_NAMES.includes(event.toolName) || !isTuiContext(ctx)) {
+                return;
+            }
+            this.state.lastUiContext = ctx;
+            if (this.state.asyncJobs.size > 0) {
+                this.refreshView();
+                const ui = ctx.ui;
+                ui.requestRender?.();
+                this.tracker.ensurePoller();
+            }
+        });
+    }
+    registerSessionEvents() {
+        this.pi.on("session_start", async (_event, ctx) => {
+            if (this.eventUnsubscribes.length === 0) {
+                this.subscribeEvents();
+            }
+            await this.resetSession(ctx);
+            await this.reconcileTools();
+        });
+        this.pi.on("session_shutdown", () => this.shutdown());
+    }
+    stopPoller() {
+        if (this.state.poller) {
+            clearInterval(this.state.poller);
+        }
+        this.state.poller = null;
+    }
+    cleanupRuntime() {
+        this.agentView.dispose();
+        closeRunHistory(this.state).catch((error) => {
+            console.error("Could not close subagent history:", error);
+        });
+        this.completionDelivery.stop();
+        this.stopPoller();
+    }
+    ensureSession(ctx) {
+        if (this.sessionReset) {
+            return this.sessionReset;
+        }
+        return this.state.currentSessionId !== resolveCurrentSessionId(ctx.sessionManager)
+            ? this.resetSession(ctx)
+            : Promise.resolve();
+    }
+    resetSession(ctx) {
+        if (this.sessionReset) {
+            return this.sessionReset;
+        }
+        this.sessionReset = this.restoreSession(ctx).finally(() => {
+            this.sessionReset = undefined;
+        });
+        return this.sessionReset;
+    }
+    async restoreSession(ctx) {
+        this.pendingIdleNotices.clear();
+        this.agentView.dispose();
+        this.stopPoller();
+        await this.completionDelivery.stopAndJoin();
+        closeRunHistory(this.state).catch((error) => {
+            console.error("Could not close subagent history:", error);
+        });
+        ensureAccessibleDir(RESULTS_DIR);
+        ensureAccessibleDir(ASYNC_DIR);
+        this.state.baseCwd = ctx.cwd;
+        this.state.currentSessionId = resolveCurrentSessionId(ctx.sessionManager);
+        this.state.lastUiContext = ctx;
+        this.tracker.resetJobs();
+        const restoration = await restoreOwnedRunsAsync(this.state, ctx);
+        try {
+            this.tracker.restoreJobs(this.state.currentSessionId, ctx, restoration);
+        }
+        catch (error) {
+            console.error("Failed to restore active async jobs:", error);
+            this.tracker.resetJobs(ctx);
+        }
+        startRunHistory(this.state, ctx);
+        this.reconcileInBackground();
+        this.agentView.start(ctx);
+        await this.cleanupArtifacts(ctx);
+        restoreSlashFinalSnapshots(ctx.sessionManager.getEntries());
+        this.completionDelivery.start();
+    }
+    async cleanupArtifacts(ctx) {
+        await cleanupOldRunStorage();
+        await cleanupOldChainDirs();
+        await cleanupAllArtifactDirs(ARTIFACT_CLEANUP_DAYS);
+        try {
+            const file = ctx.sessionManager.getSessionFile();
+            if (file !== undefined && file.length > 0) {
+                await cleanupOldArtifacts(getArtifactsDir(file), ARTIFACT_CLEANUP_DAYS);
+            }
+        }
+        catch {
+            // Artifact failures must not block native session lifecycle events.
+        }
+    }
+    async shutdown() {
+        // A reset can still publish history, view and delivery after its awaited restoration/cleanup.
+        // Join that owner before disposing the resources it may start.
+        try {
+            await this.sessionReset;
+        }
+        finally {
+            await this.disposeSession();
+        }
+    }
+    async disposeSession() {
+        this.agentView.dispose();
+        this.stopPoller();
+        await this.completionDelivery.stopAndJoin({ preservePending: true });
+        await closeRunHistory(this.state);
+        await Promise.allSettled(this.pendingReconciliations);
+        for (const unsubscribe of this.eventUnsubscribes) {
+            try {
+                unsubscribe();
+            }
+            catch {
+                /* Shutdown also owns already-disposed subscriptions. */
+            }
+        }
+        removeSharedRuntimeValue(EVENT_UNSUBSCRIBES_KEY, this.eventUnsubscribes);
+        this.eventUnsubscribes = [];
+        for (const timer of this.state.cleanupTimers.values()) {
+            clearTimeout(timer);
+        }
+        this.state.cleanupTimers.clear();
+        this.state.asyncJobs.clear();
+        clearSlashSnapshots();
+        this.bridges.slash.cancelAll();
+        this.bridges.slash.dispose();
+        this.bridges.template.cancelAll();
+        this.bridges.template.dispose();
+        removeSharedRuntimeValue(RUNTIME_CLEANUP_KEY, this.runtimeCleanup);
+        this.clearWidget();
+    }
+    clearWidget() {
+        try {
+            if (this.state.lastUiContext && isTuiContext(this.state.lastUiContext)) {
+                this.state.lastUiContext.ui.setWidget(WIDGET_KEY, undefined);
+            }
+        }
+        catch (error) {
+            if (!isStaleExtensionContextError(error)) {
+                throw error;
+            }
+        }
+    }
+}

package/dist/extension/primary-tool.js

@@ -0,0 +1,69 @@
+import { Text } from "@earendil-works/pi-tui";
+import { normalizeSubagentParamsLike, resolveAsyncExecutionMode, } from "../runs/foreground/subagent-executor.js";
+import { applyForceTopLevelAsyncOverride } from "../runs/background/top-level-async.js";
+import { renderSubagentResult } from "../tui/render.js";
+import { SubagentParams } from "./schemas.js";
+export const SUBAGENT_GUIDELINES = [
+    "Use subagent for materially parallelizable scouting, review, or implementation work where another focused agent adds value.",
+    "Top-level subagent execution uses the stock async default unless configuration opts out. Launch a small bounded fanout of independent agents as separate single-agent runs so each completion wakes the parent, with at most one writer. Use one tasks call for non-review fanout when all child results are required together, when shared concurrency/task limits are needed, or when multiple writers require worktree isolation; the parent receives one aggregate completion. If no useful parent work remains, end the turn and wait instead of polling; completion wakes the parent. This also applies when an incomplete active Pi goal needs child evidence: yield, then continue the goal after automatic completion delivery. Set async:false only for explicitly chosen foreground execution.",
+    'Before executing subagent runs, call subagent with { action: "list" } unless the requested executable agent or chain is already known from this conversation.',
+    "Keep the parent session responsible for final decisions, verification, and user-facing status; treat subagent output as evidence to review, not automatic truth.",
+    "Fresh-child handoffs must include relevant exact user instructions and settled decisions or readable source references alongside the bounded task; summaries do not replace original requirements.",
+    "Keep independent review as a separate parent-launched reviewer run after the worker; acceptance.review is unsupported.",
+    "For review-only tasks, omit acceptance unless the user explicitly requests a same-session acceptance contract; acceptance adds a finalization turn and is not independent review.",
+    "For live child guidance, answers, corrections, or blockers, inspect status and prefer action='nudge'; it sends a non-blocking steer that supplements the active task unless the message explicitly replaces it. Use the shown blocking intercom ask only when the parent must stay alive waiting for a reply.",
+    "Do not use subagent when a direct local tool call or small edit is cheaper than delegation.",
+];
+function effectiveParallelTaskCount(tasks) {
+    return (tasks?.reduce((total, task) => total +
+        (typeof task.count === "number" && Number.isInteger(task.count) && task.count >= 1
+            ? task.count
+            : 1), 0) ?? 0);
+}
+function renderManagement(args, theme) {
+    const agent = args.agent ?? "";
+    const target = agent.length > 0 ? agent : (args.chainName ?? "");
+    const title = theme.fg("toolTitle", theme.bold("subagent "));
+    return new Text(`${title}${args.action}${target.length > 0 ? ` ${theme.fg("accent", target)}` : ""}`, 0, 0);
+}
+function renderExecution(args, theme, options) {
+    const title = theme.fg("toolTitle", theme.bold("subagent "));
+    const renderedArgs = applyForceTopLevelAsyncOverride(args, 0, options.config.forceTopLevelAsync === true);
+    const asyncLabel = resolveAsyncExecutionMode(renderedArgs, options.asyncByDefault).effectiveAsync
+        ? theme.fg("warning", " [async]")
+        : "";
+    if (args.chain !== undefined && args.chain.length > 0) {
+        return new Text(`${title}chain (${args.chain.length})${asyncLabel}`, 0, 0);
+    }
+    if (args.tasks !== undefined && args.tasks.length > 0) {
+        return new Text(`${title}parallel (${effectiveParallelTaskCount(args.tasks)})${asyncLabel}`, 0, 0);
+    }
+    const agent = args.agent ?? "";
+    return new Text(`${title}${theme.fg("accent", agent.length > 0 ? agent : "?")}${asyncLabel}`, 0, 0);
+}
+export function registerParentSubagentTool(pi, options) {
+    const tool = {
+        name: "subagent",
+        defaultActive: false,
+        label: "Subagent",
+        description: `Delegate bounded work to configured Pi subagents, chains, or parallel reviewers; manage agent definitions; inspect/control async runs. Indexed status lists support global agent/state/text filters and sort/cursors; history pages bounded native previews and search finds saved visible words or one quoted phrase. Browse freshness is not canonical proof. Use exactly one execution mode (agent, tasks, or chain) or one management/control action. Before execution, use { action: "list" } to inspect configured agents/chains. Only execute agents listed as executable/non-disabled. Parallel tasks support output?,reads?,progress?. maxOutput accepts { bytes?: number, lines?: number }. Prefer acceptance for goal/spec handoffs and status/resume/interrupt/extend/nudge for active runs. Exact status is concise by default; full:true includes the full task/configuration. Review notes are parent-only, not sent to children; put actionable instructions in resume/nudge. Resume/answer preserves saved settings unless agent selects a current profile (including model/thinking/fallbacks); a separate model override wins. Live guidance never mutates model or acceptance.`,
+        parameters: SubagentParams,
+        async execute(id, params, signal, onUpdate, ctx) {
+            return options.adapt(await options.executor.execute({
+                toolCallId: id,
+                params: normalizeSubagentParamsLike(params),
+                signal,
+                onUpdate,
+                ctx,
+            }), ctx);
+        },
+        renderCall: (args, theme) => {
+            if (args.action !== undefined && args.action.length > 0) {
+                return renderManagement({ ...args, action: args.action }, theme);
+            }
+            return renderExecution(args, theme, options);
+        },
+        renderResult: renderSubagentResult,
+    };
+    pi.registerTool(tool);
+}

package/dist/extension/result-snapshot.js

@@ -0,0 +1,22 @@
+/** A new result owns its progress buffers; native messages and accounting stay shared snapshots. */
+export function copyProgress(progress) {
+    return {
+        ...progress,
+        recentTools: progress.recentTools.map((tool) => ({ ...tool })),
+        recentOutput: [...progress.recentOutput],
+    };
+}
+export function copyResult(result) {
+    return { ...result, progress: result.progress ? copyProgress(result.progress) : undefined };
+}
+export function copyDetails(details) {
+    return {
+        ...details,
+        results: details.results.map(copyResult),
+        progress: details.progress?.map(copyProgress),
+    };
+}
+/** Preserve the native result envelope while giving the receiving tool its own content array. */
+export function copyExecutionResult(result) {
+    return { ...result, content: [...result.content] };
+}

package/dist/extension/runtime-reload.js

@@ -0,0 +1,62 @@
+import { isUnknownArray } from "../shared/unknown.js";
+export const RUNTIME_CLEANUP_KEY = "__piSubagentRuntimeCleanup";
+export const EVENT_UNSUBSCRIBES_KEY = "__piSubagentEventUnsubscribes";
+const VISIBLE_NOTICES_KEY = "__piSubagentVisibleControlNotices";
+export function sharedRuntimeValue(key) {
+    return Reflect.get(globalThis, key);
+}
+export function setSharedRuntimeValue(key, value) {
+    if (!Reflect.set(globalThis, key, value)) {
+        throw new Error(`Could not register subagent runtime value '${key}'.`);
+    }
+}
+export function removeSharedRuntimeValue(key, current) {
+    if (sharedRuntimeValue(key) === current) {
+        Reflect.deleteProperty(globalThis, key);
+    }
+}
+function isCallback(value) {
+    return typeof value === "function";
+}
+function cleanupCallback(value) {
+    if (!isCallback(value)) {
+        return;
+    }
+    try {
+        const pending = value();
+        if (pending instanceof Promise) {
+            pending.catch((error) => {
+                console.error("Could not clean stale subagent runtime:", error);
+            });
+        }
+    }
+    catch {
+        // Stale cleanup must not prevent the replacement extension from registering.
+    }
+}
+export function cleanupStaleRuntime(key = RUNTIME_CLEANUP_KEY) {
+    cleanupCallback(sharedRuntimeValue(key));
+}
+export function isStaleExtensionContextError(error) {
+    return error instanceof Error && error.message.includes("Extension context no longer active");
+}
+export function cleanupStaleSubscriptions() {
+    const previous = sharedRuntimeValue(EVENT_UNSUBSCRIBES_KEY);
+    if (isUnknownArray(previous)) {
+        for (const unsubscribe of previous) {
+            cleanupCallback(unsubscribe);
+        }
+    }
+}
+function isStringSet(value) {
+    return value instanceof Set && [...value].every((entry) => typeof entry === "string");
+}
+export function visibleControlNotices() {
+    const previous = sharedRuntimeValue(VISIBLE_NOTICES_KEY);
+    if (isStringSet(previous)) {
+        return previous;
+    }
+    const notices = new Set();
+    setSharedRuntimeValue(VISIBLE_NOTICES_KEY, notices);
+    return notices;
+}

package/dist/extension/runtime-storage.js

@@ -0,0 +1,43 @@
+import * as fs from "node:fs";
+import * as os from "node:os";
+import * as path from "node:path";
+import { OWNED_RUN_ENTRY } from "../runs/shared/run-records.js";
+import { ensureSafeTempPath } from "../shared/temp-root.js";
+export function getSubagentSessionRoot(parentSessionFile) {
+    if (parentSessionFile !== null && parentSessionFile.length > 0) {
+        return path.join(path.dirname(parentSessionFile), path.basename(parentSessionFile, ".jsonl"));
+    }
+    return fs.mkdtempSync(path.join(os.tmpdir(), "pi-subagent-session-"));
+}
+export function expandTilde(value) {
+    return value.startsWith("~/") ? path.join(os.homedir(), value.slice(2)) : value;
+}
+export function ensureAccessibleDir(dir) {
+    ensureSafeTempPath(dir);
+    fs.mkdirSync(dir, { recursive: true });
+    fs.accessSync(dir, fs.constants.R_OK | fs.constants.W_OK);
+}
+export function createRuntimeState(pi) {
+    return {
+        baseCwd: "",
+        currentSessionId: null,
+        asyncJobs: new Map(),
+        foregroundRuns: new Map(),
+        ownedRuns: new Map(),
+        persistOwnedRun: (run) => {
+            pi.appendEntry(OWNED_RUN_ENTRY, run);
+        },
+        cleanupTimers: new Map(),
+        lastUiContext: null,
+        poller: null,
+        completionSeen: new Map(),
+        watcher: null,
+        watcherRestartTimer: null,
+        resultFileCoalescer: {
+            schedule: () => false,
+            clear: () => {
+                /* The async tracker installs a real coalescer when its watcher starts. */
+            },
+        },
+    };
+}

package/dist/extension/schema-overrides.js

@@ -0,0 +1,75 @@
+import { Type } from "../shared/native-typebox.js";
+import { AcceptanceOverride } from "./acceptance-schema.js";
+export const requiredObject = (...required) => ({ type: "object", required });
+export const SkillOverride = Type.Unsafe({
+    anyOf: [
+        { type: "array", items: { type: "string", minLength: 1 } },
+        { type: "boolean" },
+        { type: "string" },
+    ],
+    description: "Skill name(s): string, comma-separated string, array, or false to disable",
+});
+export const OutputOverride = Type.Unsafe({
+    anyOf: [{ type: "string", minLength: 1 }, { type: "boolean" }],
+    description: "Output file path, or false to disable file output.",
+});
+export const OutputModeOverride = Type.Enum(["inline", "file-only"], {
+    type: "string",
+    description: "inline (default) or file-only; file-only requires output to be a path.",
+});
+export const ReadsOverride = Type.Unsafe({
+    anyOf: [{ type: "array", items: { type: "string", minLength: 1 } }, { type: "boolean" }],
+    description: "Files to read before running, or false to disable",
+});
+export const JsonSchemaObject = Type.Unsafe({
+    type: "object",
+    additionalProperties: true,
+    description: "JSON Schema (object root) for strict structured output.",
+});
+export const ModelOverride = Type.Optional(Type.String({
+    description: 'Profiles are defaults; warranted overrides are allowed subject to user instructions and provider authorization. Use model: "provider/model:high" to pin route/effort (no profile fallbacks; same-choice transport retries remain). Omit for profile fallbacks. No standalone thinking argument.',
+}));
+export const TaskItem = Type.Object({
+    agent: Type.String({ minLength: 1 }),
+    task: Type.String({ minLength: 1 }),
+    label: Type.Optional(Type.String({
+        minLength: 1,
+        description: "Short task label for the Agents strip and conversation.",
+    })),
+    cwd: Type.Optional(Type.String()),
+    count: Type.Optional(Type.Integer({ minimum: 1, description: "Repeat this parallel task N times." })),
+    outputSchema: Type.Optional(JsonSchemaObject),
+    output: Type.Optional(OutputOverride),
+    outputMode: Type.Optional(OutputModeOverride),
+    reads: Type.Optional(ReadsOverride),
+    progress: Type.Optional(Type.Boolean({ description: "Enable progress.md tracking for this task" })),
+    model: ModelOverride,
+    skill: Type.Optional(SkillOverride),
+    acceptance: Type.Optional(AcceptanceOverride),
+}, { additionalProperties: false });
+export const HistoryQueryFields = {
+    cursor: Type.Optional(Type.String({
+        minLength: 1,
+        description: "Opaque page cursor returned by list/history/search; expires when the indexed snapshot changes.",
+    })),
+    sort: Type.Optional(Type.Enum(["attention", "newest", "oldest", "relevance"], {
+        type: "string",
+        description: "List: attention (default), newest, oldest. Search: relevance (default), newest.",
+    })),
+    state: Type.Optional(Type.Enum(["live", "completed", "failed", "blocked", "paused", "unknown"], {
+        type: "string",
+        description: "List only: execution-state filter, applied before paging.",
+    })),
+    text: Type.Optional(Type.String({
+        minLength: 1,
+        description: "List only: filter saved task/assignment text before paging.",
+    })),
+    query: Type.Optional(Type.String({
+        minLength: 1,
+        description: "Search visible saved text using 1–12 lexical words (all must match) or one double-quoted phrase. Operators, punctuation and prefixes are rejected. Thinking, images, tool arguments and hidden data are excluded.",
+    })),
+    before: Type.Optional(Type.Integer({
+        minimum: 1,
+        description: "History only: exclusive native-entry position returned by the earlier page; omit for the latest page.",
+    })),
+};