@pikku/core 0.12.143 → 0.12.145

package/dist/wirings/agent/agent-helpers.d.ts

@@ -1,14 +1,49 @@
 import type { AgentInterruptResult } from './agent-interrupt.js';
+/**
+ * Builds a function config that runs `agentName` to completion through `rpc.agent.run` and
+ * returns its result, for wiring an agent as an ordinary (non-streaming) endpoint.
+ *
+ * The agent's own `auth`, `scopes` and `permissions` are checked on every call, and the thread
+ * is partitioned under the caller's session principal, so a client-supplied `resourceId` can never
+ * reach another user's thread. A run that hits a tool needing approval returns `status: 'suspended'`
+ * with its `pendingApprovals`.
+ *
+ * @param agentName - The agent to run.
+ * @returns A `{ func }` to pass to `wireHTTP`, `wireChannel` or similar.
+ * @example snippet: aiAgentInvoke
+ */
 export declare function agent<TAgentMap extends Record<string, {
     output: any;
 }>>(agentName: string & keyof TAgentMap): {
     func: (services: any, data: any, wire: any) => Promise<any>;
 };
+/**
+ * Builds a function config that streams an agent run to the wire's channel as AG-UI events,
+ * through `rpc.agent.stream`. Requires a wiring that provides a channel (an SSE route or a
+ * WebSocket); authorization and thread partitioning are as for `agent`.
+ *
+ * @param agentName - The agent to stream. When omitted, it is read from `agentName` on the input,
+ * so one route can serve several agents; every agent stays subject to its own auth checks.
+ * @returns A `{ func }` to pass to a streaming wiring.
+ * @throws Error when no agent name is given either way, or the wire has no channel.
+ * @example snippet: aiAgentStream
+ */
 export declare function agentStream<TAgentMap extends Record<string, {
     output: any;
 }>>(agentName?: string & keyof TAgentMap): {
     func: (services: any, data: any, wire: any) => Promise<void>;
 };
