@loopingai/core 0.1.0

package/dist/subtasks/delegate.js

@@ -0,0 +1,102 @@
+import { tool } from "ai";
+import { makeDecompositionProposalSchema } from "./decomposition.js";
+/**
+ * The `delegate` tool — the single act by which the main agent hands work to
+ * subagents, and the shape both ends of that act agree on.
+ *
+ * Delegation is a **durable tool call**: a round emits it for real (the model
+ * picks it and fills its input), the Workflow performs it over minutes or hours,
+ * and a later round reassembles the call with its result to keep working. The two
+ * halves are separated by a Workflow boundary, not by a fiction — nothing here is
+ * fabricated on the model's behalf.
+ *
+ * This module owns the tool's identity because every round depends on it
+ * agreeing: a later round pairs a synthesized `tool-result` to an earlier round's
+ * `tool-call` by name and id, and a mismatch would not throw — it would silently
+ * produce a malformed history that the model quietly misreads.
+ */
+export const DELEGATE_TOOL_NAME = "delegate";
+/**
+ * The tool as the model sees it. Deliberately **without `execute`**: the Workflow
+ * performs this call, durably, outside the inference — so there is nothing for the
+ * SDK to run, and the tool loop halts on the call rather than trying to continue
+ * past it. That is what makes it a *control* tool: unlike the agent's work tools
+ * (`recall`, `browser_*`, `set_context`), calling it ends the round.
+ *
+ * Its `inputSchema` is the delegation contract itself, and it is the **only**
+ * declaration of this tool. One schema has to serve both directions — the calls
+ * the model emits now, and the calls reconstructed from durable rows in later
+ * rounds — because a provider cannot be shown two shapes for one tool name in a
+ * single request. See {@link delegateCallInput} for how a durable row is rendered
+ * back into it.
+ *
+ * Built per registry rather than declared as a module constant: both the type
+ * enum in its schema and the catalogue in its description are facts about which
+ * plugins are installed, and in the predecessor repo both were frozen at import
+ * time — which is exactly what made the type set unoverridable.
+ */
+export function makeDelegateTool(types, maxSubtasks) {
+    return tool({
+        description: "Delegate part of the user's request to isolated subagents and acknowledge it. Their results return to you, and you then decide what to do next — answer the user, or delegate again.\n\n" +
+            "Every subtask must name one of these types, and supply the params that type requires:\n" +
+            types.renderTypes(),
+        inputSchema: makeDecompositionProposalSchema(types, maxSubtasks)
+    });
+}
+/**
+ * The call's id, derived from the parent Task and the round that emitted it —
+ * deterministic and replay-safe, the same discipline as the Session message ids
+ * it sits alongside (see {@link file://../history.ts}). Later rounds rebuild it
+ * rather than storing it.
+ */
+export function delegateToolCallId(taskId, round) {
+    return `task:${taskId}:round:${round}:delegate`;
+}
+/**
+ * The draft-local key a reconstructed call uses for a durable Subtask.
+ *
+ * A row does not keep the `localKey` its round's model chose — the data layer
+ * resolved it to a SQLite id and dropped it. So reconstruction derives a stable
+ * key from that id instead: the *same* id the matching outcome carries in
+ * {@link DelegateSubtaskOutcome}, so the model can line each result up with the
+ * work that produced it.
+ */
+function localKeyForId(id) {
+    return `s${id}`;
+}
+/**
+ * Rebuild one round's call input from its durable rows, in stable ordinal order.
+ * Typed as {@link DecompositionProposal} — the same type the model's own calls
+ * are validated into — so the reconstructed call and an emitted one cannot drift
+ * apart in shape.
+ *
+ * `referenceIndexes` is omitted rather than faked: this round's references were
+ * snapshotted verbatim onto the rows when it ran, and the catalog they were
+ * chosen from is long gone.
+ */
+export function delegateCallInput(reply, branches) {
+    return {
+        reply,
+        subtasks: branches.map((branch) => ({
+            localKey: localKeyForId(branch.subtaskId),
+            type: branch.type,
+            prompt: branch.prompt,
+            dependsOn: branch.dependsOn.map(localKeyForId),
+            // Reconstructed verbatim from the row: a later round must see the same
+            // params the call really carried, or it cannot reason about what ran.
+            params: branch.params
+        }))
+    };
+}
+/** Rebuild one round's call result from its durable rows, in stable ordinal order. */
+export function delegateCallOutput(branches) {
+    return branches.map((branch) => ({
+        subtaskId: branch.subtaskId,
+        type: branch.type,
+        status: branch.status,
+        output: branch.status === "completed"
+            ? (branch.resultParts ?? []).map((part) => part.text).join("\n")
+            : null
+    }));
+}
+//# sourceMappingURL=delegate.js.map

