@cerebriline/core 4.100.240

package/dist/extensions/tools/task-progress.d.ts

@@ -0,0 +1,217 @@
+/**
+ * Task progress — the checklist the model keeps while it works.
+ *
+ * A run that starts by naming the work and then does it in order behaves very
+ * differently from one that discovers the work as it goes. The difference is
+ * not that the model is incapable of planning: it plans fine, and then loses
+ * the plan, because nothing carries it forward. What comes out the far end is
+ * the "wait, I also have to fix..." style of run, where each turn re-derives
+ * the goal from whatever is nearest.
+ *
+ * So this module is two things that have to exist together. A checklist the
+ * model can write as a side effect of work it is already doing — an optional
+ * `task_progress` parameter on every tool, so keeping the list current never
+ * costs a round trip — and a reminder that puts the list back in front of the
+ * model every few calls. The list alone is a display feature; the reminder is
+ * what changes behaviour.
+ *
+ * The parameter is added to the JSON schema rather than the zod schema on
+ * purpose: several tools validate with `.refine(...)`, which has no `.extend`,
+ * and every tool strips unknown keys before `execute` sees them. Capture
+ * therefore reads the *raw* input in a decorator that runs before the tool's
+ * own validation.
+ */
+import type { AgentTool } from "@cerebriline/shared";
+/** The wire name of the checklist parameter, shared with the host. */
+export declare const TASK_PROGRESS_PARAM = "task_progress";
+/**
+ * How often the checklist is put back in front of the model, counted in tool
+ * calls. Matches the legacy default (`remindClineInterval`).
+ *
+ * A reminder is not free — it is re-sent text, and at a large context that is
+ * real budget — so the interval trades staleness against cost rather than
+ * being set as low as it can go.
+ */
+export declare const DEFAULT_TASK_PROGRESS_REMINDER_INTERVAL = 6;
+/**
+ * The same reminder, counted in calls that changed the workspace.
+ *
+ * Asked for after a pandorum run that wrote for twenty turns without once
+ * re-marking the list. A read does not finish an item; a write usually does, so
+ * three of them is where the list has most likely gone stale, and it arrives
+ * sooner than the every-six-calls interval in exactly the runs that are doing
+ * the most work. Both counters share one reminder and one reset, so a busy run
+ * is not reminded twice.
+ */
+export declare const DEFAULT_TASK_PROGRESS_WRITE_INTERVAL = 3;
+/**
+ * The description the model reads.
+ *
+ * Written to be answerable at the moment of any tool call, because that is
+ * when it is read: it says what to send the first time (the whole plan) and
+ * what to send afterwards (the same list, re-marked), which is the distinction
+ * models get wrong when told only "keep it updated". It also states the format
+ * exactly, since the list is parsed.
+ */
+export declare const TASK_PROGRESS_PARAM_DESCRIPTION: string;
+/** A single parsed checklist line. */
+export interface TaskProgressItem {
+    text: string;
+    done: boolean;
+}
+/** The checklist as the UI and the reminder consume it. */
+export interface TaskProgressState {
+    /** The raw markdown exactly as the model sent it. */
+    markdown: string;
+    items: TaskProgressItem[];
+    completed: number;
+    total: number;
+}
+/**
+ * Add the checklist parameter to a tool's JSON input schema.
+ *
+ * Returns the schema unchanged when it is not object-shaped, rather than
+ * throwing: a tool with an exotic schema should lose the checklist, not fail
+ * to register.
+ */
+export declare function withTaskProgressParam(inputSchema: Record<string, unknown>): Record<string, unknown>;
+/**
+ * Read the checklist off a raw tool input.
+ *
+ * The field advertises `string`, and two thirds of the time that is what
+ * arrives. The rest of the time the items are all present and the container is
+ * not: measured across 240 pandorum sessions, of 1,920 tool calls carrying the
+ * field **641 -- 33.4% -- were discarded**, as an array (5.8%), as the field
+ * nested inside itself (20.5%), or as a string with no `- [ ]` lines (7.1%).
+ *
+ * That was deliberate once -- "a model that sends the field as an array has not
+ * sent a checklist" -- and the measurement says otherwise: the arrays are the
+ * parsed form, just not joined with newlines. Nothing here invents an item. A
+ * container it cannot read still returns `undefined`, and a checklist with no
+ * usable entry is still nothing.
+ *
+ * The silence is what made this expensive. No error is returned for a dropped
+ * payload, so `task_progress` reports a 0% failure rate either way.
+ */
+export declare function readTaskProgress(input: unknown): string | undefined;
+/**
+ * Parse a markdown checklist.
+ *
+ * Only `- [ ]` / `- [x]` lines become items. Models routinely wrap the list in
+ * a heading or a sentence, and treating those as unchecked items would report
+ * work that does not exist and never complete.
+ */
+export declare function parseTaskProgress(markdown: string): TaskProgressItem[];
+/** Build the full checklist state from raw markdown. */
+export declare function buildTaskProgressState(markdown: string): TaskProgressState;
+/**
+ * Render the reminder appended to a tool result.
+ *
+ * Sent as the checklist the model itself wrote, not as an instruction about
+ * checklists: the model already has the parameter description for that, and
+ * repeating advice every few calls trains it to skim the block. What it needs
+ * back is the *content* — which of its own steps are still open.
+ */
+export declare function buildTaskProgressReminder(state: TaskProgressState): string;
+/**
+ * Find the most recent checklist in a transcript.
+ *
+ * Structurally typed rather than importing the message types: this reads one
+ * optional field out of tool-call inputs, and every shape it walks is
+ * defensively narrowed, so tying it to a concrete Message union would buy
+ * nothing but a dependency.
+ */
+export declare function findLatestTaskProgress(messages: readonly {
+    content?: unknown;
+}[] | undefined): string | undefined;
+/**
+ * The nudge sent when a run is about to end with checklist items still open.
+ *
+ * Measured: a 58-minute run set the checklist once, on its 11th message of 137,
+ * and never touched it again — finishing with "Fix syntax errors" and "Verify
+ * fix with browser" unticked, both of which it had in fact done. The list is
+ * written as a side effect of a tool call, so once the model stops passing
+ * `task_progress` nothing ever ticks the boxes, and the panel ends the run
+ * reading as though the task failed.
+ *
+ * Two outcomes are acceptable and the message names both, because the checklist
+ * being stale and the work being unfinished are genuinely different situations
+ * and only the model knows which one it is in.
+ */
+export declare function buildTaskProgressCloseOutNudge(state: TaskProgressState, attempt?: 1 | 2): string;
+/**
+ * A `completionPolicy.completionGuard` that will not let a run end quietly on a
+ * checklist with open items.
+ *
+ * Stops as soon as the checklist is closed: the second ask only happens if the
+ * first one changed nothing, so a model that ticks the boxes never sees it.
+ * After the budget is spent, the ordinary no-tool-call nudge and its own budget
+ * take over.
+ */
+export declare function createTaskProgressCompletionGuard(tracker: TaskProgressTracker): () => string | undefined;
+/** Whether a tool has already been wrapped for checklist capture. */
+export declare function isTaskProgressWrapped(tool: object): boolean;
+export interface TaskProgressTrackerOptions {
+    /** Tool calls between reminders. Zero or less disables reminding. */
+    reminderInterval?: number;
+    /**
+     * Workspace-changing calls between reminders. Zero or less disables that
+     * half, leaving the plain interval above.
+     */
+    writeInterval?: number;
+    /** Called whenever the model sends a new checklist. */
+    onUpdate?: (state: TaskProgressState) => void;
+}
+/**
+ * Holds the current checklist for a session and decides when to remind.
+ *
+ * The reminder counter advances on every tool call, not only on calls that
+ * carried a checklist — a model that has stopped updating the list is exactly
+ * the one that needs to see it again.
+ */
+export declare class TaskProgressTracker {
+    private state;
+    private callsSinceReminder;
+    private writesSinceReminder;
+    private readonly reminderInterval;
+    private readonly writeInterval;
+    private readonly onUpdate;
+    constructor(options?: TaskProgressTrackerOptions);
+    /** The checklist as last sent, or undefined if the model never sent one. */
+    getState(): TaskProgressState | undefined;
+    /**
+     * Restore the checklist from history without treating it as a fresh update.
+     *
+     * The tracker is per-session memory, so a resumed task would otherwise come
+     * back with an empty list and the model would be reminded of nothing. It
+     * does not need to be persisted separately: every call that carried a
+     * checklist is already in the transcript, so history is the durable copy and
+     * this is a cache being warmed from it. Silent by design — a restore is not
+     * the model saying something new, and firing `onUpdate` would replay a
+     * checklist message the UI already has.
+     *
+     * Only fills an empty tracker; a live checklist is never overwritten by an
+     * older one from history.
+     */
+    hydrate(markdown: string | undefined): void;
+    /**
+     * Record one tool call. Returns the reminder to append to its result, or
+     * undefined.
+     *
+     * A call that carried a checklist never also gets a reminder: the model just
+     * demonstrated it has the list, and echoing it straight back is pure cost.
+     */
+    recordToolCall(input: unknown, toolName?: string): string | undefined;
+}
+/**
+ * Wrap a tool so its calls feed the tracker and its results carry reminders.
+ *
+ * The wrapper sits outside the tool's own validation, which is the only place
+ * the checklist is still visible: every tool strips keys its schema does not
+ * name, so by the time `execute` runs the field is gone.
+ *
+ * Reminders are only appended to string results. A tool that returns structured
+ * output has a shape its caller parses, and appending prose to that would break
+ * the consumer to nudge the model — the wrong trade.
+ */
+export declare function withTaskProgressCapture<TInput, TOutput>(tool: AgentTool<TInput, TOutput>, tracker: TaskProgressTracker): AgentTool<TInput, TOutput>;

