@pikku/core 0.12.72 → 0.12.74

package/dist/wirings/ai-agent/ai-agent-interrupt.d.ts

@@ -0,0 +1,153 @@
+import type { AIStorageService } from '../../services/ai-storage-service.js';
+/**
+ * Why an in-flight agent run was cut short.
+ *
+ * Deliberately carries no interjection text. A voice interruption is not a
+ * cancel button — it is the user starting to talk — but what they said arrives
+ * a second later as an ordinary next turn on the same thread, and that turn
+ * already has a working path through `streamAIAgent`. The model then sees its
+ * own truncated message (marked `interrupted`) followed by the interjection and
+ * decides for itself whether to resume, correct itself or drop the thread.
+ * Nothing here classifies the interjection; a second delivery path for the same
+ * text would only give the two ways to disagree about ordering.
+ */
+export interface AgentInterruption {
+    /** `'speech'` — the user started talking over the agent (voice barge-in).
+     *  `'user'` — an explicit stop (a button). `'timeout'` — a caller-side deadline. */
+    reason: 'speech' | 'user' | 'timeout';
+}
+/**
+ * Thrown out of the step loop when a run is interrupted, so an interruption is
+ * distinguishable from a genuine failure at the one `catch` that would
+ * otherwise mark the run `failed`.
+ */
+export declare class AgentInterruptedError extends Error {
+    readonly runId: string;
+    readonly interruption: AgentInterruption;
+    constructor(runId: string, interruption: AgentInterruption);
+}
+/**
+ * A tool call that settled after its run was interrupted, so its result never
+ * reached the model.
+ *
+ * These are not failures, and they are only ever mutations. The tool ran, its
+ * side effect happened, and the only thing the interrupt cost was the reply
+ * describing it — so the result is worth mentioning on the next turn. Reads are
+ * excluded at the call site: nothing changed, so there is nothing to account
+ * for, and a stale answer is worse than re-reading.
+ */
+export interface OrphanedToolResult {
+    toolCallId: string;
+    toolName: string;
+    result: unknown;
+    /** Set instead of `result` when the tool threw after the interrupt. */
+    error?: string;
+}
+/** What an authorized interrupt actually achieved. */
+export interface AgentInterruptResult {
+    /**
+     * Whether a generating run was stopped. `false` is routine, not an error:
+     * racing a run that finishes on its own is the normal case in voice.
+     */
+    stopped: boolean;
+    /**
+     * Tools that were still executing when the interrupt landed. Their side
+     * effects have already happened and cannot be undone from here — this is for
+     * saying something true ("the deploy is still going"), not for offering to
+     * roll it back. Each will surface as an `undelivered` tool message on the
+     * thread once it settles.
+     */
+    inFlightTools: string[];
+}
+export interface InterruptibleRunHandle {
+    readonly signal: AbortSignal;
+    /** Set at the moment the run is interrupted; `undefined` on a clean run. */
+    readonly interruption: AgentInterruption | undefined;
+    /** Names of tools executing right now — what an interrupt would talk over. */
+    readonly inFlightTools: string[];
+    /**
+     * Wrap a tool execution so it survives an interrupt. Before the interrupt
+     * this is a pass-through; after one, the settled value is collected as an
+     * {@link OrphanedToolResult} rather than vanishing with the aborted stream.
+     */
+    trackTool<T>(toolName: string, toolCallId: string, exec: () => Promise<T>, opts?: {
+        collectResult?: boolean;
+    }): Promise<T>;
+    /**
+     * Resolves once every tool still running at the moment of the interrupt has
+     * settled, with the results the model never got to see.
+     *
+     * Deliberately not awaited before the stream closes: barge-in has to stop the
+     * agent talking immediately, and a tool holding that up for its own duration
+     * is the one thing voice cannot tolerate.
+     */
+    settle(timeoutMs?: number): Promise<OrphanedToolResult[]>;
+    release(): void;
+}
+/**
+ * Make a run interruptible for the duration of its stream. The returned signal
+ * is threaded into the model call, so an interrupt cancels the upstream HTTP
+ * request rather than merely stopping delivery of tokens we are still paying
+ * for.
+ */
+export declare const registerInterruptibleRun: (runId: string) => InterruptibleRunHandle;
+/**
+ * Stop a run that is generating right now.
+ *
+ * Plumbing: this performs NO authorization, so anyone holding a runId can stop
+ * it. Reach for {@link interruptAIAgent} instead unless the caller has already
+ * established that the run belongs to the session — which in practice means
+ * only the runner itself and code already inside an authorized run.
+ *
+ * Returns `false` when the run is not in flight in this process — already
+ * finished, never started, or running elsewhere — which callers should treat as
+ * "nothing to interrupt", not as an error: racing a run that finishes on its own
+ * is the normal case in voice.
+ */
+export declare const signalRunInterrupt: (runId: string, interruption?: AgentInterruption) => boolean;
+/** Whether a run is currently interruptible in this process. */
+export declare const isRunInterruptible: (runId: string) => boolean;
+/**
+ * Tools executing in a run right now. Empty for a run that is merely
+ * generating, or one this process does not hold.
+ *
+ * Callers use this to say something true about work that outlives the reply —
+ * "that deploy is still going" — rather than to offer to stop it. By the time a
+ * tool is executing its side effect has already happened, and pikku functions
+ * receive no abort signal, so there is nothing left to cancel.
+ */
+export declare const getInFlightTools: (runId: string) => string[];
+/**
+ * Wrap tool definitions so their results survive an interrupt.
+ *
+ * Applied by the runner after the handle exists rather than in `buildToolDefs`,
+ * which builds tools before there is a runId to attach them to.
+ */
+export declare const trackToolExecution: <T extends {
+    name: string;
+    readonly?: boolean;
+    execute: (input: any) => Promise<any>;
+}>(tools: T[], handle: InterruptibleRunHandle) => T[];
+export declare const trackInterruptNote: (threadId: string, write: Promise<void>) => void;
+/** Await an interrupted tool result still being written to this thread. */
+export declare const awaitPendingInterruptNote: (threadId: string) => Promise<void>;
+/**
+ * Write the results of tools that were still running when a run was cut off.
+ *
+ * Saved as an ordinary tool message so it reaches the model through the same
+ * context load as everything else — there is no separate "notes" channel to
+ * keep in sync, and storage that drops the `undelivered` flag still keeps the
+ * result itself.
+ *
+ * Callers should hand this to {@link trackInterruptNote} rather than awaiting
+ * it: an interrupt has to end the reply immediately, and a slow tool must not
+ * hold that up.
+ */
+export declare const persistOrphanedToolResults: (handle: InterruptibleRunHandle, storage: AIStorageService, threadId: string) => Promise<void>;
+/**
+ * Whether a thrown value is an abort rather than a failure. The AI SDK
+ * surfaces cancellation as a DOMException/Error named `AbortError`, so the
+ * name is the only portable signal — there is no shared error class to
+ * `instanceof` against across fetch, undici and the provider SDKs.
+ */
+export declare const isAbortError: (err: unknown) => boolean;