package/dist/subtasks/delegate.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"delegate.js","sourceRoot":"","sources":["../../src/subtasks/delegate.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,IAAI,EAAa,MAAM,IAAI,CAAC;AACrC,OAAO,EAAE,+BAA+B,EAAE,MAAM,oBAAoB,CAAC;AASrE;;;;;;;;;;;;;;GAcG;AAEH,MAAM,CAAC,MAAM,kBAAkB,GAAG,UAAU,CAAC;AAE7C;;;;;;;;;;;;;;;;;;GAkBG;AACH,MAAM,UAAU,gBAAgB,CAC9B,KAA0B,EAC1B,WAAmB;IAEnB,OAAO,IAAI,CAAC;QACV,WAAW,EACT,0LAA0L;YAC1L,yFAAyF;YACzF,KAAK,CAAC,WAAW,EAAE;QACrB,WAAW,EAAE,+BAA+B,CAAC,KAAK,EAAE,WAAW,CAAC;KACjE,CAAC,CAAC;AACL,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,kBAAkB,CAAC,MAAc,EAAE,KAAa;IAC9D,OAAO,QAAQ,MAAM,UAAU,KAAK,WAAW,CAAC;AAClD,CAAC;AAED;;;;;;;;GAQG;AACH,SAAS,aAAa,CAAC,EAAa;IAClC,OAAO,IAAI,EAAE,EAAE,CAAC;AAClB,CAAC;AAoBD;;;;;;;;;GASG;AACH,MAAM,UAAU,iBAAiB,CAC/B,KAAa,EACb,QAA6B;IAE7B,OAAO;QACL,KAAK;QACL,QAAQ,EAAE,QAAQ,CAAC,GAAG,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC;YAClC,QAAQ,EAAE,aAAa,CAAC,MAAM,CAAC,SAAS,CAAC;YACzC,IAAI,EAAE,MAAM,CAAC,IAAI;YACjB,MAAM,EAAE,MAAM,CAAC,MAAM;YACrB,SAAS,EAAE,MAAM,CAAC,SAAS,CAAC,GAAG,CAAC,aAAa,CAAC;YAC9C,uEAAuE;YACvE,sEAAsE;YACtE,MAAM,EAAE,MAAM,CAAC,MAAM;SACtB,CAAC,CAAC;KACJ,CAAC;AACJ,CAAC;AAED,sFAAsF;AACtF,MAAM,UAAU,kBAAkB,CAChC,QAA6B;IAE7B,OAAO,QAAQ,CAAC,GAAG,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC;QAC/B,SAAS,EAAE,MAAM,CAAC,SAAS;QAC3B,IAAI,EAAE,MAAM,CAAC,IAAI;QACjB,MAAM,EAAE,MAAM,CAAC,MAAM;QACrB,MAAM,EACJ,MAAM,CAAC,MAAM,KAAK,WAAW;YAC3B,CAAC,CAAC,CAAC,MAAM,CAAC,WAAW,IAAI,EAAE,CAAC,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC;YAChE,CAAC,CAAC,IAAI;KACX,CAAC,CAAC,CAAC;AACN,CAAC"}

package/dist/subtasks/index.d.ts

