@theokit/sdk 0.0.0-compat-580-20260905204608

package/dist/a2a/subagent.d.ts

@@ -0,0 +1,231 @@
+/**
+ * Subagent delegation — declarative child agent invocable as a tool.
+ *
+ * Per ADR D2: `defineSubAgent(spec)` returns a `CustomTool` that, when
+ * invoked by the LLM, creates a child agent and sends the input as a
+ * message. EC-2: delegation depth is tracked across the RUN (#364) — each
+ * delegation publishes its depth on the async scope its child executes in, so a
+ * subagent that delegates to a subagent is bounded by `maxDelegationDepth`
+ * without the caller threading a counter by hand.
+ *
+ * SE10 — the handler forwards the parent run's `AbortSignal` to the child.
+ * SE11 — optional `onDelegationStart` / `onDelegationComplete` lifecycle hooks
+ * let the caller reject, rewrite, observe, or annotate a delegation.
+ *
+ * @public
+ */
+import { TheokitAgentError } from "../errors.js";
+import { type InheritedCredentials } from "../internal/concurrency/subagent-credentials.js";
+import type { AgentOptions, BuiltinToolName, CustomTool, ToolContextMessage } from "../types/agent.js";
+import type { ModelSelection } from "../types/agent-prims.js";
+/** Arguments passed to {@link SubAgentSpec.messageFilter} (SE12). */
+export interface MessageFilterArgs {
+    /** The supervisor transcript (read-only text projection) available to this delegation. */
+    messages: readonly ToolContextMessage[];
+    /** The prompt about to be delegated (after any `onDelegationStart` rewrite). */
+    input: string;
+    /** The subagent's name. */
+    name: string;
+}
+/** Context passed to {@link SubAgentSpec.onDelegationStart} before the child runs. */
+export interface DelegationStartContext {
+    input: string;
+    name: string;
+    /**
+     * SE15 — 1-based count of times THIS subagent tool has been invoked (a
+     * per-`defineSubAgent`-instance counter). Incremented before this hook runs;
+     * a rejected delegation still counts. Enables reject-after-N patterns.
+     */
+    iteration: number;
+}
+/**
+ * Decision returned from {@link SubAgentSpec.onDelegationStart}. Discriminated on
+ * `proceed` so a rejection (`proceed: false` + `rejectionReason`) and an approval
+ * (`modifiedInput`) cannot be mixed into one nonsensical object.
+ */
+export type DelegationStartDecision = {
+    proceed: false;
+    rejectionReason?: string;
+} | {
+    proceed?: true;
+    modifiedInput?: string;
+    /** SE13 — cap the child's iteration count (forwarded as `SendOptions.maxIterations`). */
+    modifiedMaxSteps?: number;
+};
+/** Context passed to {@link SubAgentSpec.onDelegationComplete} after the child settles. */
+export interface DelegationCompleteContext {
+    input: string;
+    name: string;
+    /** The child's text result (present on success). */
+    result?: string;
+    /** The error the child threw (present on failure); the error is still re-thrown. */
+    error?: unknown;
+    /** SE15 — the same 1-based iteration this delegation's `onDelegationStart` saw. */
+    iteration: number;
+}
+/**
+ * The return of a delegation hook: a decision, a promise of one, or nothing —
+ * `void` lets a side-effect-only callback (`(ctx) => { log(ctx) }`) type-check,
+ * which is the common case (mirrors a peer framework's `async ctx => { ... }` hooks).
+ */
+type DelegationHookResult<T> = T | void | Promise<T | void>;
+/** Decision returned from {@link SubAgentSpec.onDelegationComplete}. */
+export interface DelegationCompleteDecision {
+    /** Appended to the child's result string. */
+    feedback?: string;
+}
+/**
+ * The declaration of a delegating child agent, handed to `SubAgent.create(spec)`.
+ *
+ * `name`, `description` and `instructions` are the only required fields: the first
+ * two become the tool the supervisor's model sees, the third becomes the child's
+ * system prompt. Everything else narrows what the child inherits.
+ *
+ *   const research = SubAgent.create({
+ *     name: "research",
+ *     description: "Look a fact up",
+ *     instructions: "You answer with one sentence.",
+ *   });
+ *   const agent = await Agent.create({ tools: [research] });
+ *
+ * The tool's own input schema is fixed — one required string property, `input`.
+ * It is not derived from this spec and cannot be widened here.
+ *
+ * What the child inherits from the parent AT DISPATCH TIME, not from this object:
+ * the API key, the model (unless `model` is set), the parent's plugins, and the
+ * parent's sandbox posture (unless `sandbox` is set). An absent `sandbox` inherits;
+ * an explicit `sandbox: false` turns confinement OFF for a child of a confined
+ * parent, which is not the same thing.
+ *
+ * How it fails: the child's failure is re-thrown to the supervisor as a tool error
+ * — a run ending in `status: "error"` becomes
+ * `subagent "<name>" run failed: <cause>`. `onDelegationStart` and `messageFilter`
+ * propagate their own throws; only a throw from `onDelegationComplete` ON THE
+ * ERROR PATH is suppressed, so it cannot mask the real cause.
+ *
+ * Traps:
+ *  - `model` as a bare string drops reasoning parameters. Pass the
+ *    {@link ModelSelection} object form when the child needs `params`.
+ *  - `maxDelegationDepth` (default 3) bounds the delegation CHAIN, counted at
+ *    dispatch across the run (#364) — the depth is not something you thread. The
+ *    `parentDepth` argument of `SubAgent.create` still offsets it, for a supervisor
+ *    that wants a lower ceiling than the chain it sits in.
+ *  - Context isolation is the DEFAULT. Without `messageFilter` the child sees only
+ *    the delegated string; without `includeToolResults` the supervisor gets only
+ *    the child's final text.
+ */
+export interface SubAgentSpec {
+    name: string;
+    description: string;
+    instructions: string;
+    /**
+     * A bare id string (back-compat) OR a full {@link ModelSelection} carrying
+     * `params` (e.g. `[{ id: "thinking", value: "low" }]` for reasoning effort). The
+     * object form is required for per-subagent reasoning effort to survive to the child
+     * — the pre-M33 path took only `.id` and dropped params.
+     */
+    model?: string | ModelSelection;
+    tools?: CustomTool[];
+    /** Per-subagent shell sandbox toggle (M33). `true` ⇒ child `local.sandboxOptions.enabled`. */
+    sandbox?: boolean;
+    /**
+     * #580 — builtin tools this role removes from its child's catalog, UNIONED with whatever the
+     * parent already withheld.
+     *
+     * A role declared read-only in prose is not read-only: a `shell` tool is always registered on a
+     * local agent, including when `tools: []` is passed, so withholding is the only mechanism that
+     * removes it — and until #580 a spec could not ask for it and a parent's withholding did not
+     * survive delegation either.
+     *
+     * ## Union, not override — and this is the one field here that works that way
+     *
+     * `model` and `sandbox` let the role's own value WIN, including `sandbox: false` turning
+     * confinement off for a child of a confined parent. That asymmetry is deliberate: a posture is
+     * declared, whereas withholding removes a capability from the catalog. Letting a role override a
+     * withholding would let a child recover a tool its parent revoked, which is the defect #580
+     * reports — so a child may only ever ADD to the set.
+     */
+    withheldBuiltinTools?: readonly BuiltinToolName[];
+    /**
+     * Maximum length of the delegation CHAIN rooted at this tool, counted at dispatch
+     * (default 3). Depth 1 is this subagent; a subagent it delegates to is depth 2.
+     * Exceeding it throws {@link MaxDelegationDepthError} from the tool handler.
+     */
+    maxDelegationDepth?: number;
+    /**
+     * SE11 — called before the supervisor delegates. Return `{ proceed: false }`
+     * to reject (the child never runs and `rejectionReason` becomes the tool
+     * result), or `{ modifiedInput }` to rewrite the delegated prompt. A throwing
+     * hook surfaces (never silently swallowed).
+     */
+    onDelegationStart?: (ctx: DelegationStartContext) => DelegationHookResult<DelegationStartDecision>;
+    /**
+     * SE11 — called after the delegation settles. On success `ctx.result` is set
+     * and an optional `{ feedback }` is appended to it. On failure `ctx.error` is
+     * set and the original error is ALWAYS re-thrown after this hook runs — a throw
+     * from this hook on the error path is suppressed so it cannot mask the
+     * delegation's real failure (on the success path a throw does propagate).
+     */
+    onDelegationComplete?: (ctx: DelegationCompleteContext) => DelegationHookResult<DelegationCompleteDecision>;
+    /**
+     * SE12 — opt-in parent-context forwarding. When set, the supervisor transcript
+     * (`ctx.messages`, a read-only text projection) is passed to this filter and the
+     * returned subset is forwarded to the child as a role-tagged context preamble
+     * prepended to the delegated input. When ABSENT the child runs input-only —
+     * memory isolation stays the default. A filter returning `[]` forwards nothing.
+     * A throwing filter propagates (fail-fast, never swallowed — same contract as
+     * `onDelegationStart`); the delegation surfaces as a tool error.
+     */
+    messageFilter?: (args: MessageFilterArgs) => readonly ToolContextMessage[];
+    /**
+     * SE14 — opt-in subagent result-context control. When `true`, the child's
+     * completed tool-call results (name + result) are appended to the delegation
+     * payload returned to the supervisor, inside a `<subagent-tool-results>` block.
+     * When absent/`false` the delegation returns the child's final text only —
+     * text-only stays the default (a peer framework's scoped posture). See ADR 0006.
+     */
+    includeToolResults?: boolean;
+}
+/**
+ * Raised by `SubAgent.create(spec, parentDepth)` when `parentDepth + 1` exceeds
+ * `spec.maxDelegationDepth` (default 3). Carries `currentDepth`, `maxDepth` and a
+ * stable `code: "max_delegation_depth"`.
+ *
+ * Thrown from the subagent tool's handler when a delegation would exceed
+ * `maxDelegationDepth` (default 3), so it surfaces as the tool call's failure —
+ * catching it around the dispatching `agent.send()` works.
+ *
+ * Also thrown eagerly at TOOL-CONSTRUCTION time when a caller threads its own
+ * `parentDepth` that is already past the limit; such a tool could never be
+ * dispatched, so refusing to build it fails earlier and clearer.
+ *
+ * Before #364 the construction-time check was the ONLY one, against a depth
+ * nothing in the SDK incremented — so under the documented `SubAgent.create(spec)`
+ * call this error could not fire at all and nested delegation was unbounded. The
+ * chain length now travels with the run (`internal/runtime/concurrency/delegation-depth.ts`),
+ * and a caller-threaded `parentDepth` still adds to it.
+ */
+export declare class MaxDelegationDepthError extends TheokitAgentError {
+    readonly currentDepth: number;
+    readonly maxDepth: number;
+    readonly name = "MaxDelegationDepthError";
+    readonly code: "max_delegation_depth";
+    constructor(currentDepth: number, maxDepth: number);
+}
+/**
+ * Build the child agent's `Agent.create` options: the child inherits the parent's
+ * apiKey (else `Agent.create` throws "Missing API key"), its model (unless the spec
+ * overrides it), — #55 — the parent's plugins (permission gate/guards) so the
+ * child's inner tool calls run under the same policy, and — #578 — the configuration
+ * surfaces the parent was declared to read (see {@link buildChildLocalOptions}).
+ */
+export declare function buildChildCreateOptions(spec: SubAgentSpec, inherited: InheritedCredentials | undefined): AgentOptions;
+/** SE36 — `SubAgent.create` replaces `defineSubAgent` (ADR 0015). @public  *
+ * `SubAgent.create` returns a **`CustomTool`** — the sub-agent is exposed to the
+ * parent as a callable tool, not as a `SubAgent` instance.
+ */
+export declare class SubAgent {
+    private constructor();
+    static create(spec: SubAgentSpec, parentDepth?: number): CustomTool;
+}
+export {};