package/dist/wirings/ai-agent/ai-agent-interrupt.js

@@ -0,0 +1,256 @@
+import { randomUUID } from './ai-agent-utils.js';
+import { AbandonedError, runInAbortScope, } from '../../function/abort-scope.js';
+/**
+ * Thrown out of the step loop when a run is interrupted, so an interruption is
+ * distinguishable from a genuine failure at the one `catch` that would
+ * otherwise mark the run `failed`.
+ */
+export class AgentInterruptedError extends Error {
+    runId;
+    interruption;
+    constructor(runId, interruption) {
+        super(`Agent run ${runId} interrupted (${interruption.reason})`);
+        this.runId = runId;
+        this.interruption = interruption;
+        this.name = 'AgentInterruptedError';
+    }
+}
+/**
+ * Live runs, keyed by runId.
+ *
+ * Module-level rather than `pikkuState` because the value is an
+ * `AbortController` — a process-local object that cannot be serialised or
+ * shared. That is also this registry's limit: an interrupt only reaches a run
+ * executing in the same process. Single-process and channel-attached callers
+ * (where the interrupt arrives on the socket already carrying the run) are
+ * covered; a horizontally-scaled deployment interrupting over a *separate* HTTP
+ * request needs the interrupt fanned out over `eventHub` to every instance
+ * first, with each instance calling `signalRunInterrupt` locally.
+ */
+const runs = new Map();
+/**
+ * Make a run interruptible for the duration of its stream. The returned signal
+ * is threaded into the model call, so an interrupt cancels the upstream HTTP
+ * request rather than merely stopping delivery of tokens we are still paying
+ * for.
+ */
+export const registerInterruptibleRun = (runId) => {
+    const entry = {
+        controller: new AbortController(),
+        inFlight: new Map(),
+        orphaned: [],
+        pending: new Set(),
+    };
+    runs.set(runId, entry);
+    return {
+        signal: entry.controller.signal,
+        get interruption() {
+            return entry.interruption;
+        },
+        get inFlightTools() {
+            return [...entry.inFlight.values()];
+        },
+        trackTool: async (toolName, toolCallId, exec, opts) => {
+            entry.inFlight.set(toolCallId, toolName);
+            const call = exec();
+            // Tracked separately from the returned promise so an interrupt can wait
+            // on the tool without the caller's rejection becoming an unhandled one.
+            const tracked = call.then((result) => {
+                entry.inFlight.delete(toolCallId);
+                // Read now rather than at call time: a tool that uses
+                // `beginChanges()` only reveals partway through whether it mutated.
+                if ((opts?.collectResult ?? true) &&
+                    entry.controller.signal.aborted) {
+                    entry.orphaned.push({ toolCallId, toolName, result });
+                }
+            }, (err) => {
+                entry.inFlight.delete(toolCallId);
+                // A tool that stopped *at* its own checkpoint changed nothing by
+                // construction, so it never files a note — reporting "it aborted"
+                // is exactly the noise `beginChanges()` exists to remove.
+                if (err instanceof AbandonedError)
+                    return;
+                if ((opts?.collectResult ?? true) &&
+                    entry.controller.signal.aborted) {
+                    entry.orphaned.push({
+                        toolCallId,
+                        toolName,
+                        result: undefined,
+                        error: err instanceof Error ? err.message : String(err),
+                    });
+                }
+            });
+            entry.pending.add(tracked);
+            void tracked.finally(() => entry.pending.delete(tracked));
+            return call;
+        },
+        settle: async (timeoutMs = 30_000) => {
+            if (entry.pending.size > 0) {
+                // A tool that never settles must not strand the note forever; whatever
+                // has landed by the deadline is what gets reported.
+                let timer;
+                await Promise.race([
+                    Promise.all([...entry.pending]),
+                    new Promise((resolve) => {
+                        timer = setTimeout(resolve, timeoutMs);
+                    }),
+                ]);
+                if (timer)
+                    clearTimeout(timer);
+            }
+            return entry.orphaned;
+        },
+        release: () => {
+            if (runs.get(runId) === entry)
+                runs.delete(runId);
+        },
+    };
+};
+/**
+ * Stop a run that is generating right now.
+ *
+ * Plumbing: this performs NO authorization, so anyone holding a runId can stop
+ * it. Reach for {@link interruptAIAgent} instead unless the caller has already
+ * established that the run belongs to the session — which in practice means
+ * only the runner itself and code already inside an authorized run.
+ *
+ * Returns `false` when the run is not in flight in this process — already
+ * finished, never started, or running elsewhere — which callers should treat as
+ * "nothing to interrupt", not as an error: racing a run that finishes on its own
+ * is the normal case in voice.
+ */
+export const signalRunInterrupt = (runId, interruption = { reason: 'user' }) => {
+    const entry = runs.get(runId);
+    if (!entry || entry.controller.signal.aborted)
+        return false;
+    entry.interruption = interruption;
+    entry.controller.abort();
+    return true;
+};
+/** Whether a run is currently interruptible in this process. */
+export const isRunInterruptible = (runId) => runs.has(runId);
+/**
+ * Tools executing in a run right now. Empty for a run that is merely
+ * generating, or one this process does not hold.
+ *
+ * Callers use this to say something true about work that outlives the reply —
+ * "that deploy is still going" — rather than to offer to stop it. By the time a
+ * tool is executing its side effect has already happened, and pikku functions
+ * receive no abort signal, so there is nothing left to cancel.
+ */
+export const getInFlightTools = (runId) => {
+    const entry = runs.get(runId);
+    return entry ? [...entry.inFlight.values()] : [];
+};
+/**
+ * Wrap tool definitions so their results survive an interrupt.
+ *
+ * Applied by the runner after the handle exists rather than in `buildToolDefs`,
+ * which builds tools before there is a runId to attach them to.
+ */
+export const trackToolExecution = (tools, handle) => tools.map((tool) => {
+    // Reads run outside the scope entirely: they never produce a note and have
+    // nothing to declare, so `beginChanges()` inside one is a no-op rather than
+    // a contradiction to resolve.
+    if (tool.readonly) {
+        return {
+            ...tool,
+            execute: (input) => handle.trackTool(tool.name, randomUUID(), () => tool.execute(input), {
+                collectResult: false,
+            }),
+        };
+    }
+    return {
+        ...tool,
+        execute: (input) => {
+            // Assumed to have changed something unless it says otherwise — the tool
+            // that never declares its checkpoint is the one that cannot be assumed
+            // harmless. `beginChanges()` can only ever make this more precise.
+            const call = { mutating: true };
+            const scope = {
+                get abandoned() {
+                    return handle.signal.aborted;
+                },
+                get reason() {
+                    return handle.interruption?.reason;
+                },
+                onBeginChanges: () => {
+                    call.mutating = true;
+                },
+            };
+            return handle.trackTool(tool.name, randomUUID(), () => runInAbortScope(scope, () => tool.execute(input)), {
+                get collectResult() {
+                    return call.mutating;
+                },
+            });
+        },
+    };
+});
+/**
+ * Threads with an interrupted tool call still settling.
+ *
+ * The note describing that result has to be in the thread before the turn that
+ * ought to mention it loads its context, and the user's next sentence usually
+ * arrives well inside a slow tool. Runs await this for their own thread first,
+ * so the ordering holds without the interrupt itself blocking on anything.
+ */
+const pendingNotes = new Map();
+export const trackInterruptNote = (threadId, write) => {
+    const done = write.finally(() => {
+        if (pendingNotes.get(threadId) === done)
+            pendingNotes.delete(threadId);
+    });
+    pendingNotes.set(threadId, done);
+};
+/** Await an interrupted tool result still being written to this thread. */
+export const awaitPendingInterruptNote = async (threadId) => {
+    await pendingNotes.get(threadId);
+};
+/**
+ * Write the results of tools that were still running when a run was cut off.
+ *
+ * Saved as an ordinary tool message so it reaches the model through the same
+ * context load as everything else — there is no separate "notes" channel to
+ * keep in sync, and storage that drops the `undelivered` flag still keeps the
+ * result itself.
+ *
+ * Callers should hand this to {@link trackInterruptNote} rather than awaiting
+ * it: an interrupt has to end the reply immediately, and a slow tool must not
+ * hold that up.
+ */
+export const persistOrphanedToolResults = async (handle, storage, threadId) => {
+    let orphaned;
+    try {
+        orphaned = await handle.settle();
+    }
+    finally {
+        handle.release();
+    }
+    if (orphaned.length === 0)
+        return;
+    await storage.saveMessages(threadId, [
+        {
+            id: randomUUID(),
+            role: 'tool',
+            toolResults: orphaned.map((entry) => ({
+                id: entry.toolCallId,
+                name: entry.toolName,
+                result: entry.error
+                    ? `Error: ${entry.error}`
+                    : typeof entry.result === 'string'
+                        ? entry.result
+                        : JSON.stringify(entry.result),
+            })),
+            undelivered: true,
+            createdAt: new Date(),
+        },
+    ]);
+};
+/**
+ * Whether a thrown value is an abort rather than a failure. The AI SDK
+ * surfaces cancellation as a DOMException/Error named `AbortError`, so the
+ * name is the only portable signal — there is no shared error class to
+ * `instanceof` against across fetch, undici and the provider SDKs.
+ */
+export const isAbortError = (err) => err instanceof Error &&
+    (err.name === 'AbortError' || err.name === 'TimeoutError');