@@ -0,0 +1,11 @@
+/**
+ * `@loopingai/core/subtasks` — the delegation layer: what a round may hand out,
+ * how a proposal becomes durable drafts, and which of them may run next.
+ */
+export { makeSubtaskTypes, SubtaskParamsError, type SubtaskTypeRegistry } from "./subtask-types.js";
+export { DecompositionValidationError, makeDecompositionProposalSchema, nonBlank, resolveDecomposition } from "./decomposition.js";
+export { DELEGATE_TOOL_NAME, makeDelegateTool, delegateToolCallId, delegateCallInput, delegateCallOutput, type DelegateSubtaskOutcome } from "./delegate.js";
+export { selectWave, type WaveDecision } from "./scheduler.js";
+export { isCatalogEligible, type ReferenceCatalogEntry } from "./catalog.js";
+export * from "./types.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/subtasks/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/subtasks/index.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EACL,gBAAgB,EAChB,kBAAkB,EAClB,KAAK,mBAAmB,EACzB,MAAM,oBAAoB,CAAC;AAE5B,OAAO,EACL,4BAA4B,EAC5B,+BAA+B,EAC/B,QAAQ,EACR,oBAAoB,EACrB,MAAM,oBAAoB,CAAC;AAE5B,OAAO,EACL,kBAAkB,EAClB,gBAAgB,EAChB,kBAAkB,EAClB,iBAAiB,EACjB,kBAAkB,EAClB,KAAK,sBAAsB,EAC5B,MAAM,eAAe,CAAC;AAEvB,OAAO,EAAE,UAAU,EAAE,KAAK,YAAY,EAAE,MAAM,gBAAgB,CAAC;AAE/D,OAAO,EAAE,iBAAiB,EAAE,KAAK,qBAAqB,EAAE,MAAM,cAAc,CAAC;AAE7E,cAAc,YAAY,CAAC"}

package/dist/subtasks/index.js

@@ -0,0 +1,11 @@
+/**
+ * `@loopingai/core/subtasks` — the delegation layer: what a round may hand out,
+ * how a proposal becomes durable drafts, and which of them may run next.
+ */
+export { makeSubtaskTypes, SubtaskParamsError } from "./subtask-types.js";
+export { DecompositionValidationError, makeDecompositionProposalSchema, nonBlank, resolveDecomposition } from "./decomposition.js";
+export { DELEGATE_TOOL_NAME, makeDelegateTool, delegateToolCallId, delegateCallInput, delegateCallOutput } from "./delegate.js";
+export { selectWave } from "./scheduler.js";
+export { isCatalogEligible } from "./catalog.js";
+export * from "./types.js";
+//# sourceMappingURL=index.js.map

package/dist/subtasks/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/subtasks/index.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EACL,gBAAgB,EAChB,kBAAkB,EAEnB,MAAM,oBAAoB,CAAC;AAE5B,OAAO,EACL,4BAA4B,EAC5B,+BAA+B,EAC/B,QAAQ,EACR,oBAAoB,EACrB,MAAM,oBAAoB,CAAC;AAE5B,OAAO,EACL,kBAAkB,EAClB,gBAAgB,EAChB,kBAAkB,EAClB,iBAAiB,EACjB,kBAAkB,EAEnB,MAAM,eAAe,CAAC;AAEvB,OAAO,EAAE,UAAU,EAAqB,MAAM,gBAAgB,CAAC;AAE/D,OAAO,EAAE,iBAAiB,EAA8B,MAAM,cAAc,CAAC;AAE7E,cAAc,YAAY,CAAC"}

package/dist/subtasks/scheduler.d.ts

@@ -0,0 +1,49 @@
+import type { SubtaskId, SubtaskNode } from "./types.js";
+/**
+ * The Phase 2 wave scheduler: given the DAG's current state, decide what runs
+ * next.
+ *
+ * Pure and non-mutating. Skipping nodes blocked by a failed prerequisite is the
+ * parent's job (`skipBlockedSubtasks`, which runs to a fixpoint and owns the
+ * durable writes); this only reads statuses and picks a wave. The Workflow calls
+ * it between durable steps, so it must be a plain function of its input — no I/O,
+ * no clock, no randomness.
+ */
+/** What the Workflow should do with the DAG as it currently stands. */
+export type WaveDecision = 
+/** These nodes' prerequisites all succeeded — run them concurrently, now. */
+{
+    kind: "ready";
+    ids: SubtaskId[];
+}
+/** Every node reached a terminal status. Phase 2 is over. */
+ | {
+    kind: "done";
+}
+/** Non-terminal nodes remain but none can ever run. An invariant violation. */
+ | {
+    kind: "stuck";
+    active: SubtaskId[];
+};
+/**
+ * Select the next wave of dependency-ready Subtasks.
+ *
+ * A node is ready when it is still active and **every** dependency completed
+ * successfully — `completed` specifically, not merely terminal: a dependent must
+ * never run on a failed prerequisite's absent output.
+ *
+ * Ready ids come back in `ordinal` order. The Workflow builds durable step names
+ * from them (`execute:<id>`), and step names are a cache key, so the traversal
+ * that produces them has to be deterministic.
+ *
+ * **On `stuck`:** one "active nodes, none ready" check is the whole safety net. A
+ * cycle, a self-dependency, and a dangling dependency id all manifest identically
+ * here — every node in a cycle waits on a non-completed peer, a self-dependency
+ * waits on its own non-completed self, and an unknown id resolves to `undefined`,
+ * which is not `completed`. None of them are reachable: `createDecomposition`
+ * validates the DAG before it persists a single row. So this is a loud assertion
+ * for a corrupted DAG, not a control path — which is exactly why it is one check
+ * and not three detectors that can never fire.
+ */
+export declare function selectWave(nodes: SubtaskNode[]): WaveDecision;
+//# sourceMappingURL=scheduler.d.ts.map