+/**
+ * Builds a function config that answers one pending tool approval on a suspended run and streams
+ * the continuation, through `rpc.agent.resume`.
+ *
+ * Only the run's owner (the session principal it was created under) may resume it, and the agent's
+ * auth checks run again, so a revoked grant blocks the resume. Concurrent resumes of the same tool
+ * call are claimed atomically; the loser fails rather than running the tool twice.
+ *
+ * @returns A `{ func }` taking `{ runId, toolCallId, approved }`, for a streaming wiring.
+ * @example snippet: agentApproval
+ */
 export declare function agentResume(): {
     func: (services: any, data: {
         runId: string;
@@ -16,15 +51,40 @@ export declare function agentResume(): {
         approved: boolean;
     }, wire: any) => Promise<void>;
 };
+/**
+ * Builds a function config that stops a running agent (barge-in, a stop button, a timeout),
+ * through `rpc.agent.interrupt`.
+ *
+ * Only the run's owner may interrupt it; the agent's auth checks are deliberately not re-run, so a
+ * user can always stop their own run. Tools already executing keep running and are reported in the
+ * result rather than rolled back.
+ *
+ * @returns A `{ func }` taking `{ runId, reason? }` and returning whether the run was stopped and
+ * which tools were still in flight.
+ */
 export declare function agentInterrupt(): {
     func: (services: any, data: {
         runId: string;
         reason?: 'speech' | 'user' | 'timeout';
     }, wire: any) => Promise<AgentInterruptResult>;
 };
+/**
+ * Builds a function config that answers a batch of pending tool approvals and runs the suspended
+ * agent to completion without streaming, through `rpc.agent.approve`.
+ *
+ * Ownership, re-authorization and the once-only claim behave as for `agentResume`. The route is
+ * scoped to `agentName`: a run that belongs to any other agent is refused with a `ForbiddenError`
+ * (403), even when the caller owns it.
+ *
+ * @param agentName - The agent this route answers approvals for; also types the result.
+ * @returns A `{ func }` taking `{ runId, approvals }`.
+ * @throws ForbiddenError when the run belongs to a different agent.
+ * @throws Error when every approval in the batch was already resolved by another caller.
+ * @example snippet: agentApproval
+ */
 export declare function agentApprove<TAgentMap extends Record<string, {
     output: any;
-}>>(_agentName: string & keyof TAgentMap): {
+}>>(agentName: string & keyof TAgentMap): {
     func: (services: any, data: {
         runId: string;
         approvals: {

package/dist/wirings/agent/agent-helpers.js

@@ -1,3 +1,16 @@
+/**
+ * Builds a function config that runs `agentName` to completion through `rpc.agent.run` and
+ * returns its result, for wiring an agent as an ordinary (non-streaming) endpoint.
+ *
+ * The agent's own `auth`, `scopes` and `permissions` are checked on every call, and the thread
+ * is partitioned under the caller's session principal, so a client-supplied `resourceId` can never
+ * reach another user's thread. A run that hits a tool needing approval returns `status: 'suspended'`
+ * with its `pendingApprovals`.
+ *
+ * @param agentName - The agent to run.
+ * @returns A `{ func }` to pass to `wireHTTP`, `wireChannel` or similar.
+ * @example snippet: aiAgentInvoke
+ */
 export function agent(agentName) {
     return {
         func: async (_services, data, { rpc }) => {
@@ -5,6 +18,17 @@ export function agent(agentName) {
         },
     };
 }
+/**
+ * Builds a function config that streams an agent run to the wire's channel as AG-UI events,
+ * through `rpc.agent.stream`. Requires a wiring that provides a channel (an SSE route or a
+ * WebSocket); authorization and thread partitioning are as for `agent`.
+ *
+ * @param agentName - The agent to stream. When omitted, it is read from `agentName` on the input,
+ * so one route can serve several agents; every agent stays subject to its own auth checks.
+ * @returns A `{ func }` to pass to a streaming wiring.
+ * @throws Error when no agent name is given either way, or the wire has no channel.
+ * @example snippet: aiAgentStream
+ */
 export function agentStream(agentName) {
     return {
         func: async (_services, data, { rpc }) => {
@@ -21,6 +45,17 @@ export function agentStream(agentName) {
         },
     };
 }
+/**
+ * Builds a function config that answers one pending tool approval on a suspended run and streams
+ * the continuation, through `rpc.agent.resume`.
+ *
+ * Only the run's owner (the session principal it was created under) may resume it, and the agent's
+ * auth checks run again, so a revoked grant blocks the resume. Concurrent resumes of the same tool
+ * call are claimed atomically; the loser fails rather than running the tool twice.
+ *
+ * @returns A `{ func }` taking `{ runId, toolCallId, approved }`, for a streaming wiring.
+ * @example snippet: agentApproval
+ */
 export function agentResume() {
     return {
         func: async (_services, data, { rpc }) => {
@@ -31,6 +66,17 @@ export function agentResume() {
         },
     };
 }
+/**
+ * Builds a function config that stops a running agent (barge-in, a stop button, a timeout),
+ * through `rpc.agent.interrupt`.
+ *
+ * Only the run's owner may interrupt it; the agent's auth checks are deliberately not re-run, so a
+ * user can always stop their own run. Tools already executing keep running and are reported in the
+ * result rather than rolled back.
+ *
+ * @returns A `{ func }` taking `{ runId, reason? }` and returning whether the run was stopped and
+ * which tools were still in flight.
+ */
 export function agentInterrupt() {
     return {
         func: async (_services, data, { rpc }) => {
@@ -38,10 +84,24 @@ export function agentInterrupt() {
         },
     };
 }
-export function agentApprove(_agentName) {
+/**
+ * Builds a function config that answers a batch of pending tool approvals and runs the suspended
+ * agent to completion without streaming, through `rpc.agent.approve`.
+ *
+ * Ownership, re-authorization and the once-only claim behave as for `agentResume`. The route is
+ * scoped to `agentName`: a run that belongs to any other agent is refused with a `ForbiddenError`
+ * (403), even when the caller owns it.
+ *
+ * @param agentName - The agent this route answers approvals for; also types the result.
+ * @returns A `{ func }` taking `{ runId, approvals }`.
+ * @throws ForbiddenError when the run belongs to a different agent.
+ * @throws Error when every approval in the batch was already resolved by another caller.
+ * @example snippet: agentApproval
+ */
+export function agentApprove(agentName) {
     return {
         func: async (_services, data, { rpc }) => {
-            return rpc.agent.approve(data.runId, data.approvals);
+            return rpc.agent.approve(data.runId, data.approvals, agentName);
         },
     };
 }

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

@@ -60,6 +60,11 @@ export interface AgentInterruptResult {
      */
     inFlightTools: string[];
 }
+/**
+ * A live run's interrupt handle: the abort signal the model call listens to, plus tracking for
+ * tools still executing when an interrupt lands.
+ * @internal
+ */
 export interface InterruptibleRunHandle {
     readonly signal: AbortSignal;
     /** Set at the moment the run is interrupted; `undefined` on a clean run. */

package/dist/wirings/agent/agent-output.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Removes the `null`s a provider sends for optional fields.
+ *
+ * Strict structured-output modes (OpenAI's among them) require every property,
+ * so a runner widens each optional one to nullable and the model answers
+ * `null` for "absent". Validating that against the schema the agent declared —
+ * where the field is optional, not nullable — would reject a valid answer, so
+ * a `null` is dropped wherever the original schema neither requires the field
+ * nor allows `null` for it. Anything else is left for validation to judge.
+ */
+export declare const dropNullOptionals: (schema: unknown, value: unknown) => unknown;
+/**
+ * Checks a `pikkuAgent`'s structured output against the output schema it was
+ * declared with, which codegen compiled to JSON Schema under `schemaName`.
+ *
+ * Returns the object with provider `null`s for optional fields removed; throws
+ * `AgentOutputValidationError` when it does not match. No object — the run
+ * ended on text — is returned as is.
+ */
+export declare const validateAgentOutput: (agentName: string, schemaName: string | null | undefined, object: unknown, packageName?: string | null) => Promise<unknown>;

package/dist/wirings/agent/agent-output.js

@@ -0,0 +1,69 @@
+import { AgentOutputValidationError, UnprocessableContentError, } from '../../errors/errors.js';
+import { getSingletonServices, pikkuState } from '../../pikku-state.js';
+import { validateSchema } from '../../schema.js';
+const allowsNull = (schema) => {
+    if (!schema)
+        return true;
+    if (schema.type === 'null')
+        return true;
+    if (Array.isArray(schema.type) && schema.type.includes('null'))
+        return true;
+    return [...(schema.anyOf ?? []), ...(schema.oneOf ?? [])].some(allowsNull);
+};
+/**
+ * Removes the `null`s a provider sends for optional fields.
+ *
+ * Strict structured-output modes (OpenAI's among them) require every property,
+ * so a runner widens each optional one to nullable and the model answers
+ * `null` for "absent". Validating that against the schema the agent declared —
+ * where the field is optional, not nullable — would reject a valid answer, so
+ * a `null` is dropped wherever the original schema neither requires the field
+ * nor allows `null` for it. Anything else is left for validation to judge.
+ */
+export const dropNullOptionals = (schema, value) => {
+    const node = schema;
+    if (!node || typeof node !== 'object' || value === null)
+        return value;
+    if (Array.isArray(value)) {
+        return node.items
+            ? value.map((item) => dropNullOptionals(node.items, item))
+            : value;
+    }
+    if (typeof value !== 'object' || !node.properties)
+        return value;
+    const required = new Set(node.required ?? []);
+    const result = {};
+    for (const [key, field] of Object.entries(value)) {
+        const fieldSchema = node.properties[key];
+        if (field === null && !required.has(key) && !allowsNull(fieldSchema)) {
+            continue;
+        }
+        result[key] = dropNullOptionals(fieldSchema, field);
+    }
+    return result;
+};
+// knowledge: decisions/internals/agent-structured-output-is-validated-against-the-declared-schema.md
+/**
+ * Checks a `pikkuAgent`'s structured output against the output schema it was
+ * declared with, which codegen compiled to JSON Schema under `schemaName`.
+ *
+ * Returns the object with provider `null`s for optional fields removed; throws
+ * `AgentOutputValidationError` when it does not match. No object — the run
+ * ended on text — is returned as is.
+ */
+export const validateAgentOutput = async (agentName, schemaName, object, packageName = null) => {
+    if (!schemaName || object === undefined)
+        return object;
+    const normalized = dropNullOptionals(pikkuState(packageName, 'misc', 'schemas').get(schemaName), object);
+    const { logger, schema } = getSingletonServices();
+    try {
+        await validateSchema(logger, schema, schemaName, normalized, packageName);
+    }
+    catch (error) {
+        if (error instanceof UnprocessableContentError) {
+            throw new AgentOutputValidationError(agentName, [error.message]);
+        }
+        throw error;
+    }
+    return normalized;
+};

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

@@ -3,6 +3,10 @@ import type { CoreAgent, AgentInput, AgentToolDef, AgentMessage, AgentStreamChan
 import type { AgentRunnerParams } from '../../services/agent-runner-service.js';
 import { PikkuError } from '../../errors/error-handler.js';
 import type { SessionService } from '../../services/user-session-service.js';
+/**
+ * Per-request context for running an agent: the caller's session, credential access and, for
+ * a sessionless request, the minted anonymous owner id.
+ */
 export type RunAgentParams = {
     sessionService?: SessionService<CoreUserSession>;
     /** Credential accessor for the current request — used to read per-user overrides (e.g. AI_API_KEY). */
@@ -13,17 +17,41 @@ export type RunAgentParams = {
 export declare function resolveSessionPrincipal(params: RunAgentParams, sessionScope: SessionScope | undefined): string | undefined;
 export declare function resolveOwnerResourceId(params: RunAgentParams, sessionScope: SessionScope | undefined, requestedResourceId: string): string;
 export declare function assertResourcePrincipalOwner(params: RunAgentParams, sessionScope: SessionScope | undefined, storedResourceId: string, kind: 'thread' | 'run'): void;
+/**
+ * Refuses a run that belongs to a different agent than the one a route was
+ * built for. Ownership is checked first, so only the run's owner learns which
+ * agent it belongs to.
+ */
+export declare function assertRunBelongsToAgent(run: {
+    runId: string;
+    agentName: string;
+}, expectedAgentName: string | undefined): void;
 export declare function agentSessionScope(agentName: string): SessionScope;
 export declare function assertResourceOwner(ownerResourceId: string, storedResourceId: string, kind: 'thread' | 'run'): void;
 export declare function sessionPrincipals(session: {
     userId?: string;
     orgId?: string;
 } | undefined): string[];
+/**
+ * Whether a stored thread or run `resourceId` belongs to `principal`: it is the principal itself
+ * or one of its `principal:` sub-partitions.
+ */
 export declare function isOwnedByPrincipal(storedResourceId: string, principal: string): boolean;
+/**
+ * The principals (user id, then org id) a session may list threads for. Pass it as the `owners`
+ * filter to `AgentRunService.listThreads`; an empty array, for a missing session, matches nothing.
+ */
 export declare function threadOwnerConstraint(session: {
     userId?: string;
     orgId?: string;
 } | undefined): string[];
+/**
+ * Whether `session` may read the thread or run stored under `storedResourceId`: true only when the
+ * resource belongs to the session's user or org. A missing session is always refused.
+ *
+ * Use it before returning a thread over the wire; answering "not found" for both a missing and a
+ * forbidden thread avoids revealing which threads exist.
+ */
 export declare function canAccessThread(storedResourceId: string, session: {
     userId?: string;
     orgId?: string;
@@ -42,6 +70,10 @@ export declare function canAccessThread(storedResourceId: string, session: {
  * against it.
  */
 export declare const agentCallOptions: (input: AgentInput) => AgentInput;
+/**
+ * Options for a streamed run: which tool calls need approval (`'all'`, only tools that declare it,
+ * or none) and a callback receiving the run id once it is created.
+ */
 export type StreamAgentOptions = {
     requiresToolApproval?: 'all' | 'explicit' | false;
     onRunCreated?: (runId: string) => void;
@@ -53,6 +85,10 @@ export declare const APPROVAL_REQUIRED: unique symbol;
  * has crossed a JSON boundary has lost the brand and is treated as untrusted.
  */
 export declare const CREDENTIAL_REQUIRED: unique symbol;
+/**
+ * Raised when a tool call needs a human's approval before it runs. The run is suspended with the
+ * call recorded in `pendingApprovals`, and resumes through `agentResume` or `agentApprove`.
+ */
 export declare class ToolApprovalRequired extends PikkuError {
     readonly toolCallId: string;
     readonly toolName: string;
@@ -63,6 +99,11 @@ export declare class ToolApprovalRequired extends PikkuError {
     readonly agentRunId?: string;
     constructor(toolCallId: string, toolName: string, args: unknown, reason?: string, displayToolName?: string, displayArgs?: unknown, agentRunId?: string);
 }
+/**
+ * Raised when a tool needs a credential the user has not connected. The run is suspended and the
+ * client is sent the credential's name, type and connect URL. Only requests pikku itself produced
+ * are honoured, so tool output cannot forge one.
+ */
 export declare class ToolCredentialRequired extends PikkuError {
     readonly toolCallId: string;
     readonly toolName: string;

package/dist/wirings/agent/agent-prepare.js

@@ -7,8 +7,6 @@ import { pikkuState, getSingletonServices } from '../../pikku-state.js';
 import { createMiddlewareSessionWireProps } from '../../services/user-session-service.js';
 import { randomUUID } from './agent-utils.js';
 import { awaitPendingInterruptNote } from './agent-interrupt.js';
-import { streamAgent } from './agent-stream.js';
-import { runAgent } from './agent-runner.js';
 import { resolveNamespace, ContextAwareRPCService, } from '../../wirings/rpc/rpc-runner.js';
 import { getOrCreatePackageSingletonServices } from '../../wirings/addon/addon-runner.js';
 import { resolveMemoryServices, loadContextMessages, trimMessages, } from './agent-memory.js';
@@ -41,6 +39,16 @@ export function assertResourcePrincipalOwner(params, sessionScope, storedResourc
         throw new ForbiddenError(`Not authorized to access this ${kind}`);
     }
 }
+/**
+ * Refuses a run that belongs to a different agent than the one a route was
+ * built for. Ownership is checked first, so only the run's owner learns which
+ * agent it belongs to.
+ */
+export function assertRunBelongsToAgent(run, expectedAgentName) {
+    if (expectedAgentName && run.agentName !== expectedAgentName) {
+        throw new ForbiddenError(`Run ${run.runId} belongs to agent '${run.agentName}', not '${expectedAgentName}'`);
+    }
+}
 export function agentSessionScope(agentName) {
     return resolveAgent(agentName).agent.sessionScope ?? 'user';
 }
@@ -52,13 +60,28 @@ export function assertResourceOwner(ownerResourceId, storedResourceId, kind) {
 export function sessionPrincipals(session) {
     return [session?.userId, session?.orgId].filter((principal) => Boolean(principal));
 }
+/**
+ * Whether a stored thread or run `resourceId` belongs to `principal`: it is the principal itself
+ * or one of its `principal:` sub-partitions.
+ */
 export function isOwnedByPrincipal(storedResourceId, principal) {
     return (storedResourceId === principal ||
         storedResourceId.startsWith(`${principal}:`));
 }
+/**
+ * The principals (user id, then org id) a session may list threads for. Pass it as the `owners`
+ * filter to `AgentRunService.listThreads`; an empty array, for a missing session, matches nothing.
+ */
 export function threadOwnerConstraint(session) {
     return sessionPrincipals(session);
 }
+/**
+ * Whether `session` may read the thread or run stored under `storedResourceId`: true only when the
+ * resource belongs to the session's user or org. A missing session is always refused.
+ *
+ * Use it before returning a thread over the wire; answering "not found" for both a missing and a
+ * forbidden thread avoids revealing which threads exist.
+ */
 export function canAccessThread(storedResourceId, session) {
     const principals = sessionPrincipals(session);
     if (principals.length === 0)
@@ -96,6 +119,10 @@ export const APPROVAL_REQUIRED = Symbol('pikku.ai.approvalRequired');
  * has crossed a JSON boundary has lost the brand and is treated as untrusted.
  */
 export const CREDENTIAL_REQUIRED = Symbol('pikku.ai.credentialRequired');
+/**
+ * Raised when a tool call needs a human's approval before it runs. The run is suspended with the
+ * call recorded in `pendingApprovals`, and resumes through `agentResume` or `agentApprove`.
+ */
 export class ToolApprovalRequired extends PikkuError {
     toolCallId;
     toolName;
@@ -115,6 +142,11 @@ export class ToolApprovalRequired extends PikkuError {
         this.agentRunId = agentRunId;
     }
 }
+/**
+ * Raised when a tool needs a credential the user has not connected. The run is suspended and the
+ * client is sent the credential's name, type and connect URL. Only requests pikku itself produced
+ * are honoured, so tool output cannot forge one.
+ */
 export class ToolCredentialRequired extends PikkuError {
     toolCallId;
     toolName;
@@ -460,6 +492,8 @@ export async function buildToolDefs(params, agentSessionMap, resourceId, agentNa
                         threadId = randomUUID();
                         agentSessionMap.set(sessionKey, threadId);
                     }
+                    // A sub-agent runs on the same runners that build these tools. They
+                    // import this module, so importing them back statically is a cycle.
                     if (streamContext) {
                         const isDelegate = agentMode !== 'supervise';
                         if (isDelegate && streamContext.delegateState) {
@@ -484,6 +518,7 @@ export async function buildToolDefs(params, agentSessionMap, resourceId, agentNa
                                     await subChannel.send(event);
                                 },
                             };
+                        const { streamAgent } = await import('./agent-stream.js');
                         const resultText = await streamAgent(subAgentName, buildSubAgentRunInput(message, threadId, resourceId, parentContext), effectiveChannel, params, agentSessionMap, streamContext.options);
                         if (subChannel.approvals.length > 0) {
                             return {
@@ -503,6 +538,7 @@ export async function buildToolDefs(params, agentSessionMap, resourceId, agentNa
                         });
                         return resultText;
                     }
+                    const { runAgent } = await import('./agent-runner.js');
                     const result = await runAgent(subAgentName, buildSubAgentRunInput(message, threadId, resourceId, parentContext), params, agentSessionMap);
                     if (result.status === 'suspended' &&
                         result.pendingApprovals?.length) {

package/dist/wirings/agent/agent-registry.d.ts

@@ -1,6 +1,14 @@
 import type { CoreAgent } from './agent.types.js';
 import type { AgentRunStateService } from '../../services/agent-run-state-service.js';
 import { type RunAgentParams } from './agent-prepare.js';
+/**
+ * Registers an agent's runtime config under its name. Called by generated code.
+ *
+ * Skipped with a warning when the inspector recorded no metadata for the agent.
+ *
+ * @throws Error when an agent with the same name is already registered.
+ * @internal
+ */
 export declare const addAgent: (agentName: string, agent: CoreAgent<any, any>, packageName?: string | null) => void;
 export declare function approveAgent(agentRunState: AgentRunStateService, runId: string, approvals: {
     toolCallId: string;

package/dist/wirings/agent/agent-registry.js

@@ -1,5 +1,13 @@
 import { pikkuState } from '../../pikku-state.js';
-import { agentSessionScope, assertAgentAuthorized, assertResourcePrincipalOwner, resolveAgent, } from './agent-prepare.js';
+import { agentSessionScope, assertAgentAuthorized, assertResourcePrincipalOwner, assertRunBelongsToAgent, resolveAgent, } from './agent-prepare.js';
+/**
+ * Registers an agent's runtime config under its name. Called by generated code.
+ *
+ * Skipped with a warning when the inspector recorded no metadata for the agent.
+ *
+ * @throws Error when an agent with the same name is already registered.
+ * @internal
+ */
 export const addAgent = (agentName, agent, packageName = null) => {
     const agentsMeta = pikkuState(packageName, 'agent', 'agentsMeta');
     const agentMeta = agentsMeta[agentName];
@@ -20,9 +28,7 @@ export async function approveAgent(agentRunState, runId, approvals, expectedAgen
     if (!run)
         throw new Error('Run not found: ' + runId);
     assertResourcePrincipalOwner(params, agentSessionScope(run.agentName), run.resourceId, 'run');
-    if (expectedAgentName && run.agentName !== expectedAgentName) {
-        throw new Error(`Run ${runId} belongs to agent '${run.agentName}', not '${expectedAgentName}'`);
-    }
+    assertRunBelongsToAgent(run, expectedAgentName);
     if (run.status !== 'suspended')
         throw new Error('Run is not suspended: ' + run.status);
     const { agent, packageName } = resolveAgent(run.agentName);

package/dist/wirings/agent/agent-runner.d.ts

@@ -1,6 +1,39 @@
 import type { AgentInput, AgentOutput } from './agent.types.js';
 import { type RunAgentParams } from './agent-prepare.js';
+/**
+ * Runs an agent to completion: loads the thread, applies agent middleware, calls the model step by
+ * step (up to the agent's `maxSteps`) and persists the messages and run state.
+ *
+ * Before anything runs, the agent's `auth`, `scopes` and `permissions` are checked against the
+ * session, and `input.resourceId` is partitioned under the session principal (or an anonymous id
+ * minted per request), so a caller cannot address another user's thread.
+ *
+ * @param agentName - The agent to run.
+ * @param input - The user message, thread and resource ids, and optional model overrides.
+ * @param params - The caller's session and credential access.
+ * @param agentSessionMap - Sub-agent session ids, shared across delegated calls in one run.
+ * @returns The run's text or structured output, its steps and usage. A run that needs approval or
+ * a credential, or names RPCs that are not registered, returns `status: 'suspended'` instead.
+ * @throws MissingSessionError when the agent requires auth and there is no session; ForbiddenError
+ * for a scope or permission failure or a thread owned by someone else; AIProviderNotConfiguredError
+ * when no `agentRunner` service is set.
+ */
 export declare function runAgent(agentName: string, input: AgentInput, params: RunAgentParams, agentSessionMap?: Map<string, string>): Promise<AgentOutput>;
+/**
+ * Answers pending approvals on a suspended run and runs it to completion without streaming. Backs
+ * `rpc.agent.approve`.
+ *
+ * Only the run's owner may resume it, and the agent is re-authorized. Each approval is claimed
+ * atomically, so concurrent callers cannot run the same tool twice.
+ *
+ * @param runId - The suspended run.
+ * @param approvals - The decision for each pending tool call.
+ * @param params - The caller's session.
+ * @param expectedAgentName - When given, the run must belong to this agent.
+ * @returns The run's final output, or `status: 'suspended'` again if more approvals are needed.
+ * @throws ForbiddenError when the caller does not own the run; Error when the run is missing, not
+ * suspended, belongs to another agent, or every approval was already claimed.
+ */
 export declare function resumeAgentSync(runId: string, approvals: {
     toolCallId: string;
     approved: boolean;

package/dist/wirings/agent/agent-runner.js

@@ -1,11 +1,12 @@
 import { saveMessages, resolveMemoryServices, loadContextMessages, trimMessages, getWorkingMemoryMiddleware, } from './agent-memory.js';
-import { prepareAgentRun, resolveAgent, buildInstructions, buildToolDefs, resolveOwnerResourceId, agentSessionScope, assertResourcePrincipalOwner, assertAgentAuthorized, } from './agent-prepare.js';
+import { prepareAgentRun, resolveAgent, buildInstructions, buildToolDefs, resolveOwnerResourceId, agentSessionScope, assertResourcePrincipalOwner, assertRunBelongsToAgent, assertAgentAuthorized, } from './agent-prepare.js';
 import { checkForApprovals, appendStepMessages } from './agent-stream.js';
 import { AgentInterruptedError, isAbortError, persistOrphanedToolResults, registerInterruptibleRun, trackInterruptNote, trackToolExecution, } from './agent-interrupt.js';
 import { pikkuState, getSingletonServices } from '../../pikku-state.js';
 import { applyInputMiddleware, describeApprovals, notifyAfterStep, toAccumulatedStep, } from './agent-turn.js';
 import { applyOutputMiddleware, finalizeAgentRun, lastUserMessageText, } from './agent-finalize.js';
 import { resolveModelConfig } from './agent-model-config.js';
+import { validateAgentOutput } from './agent-output.js';
 import { AIProviderNotConfiguredError } from '../../errors/errors.js';
 import { deniedToolResult, randomUUID } from './agent-utils.js';
 function stripNulls(obj) {
@@ -33,13 +34,31 @@ function extractStructuredAssistantOutput(object) {
         uiSpec: record.ui ?? null,
     };
 }
+/**
+ * Runs an agent to completion: loads the thread, applies agent middleware, calls the model step by
+ * step (up to the agent's `maxSteps`) and persists the messages and run state.
+ *
+ * Before anything runs, the agent's `auth`, `scopes` and `permissions` are checked against the
+ * session, and `input.resourceId` is partitioned under the session principal (or an anonymous id
+ * minted per request), so a caller cannot address another user's thread.
+ *
+ * @param agentName - The agent to run.
+ * @param input - The user message, thread and resource ids, and optional model overrides.
+ * @param params - The caller's session and credential access.
+ * @param agentSessionMap - Sub-agent session ids, shared across delegated calls in one run.
+ * @returns The run's text or structured output, its steps and usage. A run that needs approval or
+ * a credential, or names RPCs that are not registered, returns `status: 'suspended'` instead.
+ * @throws MissingSessionError when the agent requires auth and there is no session; ForbiddenError
+ * for a scope or permission failure or a thread owned by someone else; AIProviderNotConfiguredError
+ * when no `agentRunner` service is set.
+ */
 export async function runAgent(agentName, input, params, agentSessionMap) {
     const sessionMap = agentSessionMap ?? new Map();
     input = {
         ...input,
         resourceId: resolveOwnerResourceId(params, agentSessionScope(agentName), input.resourceId),
     };
-    const { agent, agentRunner, storage, memoryConfig, threadId, userMessage, runnerParams, maxSteps, missingRpcs, workingMemorySchemaName, } = await prepareAgentRun(agentName, input, params, sessionMap);
+    const { agent, packageName, resolvedName, agentRunner, storage, memoryConfig, threadId, userMessage, runnerParams, maxSteps, missingRpcs, workingMemorySchemaName, } = await prepareAgentRun(agentName, input, params, sessionMap);
     runnerParams.agentId = agentName;
     const singletonServices = getSingletonServices();
     const { agentRunState } = singletonServices;
@@ -186,7 +205,8 @@ export async function runAgent(agentName, input, params, agentSessionMap) {
             }
             appendStepMessages(runnerParams, stepResult);
         }
-        const finalObject = lastStepResult?.object;
+        const finalObject = await validateAgentOutput(agentName, pikkuState(packageName, 'agent', 'agentsMeta')[resolvedName]
+            ?.outputSchema, lastStepResult?.object, packageName);
         const structuredOutput = extractStructuredAssistantOutput(finalObject);
         const finalText = structuredOutput.text ?? lastStepResult?.text ?? '';
         const result = {
@@ -255,6 +275,21 @@ export async function runAgent(agentName, input, params, agentSessionMap) {
         interruptHandle.release();
     }
 }
+/**
+ * Answers pending approvals on a suspended run and runs it to completion without streaming. Backs
+ * `rpc.agent.approve`.
+ *
+ * Only the run's owner may resume it, and the agent is re-authorized. Each approval is claimed
+ * atomically, so concurrent callers cannot run the same tool twice.
+ *
+ * @param runId - The suspended run.
+ * @param approvals - The decision for each pending tool call.
+ * @param params - The caller's session.
+ * @param expectedAgentName - When given, the run must belong to this agent.
+ * @returns The run's final output, or `status: 'suspended'` again if more approvals are needed.
+ * @throws ForbiddenError when the caller does not own the run; Error when the run is missing, not
+ * suspended, belongs to another agent, or every approval was already claimed.
+ */
 export async function resumeAgentSync(runId, approvals, params, expectedAgentName) {
     const singletonServices = getSingletonServices();
     const { agentRunState } = singletonServices;
@@ -265,9 +300,7 @@ export async function resumeAgentSync(runId, approvals, params, expectedAgentNam
     if (!run)
         throw new Error(`No run found for runId ${runId}`);
     assertResourcePrincipalOwner(params, agentSessionScope(run.agentName), run.resourceId, 'run');
-    if (expectedAgentName && run.agentName !== expectedAgentName) {
-        throw new Error(`Run ${runId} belongs to agent '${run.agentName}', not '${expectedAgentName}'`);
-    }
+    assertRunBelongsToAgent(run, expectedAgentName);
     if (run.status !== 'suspended') {
         throw new Error(`Run ${runId} is not suspended (status: ${run.status})`);
     }
@@ -510,7 +543,7 @@ async function continueAfterToolResultSync(run, agent, packageName, resolvedName
             appendStepMessages(runnerParams, stepResult);
         }
         const finalText = lastStepResult?.text ?? '';
-        const finalObject = lastStepResult?.object;
+        const finalObject = await validateAgentOutput(run.agentName, meta?.outputSchema, lastStepResult?.object, packageName);
         const result = {
             text: finalText,
             steps: accumulatedSteps,