package/dist/wirings/ai-agent/ai-agent-memory.js

@@ -288,8 +288,6 @@ export function createWorkingMemoryMiddleware(options) {
                         options.logger?.warn(`Working memory validation failed: ${err instanceof Error ? err.message : String(err)}`);
                     }
                 }
-                // Only persist when the merged value passes schema validation —
-                // saving invalid data would poison subsequent getWorkingMemory reads.
                 if (valid) {
                     await options.storage.saveWorkingMemory(options.threadId, 'thread', merged);
                 }

package/dist/wirings/ai-agent/ai-agent-model-config.d.ts

@@ -1,12 +1,3 @@
-/**
- * Resolves the effective model/temperature/maxSteps for an agent at runtime.
- *
- * Models are declared per-agent using the provider-qualified `provider/model`
- * form (e.g. `openai/gpt-5-mini`); there is no config-level alias map. This
- * function remains the single merge point for request-time overrides (see
- * ai-agent-prepare's `input.model`), so callers stay decoupled from how the
- * effective config is assembled.
- */
 export declare function resolveModelConfig(_agentName: string, agent: {
     model: string;
     temperature?: number;

package/dist/wirings/ai-agent/ai-agent-model-config.js

@@ -1,12 +1,4 @@
-/**
- * Resolves the effective model/temperature/maxSteps for an agent at runtime.
- *
- * Models are declared per-agent using the provider-qualified `provider/model`
- * form (e.g. `openai/gpt-5-mini`); there is no config-level alias map. This
- * function remains the single merge point for request-time overrides (see
- * ai-agent-prepare's `input.model`), so callers stay decoupled from how the
- * effective config is assembled.
- */
+// knowledge: decisions/internals/ai-agent-model-config-stays-a-single-resolution-seam.md
 export function resolveModelConfig(_agentName, agent) {
     return {
         model: agent.model,

package/dist/wirings/ai-agent/ai-agent-prepare.d.ts

@@ -7,92 +7,38 @@ export type RunAIAgentParams = {
     sessionService?: SessionService<CoreUserSession>;
     /** Credential accessor for the current request — used to read per-user overrides (e.g. AI_API_KEY). */
     getCredential?: <T = unknown>(name: string) => T | null | Promise<T | null>;
+    /** Ephemeral owner identity minted for a sessionless request; never client-supplied, never reused across requests. */
+    anonymousOwnerResourceId?: string;
 };
-/**
- * The ownership key for a thread/run: the trusted principal (the authenticated
- * `session.userId` for `'user'` scope, or `session.orgId` for `'org'` scope)
- * composed with the client-supplied `resourceId` as a sub-partition —
- * `principal:resourceId`. Because the principal is always the prefix, a client
- * `resourceId` can sub-divide within the caller's own boundary but can never
- * widen access to another user's or org's threads.
- *
- * Idempotent: a value that is already within the caller's namespace (top-level
- * re-entry, sub-agent recursion, or resume, which all pass an already-composite
- * `resourceId`) is returned unchanged rather than double-composed.
- *
- * `'org'` scope with no session org throws {@link ForbiddenError} — falling back
- * to a bare/shared key would leak across organizations. Sessionless `'user'`
- * wirings have no trusted principal and fall back to the requested `resourceId`
- * as a best-effort partition key.
- */
+export declare function resolveSessionPrincipal(params: RunAIAgentParams, sessionScope: SessionScope | undefined): string | undefined;
 export declare function resolveOwnerResourceId(params: RunAIAgentParams, sessionScope: SessionScope | undefined, requestedResourceId: string): string;
-/** The declared {@link SessionScope} for an agent, defaulting to `'user'`. */
+export declare function assertResourcePrincipalOwner(params: RunAIAgentParams, sessionScope: SessionScope | undefined, storedResourceId: string, kind: 'thread' | 'run'): void;
 export declare function agentSessionScope(agentName: string): SessionScope;
-/**
- * Enforce that a stored thread/run belongs to the caller's owner resource,
- * throwing {@link ForbiddenError} (without echoing the id, to avoid an
- * existence oracle) on a mismatch.
- */
 export declare function assertResourceOwner(ownerResourceId: string, storedResourceId: string, kind: 'thread' | 'run'): void;
-/** A session's trusted principals, in the order they may be read as. */
 export declare function sessionPrincipals(session: {
     userId?: string;
     orgId?: string;
 } | undefined): string[];
-/**
- * Whether `storedResourceId` belongs to `principal` under the composition
- * {@link resolveOwnerResourceId} performs — either the bare principal or one of
- * its `principal:` sub-partitions. The `:` is required so that `alice` does not
- * match a `alice-evil:…` lookalike.
- */
 export declare function isOwnedByPrincipal(storedResourceId: string, principal: string): boolean;
-/**
- * The `owners` constraint to pass to `AgentRunService.listThreads` for a caller.
- *
- * Returns `undefined` — not `[]` — for a session with no principal, because an
- * empty list means "match nothing" whereas a sessionless deployment (agent
- * `no-auth`) has no ownership model to constrain by. Keeping that carve-out here
- * rather than at each call site stops it from being re-derived inconsistently.
- */
 export declare function threadOwnerConstraint(session: {
     userId?: string;
     orgId?: string;
-} | undefined): string[] | undefined;
-/**
- * Whether a stored thread/run may be read by the caller. Shaped as a predicate
- * so it can back a `pikkuPermission` — authorization belongs in a function's
- * `permissions` field, never in its body.
- *
- * Unlike {@link assertResourceOwner}, which compares against a single composed
- * owner key on the run path, this guards the thread-management reads where the
- * caller supplies only a `threadId` — so ownership has to be derived from the
- * session rather than from the request.
- *
- * A session with no principal means the deployment opted out of authorization
- * (agent `no-auth`), so there is no ownership model to enforce and access is not
- * gated — mirroring {@link resolveOwnerResourceId}'s sessionless fallback to a
- * bare resourceId.
- */
+} | undefined): string[];
 export declare function canAccessThread(storedResourceId: string, session: {
     userId?: string;
     orgId?: string;
 } | undefined): boolean;
 export type StreamAIAgentOptions = {
     requiresToolApproval?: 'all' | 'explicit' | false;
-    /**
-     * Invoked as soon as the run's AIRunStateService id exists, so transport
-     * wrappers (e.g. the AG-UI bridge) can stamp the real runId on RUN_STARTED.
-     */
     onRunCreated?: (runId: string) => void;
 };
+export declare const APPROVAL_REQUIRED: unique symbol;
 /**
- * Non-forgeable brand for the sub-agent approval marker. Only framework code
- * (the delegating sub-agent tools below) sets this Symbol on a tool result; a
- * sub-agent's LLM-shaped `result.object` — plain JSON — cannot carry a Symbol,
- * so `checkForApprovals` trusts the brand rather than the `__approvalRequired`
- * string key to decide an approval must be surfaced.
+ * In-process brand proving a credential request was produced by pikku itself and
+ * not by tool output an attacker can influence. Never serialized — a value that
+ * has crossed a JSON boundary has lost the brand and is treated as untrusted.
  */
-export declare const APPROVAL_REQUIRED: unique symbol;
+export declare const CREDENTIAL_REQUIRED: unique symbol;
 export declare class ToolApprovalRequired extends PikkuError {
     readonly toolCallId: string;
     readonly toolName: string;
@@ -119,10 +65,6 @@ export interface AddonCredentialRequirement {
     type: 'wire';
     oauth2: boolean;
 }
-/**
- * Given a list of tool names (e.g. ["oauth-api:getProfile"]),
- * returns the wire OAuth credentials required by their addons.
- */
 export declare function getAddonCredentialRequirements(toolNames: string[]): AddonCredentialRequirement[];
 export type StreamContext = {
     channel: AIStreamChannel;
@@ -136,26 +78,6 @@ export declare const resolveAgent: (agentName: string) => {
     packageName: string | null;
     resolvedName: string;
 };
-/**
- * Enforces an agent's own authorization before it runs: session presence
- * (`auth`), then `scopes`, then `permissions`.
- *
- * The ordering mirrors the function runner — scopes are an AND gate checked
- * first, so they can only ever narrow access, and a missing scope short-circuits
- * before any permission function does I/O.
- *
- * `auth` follows `pikkuSessionlessFunc` rather than `pikkuFunc`: a session is
- * required only when `auth: true` is set explicitly. An agent is normally
- * reached from a function that has already enforced its own auth, and agents are
- * also run from genuinely sessionless contexts (crons, queue workers), so
- * requiring a session by default would reject those without adding a meaningful
- * gate. `scopes` and `permissions` are always enforced when declared.
- *
- * Globals are evaluated here too (via {@link runPermissions}) rather than being
- * assumed to have already run: an agent is reachable from entry points that do
- * not go through the function runner, and re-evaluating an AND gate of
- * side-effect-free predicates is idempotent.
- */
 export declare function assertAgentAuthorized(agent: CoreAIAgent, params: RunAIAgentParams, packageName: string | null): Promise<void>;
 export declare function buildInstructions(agentName: string, packageName: string | null): Promise<string>;
 export type ScopedChannel = AIStreamChannel & {
@@ -168,17 +90,6 @@ export type ScopedChannel = AIStreamChannel & {
     }>;
 };
 export declare function createScopedChannel(parent: AIStreamChannel, agentName: string, session: string): ScopedChannel;
-/**
- * Build the run input for a delegated sub-agent.
- *
- * `context` is the PARENT run's identifier block (the "Current context" text
- * with organizationId, project/stage ids). A sub-agent's tool-call schema only
- * carries { message, session }, so unless the sub-agent inherits the parent's
- * context it never sees the authoritative ids — it depends on the model
- * re-typing them into `message`, which weak models botch, causing
- * schema/permission rejections and retry loops. Forwarding it here is the
- * regression this seam guards.
- */
 export declare function buildSubAgentRunInput(message: string, threadId: string, resourceId: string, parentContext?: string): {
     message: string;
     threadId: string;