package/dist/subtasks/scheduler.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"scheduler.d.ts","sourceRoot":"","sources":["../../src/subtasks/scheduler.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,WAAW,EAAiB,MAAM,YAAY,CAAC;AAExE;;;;;;;;;GASG;AAEH,uEAAuE;AACvE,MAAM,MAAM,YAAY;AACtB,6EAA6E;AAC3E;IAAE,IAAI,EAAE,OAAO,CAAC;IAAC,GAAG,EAAE,SAAS,EAAE,CAAA;CAAE;AACrC,6DAA6D;GAC3D;IAAE,IAAI,EAAE,MAAM,CAAA;CAAE;AAClB,+EAA+E;GAC7E;IAAE,IAAI,EAAE,OAAO,CAAC;IAAC,MAAM,EAAE,SAAS,EAAE,CAAA;CAAE,CAAC;AAiB3C;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,UAAU,CAAC,KAAK,EAAE,WAAW,EAAE,GAAG,YAAY,CAa7D"}

package/dist/subtasks/scheduler.js

@@ -0,0 +1,48 @@
+/**
+ * Non-terminal statuses — nodes Phase 2 still owes an outcome for.
+ *
+ * `running` counts as active on purpose. `executeSubtask` accepts a row that is
+ * `pending` **or** `running`: the latter is its ambiguous-retry path, where a
+ * previous attempt crashed mid-execution and the managed child's fingerprint
+ * cache may still hold the terminal result that makes the retry free. So a row
+ * stranded `running` is re-runnable, and treating it as inert would deadlock its
+ * dependents instead of recovering them.
+ */
+const ACTIVE = new Set([
+    "pending",
+    "running"
+]);
+/**
+ * Select the next wave of dependency-ready Subtasks.
+ *
+ * A node is ready when it is still active and **every** dependency completed
+ * successfully — `completed` specifically, not merely terminal: a dependent must
+ * never run on a failed prerequisite's absent output.
+ *
+ * Ready ids come back in `ordinal` order. The Workflow builds durable step names
+ * from them (`execute:<id>`), and step names are a cache key, so the traversal
+ * that produces them has to be deterministic.
+ *
+ * **On `stuck`:** one "active nodes, none ready" check is the whole safety net. A
+ * cycle, a self-dependency, and a dangling dependency id all manifest identically
+ * here — every node in a cycle waits on a non-completed peer, a self-dependency
+ * waits on its own non-completed self, and an unknown id resolves to `undefined`,
+ * which is not `completed`. None of them are reachable: `createDecomposition`
+ * validates the DAG before it persists a single row. So this is a loud assertion
+ * for a corrupted DAG, not a control path — which is exactly why it is one check
+ * and not three detectors that can never fire.
+ */
+export function selectWave(nodes) {
+    const statusById = new Map(nodes.map((n) => [n.id, n.status]));
+    const active = nodes.filter((n) => ACTIVE.has(n.status));
+    if (active.length === 0)
+        return { kind: "done" };
+    const ready = active
+        .filter((n) => n.dependsOn.every((d) => statusById.get(d) === "completed"))
+        .sort((a, b) => a.ordinal - b.ordinal)
+        .map((n) => n.id);
+    if (ready.length === 0)
+        return { kind: "stuck", active: active.map((n) => n.id) };
+    return { kind: "ready", ids: ready };
+}
+//# sourceMappingURL=scheduler.js.map