package/dist/a2a/types.d.cts

@@ -0,0 +1,45 @@
+/**
+ * A2A (Agent-to-Agent) communication types (T20.1, ADR D453).
+ * @public
+ */
+import type { MessageOrigin } from "../types/run.js";
+/**
+ * One message as a handler receives it.
+ *
+ * Senders never build this value: `MessageBus.send` / `MessageBus.request` accept
+ * only `{ type, payload }` and fill in `from`, `to`, `timestamp` (`Date.now()`)
+ * and `origin` themselves.
+ *
+ * `type` is a free-form string with no registry — sender and handler must agree on
+ * it out of band, and an unrecognised `type` is delivered like any other rather
+ * than rejected.
+ *
+ * The `T` parameter types `payload` only. The bus itself is untyped (both entry
+ * points take `payload: unknown`), so declaring `MessageHandler<Foo>` is an
+ * assertion rather than a validated cast — parse `payload` before trusting it.
+ */
+export interface A2AMessage<T = unknown> {
+    type: string;
+    payload: T;
+    from: string;
+    to: string;
+    timestamp: number;
+    /**
+     * SE3 — provenance projection of the sender address: `{ kind: "peer", from }`.
+     * A thin view over `from` (not a parallel system), so a receiver that turns an
+     * a2a message into a turn can forward it via `SendOptions.origin`.
+     */
+    origin?: MessageOrigin;
+}
+/**
+ * What an agent does with an inbound {@link A2AMessage}.
+ *
+ * The return value is the REPLY that `MessageBus.request` resolves with (awaited
+ * when it is a promise) and is DISCARDED by `MessageBus.send`. Returning
+ * `undefined` is indistinguishable, at the requester, from a handler that
+ * deliberately answered `undefined`.
+ *
+ * Throwing rejects the pending `request`. Under `send` the same throw becomes an
+ * unhandled rejection nobody observes — see {@link MessageBus}.
+ */
+export type MessageHandler<T = unknown> = (message: A2AMessage<T>) => undefined | unknown | Promise<undefined | unknown>;