package/dist/extensions/tools/team/agent-admission.d.ts

@@ -0,0 +1,127 @@
+/**
+ * Asking the engine whether one more agent fits, before spending a prefill
+ * finding out that it does not.
+ *
+ * opencoti's admission gate refuses a saturated pool with `429` + `Retry-After`,
+ * and the retry middleware in `@cerebriline/llms` waits that out. This is the other
+ * half, and the better one: a request that is going to be refused is a request
+ * worth not sending. `GET /polykv/pools/{id}/capacity` answers directly --
+ * `can_admit`, and `headroom_sessions` for how many more the pool will take --
+ * which is the contract the reference fan-out node is built on (FS-H1:
+ * "bounds the round by /capacity -- headroom_sessions caps, hard reject holds
+ * all").
+ *
+ * THE ONE RULE THIS FILE EXISTS TO ENFORCE: on c7, every `GET /capacity` folds
+ * the settle and bias EWMAs. It is not a read -- it advances the learner. A
+ * client that polls it corrupts the measurement it is asking for, and then acts
+ * on the corrupted answer. So capacity is read exactly once per round, where a
+ * round is the burst of spawns between one quiescent point and the next, and
+ * the agents in that round draw from that one answer. Nothing else in this
+ * codebase may call it. (c8 makes the GET read-only and moves the fold behind
+ * `?fold=1`; this file does not need to change when it does, it just stops
+ * being load-bearing.)
+ *
+ * A hold is not a failure. The engine is describing this moment, and a held
+ * agent has not started, so there is nothing to fail -- it waits for one of its
+ * siblings to finish and goes then. That is the difference between pacing a
+ * swarm and killing it, and it is the whole reason this sits before the spawn
+ * rather than after the refusal.
+ */
+import type { PolykvCapacity } from "@cerebriline/llms";
+/** What one capacity read says, in the only three terms this file acts on. */
+export interface AdmissionCapacity {
+    /** Whether the engine would take one more right now. */
+    canAdmit: boolean;
+    /**
+     * How many more it would take. Negative means the engine has no
+     * measurement yet -- which is NOT "none": clamping `-1` to `0` is what told
+     * an empty server it was full (c8 T9), and it must read as "unbounded by
+     * this signal" instead.
+     */
+    headroomSessions: number;
+    /**
+     * Why, in the engine's own words. Carried back verbatim: the engine keeps
+     * `elastic_reason` distinct from `kv headroom exhausted` precisely so a
+     * caller can tell "raise --max-parallel" from "this context does not fit",
+     * and collapsing them into one word throws that away.
+     */
+    reason: string;
+}
+/**
+ * Read a `/capacity` payload into the three terms this file acts on.
+ *
+ * Both absences are deliberate readings, not defaults of convenience. A
+ * missing `can_admit` is a pool with an advisory policy -- the engine
+ * reporting rather than gating -- and reading it as a refusal would hold every
+ * agent on a server that never says no. A missing or negative
+ * `headroom_sessions` is the engine saying it has no measurement yet, which is
+ * the `-1` that must not be clamped to zero (c8 T9).
+ */
+export declare function admissionFromCapacity(capacity: Partial<PolykvCapacity> | undefined): AdmissionCapacity | undefined;
+export interface AgentAdmissionController {
+    /**
+     * Resolves when this agent may start, having waited however long the
+     * engine's answer required. Rejects only on cancellation.
+     */
+    acquire(signal?: AbortSignal): Promise<{
+        reason: string;
+    }>;
+    /**
+     * The same question, answered instead of waited on.
+     *
+     * `undefined` where {@link acquire} would have held. A supervisor that
+     * re-checks on a tick needs an answer rather than a wait, or the first
+     * refusal stalls the loop whose whole job is to ask again later.
+     *
+     * **It reads the engine only when the answer could have changed.** On c7
+     * every `GET /capacity` folds the settle and bias EWMAs, so a 5-second tick
+     * that reached the wire would fold the learner twelve times a minute for
+     * the life of the swarm and corrupt the measurement it is reading. What
+     * changes the answer is an agent finishing, so a fresh read is bought by a
+     * {@link release} and by nothing else -- not by time passing.
+     */
+    tryAcquire(): Promise<{
+        reason: string;
+    } | undefined>;
+    /**
+     * Whether one more could start right now — **without taking the slot**.
+     *
+     * For a caller that is deciding whether to launch, where something else
+     * does the real acquiring: a swarm supervisor asks this, and the worker it
+     * launches then acquires through its own gate. Consuming here would book
+     * every worker twice and halve the round.
+     *
+     * Reads under the same discipline as {@link tryAcquire}: a fresh answer is
+     * bought by an agent finishing, never by time passing.
+     */
+    canAdmitMore(): Promise<boolean>;
+    /** Called when an admitted agent finishes, however it finished. */
+    release(): void;
+}
+interface AdmissionLogger {
+    log?(message: string, meta?: Record<string, unknown>): void;
+}
+export interface AgentAdmissionOptions {
+    /**
+     * One capacity read. `undefined` for "could not be asked" -- an unreachable
+     * control plane, or an endpoint with no pool -- which admits rather than
+     * holds, matching the engine's own default when its internal capacity check
+     * fails (it warns and admits; only `--polykv-adm-on-error deny` refuses).
+     */
+    capacity: () => Promise<AdmissionCapacity | undefined>;
+    /**
+     * How long a held agent waits before asking again, when no sibling is
+     * running to release it.
+     *
+     * Only reached when the whole round is held and nothing is outstanding, so
+     * there is no release coming. Long enough that re-asking does not become
+     * the poll this file forbids.
+     */
+    holdRetryMs?: number;
+    logger?: AdmissionLogger;
+    /** Seam for tests; the real one is abort-aware. */
+    sleep?: (ms: number, signal?: AbortSignal) => Promise<void>;
+}
+export declare const DEFAULT_ADMISSION_HOLD_RETRY_MS = 2000;
+export declare function createAgentAdmissionController(options: AgentAdmissionOptions): AgentAdmissionController;
+export {};