package/dist/subtasks/scheduler.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"scheduler.js","sourceRoot":"","sources":["../../src/subtasks/scheduler.ts"],"names":[],"mappings":"AAsBA;;;;;;;;;GASG;AACH,MAAM,MAAM,GAA+B,IAAI,GAAG,CAAgB;IAChE,SAAS;IACT,SAAS;CACV,CAAC,CAAC;AAEH;;;;;;;;;;;;;;;;;;;GAmBG;AACH,MAAM,UAAU,UAAU,CAAC,KAAoB;IAC7C,MAAM,UAAU,GAAG,IAAI,GAAG,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC;IAC/D,MAAM,MAAM,GAAG,KAAK,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC;IACzD,IAAI,MAAM,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,EAAE,IAAI,EAAE,MAAM,EAAE,CAAC;IAEjD,MAAM,KAAK,GAAG,MAAM;SACjB,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,SAAS,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,UAAU,CAAC,GAAG,CAAC,CAAC,CAAC,KAAK,WAAW,CAAC,CAAC;SAC1E,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,OAAO,GAAG,CAAC,CAAC,OAAO,CAAC;SACrC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC;IAEpB,IAAI,KAAK,CAAC,MAAM,KAAK,CAAC;QACpB,OAAO,EAAE,IAAI,EAAE,OAAO,EAAE,MAAM,EAAE,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC;IAC5D,OAAO,EAAE,IAAI,EAAE,OAAO,EAAE,GAAG,EAAE,KAAK,EAAE,CAAC;AACvC,CAAC"}

package/dist/subtasks/subtask-types.d.ts

@@ -0,0 +1,100 @@
+import { z } from "zod";
+import type { DelegationNames, ResolvedRecipe, SubtaskParams, SubtaskTypeSpec } from "../contract/recipe.js";
+/**
+ * The **closed set of subtask types** the main agent may delegate, as the
+ * runtime uses it: lookup, the delegate enum, param validation, and the
+ * catalogue the delegating model is shown.
+ *
+ * The set is not declared here, and — unlike the predecessor repo — it is not a
+ * module constant. There, `SUBTASK_TYPE_SPECS` was imported at module scope and
+ * every derived value (`SUBTASK_TYPES`, `SUBTASK_TYPE_KEYS`, the delegate tool's
+ * description, the round contract) was computed at *import time*. That made the
+ * registry unoverridable, froze it before `env` exists, and pulled every
+ * domain's module into the bundle whether or not the agent used it.
+ *
+ * So it is a factory. The host builds one registry per DO instance from its
+ * installed plugins, and everything downstream reads that object.
+ */
+export type { DelegationNames, SubtaskParams, SubtaskTypeSpec };
+/** A subtask whose params do not satisfy its type's contract. */
+export declare class SubtaskParamsError extends Error {
+    constructor(message: string);
+}
+export interface SubtaskTypeRegistry {
+    /** Every known spec, in declaration order. */
+    readonly specs: readonly SubtaskTypeSpec[];
+    /** Every known type, keyed by its `key`. */
+    readonly byKey: ReadonlyMap<string, SubtaskTypeSpec>;
+    /** The type keys in declaration order. Empty when the agent delegates nothing. */
+    readonly keys: readonly string[];
+    /**
+     * The keys as a non-empty tuple for `z.enum` in the delegate schema — the
+     * model cannot emit anything outside it, so an unknown type never reaches the
+     * data layer.
+     *
+     * Throws when no type is registered. Not a defensive check but the real
+     * contract: an agent with no subtask types has nothing to delegate to, and
+     * must not offer a delegate tool at all.
+     */
+    enumKeys(): [string, ...string[]];
+    /** Look up a type, or null when it is not one we know. */
+    spec(type: string): SubtaskTypeSpec | null;
+    /**
+     * Resolve a subtask type to the recipe it runs under. Throws
+     * {@link SubtaskParamsError} for an unknown or retired type — the delegate
+     * enum prevents the model from emitting one, so any unknown type reaching
+     * execution is a configuration bug and should fail terminally.
+     */
+    resolveRecipe(type: string): ResolvedRecipe;
+    /**
+     * Validate a subtask's params against its type's contract, returning the
+     * params to persist. A type with no schema must carry no params — a stray
+     * param would otherwise ride along unread, looking meaningful.
+     *
+     * Shape only: whether an id names something the outside world actually offers
+     * is a question for that world, answered when the work starts. Unknown keys
+     * are stripped rather than refused — a model that invents one has produced a
+     * valid subtask with noise attached, and the noise provably cannot reach the
+     * execution.
+     */
+    validateParams(type: string, params: SubtaskParams | undefined): SubtaskParams;
+    /**
+     * Every param key any type declares, as the optional properties of the single
+     * flat `params` object the delegate tool advertises.
+     *
+     * Optional is not a weakening: which keys a given type *requires* is
+     * {@link validateParams}'s call, and it still refuses a subtask whose type's
+     * params are missing. What this adds is **visibility**. One tool schema has to
+     * serve every type, so the only alternative to naming the union of keys here
+     * is naming none of them — and a key the schema does not name is a key the
+     * model has no legal way to send, whatever the description promises. That is
+     * exactly how a domain subtask once reached validation with none of its
+     * declared ids: the field was declared as a free-form record, which the
+     * provider's schema conversion flattens to an object permitting no keys at all.
+     *
+     * Descriptions are prefixed with the owning type, so a flat namespace still
+     * reads unambiguously to the model (and a key two types share names both).
+     */
+    paramProperties(): Record<string, z.ZodType<string | undefined>>;
+    /** The type catalogue as the delegating model is shown it. */
+    renderTypes(): string;
+    /**
+     * Every type's {@link SubtaskTypeSpec.capability}, for the main agent's soul.
+     *
+     * Returns `""` when no type declares one, and that case is worth naming: it is
+     * what lets each call site append unconditionally instead of emitting a
+     * separator around nothing.
+     */
+    renderCapabilities(): string;
+    /** Every type's {@link SubtaskTypeSpec.delegationGuidance}, for the round contract. */
+    renderDelegationGuidance(names: DelegationNames): string;
+}
+/**
+ * Build the registry from the specs the installed plugins declared.
+ *
+ * Duplicate keys are refused rather than last-one-wins: two plugins claiming one
+ * type is a misconfiguration whose symptom would otherwise be work silently
+ * routed to the wrong domain.
+ */
+export declare function makeSubtaskTypes(specs: readonly SubtaskTypeSpec[]): SubtaskTypeRegistry;
+//# sourceMappingURL=subtask-types.d.ts.map

