@cogitator-ai/tetsu 0.2.0 → 0.3.0

package/README.md

@@ -63,24 +63,26 @@ A Tetsu controller named `Cogitator`: `operationId`s in the OpenAPI document are
 
 ## Endpoints
 
-| Method   | Path                       | Description                             |
-| -------- | -------------------------- | --------------------------------------- |
-| `GET`    | `/health`, `/ready`        | Liveness and readiness, without `auth`  |
-| `GET`    | `/agents`                  | Agents with their description and tools |
-| `POST`   | `/agents/:name/run`        | Run an agent and wait for the answer    |
-| `POST`   | `/agents/:name/stream`     | Run an agent over SSE                   |
-| `GET`    | `/tools`                   | Tools of every agent, as JSON Schema    |
-| `GET`    | `/threads/:id`             | Messages of a memory thread             |
-| `POST`   | `/threads/:id/messages`    | Append a message                        |
-| `DELETE` | `/threads/:id`             | Delete a thread                         |
-| `GET`    | `/workflows`               | Workflows with their nodes              |
-| `POST`   | `/workflows/:name/run`     | Run a workflow                          |
-| `POST`   | `/workflows/:name/stream`  | Run a workflow over SSE                 |
-| `GET`    | `/swarms`                  | Swarms with their agents                |
-| `POST`   | `/swarms/:name/run`        | Run a swarm                             |
-| `POST`   | `/swarms/:name/stream`     | Run a swarm over SSE                    |
-| `GET`    | `/swarms/:name/blackboard` | Configured blackboard sections          |
-| `GET`    | `/ws`                      | WebSocket, when `websocket` is set      |
+| Method   | Path                          | Description                             |
+| -------- | ----------------------------- | --------------------------------------- |
+| `GET`    | `/health`, `/ready`           | Liveness and readiness, without `auth`  |
+| `GET`    | `/agents`                     | Agents with their description and tools |
+| `POST`   | `/agents/:name/run`           | Run an agent and wait for the answer    |
+| `POST`   | `/agents/:name/stream`        | Run an agent over SSE                   |
+| `POST`   | `/agents/:name/resume`        | Resume a run paused for approvals       |
+| `POST`   | `/agents/:name/resume/stream` | Resume a paused run over SSE            |
+| `GET`    | `/tools`                      | Tools of every agent, as JSON Schema    |
+| `GET`    | `/threads/:id`                | Messages of a memory thread             |
+| `POST`   | `/threads/:id/messages`       | Append a message                        |
+| `DELETE` | `/threads/:id`                | Delete a thread                         |
+| `GET`    | `/workflows`                  | Workflows with their nodes              |
+| `POST`   | `/workflows/:name/run`        | Run a workflow                          |
+| `POST`   | `/workflows/:name/stream`     | Run a workflow over SSE                 |
+| `GET`    | `/swarms`                     | Swarms with their agents                |
+| `POST`   | `/swarms/:name/run`           | Run a swarm                             |
+| `POST`   | `/swarms/:name/stream`        | Run a swarm over SSE                    |
+| `GET`    | `/swarms/:name/blackboard`    | Configured blackboard sections          |
+| `GET`    | `/ws`                         | WebSocket, when `websocket` is set      |
 
 Request bodies:
 
@@ -88,6 +90,13 @@ Request bodies:
 // POST /agents/:name/run, /agents/:name/stream
 { input: string; context?: Record<string, unknown>; threadId?: string }
 
+// POST /agents/:name/resume, /agents/:name/resume/stream
+{
+  threadId: string;
+  decisions?: Record<string, { approved: boolean; reason?: string }>; // by tool call id
+  defaultDecision?: { approved: boolean; reason?: string };
+}
+
 // POST /swarms/:name/run, /swarms/:name/stream
 { input: string; context?: Record<string, unknown>; threadId?: string; timeout?: number }
 