package/dist/extensions/tools/team/agent-check.d.ts

@@ -0,0 +1,152 @@
+/**
+ * The lead's check on a delegated agent: a command and what its output must
+ * say, run when the agent says it is done.
+ *
+ * The same thing the change protocol's approved check is, with the same
+ * runner (`runtime/atomic/oracle.ts`) and the same semantics: it runs once at
+ * each completion attempt; on a fail the agent is shown the output and goes on
+ * working, within its iteration budget; on a pass -- or when the budget is
+ * spent -- the verdict goes into the agent's report. What an agent's own "it
+ * works now" is worth was measured across the atomic campaign: routinely
+ * nothing, because a model reports on the edit it meant to make.
+ *
+ * Where it runs is the part that differs. A delegated agent works on a private
+ * overlay of the workspace, so the lead's files do not hold its work, and a
+ * check run on them judges nothing the agent did. The check runs where the
+ * agent's own shell runs: under the sandbox launcher (`wrapSpawn`), which maps
+ * the workspace onto the agent's overlay. Where there is no launcher -- no
+ * sandbox on this platform, or "Agents can run commands" off -- the check is
+ * NOT run on the host instead: every delegated command runs sandboxed, and an
+ * unsandboxed one would both read the wrong files and be free to write the
+ * real ones. The report says "not run: no command sandbox".
+ */
+import { z } from "zod";
+import { type OracleSpawnWrapper, runOracle } from "../../../runtime/atomic/oracle";
+/** What the lead writes: a command, a pattern, and which way it must go. */
+export interface AgentCheck {
+    command: string;
+    /** A regular expression, matched against stdout and stderr together. */
+    expect: string;
+    /** `match` (default): the output must match. `not_match`: it must not. */
+    must?: "match" | "not_match";
+}
+/** The check as a tool field; see {@link readAgentCheck} for what is tolerated. */
+export declare const AgentCheckSchema: z.ZodObject<{
+    command: z.ZodString;
+    expect: z.ZodString;
+    must: z.ZodOptional<z.ZodEnum<{
+        match: "match";
+        not_match: "not_match";
+    }>>;
+}, z.core.$strip>;
+/** How the check came out, in the agent's report. */
+export interface AgentOracleResult {
+    status: "pass" | "fail" | "not_run";
+    command: string;
+    expect: string;
+    must: "match" | "not_match";
+    /** Exit status of the last run; `null` when it could not start or was not run. */
+    exitCode: number | null;
+    /** The end of the last run's output, bounded. */
+    output: string;
+    /** How many completion attempts it judged. */
+    runs: number;
+    /** Why it was not run, or what stopped it being re-run. */
+    reason?: string;
+}
+/** Most of a check's output kept for the report and the agent. */
+export declare const AGENT_CHECK_OUTPUT_TAIL_CHARS = 1500;
+/**
+ * Identical failing verdicts in a row after which the check stops holding the
+ * agent back.
+ *
+ * Needed because the default iteration cap is none: a check that cannot pass
+ * (a pattern the fixed program never prints -- measured on the change
+ * protocol's auto-approved checks) would otherwise keep an uncapped agent at
+ * it forever. A check re-run over output that has not moved cannot say
+ * anything the run before it did not, which is the change protocol's own
+ * stalled-check rule. The agent is let finish; the verdict stays `fail`.
+ */
+export declare const AGENT_CHECK_MAX_IDENTICAL_FAILS = 3;
+/**
+ * Failing runs in a row where the shell did not find the check's program,
+ * after which the agent is let finish and the check counts as not run.
+ */
+export declare const AGENT_CHECK_MAX_UNRESOLVED = 2;
+/** Whether a failed run says the shell never found the program. */
+export declare function checkCommandUnresolved(verdict: {
+    exitCode: number | null;
+    output: string;
+}): boolean;
+/** The reason a check is not run when the agent has no sandboxed shell. */
+export declare const AGENT_CHECK_NO_SANDBOX = "no command sandbox";
+/**
+ * The check as the lead wrote it, read tolerantly, or `undefined` for none.
+ *
+ * Models send tool arguments in more shapes than the schema names: the object
+ * as JSON text, `cmd` for `command`, `pattern` or `regex` for `expect`, a
+ * pattern wrapped in slashes, `must: "not-match"`. Each of those has only one
+ * reading, so it is taken. What cannot be read -- no command, or a pattern
+ * that will not compile -- is refused with the reason, at spawn time: a check
+ * that fails every run for a typo would hold the agent to work it can never
+ * finish.
+ */
+export declare function readAgentCheck(raw: unknown): AgentCheck | undefined;
+/**
+ * What the agent is told up front, at the end of its task, so it can run the
+ * check itself before it says it is done.
+ */
+export declare function describeAgentCheck(check: AgentCheck, canRun: boolean): string;
+export interface DelegatedAgentCheck {
+    readonly check: AgentCheck;
+    /** Whether it will actually be run: a sandboxed shell to run it in. */
+    readonly canRun: boolean;
+    /** For the agent's `completionPolicy.onCompletionAttempt`. */
+    onCompletionAttempt(context: {
+        text?: string;
+        forced?: boolean;
+    }): Promise<string | undefined>;
+    /** The verdict so far; `undefined` before any completion attempt. */
+    result(): AgentOracleResult | undefined;
+    /**
+     * Stop judging: the run is over, and anything that follows on the same
+     * conversation -- the summary asked for the lead -- is not a completion
+     * attempt of the task.
+     */
+    close(): void;
+}
+export interface CreateDelegatedAgentCheckOptions {
+    check: AgentCheck;
+    /** The workspace root, which the launcher maps onto the agent's overlay. */
+    cwd: string;
+    /**
+     * The agent's sandboxed shell launcher. Absent means no command sandbox,
+     * and the check is reported as not run -- never run on the host instead.
+     */
+    wrapSpawn?: OracleSpawnWrapper;
+    timeoutMs?: number;
+    /** Test seam: the runner. The change protocol's by default. */
+    run?: typeof runOracle;
+}
+/**
+ * A check bound to one agent: its launcher, its counters, its verdict.
+ */
+export declare function createDelegatedAgentCheck(options: CreateDelegatedAgentCheckOptions): DelegatedAgentCheck;
+/** Its task reads as review and report only, with nothing to change. */
+export declare function isReviewOnlyTask(text: string): boolean;
+/**
+ * Agents given a check they cannot pass by doing what they were asked.
+ *
+ * A check judges an agent's copy of the workspace, so it measures edits; a
+ * reviewer's job leaves the copy as it was, and every "done" is sent back to
+ * work by a check that still fails. Six reviewers in swarm czbnh ended on a
+ * failing check after editing the file they were told to review, and ground
+ * on until the lead stopped them. Warned, not refused: the heuristic reads
+ * words, and the lead may mean it.
+ */
+export declare function reviewOnlyCheckWarning(members: ReadonlyArray<{
+    name: string;
+    task: string;
+    instructions?: string;
+    check?: AgentCheck;
+}>): string | undefined;