package/dist/subtasks/subtask-types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"subtask-types.d.ts","sourceRoot":"","sources":["../../src/subtasks/subtask-types.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,KAAK,EACV,eAAe,EACf,cAAc,EACd,aAAa,EACb,eAAe,EAChB,MAAM,uBAAuB,CAAC;AAE/B;;;;;;;;;;;;;;GAcG;AAEH,YAAY,EAAE,eAAe,EAAE,aAAa,EAAE,eAAe,EAAE,CAAC;AAEhE,iEAAiE;AACjE,qBAAa,kBAAmB,SAAQ,KAAK;gBAC/B,OAAO,EAAE,MAAM;CAI5B;AAED,MAAM,WAAW,mBAAmB;IAClC,8CAA8C;IAC9C,QAAQ,CAAC,KAAK,EAAE,SAAS,eAAe,EAAE,CAAC;IAC3C,4CAA4C;IAC5C,QAAQ,CAAC,KAAK,EAAE,WAAW,CAAC,MAAM,EAAE,eAAe,CAAC,CAAC;IACrD,kFAAkF;IAClF,QAAQ,CAAC,IAAI,EAAE,SAAS,MAAM,EAAE,CAAC;IACjC;;;;;;;;OAQG;IACH,QAAQ,IAAI,CAAC,MAAM,EAAE,GAAG,MAAM,EAAE,CAAC,CAAC;IAClC,0DAA0D;IAC1D,IAAI,CAAC,IAAI,EAAE,MAAM,GAAG,eAAe,GAAG,IAAI,CAAC;IAC3C;;;;;OAKG;IACH,aAAa,CAAC,IAAI,EAAE,MAAM,GAAG,cAAc,CAAC;IAC5C;;;;;;;;;;OAUG;IACH,cAAc,CACZ,IAAI,EAAE,MAAM,EACZ,MAAM,EAAE,aAAa,GAAG,SAAS,GAChC,aAAa,CAAC;IACjB;;;;;;;;;;;;;;;;OAgBG;IACH,eAAe,IAAI,MAAM,CAAC,MAAM,EAAE,CAAC,CAAC,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC,CAAC,CAAC;IACjE,8DAA8D;IAC9D,WAAW,IAAI,MAAM,CAAC;IACtB;;;;;;OAMG;IACH,kBAAkB,IAAI,MAAM,CAAC;IAC7B,uFAAuF;IACvF,wBAAwB,CAAC,KAAK,EAAE,eAAe,GAAG,MAAM,CAAC;CAC1D;AAED;;;;;;GAMG;AACH,wBAAgB,gBAAgB,CAC9B,KAAK,EAAE,SAAS,eAAe,EAAE,GAChC,mBAAmB,CAmHrB"}