package/dist/a2a/types.d.ts

@@ -0,0 +1,45 @@
+/**
+ * A2A (Agent-to-Agent) communication types (T20.1, ADR D453).
+ * @public
+ */
+import type { MessageOrigin } from "../types/run.js";
+/**
+ * One message as a handler receives it.
+ *
+ * Senders never build this value: `MessageBus.send` / `MessageBus.request` accept
+ * only `{ type, payload }` and fill in `from`, `to`, `timestamp` (`Date.now()`)
+ * and `origin` themselves.
+ *
+ * `type` is a free-form string with no registry — sender and handler must agree on
+ * it out of band, and an unrecognised `type` is delivered like any other rather
+ * than rejected.
+ *
+ * The `T` parameter types `payload` only. The bus itself is untyped (both entry
+ * points take `payload: unknown`), so declaring `MessageHandler<Foo>` is an
+ * assertion rather than a validated cast — parse `payload` before trusting it.
+ */
+export interface A2AMessage<T = unknown> {
+    type: string;
+    payload: T;
+    from: string;
+    to: string;
+    timestamp: number;
+    /**
+     * SE3 — provenance projection of the sender address: `{ kind: "peer", from }`.
+     * A thin view over `from` (not a parallel system), so a receiver that turns an
+     * a2a message into a turn can forward it via `SendOptions.origin`.
+     */
+    origin?: MessageOrigin;
+}
+/**
+ * What an agent does with an inbound {@link A2AMessage}.
+ *
+ * The return value is the REPLY that `MessageBus.request` resolves with (awaited
+ * when it is a promise) and is DISCARDED by `MessageBus.send`. Returning
+ * `undefined` is indistinguishable, at the requester, from a handler that
+ * deliberately answered `undefined`.
+ *
+ * Throwing rejects the pending `request`. Under `send` the same throw becomes an
+ * unhandled rejection nobody observes — see {@link MessageBus}.
+ */
+export type MessageHandler<T = unknown> = (message: A2AMessage<T>) => undefined | unknown | Promise<undefined | unknown>;