package/dist/extensions/tools/team/agent-controls.d.ts

@@ -0,0 +1,55 @@
+/**
+ * The two per-agent controls every spawn tool offers the lead:
+ * `max_iterations` (see `agent-iteration-cap.ts`) and `check` (see
+ * `agent-check.ts`). Stated once here so that `spawn_agent`, its batch
+ * entries, configured agents and `spawn_swarm` read them -- and describe them
+ * -- the same way.
+ */
+import { z } from "zod";
+/** Highest cap accepted; anything above is a typo, not a plan. */
+export declare const MAX_ITERATIONS_CEILING = 100000;
+export declare const MaxIterationsField: z.ZodOptional<z.ZodUnion<readonly [z.ZodNumber, z.ZodString]>>;
+/**
+ * The controls a spawn tool offers the lead: its check.
+ *
+ * `max_iterations` is not offered (user ruling, 2026-09-28). No agent the lead
+ * launches is capped by default, and a lead given the field set one anyway --
+ * 25 on every agent of pandorum's h0o2o swarm -- and then reported "7 agents
+ * reached their 25-iteration caps before completing" as a flaw of the harness.
+ * What watches a long run instead is the lead being told every
+ * {@link LEAD_ITERATION_NUDGE_EVERY} iterations to look at it. A cap the user
+ * wrote into an agent file still applies, and a model that sends the field
+ * anyway is ignored rather than refused (see {@link controlFields}).
+ */
+export declare const AgentControlFields: {
+    check: z.ZodOptional<z.ZodObject<{
+        command: z.ZodString;
+        expect: z.ZodString;
+        must: z.ZodOptional<z.ZodEnum<{
+            match: "match";
+            not_match: "not_match";
+        }>>;
+    }, z.core.$strip>>;
+};
+/** Iterations between the notes that ask the lead to look at a long-running agent. */
+export declare const LEAD_ITERATION_NUDGE_EVERY = 60;
+/**
+ * `max_iterations` as a number, or `undefined` for the default.
+ *
+ * Tolerant of what models send: a numeric string, a float (floored), the
+ * camel-cased name. What cannot be a cap -- zero, a negative, words -- is
+ * refused with the reason rather than read as "no cap", which is the one
+ * reading that turns a typo into an unbounded agent.
+ */
+export declare function readMaxIterations(raw: unknown): number | undefined;
+/** The field under either name a model uses for it. */
+export declare function maxIterationsOf(input: unknown): number | undefined;
+/**
+ * How the system works and what the lead's part in it is. Swarm 2026-09-27:
+ * the lead told 50 agents "DO NOT modify any file" for fear of concurrent
+ * edits, gave review-only agents a check they could never pass, and never
+ * applied a single revision -- it did not know that was its job.
+ */
+export declare const AGENT_SANDBOX_ROLE_NOTE = "How agents work: each runs in its own sandboxed copy of the workspace, so any number may read and edit the same files at once -- there is no concurrency problem to avoid, and no reason to forbid edits. Your files stay unchanged: each agent's edits come back to you as revisions. You are the synthesizer, and nothing merges on its own: read each report, inspect its revisions (`read_files` with `revision`), apply what is right (`restore_file`), reconcile agents that disagree, and verify the result yourself. ";
+/** What a spawn tool's description says about the two controls. */
+export declare const AGENT_CONTROLS_NOTE = "Agents run without an iteration cap; you are told every 60 iterations of a long-running one, so you can check on it with `agents_status`. A configured agent whose file sets a cap stops at it and waits for you with its work kept: `resume_agent(agent_ids?)` continues it, or `stop_agents` takes its work as it is. An agent the loop guard stops for sending the same call again waits for you the same way, reported as looping with the call it repeated: resume it with `instructions` saying what to do instead, or restart it. Per agent, or for the whole call (an agent's own wins): `check: {command, expect, must?}` is its oracle, and it is deterministic: when it says it is done, `command` runs in its own sandboxed copy of the workspace and must exit 0 with output matching the regex `expect` (`must: \"not_match\"`: not matching); on a fail it is shown the output and keeps working. It judges only that agent's own copy -- not the merged result, which is yours to check -- and a call-level check applies to every agent of the call: give it per agent to those whose edits it measures, never to review or analysis agents, which cannot pass it. It is told its check up front. Its report gives `iterations`/`maxIterations`, `stopReason` (`iteration_cap` or `loop_guard`) when either ended it, and `oracle` {status, exitCode, output}. ";

package/dist/extensions/tools/team/agent-file.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Writing an agent file to disk.
+ *
+ * The format itself -- the frontmatter order, the quoting, the file name --
+ * lives in `@cerebriline/shared` so the VS Code agent editor and this share one
+ * renderer. Only the part that touches the filesystem is here.
+ */
+import { type AgentFileFields, agentFileName, renderAgentFile, validateAgentFields } from "@cerebriline/shared";
+export type { AgentFileFields };
+export { agentFileName, renderAgentFile, validateAgentFields };
+export interface WriteAgentFileResult {
+    path: string;
+    /** True when a file of the same name was replaced. */
+    overwritten: boolean;
+}
+/**
+ * Write one agent file into `directory`, creating the directory if needed.
+ *
+ * Refuses to replace an existing agent unless told to. A model asked to "create
+ * an agent for network troubleshooting" twice should say the second one is
+ * already there, not silently discard whatever the user had tuned in the first.
+ */
+export declare function writeAgentFile(input: {
+    directory: string;
+    agent: AgentFileFields;
+    overwrite?: boolean;
+    fileExists: (path: string) => Promise<boolean>;
+}): Promise<WriteAgentFileResult>;