package/dist/subtasks/subtask-types.js

@@ -0,0 +1,111 @@
+import { z } from "zod";
+/** A subtask whose params do not satisfy its type's contract. */
+export class SubtaskParamsError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "SubtaskParamsError";
+    }
+}
+/**
+ * Build the registry from the specs the installed plugins declared.
+ *
+ * Duplicate keys are refused rather than last-one-wins: two plugins claiming one
+ * type is a misconfiguration whose symptom would otherwise be work silently
+ * routed to the wrong domain.
+ */
+export function makeSubtaskTypes(specs) {
+    const byKey = new Map();
+    for (const spec of specs) {
+        if (byKey.has(spec.key)) {
+            throw new Error(`duplicate subtask type "${spec.key}" — two plugins declare the same type`);
+        }
+        byKey.set(spec.key, spec);
+    }
+    const keys = specs.map((s) => s.key);
+    const lookup = (type) => byKey.get(type) ?? null;
+    return {
+        specs,
+        byKey,
+        keys,
+        enumKeys() {
+            if (keys.length === 0) {
+                throw new Error("no subtask types are registered — an agent with no types cannot delegate, " +
+                    "so it must not build a delegate tool");
+            }
+            return keys;
+        },
+        spec: lookup,
+        resolveRecipe(type) {
+            const found = lookup(type);
+            if (!found)
+                throw new SubtaskParamsError(`unknown subtask type: ${type}`);
+            return found.recipe;
+        },
+        validateParams(type, params) {
+            const found = lookup(type);
+            if (!found)
+                throw new SubtaskParamsError(`unknown subtask type: ${type}`);
+            const supplied = params ?? {};
+            if (!found.params) {
+                const extra = Object.keys(supplied);
+                if (extra.length > 0) {
+                    throw new SubtaskParamsError(`subtask type "${type}" takes no params, got: ${extra.join(", ")}`);
+                }
+                return {};
+            }
+            const parsed = found.params.safeParse(supplied);
+            if (!parsed.success) {
+                const detail = parsed.error.issues
+                    .map((i) => `${i.path.join(".") || "(root)"}: ${i.message}`)
+                    .join("; ");
+                throw new SubtaskParamsError(`subtask type "${type}" has invalid params — ${detail}`);
+            }
+            return parsed.data;
+        },
+        paramProperties() {
+            const owners = new Map();
+            const declared = new Map();
+            for (const s of specs) {
+                if (!s.params)
+                    continue;
+                for (const [key, field] of Object.entries(s.params.shape)) {
+                    owners.set(key, [...(owners.get(key) ?? []), s.key]);
+                    declared.set(key, field);
+                }
+            }
+            return Object.fromEntries([...declared].map(([key, field]) => [
+                key,
+                // Described *after* `.optional()`, so the text sits on the schema this
+                // returns rather than on the type it wraps — readable by both the JSON
+                // Schema conversion and anything inspecting these properties directly.
+                field
+                    .optional()
+                    .describe(`${owners.get(key)?.join("/")}: ${field.description ?? key}`)
+            ]));
+        },
+        renderTypes() {
+            return specs
+                .map((s) => {
+                const help = s.paramsHelp ? ` — ${s.paramsHelp}` : "";
+                return `- \`${s.key}\`: ${s.description}${help}`;
+            })
+                .join("\n");
+        },
+        renderCapabilities() {
+            const blocks = [];
+            for (const s of specs)
+                if (s.capability)
+                    blocks.push(s.capability);
+            return blocks.join("\n\n");
+        },
+        renderDelegationGuidance(names) {
+            const sections = [];
+            for (const s of specs) {
+                if (s.delegationGuidance)
+                    sections.push(s.delegationGuidance(names));
+            }
+            return sections.join("\n\n");
+        }
+    };
+}
+//# sourceMappingURL=subtask-types.js.map

package/dist/subtasks/subtask-types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"subtask-types.js","sourceRoot":"","sources":["../../src/subtasks/subtask-types.ts"],"names":[],"mappings":"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"}