@@ -113,6 +122,7 @@ Every error is answered in Tetsu's envelope:
 | 403     | `THREAD_FORBIDDEN`                                         | `authorizeThread` refused the thread                                 |
 | 404     | `AGENT_NOT_FOUND`, `WORKFLOW_NOT_FOUND`, `SWARM_NOT_FOUND` | No such name                                                         |
 | 409     | `BLACKBOARD_DISABLED`                                      | The swarm has no blackboard                                          |
+| 409     | `RUN_NOT_PAUSED`                                           | A resume named a thread without a paused run                         |
 | 422     | `VALIDATION_FAILED`                                        | The body or the path failed its schema; `issues` lists every problem |
 | 501     | `PACKAGE_NOT_INSTALLED`                                    | `@cogitator-ai/workflows` or `@cogitator-ai/swarms` is missing       |
 | 503     | `MEMORY_NOT_CONFIGURED`                                    | A thread endpoint was called on a runtime without memory             |
@@ -201,6 +211,39 @@ cogitatorController({
 
 Use it for rules ownership does not express, such as thread ids your server hands out.
 
+## Approvals
+
+A tool with `requiresApproval` pauses the run before it executes. `POST /agents/:name/run` then answers with `status: 'paused'` and the calls waiting for a decision; the run's checkpoint stays on the server, stored by the runtime per thread:
+
+```json
+{
+  "output": "Let me refund that.",
+  "threadId": "thread_…",
+  "status": "paused",
+  "pendingApprovals": [
+    {
+      "toolCallId": "call_1",
+      "toolName": "refund",
+      "arguments": { "order": "A-1", "amount": 500 },
+      "description": "Refund an order",
+      "sideEffects": ["payment"]
+    }
+  ],
+  "usage": { "inputTokens": 10, "outputTokens": 5, "totalTokens": 15 },
+  "toolCalls": []
+}
+```
+
+A stream that pauses sends `{"type":"approval-required","threadId":"…","approvals":[…]}` right before `finish`. Continue with the decisions:
+
+```bash
+curl -X POST localhost:3000/cogitator/agents/support/resume \
+  -H 'content-type: application/json' \
+  -d '{ "threadId": "thread_…", "decisions": { "call_1": { "approved": true } } }'
+```
+
+Approved calls run, declined ones answer the model with the `reason`, and calls without a decision (and no `defaultDecision`) pause the run again. `/agents/:name/resume/stream` streams the rest of the run like `/stream`. Only the user the run belongs to can resume it (`403 THREAD_ACCESS_DENIED` otherwise; `authorizeThread` is checked too), and a thread without a paused run answers `409 RUN_NOT_PAUSED`. Over the WebSocket, send `{ type: 'resume', id?, payload: { name, threadId, decisions?, defaultDecision? } }`.
+
 ## Streaming
 
 `/stream` endpoints answer with `text/event-stream` through `@tetsujs/sse`: keep-alive comments every 15 seconds, backpressure, and the run is aborted when the client goes away. Events follow the Cogitator stream protocol shared with the other adapters, one JSON object per `data:` line, ending with `data: [DONE]`:
@@ -218,6 +261,8 @@ data: {"type":"finish","messageId":"msg_…","usage":{"inputTokens":12,"outputTo
 data: [DONE]
 ```
 
+An agent with `reasoning: { summary: true }` also streams its reasoning summary as `reasoning-start`, `reasoning-delta` and `reasoning-end` events. A text or reasoning part opens with its first delta and is closed before a part of the other kind, a tool call or `finish`, so parts never overlap. `POST /agents/:name/run` returns the summary as `reasoning`, and `usage` gains `reasoningTokens`, `cachedInputTokens` and `cacheWriteTokens` when the provider reports them.
+
 A run that fails ends with `{"type":"error","message":"…","code":"…"}` instead of `finish`. An unexpected failure is also reported to the application's `reportError` with `source: "stream"`. Workflow streams send `workflow` events (`node_started`, `node_completed`, `node_error`, `node_progress`, `workflow_completed`), swarm streams send `swarm` events (`agent_start`, `agent_complete`, `agent_error`, `message`, `swarm_completed`).
 
 Validation, `401`, `403` and `404` are answered as JSON before the stream opens.
@@ -230,11 +275,12 @@ cogitatorController({ cogitator, agents, auth, websocket: true });
 
 The handshake runs `auth` like any route. Each socket runs one agent, workflow or swarm at a time.
 
-| Client sends                                                                                                  | Server answers                                                                                       |
-| ------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------- |
-| `{ type: 'run', id?, payload: { type: 'agent' \| 'workflow' \| 'swarm', name, input, context?, threadId? } }` | `event` frames: `token`, `tool-call`, `tool-result`, then `complete` with the result, or `cancelled` |
-| `{ type: 'stop' }`                                                                                            | cancels the current run                                                                              |
-| `{ type: 'ping', id? }`                                                                                       | `{ type: 'pong', id }`                                                                               |
+| Client sends                                                                                                  | Server answers                                                                                                    |
+| ------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------- |
+| `{ type: 'run', id?, payload: { type: 'agent' \| 'workflow' \| 'swarm', name, input, context?, threadId? } }` | `event` frames: `token`, `reasoning`, `tool-call`, `tool-result`, then `complete` with the result, or `cancelled` |
+| `{ type: 'resume', id?, payload: { name, threadId, decisions?, defaultDecision? } }`                          | the same frames for an agent run paused for [approvals](#approvals)                                               |
+| `{ type: 'stop' }`                                                                                            | cancels the current run                                                                                           |
+| `{ type: 'ping', id? }`                                                                                       | `{ type: 'pong', id }`                                                                                            |
 
 Errors arrive as `{ type: 'error', id, error, code }` and leave the socket open; an invalid frame gets `code: 'INVALID_MESSAGE'`. Closing the socket cancels its run. Bun's server-level options such as `maxPayloadLength` are set where the app is served:
 

package/dist/controller.d.ts

@@ -40,6 +40,21 @@ export declare const cogitatorController: (deps: CogitatorDeps) => {
                 context: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
                 threadId: z.ZodOptional<z.ZodString>;
             }, z.core.$strip>;
+        }, z.core.$strip>, z.ZodObject<{
+            type: z.ZodLiteral<"resume">;
+            id: z.ZodOptional<z.ZodString>;
+            payload: z.ZodObject<{
+                threadId: z.ZodString;
+                decisions: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodObject<{
+                    approved: z.ZodBoolean;
+                    reason: z.ZodOptional<z.ZodString>;
+                }, z.core.$strip>>>;
+                defaultDecision: z.ZodOptional<z.ZodObject<{
+                    approved: z.ZodBoolean;
+                    reason: z.ZodOptional<z.ZodString>;
+                }, z.core.$strip>>;
+                name: z.ZodString;
+            }, z.core.$strip>;
         }, z.core.$strip>], "type">;
     }, {
         readonly beforeParse: readonly [import("@tetsujs/core").Hook<"beforeParse", import("@tetsujs/core").BaseCtx & {
@@ -116,12 +131,27 @@ export declare const cogitatorController: (deps: CogitatorDeps) => {
                     inputTokens: z.ZodNumber;
                     outputTokens: z.ZodNumber;
                     totalTokens: z.ZodNumber;
+                    reasoningTokens: z.ZodOptional<z.ZodNumber>;
+                    cachedInputTokens: z.ZodOptional<z.ZodNumber>;
+                    cacheWriteTokens: z.ZodOptional<z.ZodNumber>;
                 }, z.core.$strip>;
                 toolCalls: z.ZodArray<z.ZodObject<{
                     id: z.ZodString;
                     name: z.ZodString;
                     arguments: z.ZodRecord<z.ZodString, z.ZodUnknown>;
                 }, z.core.$strip>>;
+                reasoning: z.ZodOptional<z.ZodString>;
+                status: z.ZodOptional<z.ZodEnum<{
+                    completed: "completed";
+                    paused: "paused";
+                }>>;
+                pendingApprovals: z.ZodOptional<z.ZodArray<z.ZodObject<{
+                    toolCallId: z.ZodString;
+                    toolName: z.ZodString;
+                    arguments: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+                    description: z.ZodString;
+                    sideEffects: z.ZodOptional<z.ZodArray<z.ZodString>>;
+                }, z.core.$strip>>>;
             }, z.core.$strip>;
             readonly 403: z.ZodObject<{
                 status: z.ZodNumber;
@@ -210,6 +240,9 @@ export declare const cogitatorController: (deps: CogitatorDeps) => {
             inputTokens: number;
             outputTokens: number;
             totalTokens: number;
+            reasoningTokens?: number | undefined;
+            cachedInputTokens?: number | undefined;
+            cacheWriteTokens?: number | undefined;
         };
         toolCalls: {
             id: string;
@@ -217,6 +250,15 @@ export declare const cogitatorController: (deps: CogitatorDeps) => {
             arguments: Record<string, unknown>;
         }[];
         structured?: unknown;
+        reasoning?: string | undefined;
+        status?: "completed" | "paused" | undefined;
+        pendingApprovals?: {
+            toolCallId: string;
+            toolName: string;
+            arguments: Record<string, unknown>;
+            description: string;
+            sideEffects?: string[] | undefined;
+        }[] | undefined;
     }>, false>;
     streamAgent: import("@tetsujs/core").RouteDef<"/agents/:name/stream", {
         readonly params: z.ZodObject<{
@@ -251,6 +293,198 @@ export declare const cogitatorController: (deps: CogitatorDeps) => {
             readonly error: unknown;
         }, unknown>];
     }, undefined, "POST", Promise<Response>, false>;
+    resumeAgent: import("@tetsujs/core").RouteDef<"/agents/:name/resume", {
+        readonly params: z.ZodObject<{
+            name: z.ZodString;
+        }, z.core.$strip>;
+        readonly body: z.ZodObject<{
+            threadId: z.ZodString;
+            decisions: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodObject<{
+                approved: z.ZodBoolean;
+                reason: z.ZodOptional<z.ZodString>;
+            }, z.core.$strip>>>;
+            defaultDecision: z.ZodOptional<z.ZodObject<{
+                approved: z.ZodBoolean;
+                reason: z.ZodOptional<z.ZodString>;
+            }, z.core.$strip>>;
+        }, z.core.$strip>;
+        readonly response: {
+            readonly 200: z.ZodObject<{
+                output: z.ZodString;
+                structured: z.ZodOptional<z.ZodUnknown>;
+                threadId: z.ZodString;
+                usage: z.ZodObject<{
+                    inputTokens: z.ZodNumber;
+                    outputTokens: z.ZodNumber;
+                    totalTokens: z.ZodNumber;
+                    reasoningTokens: z.ZodOptional<z.ZodNumber>;
+                    cachedInputTokens: z.ZodOptional<z.ZodNumber>;
+                    cacheWriteTokens: z.ZodOptional<z.ZodNumber>;
+                }, z.core.$strip>;
+                toolCalls: z.ZodArray<z.ZodObject<{
+                    id: z.ZodString;
+                    name: z.ZodString;
+                    arguments: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+                }, z.core.$strip>>;
+                reasoning: z.ZodOptional<z.ZodString>;
+                status: z.ZodOptional<z.ZodEnum<{
+                    completed: "completed";
+                    paused: "paused";
+                }>>;
+                pendingApprovals: z.ZodOptional<z.ZodArray<z.ZodObject<{
+                    toolCallId: z.ZodString;
+                    toolName: z.ZodString;
+                    arguments: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+                    description: z.ZodString;
+                    sideEffects: z.ZodOptional<z.ZodArray<z.ZodString>>;
+                }, z.core.$strip>>>;
+            }, z.core.$strip>;
+            readonly 403: z.ZodObject<{
+                status: z.ZodNumber;
+                message: z.ZodString;
+                error: z.ZodEnum<{
+                    [x: string]: string;
+                }>;
+            }, z.core.$strip>;
+            readonly 404: z.ZodObject<{
+                status: z.ZodNumber;
+                message: z.ZodString;
+                error: z.ZodEnum<{
+                    [x: string]: string;
+                }>;
+            }, z.core.$strip>;
+            readonly 409: z.ZodObject<{
+                status: z.ZodNumber;
+                message: z.ZodString;
+                error: z.ZodEnum<{
+                    [x: string]: string;
+                }>;
+            }, z.core.$strip>;
+            readonly 400: z.ZodObject<{
+                status: z.ZodNumber;
+                message: z.ZodString;
+                error: z.ZodEnum<{
+                    [x: string]: string;
+                }>;
+            }, z.core.$strip>;
+            readonly 429: z.ZodObject<{
+                status: z.ZodNumber;
+                message: z.ZodString;
+                error: z.ZodEnum<{
+                    [x: string]: string;
+                }>;
+            }, z.core.$strip>;
+            readonly 500: z.ZodObject<{
+                status: z.ZodNumber;
+                message: z.ZodString;
+                error: z.ZodEnum<{
+                    [x: string]: string;
+                }>;
+            }, z.core.$strip>;
+            readonly 502: z.ZodObject<{
+                status: z.ZodNumber;
+                message: z.ZodString;
+                error: z.ZodEnum<{
+                    [x: string]: string;
+                }>;
+            }, z.core.$strip>;
+            readonly 503: z.ZodObject<{
+                status: z.ZodNumber;
+                message: z.ZodString;
+                error: z.ZodEnum<{
+                    [x: string]: string;
+                }>;
+            }, z.core.$strip>;
+            readonly 504: z.ZodObject<{
+                status: z.ZodNumber;
+                message: z.ZodString;
+                error: z.ZodEnum<{
+                    [x: string]: string;
+                }>;
+            }, z.core.$strip>;
+            readonly 507: z.ZodObject<{
+                status: z.ZodNumber;
+                message: z.ZodString;
+                error: z.ZodEnum<{
+                    [x: string]: string;
+                }>;
+            }, z.core.$strip>;
+        };
+    }, {
+        readonly beforeParse: readonly [import("@tetsujs/core").Hook<"beforeParse", import("@tetsujs/core").BaseCtx & {
+            readonly params: {
+                [x: string]: string;
+            };
+        }, Pick<import("./auth.js").CallerFields, "cogitatorAuth">>];
+        readonly onError: readonly [import("@tetsujs/core").Hook<"onError", import("@tetsujs/core").BaseCtx & {
+            readonly error: unknown;
+        }, unknown>];
+    }, undefined, "POST", Promise<{
+        output: string;
+        threadId: string;
+        usage: {
+            inputTokens: number;
+            outputTokens: number;
+            totalTokens: number;
+            reasoningTokens?: number | undefined;
+            cachedInputTokens?: number | undefined;
+            cacheWriteTokens?: number | undefined;
+        };
+        toolCalls: {
+            id: string;
+            name: string;
+            arguments: Record<string, unknown>;
+        }[];
+        structured?: unknown;
+        reasoning?: string | undefined;
+        status?: "completed" | "paused" | undefined;
+        pendingApprovals?: {
+            toolCallId: string;
+            toolName: string;
+            arguments: Record<string, unknown>;
+            description: string;
+            sideEffects?: string[] | undefined;
+        }[] | undefined;
+    }>, false>;
+    streamResumeAgent: import("@tetsujs/core").RouteDef<"/agents/:name/resume/stream", {
+        readonly params: z.ZodObject<{
+            name: z.ZodString;
+        }, z.core.$strip>;
+        readonly body: z.ZodObject<{
+            threadId: z.ZodString;
+            decisions: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodObject<{
+                approved: z.ZodBoolean;
+                reason: z.ZodOptional<z.ZodString>;
+            }, z.core.$strip>>>;
+            defaultDecision: z.ZodOptional<z.ZodObject<{
+                approved: z.ZodBoolean;
+                reason: z.ZodOptional<z.ZodString>;
+            }, z.core.$strip>>;
+        }, z.core.$strip>;
+        readonly response: {
+            readonly 403: z.ZodObject<{
+                status: z.ZodNumber;
+                message: z.ZodString;
+                error: z.ZodEnum<{
+                    [x: string]: string;
+                }>;
+            }, z.core.$strip>;
+            readonly 404: z.ZodObject<{
+                status: z.ZodNumber;
+                message: z.ZodString;
+                error: z.ZodLiteral<"AGENT_NOT_FOUND">;
+            }, z.core.$strip>;
+        };
+    }, {
+        readonly beforeParse: readonly [import("@tetsujs/core").Hook<"beforeParse", import("@tetsujs/core").BaseCtx & {
+            readonly params: {
+                [x: string]: string;
+            };
+        }, Pick<import("./auth.js").CallerFields, "cogitatorAuth">>];
+        readonly onError: readonly [import("@tetsujs/core").Hook<"onError", import("@tetsujs/core").BaseCtx & {
+            readonly error: unknown;
+        }, unknown>];
+    }, undefined, "POST", Promise<Response>, false>;
     getThread: import("@tetsujs/core").RouteDef<"/threads/:id", {
         readonly params: z.ZodObject<{
             id: z.ZodString;

package/dist/controller.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"controller.d.ts","sourceRoot":"","sources":["../src/controller.ts"],"names":[],"mappings":"AAqBA,OAAO,KAAK,EACV,OAAO,EAMR,MAAM,qBAAqB,CAAC;AAE7B,OAAO,KAAK,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AA8C7B,OAAO,KAAK,EAAe,aAAa,EAAE,MAAM,YAAY,CAAC;AA+C7D;;;;;;;;;;;;;;;;GAgBG;AACH,eAAO,MAAM,mBAAmB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CA6W9B,CAAC"}
+{"version":3,"file":"controller.d.ts","sourceRoot":"","sources":["../src/controller.ts"],"names":[],"mappings":"AAmBA,OAAO,KAAK,EACV,OAAO,EAMR,MAAM,qBAAqB,CAAC;AAE7B,OAAO,KAAK,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAmD7B,OAAO,KAAK,EAAe,aAAa,EAAE,MAAM,YAAY,CAAC;AA0D7D;;;;;;;;;;;;;;;;GAgBG;AACH,eAAO,MAAM,mBAAmB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CA8b9B,CAAC"}

package/dist/controller.js

@@ -1,21 +1,23 @@
 import { controller, route } from '@tetsujs/core';
 import { sse } from '@tetsujs/sse';
 import { countMessageTokens } from '@cogitator-ai/memory';
-import { createErrorEvent, createFinishEvent, createStartEvent, createSwarmEvent, createTextDeltaEvent, createTextEndEvent, createTextStartEvent, createToolCallDeltaEvent, createToolCallEndEvent, createToolCallStartEvent, createToolResultEvent, createWorkflowEvent, generateId, } from '@cogitator-ai/server-shared';
+import { createApprovalRequiredEvent, createErrorEvent, createFinishEvent, createStartEvent, createSwarmEvent, createToolCallDeltaEvent, createToolCallEndEvent, createToolCallStartEvent, createToolResultEvent, createWorkflowEvent, generateId, } from '@cogitator-ai/server-shared';
 import { assertThreadAccess, ensureThreadAccess } from '@cogitator-ai/core';
 import { httpError } from '@tetsujs/core';
 import { resolveCaller } from './auth.js';
 import { clientClosedRequest, cogitatorErrors, describeError } from './errors.js';
-import { checkThreadAccess, executeSwarm, executeWorkflow, findAgent, findSwarm, findWorkflow, listAgents, listSwarms, listTools, listWorkflows, runAgent, serializeSwarmUsage, toAgentRunResponse, toSwarmRunResponse, toWorkflowRunResponse, } from './operations.js';
-import { AddMessageBody, AddMessageResponse, AgentListResponse, AgentRunResponse, BlackboardResponse, errorEnvelope, errorsEnvelope, failureEnvelope, HealthResponse, NameParams, ReadyResponse, RUN_FAILURES, RunBody, SwarmListResponse, SwarmRunBody, SwarmRunResponse, ThreadParams, ThreadResponse, ToolListResponse, WorkflowListResponse, WorkflowRunBody, WorkflowRunResponse, } from './schemas.js';
+import { checkThreadAccess, executeSwarm, executeWorkflow, findAgent, findSwarm, findWorkflow, listAgents, listSwarms, listTools, listWorkflows, resumeAgent, runAgent, serializeSwarmUsage, toAgentRunResponse, toPendingApprovals, toResumeDecisions, toSwarmRunResponse, toWorkflowRunResponse, } from './operations.js';
+import { AddMessageBody, AddMessageResponse, AgentListResponse, AgentRunResponse, BlackboardResponse, errorEnvelope, errorsEnvelope, failureEnvelope, HealthResponse, NameParams, ReadyResponse, ResumeBody, RUN_FAILURES, RunBody, SwarmListResponse, SwarmRunBody, SwarmRunResponse, ThreadParams, ThreadResponse, ToolListResponse, WorkflowListResponse, WorkflowRunBody, WorkflowRunResponse, } from './schemas.js';
 import { cogitatorSocket } from './socket.js';
-import { DONE_EVENT, eventsOf, resolveSignal, sseEvent } from './streaming.js';
+import { DONE_EVENT, eventsOf, MessageParts, resolveSignal, sseEvent } from './streaming.js';
 const AgentNotFound = errorEnvelope('AGENT_NOT_FOUND', 'No agent is registered under this name');
 const WorkflowNotFound = errorEnvelope('WORKFLOW_NOT_FOUND', 'No workflow is registered under this name');
 const SwarmNotFound = errorEnvelope('SWARM_NOT_FOUND', 'No swarm is registered under this name');
 const RunNotFound = failureEnvelope(404, 'No agent, workflow or swarm is registered under this name, or the agent called a tool it does not have', ['SWARM_NOT_FOUND']);
 const NotImplemented = failureEnvelope(501, 'The optional package this endpoint needs is not installed', ['PACKAGE_NOT_INSTALLED']);
 const ThreadForbidden = failureEnvelope(403, 'The memory thread belongs to another user, or `authorizeThread` refused it', ['THREAD_FORBIDDEN']);
+const ResumeForbidden = failureEnvelope(403, 'The paused run belongs to another user, or `authorizeThread` refused the thread', ['THREAD_FORBIDDEN']);
+const ResumeConflict = failureEnvelope(409, 'The thread has no paused run (`RUN_NOT_PAUSED`), or the agent is already running');
 const ThreadUnreadable = errorsEnvelope(['MEMORY_READ_FAILED'], 'The memory adapter could not read the thread, so its owner is unknown');
 const ThreadUnwritable = errorsEnvelope(['MEMORY_READ_FAILED', 'MEMORY_WRITE_FAILED'], 'The memory adapter could not read or create the thread');
 const MemoryNotConfigured = errorEnvelope('MEMORY_NOT_CONFIGURED', 'The Cogitator runtime has no memory adapter');
@@ -128,9 +130,66 @@ export const cogitatorController = controller('Cogitator', (deps) => {
                 const auth = ctx.cogitatorAuth;
                 const body = ctx.body;
                 await checkThreadAccess(deps, auth, body.threadId);
-                return sse(ctx, (signal) => agentEvents(deps, agent, body, auth, signal), {
-                    until: until(),
-                });
+                return sse(ctx, (signal) => agentEvents((callbacks) => runAgent(deps, agent, { ...body, ...callbacks }, auth), signal), { until: until() });
+            },
+        }),
+        resumeAgent: route({
+            method: 'POST',
+            path: '/agents/:name/resume',
+            schema: {
+                params: NameParams,
+                body: ResumeBody,
+                response: {
+                    ...RUN_FAILURES,
+                    200: AgentRunResponse,
+                    403: ResumeForbidden,
+                    404: RunNotFound,
+                    409: ResumeConflict,
+                },
+            },
+            hooks: { beforeParse: [caller], onError: [errors] },
+            docs: {
+                summary: 'Resume a run paused for tool approvals and wait for its answer',
+                description: 'Approved calls run, declined ones answer the model with the reason, and calls without a decision pause the run again.',
+                tags: ['agents'],
+            },
+            handler: async (ctx) => {
+                const agent = findAgent(deps, ctx.params.name);
+                const { threadId } = ctx.body;
+                await checkThreadAccess(deps, ctx.cogitatorAuth, threadId);
+                const signal = ctx.req.signal;
+                try {
+                    const result = await resumeAgent(deps, agent, threadId, { ...toResumeDecisions(ctx.body), signal }, ctx.cogitatorAuth);
+                    return toAgentRunResponse(result);
+                }
+                catch (error) {
+                    if (signal.aborted)
+                        throw clientClosedRequest();
+                    throw error;
+                }
+            },
+        }),
+        streamResumeAgent: route({
+            method: 'POST',
+            path: '/agents/:name/resume/stream',
+            schema: {
+                params: NameParams,
+                body: ResumeBody,
+                response: { 403: ThreadForbidden, 404: AgentNotFound },
+            },
+            hooks: { beforeParse: [caller], onError: [errors] },
+            docs: {
+                summary: 'Resume a run paused for tool approvals and stream the rest of it',
+                description: STREAM_DESCRIPTION,
+                tags: ['agents'],
+            },
+            handler: async (ctx) => {
+                const agent = findAgent(deps, ctx.params.name);
+                const auth = ctx.cogitatorAuth;
+                const { threadId } = ctx.body;
+                const decisions = toResumeDecisions(ctx.body);
+                await checkThreadAccess(deps, auth, threadId);
+                return sse(ctx, (signal) => agentEvents((callbacks) => resumeAgent(deps, agent, threadId, { ...decisions, ...callbacks }, auth), signal), { until: until() });
             },
         }),
         getThread: route({
@@ -386,23 +445,24 @@ function* failure(error) {
     if (described.unexpected)
         throw error;
 }
-async function* agentEvents(deps, agent, body, auth, signal) {
+async function* agentEvents(start, signal) {
     const messageId = generateId('msg');
-    const textId = generateId('txt');
+    const parts = new MessageParts();
     let result;
     yield sseEvent(createStartEvent(messageId));
-    yield sseEvent(createTextStartEvent(textId));
     try {
         yield* eventsOf(signal, async (emit) => {
-            result = await runAgent(deps, agent, {
-                ...body,
+            const emitAll = (events) => {
+                for (const event of events)
+                    emit(sseEvent(event));
+            };
+            result = await start({
                 stream: true,
                 signal,
-                onToken: (token) => {
-                    if (token)
-                        emit(sseEvent(createTextDeltaEvent(textId, token)));
-                },
+                onToken: (token) => emitAll(parts.delta('text', token)),
+                onReasoning: (delta) => emitAll(parts.delta('reasoning', delta)),
                 onToolCall: (call) => {
+                    emitAll(parts.end('reasoning'));
                     emit(sseEvent(createToolCallStartEvent(call.id, call.name)));
                     emit(sseEvent(createToolCallDeltaEvent(call.id, JSON.stringify(call.arguments))));
                     emit(sseEvent(createToolCallEndEvent(call.id)));
@@ -410,19 +470,22 @@ async function* agentEvents(deps, agent, body, auth, signal) {
                 onToolResult: (toolResult) => {
                     emit(sseEvent(createToolResultEvent(generateId('res'), toolResult.callId, toolResult.result)));
                 },
-            }, auth);
+            });
         });
     }
     catch (error) {
         if (signal.aborted)
             return;
-        yield sseEvent(createTextEndEvent(textId));
+        yield* parts.end().map(sseEvent);
         yield* failure(error);
         return;
     }
     if (signal.aborted || !result)
         return;
-    yield sseEvent(createTextEndEvent(textId));
+    yield* parts.end().map(sseEvent);
+    if (result.status === 'paused') {
+        yield sseEvent(createApprovalRequiredEvent(result.threadId, toPendingApprovals(result.pendingApprovals ?? [])));
+    }
     yield sseEvent(createFinishEvent(messageId, {
         inputTokens: result.usage.inputTokens,
         outputTokens: result.usage.outputTokens,