package/dist/agent-ARLOD4JX.cjs

@@ -0,0 +1,67 @@
+'use strict';
+
+var chunkD3CCY3A2_cjs = require('./chunk-D3CCY3A2.cjs');
+require('./chunk-KVSAY6NZ.cjs');
+require('./chunk-Y2KYR2ED.cjs');
+require('./chunk-BUUUWQMB.cjs');
+require('./chunk-Z2JFX372.cjs');
+require('./chunk-KGANQYP7.cjs');
+require('./chunk-BV2MWEMV.cjs');
+require('./chunk-D6POWE7E.cjs');
+require('./chunk-GHX4P3V2.cjs');
+require('./chunk-TMKTSYDS.cjs');
+require('./chunk-NQTNSHSB.cjs');
+require('./chunk-7FDKWDA2.cjs');
+require('./chunk-2HPNT6HH.cjs');
+require('./chunk-FUSDYC2B.cjs');
+require('./chunk-YJNYDJ2T.cjs');
+require('./chunk-24SYBZPL.cjs');
+require('./chunk-QOGNZMHD.cjs');
+require('./chunk-YIFFF23U.cjs');
+require('./chunk-2ZPEDVLM.cjs');
+require('./chunk-IU5N5224.cjs');
+require('./chunk-KRD3GQAA.cjs');
+require('./chunk-RQMCOFAI.cjs');
+require('./chunk-MUUQ2WFJ.cjs');
+require('./chunk-AA27GEYS.cjs');
+require('./chunk-YSTXFWQE.cjs');
+require('./chunk-FRITRLZQ.cjs');
+require('./chunk-NQTD6QOW.cjs');
+require('./chunk-NINIJCHU.cjs');
+require('./chunk-QATRS7JD.cjs');
+require('./chunk-LOHMT36V.cjs');
+require('./chunk-IJ7M6GOG.cjs');
+require('./chunk-7A6535RA.cjs');
+require('./chunk-SA6K24NB.cjs');
+require('./chunk-I2PWY7VM.cjs');
+require('./chunk-KTTHHYEW.cjs');
+require('./chunk-Z3NTRKIC.cjs');
+require('./chunk-GZV6AVRL.cjs');
+require('./chunk-A4RAL2ER.cjs');
+require('./chunk-DQZU7JK6.cjs');
+require('./chunk-BJUJT5ED.cjs');
+require('./chunk-ZF2LDKQQ.cjs');
+require('./chunk-HCT4HPCL.cjs');
+require('./chunk-JLRLCBJ4.cjs');
+require('./chunk-QYLZQ43D.cjs');
+require('./chunk-NYQ3IS7K.cjs');
+require('./chunk-HW7SEELD.cjs');
+require('./chunk-ATT276RD.cjs');
+require('./chunk-3EE6LVWT.cjs');
+require('./chunk-ANMJJD6D.cjs');
+require('./chunk-QC55H6RJ.cjs');
+require('./chunk-NVXXWAU7.cjs');
+require('./chunk-4NLCWGH7.cjs');
+require('./chunk-EXTRW7GW.cjs');
+require('./chunk-HUFSABUZ.cjs');
+require('./chunk-J7J7J2GN.cjs');
+require('./chunk-6LHQPOMI.cjs');
+
+
+
+Object.defineProperty(exports, "Agent", {
+  enumerable: true,
+  get: function () { return chunkD3CCY3A2_cjs.Agent; }
+});
+//# sourceMappingURL=agent-ARLOD4JX.cjs.map
+//# sourceMappingURL=agent-ARLOD4JX.cjs.map

package/dist/agent-ARLOD4JX.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"names":[],"mappings":"","file":"agent-ARLOD4JX.cjs"}