@gnldev/server 0.1.0

package/dist/node.js

@@ -0,0 +1,94 @@
+// Binding the REST API to a Node server — Express, Fastify, Koa, Nest, or bare `node:http`.
+//
+// The twin of packages/studio/src/node.ts, and deliberately a copy rather than an import. A backend
+// that wants agents and no dashboard had to install @gnldev/studio just to reach this function,
+// which drags @gnldev/studio-ui — a React app — into a service that will never render a page. That
+// is backwards, and one subpath is a smaller price than that dependency.
+//
+// The alternative, importing it from the sibling package, was tried and is worse than it looks: a
+// cross-package runtime import resolves through the sibling's BUILT output, so a stale dist turns
+// the call into `undefined` with no error until something downstream fails on empty input. Measured
+// in this repo the same afternoon, in @gnldev/agui, where it emptied an SSE stream and every test in
+// the package failed on `JSON.parse('')`. This file follows the convention sse.ts already set here.
+//
+// KEEP IN SYNC with packages/studio/src/node.ts. If they drift, the two packages answer the same
+// misconfiguration differently, which is worse than either answer.
+//
+// Kept on a subpath so the root export stays runtime-neutral: importing the package must not drag
+// Node's types into a Workers or Deno build.
+import { getRequestListener } from '@hono/node-server';
+import { EDGE_ERROR_CODES } from './edge-errors.js';
+const CARRIES_BODY = new Set(['POST', 'PUT', 'PATCH', 'DELETE']);
+/**
+ * True when the request announced a body and something already drained it.
+ *
+ * A body parser mounted ahead of this handler — `express.json()`, `koa-bodyparser`, Fastify's
+ * built-in JSON parser — reads the stream to the end and hands the result to the framework, not to
+ * us. What arrives here is a POST with no readable body, and the endpoint answers the only thing it
+ * can: "runId is required". Measured on a real Express app: the identical request returns 200 with a
+ * model answer without `express.json()`, and that 400 with it. The message accuses the caller of a
+ * mistake the caller did not make, which is worse than failing.
+ *
+ * Detection is deliberately narrow — a body was ANNOUNCED (content-length or chunked) and the
+ * readable side is ALREADY finished. A GET nobody read does not match; neither does a bodyless POST.
+ */
+function bodyAlreadyConsumed(req) {
+    if (!CARRIES_BODY.has(req.method ?? ''))
+        return false;
+    const announced = Number(req.headers['content-length'] ?? 0) > 0 || req.headers['transfer-encoding'] !== undefined;
+    return announced && req.readableEnded;
+}
+/**
+ * Turns a fetch handler into a Node request listener.
+ *
+ * @experimental Closes the SSE/flush class of bug inside the Node bridge — a hand-written bridge
+ * that omits `res.flushHeaders()` withholds the head until the first chunk, so a quiet event stream
+ * hangs the client forever and nothing throws. It also answers plainly when a body parser upstream
+ * has already drained the request, instead of letting the endpoint blame the caller.
+ *
+ * What it does NOT do: audit the rest of your middleware chain, or touch path prefixes — a host that
+ * mounts under a sub-path has already stripped it from `req.url` (Express) or has not (Koa, Fastify,
+ * node:http), and only the host knows which.
+ *
+ * ```ts
+ * const api = createRestApi(config);
+ *
+ * express().use('/api', toNodeHandler(api));                // Express — before express.json()
+ * await fastify.register(middie); fastify.use('/api', toNodeHandler(api));   // Fastify
+ * koa.use(c2k((rq, rs, _next) => toNodeHandler(api)(rq, rs)));   // Koa — three params, see below
+ * createServer(toNodeHandler(api));                         // node:http
+ * ```
+ *
+ * On Koa, the middleware must declare THREE parameters even though it never calls the third:
+ * `koa-connect` switches on `fn.length` and, below three, assumes the middleware does not terminate
+ * the response — it calls `next()` immediately and Koa writes its own 404 over what was already
+ * sent. Measured: `ERR_HTTP_HEADERS_SENT` and a 404 on every route, from a two-parameter version of
+ * the same working code.
+ *
+ * Bind at the MIDDLEWARE layer, never as a route, and put it ahead of the body parser. Measured:
+ * `fastify.all('/api/*', …)` runs AFTER Fastify's built-in JSON parser has drained the stream —
+ * every GET passes, a POST with a body answers 400. Through `@fastify/middie` the same handler runs
+ * before parsing and works, with the host's own routes keeping their parsed bodies.
+ */
+export function toNodeHandler(handler) {
+    const listener = getRequestListener(handler.fetch);
+    return (req, res) => {
+        // Deliberately NOT re-serialising `req.body` back into a stream. It would make the common case
+        // work and quietly change the bytes — key order, unicode escaping, and nothing at all for
+        // multipart or a raw payload — so a misordered chain would keep running until the day it
+        // matters. Ordering is also the answer the ecosystem settled on: better-auth's Node handler
+        // documents the same constraint, mount before the parser, for the same reason.
+        if (bodyAlreadyConsumed(req)) {
+            res.writeHead(500, { 'content-type': 'application/json' });
+            res.end(JSON.stringify({
+                error: 'request body was already consumed by a body parser mounted ahead of this handler '
+                    + '(express.json, koa-bodyparser, Fastify\'s built-in JSON parser). Mount the GNL handler '
+                    + 'BEFORE the parser — the parser still serves your own routes after it.',
+                code: EDGE_ERROR_CODES.bodyConsumedUpstream,
+            }));
+            return;
+        }
+        return listener(req, res);
+    };
+}
+//# sourceMappingURL=node.js.map

package/dist/node.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"node.js","sourceRoot":"","sources":["../src/node.ts"],"names":[],"mappings":"AAAA,4FAA4F;AAC5F,EAAE;AACF,oGAAoG;AACpG,gGAAgG;AAChG,mGAAmG;AACnG,yEAAyE;AACzE,EAAE;AACF,kGAAkG;AAClG,kGAAkG;AAClG,oGAAoG;AACpG,qGAAqG;AACrG,oGAAoG;AACpG,EAAE;AACF,iGAAiG;AACjG,mEAAmE;AACnE,EAAE;AACF,kGAAkG;AAClG,6CAA6C;AAC7C,OAAO,EAAE,kBAAkB,EAAE,MAAM,mBAAmB,CAAC;AAGvD,OAAO,EAAE,gBAAgB,EAAE,MAAM,kBAAkB,CAAC;AAEpD,MAAM,YAAY,GAAG,IAAI,GAAG,CAAC,CAAC,MAAM,EAAE,KAAK,EAAE,OAAO,EAAE,QAAQ,CAAC,CAAC,CAAC;AAEjE;;;;;;;;;;;;GAYG;AACH,SAAS,mBAAmB,CAAC,GAAoB;IAC/C,IAAI,CAAC,YAAY,CAAC,GAAG,CAAC,GAAG,CAAC,MAAM,IAAI,EAAE,CAAC;QAAE,OAAO,KAAK,CAAC;IACtD,MAAM,SAAS,GAAG,MAAM,CAAC,GAAG,CAAC,OAAO,CAAC,gBAAgB,CAAC,IAAI,CAAC,CAAC,GAAG,CAAC,IAAI,GAAG,CAAC,OAAO,CAAC,mBAAmB,CAAC,KAAK,SAAS,CAAC;IACnH,OAAO,SAAS,IAAI,GAAG,CAAC,aAAa,CAAC;AACxC,CAAC;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AACH,MAAM,UAAU,aAAa,CAAC,OAAqB;IACjD,MAAM,QAAQ,GAAG,kBAAkB,CAAC,OAAO,CAAC,KAAY,CAAC,CAAC;IAC1D,OAAO,CAAC,GAAoB,EAAE,GAAmB,EAAE,EAAE;QACnD,+FAA+F;QAC/F,0FAA0F;QAC1F,yFAAyF;QACzF,4FAA4F;QAC5F,+EAA+E;QAC/E,IAAI,mBAAmB,CAAC,GAAG,CAAC,EAAE,CAAC;YAC7B,GAAG,CAAC,SAAS,CAAC,GAAG,EAAE,EAAE,cAAc,EAAE,kBAAkB,EAAE,CAAC,CAAC;YAC3D,GAAG,CAAC,GAAG,CAAC,IAAI,CAAC,SAAS,CAAC;gBACrB,KAAK,EAAE,mFAAmF;sBACtF,yFAAyF;sBACzF,uEAAuE;gBAC3E,IAAI,EAAE,gBAAgB,CAAC,oBAAoB;aAC5C,CAAC,CAAC,CAAC;YACJ,OAAO;QACT,CAAC;QACD,OAAO,QAAQ,CAAC,GAAG,EAAE,GAAG,CAAC,CAAC;IAC5B,CAAC,CAAC;AACJ,CAAC","sourcesContent":["// Binding the REST API to a Node server — Express, Fastify, Koa, Nest, or bare `node:http`.\n//\n// The twin of packages/studio/src/node.ts, and deliberately a copy rather than an import. A backend\n// that wants agents and no dashboard had to install @gnldev/studio just to reach this function,\n// which drags @gnldev/studio-ui — a React app — into a service that will never render a page. That\n// is backwards, and one subpath is a smaller price than that dependency.\n//\n// The alternative, importing it from the sibling package, was tried and is worse than it looks: a\n// cross-package runtime import resolves through the sibling's BUILT output, so a stale dist turns\n// the call into `undefined` with no error until something downstream fails on empty input. Measured\n// in this repo the same afternoon, in @gnldev/agui, where it emptied an SSE stream and every test in\n// the package failed on `JSON.parse('')`. This file follows the convention sse.ts already set here.\n//\n// KEEP IN SYNC with packages/studio/src/node.ts. If they drift, the two packages answer the same\n// misconfiguration differently, which is worse than either answer.\n//\n// Kept on a subpath so the root export stays runtime-neutral: importing the package must not drag\n// Node's types into a Workers or Deno build.\nimport { getRequestListener } from '@hono/node-server';\nimport type { IncomingMessage, ServerResponse } from 'node:http';\nimport type { FetchHandler } from './handler.js';\nimport { EDGE_ERROR_CODES } from './edge-errors.js';\n\nconst CARRIES_BODY = new Set(['POST', 'PUT', 'PATCH', 'DELETE']);\n\n/**\n * True when the request announced a body and something already drained it.\n *\n * A body parser mounted ahead of this handler — `express.json()`, `koa-bodyparser`, Fastify's\n * built-in JSON parser — reads the stream to the end and hands the result to the framework, not to\n * us. What arrives here is a POST with no readable body, and the endpoint answers the only thing it\n * can: \"runId is required\". Measured on a real Express app: the identical request returns 200 with a\n * model answer without `express.json()`, and that 400 with it. The message accuses the caller of a\n * mistake the caller did not make, which is worse than failing.\n *\n * Detection is deliberately narrow — a body was ANNOUNCED (content-length or chunked) and the\n * readable side is ALREADY finished. A GET nobody read does not match; neither does a bodyless POST.\n */\nfunction bodyAlreadyConsumed(req: IncomingMessage): boolean {\n  if (!CARRIES_BODY.has(req.method ?? '')) return false;\n  const announced = Number(req.headers['content-length'] ?? 0) > 0 || req.headers['transfer-encoding'] !== undefined;\n  return announced && req.readableEnded;\n}\n\n/**\n * Turns a fetch handler into a Node request listener.\n *\n * @experimental Closes the SSE/flush class of bug inside the Node bridge — a hand-written bridge\n * that omits `res.flushHeaders()` withholds the head until the first chunk, so a quiet event stream\n * hangs the client forever and nothing throws. It also answers plainly when a body parser upstream\n * has already drained the request, instead of letting the endpoint blame the caller.\n *\n * What it does NOT do: audit the rest of your middleware chain, or touch path prefixes — a host that\n * mounts under a sub-path has already stripped it from `req.url` (Express) or has not (Koa, Fastify,\n * node:http), and only the host knows which.\n *\n * ```ts\n * const api = createRestApi(config);\n *\n * express().use('/api', toNodeHandler(api));                // Express — before express.json()\n * await fastify.register(middie); fastify.use('/api', toNodeHandler(api));   // Fastify\n * koa.use(c2k((rq, rs, _next) => toNodeHandler(api)(rq, rs)));   // Koa — three params, see below\n * createServer(toNodeHandler(api));                         // node:http\n * ```\n *\n * On Koa, the middleware must declare THREE parameters even though it never calls the third:\n * `koa-connect` switches on `fn.length` and, below three, assumes the middleware does not terminate\n * the response — it calls `next()` immediately and Koa writes its own 404 over what was already\n * sent. Measured: `ERR_HTTP_HEADERS_SENT` and a 404 on every route, from a two-parameter version of\n * the same working code.\n *\n * Bind at the MIDDLEWARE layer, never as a route, and put it ahead of the body parser. Measured:\n * `fastify.all('/api/*', …)` runs AFTER Fastify's built-in JSON parser has drained the stream —\n * every GET passes, a POST with a body answers 400. Through `@fastify/middie` the same handler runs\n * before parsing and works, with the host's own routes keeping their parsed bodies.\n */\nexport function toNodeHandler(handler: FetchHandler) {\n  const listener = getRequestListener(handler.fetch as any);\n  return (req: IncomingMessage, res: ServerResponse) => {\n    // Deliberately NOT re-serialising `req.body` back into a stream. It would make the common case\n    // work and quietly change the bytes — key order, unicode escaping, and nothing at all for\n    // multipart or a raw payload — so a misordered chain would keep running until the day it\n    // matters. Ordering is also the answer the ecosystem settled on: better-auth's Node handler\n    // documents the same constraint, mount before the parser, for the same reason.\n    if (bodyAlreadyConsumed(req)) {\n      res.writeHead(500, { 'content-type': 'application/json' });\n      res.end(JSON.stringify({\n        error: 'request body was already consumed by a body parser mounted ahead of this handler '\n          + '(express.json, koa-bodyparser, Fastify\\'s built-in JSON parser). Mount the GNL handler '\n          + 'BEFORE the parser — the parser still serves your own routes after it.',\n        code: EDGE_ERROR_CODES.bodyConsumedUpstream,\n      }));\n      return;\n    }\n    return listener(req, res);\n  };\n}\n"]}

package/dist/openapi.d.ts

@@ -0,0 +1 @@
+export declare function buildOpenApi(agentNames: string[], workflowNames?: string[], title?: string): any;

package/dist/openapi.js

@@ -0,0 +1,215 @@
+// Generate an OpenAPI 3.1 schema from the createGnl agent + workflow registry (auto-docs).
+import { EDGE_ERROR_CODES } from './edge-errors.js';
+export function buildOpenApi(agentNames, workflowNames = [], title = 'gnl agents') {
+    // ONE identity per call, and the spec says which two spellings it accepts. `required: ['runId']`
+    // is gone rather than widened to a `oneOf`: a workKey-only request is valid, a runId-only request
+    // is valid, and both together are refused — which `oneOf` can express but no generator renders
+    // usefully. The prose carries it, the 400 enforces it.
+    const runBody = {
+        required: true,
+        content: {
+            'application/json': {
+                schema: {
+                    type: 'object',
+                    description: 'Exactly one of `workKey` or `runId` is required.',
+                    properties: {
+                        workKey: {
+                            type: 'string',
+                            description: 'Your name for this unit of work (the invoice being issued, tonight\'s reconciliation) — not for a conversation. The engine derives the run id from it and returns that id in X-Gnl-Run-Id. Sending the same workKey again retries the SAME job; a conversation is `threadId`, a separate field. Keep sensitive data out of it: a workKey is reflected in error details and shown in Studio.',
+                        },
+                        runId: { type: 'string', description: 'A raw run id you already hold (a resume, a fork, an id you stored). Mutually exclusive with workKey.' },
+                        prompt: { type: 'string' },
+                        messages: { type: 'array', items: { type: 'object' } },
+                        threadId: { type: 'string' },
+                        approvals: { type: 'object', additionalProperties: { type: 'boolean' } },
+                    },
+                },
+            },
+        },
+    };
+    const runResponse = {
+        '200': {
+            description: 'Durable run result',
+            content: {
+                'application/json': {
+                    schema: {
+                        type: 'object',
+                        properties: {
+                            ok: { type: 'boolean' },
+                            runId: { type: 'string' },
+                            text: { type: 'string' },
+                            interrupts: { type: 'array', items: { type: 'object' } },
+                        },
+                    },
+                },
+            },
+        },
+        // Decision #1: run-limit exceeded — the request is valid but couldn't be processed with the given
+        // `limits`; deterministic (retry DOESN'T HELP), `limits` can be raised and resumed with the SAME runId (resumable:true).
+        '422': {
+            description: 'Run limit exceeded (RunLimitExceededError/ToolLoopDetectedError) — can continue with the same runId after raising limits',
+            content: {
+                'application/json': {
+                    schema: {
+                        type: 'object',
+                        properties: {
+                            error: { type: 'string' },
+                            code: { type: 'string', enum: [EDGE_ERROR_CODES.runLimitExceeded, EDGE_ERROR_CODES.toolLoopDetected] },
+                            detail: { type: 'object' },
+                            resumable: { type: 'boolean' },
+                        },
+                    },
+                },
+            },
+        },
+    };
+    const paths = {};
+    // Documented as unauthenticated on purpose — see the route comments in index.ts. An orchestrator
+    // reading this spec needs to know it can probe these without arranging a credential first.
+    paths['/health'] = {
+        get: {
+            summary: 'Liveness — is the process alive? No storage access; unauthenticated',
+            description: 'Point LIVENESS probes here. Deliberately independent of storage: a failing database must not cause a healthy process to be killed and restarted.',
+            responses: { '200': { description: '{ status: "ok", uptimeSec }' } },
+        },
+    };
+    paths['/ready'] = {
+        get: {
+            summary: 'Readiness — can it serve traffic? Touches storage; unauthenticated',
+            description: 'Point READINESS/traffic probes here. Returns 503 when the journal is unreachable or does not answer within the probe budget, so the instance leaves the load balancer while staying alive to recover. The underlying error is never returned (it can carry connection details) — it goes to the logs.',
+            responses: {
+                '200': { description: '{ status: "ready" }' },
+                '503': { description: '{ status: "unavailable", storage: "unreachable" }' },
+            },
+        },
+    };
+    paths['/agents'] = {
+        get: { summary: 'List of registered agent metadata', responses: { '200': { description: 'AgentMeta list' } } },
+    };
+    for (const n of agentNames) {
+        paths[`/agents/${n}/run`] = {
+            post: { summary: `Run the '${n}' agent durably`, requestBody: runBody, responses: runResponse },
+        };
+        paths[`/agents/${n}/stream`] = {
+            post: {
+                summary: `Run the '${n}' agent durably + streaming (SSE)`,
+                requestBody: runBody,
+                responses: {
+                    '200': {
+                        description: 'SSE stream: text-delta/tool-call/tool-result/interrupt/done events',
+                        content: { 'text/event-stream': { schema: { type: 'string' } } },
+                    },
+                },
+            },
+        };
+        paths[`/agents/${n}/resume`] = {
+            post: {
+                summary: `Resume the '${n}' agent with runId + approvals`,
+                requestBody: {
+                    required: true,
+                    content: {
+                        'application/json': {
+                            schema: {
+                                type: 'object',
+                                required: ['runId'],
+                                properties: {
+                                    runId: { type: 'string' },
+                                    approvals: { type: 'object', additionalProperties: { type: 'boolean' } },
+                                },
+                            },
+                        },
+                    },
+                },
+                responses: runResponse,
+            },
+        };
+    }
+    if (workflowNames.length) {
+        paths['/workflows'] = {
+            get: { summary: 'List of registered workflows (name + steps)', responses: { '200': { description: 'WorkflowMeta list' } } },
+        };
+        const wfRunBody = {
+            required: true,
+            content: {
+                'application/json': {
+                    schema: {
+                        type: 'object',
+                        properties: {
+                            runId: { type: 'string', description: 'A raw run id (optional; if given, the same id resumes). Mutually exclusive with workKey.' },
+                            workKey: { type: 'string', description: 'Your name for this unit of work; the engine derives the run id from it and returns it in X-Gnl-Run-Id.' },
+                            workScope: {
+                                type: 'string',
+                                enum: ['resource', 'org'],
+                                description: "Which address the workKey is unique within. 'resource' (default) scopes the job to the resourceId that named it; 'org' scopes it to the installation — one job no matter who triggers it (a nightly reconciliation, a scheduled sweep). Choosing 'org' by mistake is the quiet mistake: two callers share one run.",
+                            },
+                            input: { description: 'Workflow input (workflow-specific)' },
+                        },
+                    },
+                },
+            },
+        };
+        const wfRunResponse = {
+            '200': {
+                description: 'WorkflowRunResult',
+                content: {
+                    'application/json': {
+                        schema: {
+                            type: 'object',
+                            properties: {
+                                ok: { type: 'boolean' },
+                                runId: { type: 'string' },
+                                output: { description: 'Workflow output (if completed)' },
+                                suspended: { type: 'boolean' },
+                                stepId: { type: 'string' },
+                                steps: { type: 'array', items: { type: 'object' } },
+                            },
+                        },
+                    },
+                },
+            },
+        };
+        for (const w of workflowNames) {
+            paths[`/workflows/${w}/run`] = {
+                post: { summary: `Run the '${w}' workflow durably (suspend/resume safe)`, requestBody: wfRunBody, responses: wfRunResponse },
+            };
+        }
+    }
+    paths['/runs/{id}'] = {
+        get: {
+            summary: "A run's journal timeline",
+            parameters: [{ name: 'id', in: 'path', required: true, schema: { type: 'string' } }],
+            responses: { '200': { description: 'Journal entry list' } },
+        },
+    };
+    // P0.3 documents the opt-in pagination/filter query params — with none given
+    // the response is still the legacy RunSummary array (see createRestApi's GET /runs JSDoc).
+    paths['/runs'] = {
+        get: {
+            summary: 'Run summaries — legacy array with no params, or a {items,nextCursor} page when ?limit/?cursor/?status/?agent is given',
+            parameters: [
+                { name: 'limit', in: 'query', schema: { type: 'integer', minimum: 1, maximum: 1000 } },
+                // Opaque on purpose — see `Page<T>` in @gnldev/durable. It happens to be a row offset today
+                // and is intended to become a `created_at`+`runId` key; a caller that computes one instead
+                // of echoing `nextCursor` breaks on that change, and has no contract to stand on.
+                {
+                    name: 'cursor',
+                    in: 'query',
+                    description: 'Opaque continuation token — pass back the `nextCursor` from the previous page verbatim. Do not parse or compute it.',
+                    schema: { type: 'string' },
+                },
+                { name: 'status', in: 'query', schema: { type: 'string', enum: ['completed', 'suspended'] } },
+                { name: 'agent', in: 'query', schema: { type: 'string' } },
+            ],
+            responses: { '200': { description: 'RunSummary list, or {items: RunSummary[], nextCursor?: string}' } },
+        },
+    };
+    paths['/runs/{id}/cancel'] = {
+        post: {
+            summary: 'Cancel in-flight generation for a run on THIS server instance (best-effort, single-instance only — see JSDoc)',
+            parameters: [{ name: 'id', in: 'path', required: true, schema: { type: 'string' } }],
+            responses: { '200': { description: '{ok:true, cancelled:number}' }, '404': { description: 'run not found / not visible in this scope' } },
+        },
+    };
+    return { openapi: '3.1.0', info: { title, version: '0.0.0' }, paths };
+}
+//# sourceMappingURL=openapi.js.map

package/dist/openapi.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"openapi.js","sourceRoot":"","sources":["../src/openapi.ts"],"names":[],"mappings":"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","sourcesContent":["// Generate an OpenAPI 3.1 schema from the createGnl agent + workflow registry (auto-docs).\nimport { EDGE_ERROR_CODES } from './edge-errors.js';\n\nexport function buildOpenApi(agentNames: string[], workflowNames: string[] = [], title = 'gnl agents'): any {\n  // ONE identity per call, and the spec says which two spellings it accepts. `required: ['runId']`\n  // is gone rather than widened to a `oneOf`: a workKey-only request is valid, a runId-only request\n  // is valid, and both together are refused — which `oneOf` can express but no generator renders\n  // usefully. The prose carries it, the 400 enforces it.\n  const runBody = {\n    required: true,\n    content: {\n      'application/json': {\n        schema: {\n          type: 'object',\n          description: 'Exactly one of `workKey` or `runId` is required.',\n          properties: {\n            workKey: {\n              type: 'string',\n              description:\n                'Your name for this unit of work (the invoice being issued, tonight\\'s reconciliation) — not for a conversation. The engine derives the run id from it and returns that id in X-Gnl-Run-Id. Sending the same workKey again retries the SAME job; a conversation is `threadId`, a separate field. Keep sensitive data out of it: a workKey is reflected in error details and shown in Studio.',\n            },\n            runId: { type: 'string', description: 'A raw run id you already hold (a resume, a fork, an id you stored). Mutually exclusive with workKey.' },\n            prompt: { type: 'string' },\n            messages: { type: 'array', items: { type: 'object' } },\n            threadId: { type: 'string' },\n            approvals: { type: 'object', additionalProperties: { type: 'boolean' } },\n          },\n        },\n      },\n    },\n  };\n  const runResponse = {\n    '200': {\n      description: 'Durable run result',\n      content: {\n        'application/json': {\n          schema: {\n            type: 'object',\n            properties: {\n              ok: { type: 'boolean' },\n              runId: { type: 'string' },\n              text: { type: 'string' },\n              interrupts: { type: 'array', items: { type: 'object' } },\n            },\n          },\n        },\n      },\n    },\n    // Decision #1: run-limit exceeded — the request is valid but couldn't be processed with the given\n    // `limits`; deterministic (retry DOESN'T HELP), `limits` can be raised and resumed with the SAME runId (resumable:true).\n    '422': {\n      description: 'Run limit exceeded (RunLimitExceededError/ToolLoopDetectedError) — can continue with the same runId after raising limits',\n      content: {\n        'application/json': {\n          schema: {\n            type: 'object',\n            properties: {\n              error: { type: 'string' },\n              code: { type: 'string', enum: [EDGE_ERROR_CODES.runLimitExceeded, EDGE_ERROR_CODES.toolLoopDetected] },\n              detail: { type: 'object' },\n              resumable: { type: 'boolean' },\n            },\n          },\n        },\n      },\n    },\n  };\n\n  const paths: Record<string, any> = {};\n  // Documented as unauthenticated on purpose — see the route comments in index.ts. An orchestrator\n  // reading this spec needs to know it can probe these without arranging a credential first.\n  paths['/health'] = {\n    get: {\n      summary: 'Liveness — is the process alive? No storage access; unauthenticated',\n      description: 'Point LIVENESS probes here. Deliberately independent of storage: a failing database must not cause a healthy process to be killed and restarted.',\n      responses: { '200': { description: '{ status: \"ok\", uptimeSec }' } },\n    },\n  };\n  paths['/ready'] = {\n    get: {\n      summary: 'Readiness — can it serve traffic? Touches storage; unauthenticated',\n      description: 'Point READINESS/traffic probes here. Returns 503 when the journal is unreachable or does not answer within the probe budget, so the instance leaves the load balancer while staying alive to recover. The underlying error is never returned (it can carry connection details) — it goes to the logs.',\n      responses: {\n        '200': { description: '{ status: \"ready\" }' },\n        '503': { description: '{ status: \"unavailable\", storage: \"unreachable\" }' },\n      },\n    },\n  };\n  paths['/agents'] = {\n    get: { summary: 'List of registered agent metadata', responses: { '200': { description: 'AgentMeta list' } } },\n  };\n  for (const n of agentNames) {\n    paths[`/agents/${n}/run`] = {\n      post: { summary: `Run the '${n}' agent durably`, requestBody: runBody, responses: runResponse },\n    };\n    paths[`/agents/${n}/stream`] = {\n      post: {\n        summary: `Run the '${n}' agent durably + streaming (SSE)`,\n        requestBody: runBody,\n        responses: {\n          '200': {\n            description: 'SSE stream: text-delta/tool-call/tool-result/interrupt/done events',\n            content: { 'text/event-stream': { schema: { type: 'string' } } },\n          },\n        },\n      },\n    };\n    paths[`/agents/${n}/resume`] = {\n      post: {\n        summary: `Resume the '${n}' agent with runId + approvals`,\n        requestBody: {\n          required: true,\n          content: {\n            'application/json': {\n              schema: {\n                type: 'object',\n                required: ['runId'],\n                properties: {\n                  runId: { type: 'string' },\n                  approvals: { type: 'object', additionalProperties: { type: 'boolean' } },\n                },\n              },\n            },\n          },\n        },\n        responses: runResponse,\n      },\n    };\n  }\n  if (workflowNames.length) {\n    paths['/workflows'] = {\n      get: { summary: 'List of registered workflows (name + steps)', responses: { '200': { description: 'WorkflowMeta list' } } },\n    };\n    const wfRunBody = {\n      required: true,\n      content: {\n        'application/json': {\n          schema: {\n            type: 'object',\n            properties: {\n              runId: { type: 'string', description: 'A raw run id (optional; if given, the same id resumes). Mutually exclusive with workKey.' },\n              workKey: { type: 'string', description: 'Your name for this unit of work; the engine derives the run id from it and returns it in X-Gnl-Run-Id.' },\n              workScope: {\n                type: 'string',\n                enum: ['resource', 'org'],\n                description:\n                  \"Which address the workKey is unique within. 'resource' (default) scopes the job to the resourceId that named it; 'org' scopes it to the installation — one job no matter who triggers it (a nightly reconciliation, a scheduled sweep). Choosing 'org' by mistake is the quiet mistake: two callers share one run.\",\n              },\n              input: { description: 'Workflow input (workflow-specific)' },\n            },\n          },\n        },\n      },\n    };\n    const wfRunResponse = {\n      '200': {\n        description: 'WorkflowRunResult',\n        content: {\n          'application/json': {\n            schema: {\n              type: 'object',\n              properties: {\n                ok: { type: 'boolean' },\n                runId: { type: 'string' },\n                output: { description: 'Workflow output (if completed)' },\n                suspended: { type: 'boolean' },\n                stepId: { type: 'string' },\n                steps: { type: 'array', items: { type: 'object' } },\n              },\n            },\n          },\n        },\n      },\n    };\n    for (const w of workflowNames) {\n      paths[`/workflows/${w}/run`] = {\n        post: { summary: `Run the '${w}' workflow durably (suspend/resume safe)`, requestBody: wfRunBody, responses: wfRunResponse },\n      };\n    }\n  }\n\n  paths['/runs/{id}'] = {\n    get: {\n      summary: \"A run's journal timeline\",\n      parameters: [{ name: 'id', in: 'path', required: true, schema: { type: 'string' } }],\n      responses: { '200': { description: 'Journal entry list' } },\n    },\n  };\n  // P0.3 documents the opt-in pagination/filter query params — with none given\n  // the response is still the legacy RunSummary array (see createRestApi's GET /runs JSDoc).\n  paths['/runs'] = {\n    get: {\n      summary: 'Run summaries — legacy array with no params, or a {items,nextCursor} page when ?limit/?cursor/?status/?agent is given',\n      parameters: [\n        { name: 'limit', in: 'query', schema: { type: 'integer', minimum: 1, maximum: 1000 } },\n        // Opaque on purpose — see `Page<T>` in @gnldev/durable. It happens to be a row offset today\n        // and is intended to become a `created_at`+`runId` key; a caller that computes one instead\n        // of echoing `nextCursor` breaks on that change, and has no contract to stand on.\n        {\n          name: 'cursor',\n          in: 'query',\n          description: 'Opaque continuation token — pass back the `nextCursor` from the previous page verbatim. Do not parse or compute it.',\n          schema: { type: 'string' },\n        },\n        { name: 'status', in: 'query', schema: { type: 'string', enum: ['completed', 'suspended'] } },\n        { name: 'agent', in: 'query', schema: { type: 'string' } },\n      ],\n      responses: { '200': { description: 'RunSummary list, or {items: RunSummary[], nextCursor?: string}' } },\n    },\n  };\n  paths['/runs/{id}/cancel'] = {\n    post: {\n      summary: 'Cancel in-flight generation for a run on THIS server instance (best-effort, single-instance only — see JSDoc)',\n      parameters: [{ name: 'id', in: 'path', required: true, schema: { type: 'string' } }],\n      responses: { '200': { description: '{ok:true, cancelled:number}' }, '404': { description: 'run not found / not visible in this scope' } },\n    },\n  };\n\n  return { openapi: '3.1.0', info: { title, version: '0.0.0' }, paths };\n}\n"]}

package/dist/sse.d.ts

@@ -0,0 +1,57 @@
+import { streamSSE } from 'hono/streaming';
+import type { Context } from 'hono';
+import type { Interrupt } from '@gnldev/durable';
+/**
+ * `streamSSE` plus the two headers a live stream needs to survive the trip to the browser.
+ *
+ * Hono sets `Cache-Control: no-cache`, which says "don't serve this from cache" and says nothing
+ * about re-encoding. So a compression middleware in the host's chain happily takes the stream and
+ * buffers it: measured on a real Express app, `compression()` turned 13 progressive chunks with the
+ * first at 750ms into ONE chunk delivered at the end. Status 200, no error, no live screen — the
+ * failure is invisible from both sides. `no-transform` is the standard way to say don't, and
+ * `compression` honours it (measured: first byte 1520ms -> 302ms with the flag on).
+ *
+ * `X-Accel-Buffering: no` is the nginx-specific half, and measurement narrowed where it matters to
+ * one square of a 2x2 — behind a real nginx, same stream dripping five deltas 300ms apart:
+ *
+ * HTTP/1.1 + gzip, no header  → ONE chunk at 1511ms      (collapsed)
+ * HTTP/1.1 + gzip, header     → 306, 606, 911, 1211, 1511
+ * HTTP/2   + gzip, no header  → 316, 616, 916, 1217, 1518 (fine without it)
+ * HTTP/2   + gzip, header     → 312, 612, 913, 1214, 1514
+ *
+ * So it is load-bearing exactly when the CLIENT speaks HTTP/1.1 to a proxy that gzips, and inert
+ * everywhere else — including HTTP/2, which is what a browser usually gets over TLS. That leaves
+ * plenty of real traffic in the square that breaks: internal clients on plain HTTP, curl's default,
+ * anything not a modern browser. Worth a header; not worth believing it covers more than it does.
+ *
+ * Set AFTER `streamSSE` on purpose: it writes `Cache-Control` itself, so anything set on the context
+ * beforehand is overwritten. Patching the returned Response is what actually survives.
+ *
+ * Kept IN SYNC with packages/studio/src/sse.ts.
+ */
+export declare function sseResponse(c: Context, cb: Parameters<typeof streamSSE>[1], onError?: Parameters<typeof streamSSE>[2]): Response;
+/**
+ * Extracts suspended tool calls (Interrupt) from a completed step list — the SAME logic as
+ * runDurable, and now literally the same function: the sentinel goes straight into durable's
+ * `surfacedInterrupts`.
+ *
+ * It used to push the RAW sentinel, and that was wrong in exactly one shape — the one that matters
+ * most on this channel. A sub-agent that hits a human gate suspends its PARENT's record too, and
+ * that record is keyed by the parent's proxy call id because the suspend record, the replay and
+ * `consumeExistingRecord` all work through it. The engine surfaces the CHILD's interrupts and
+ * durable-tool deliberately IGNORES an answer addressed to the proxy — so a client following the
+ * standard contract (`approvals[interrupt.toolCallId] = true`) against this stream was answering an
+ * id the engine drops on the floor. Chat/SSE is the actual end-user channel: the question appeared,
+ * the human approved it, and nothing happened.
+ */
+export declare function interruptsFromSteps(steps: any[]): Interrupt[];
+/** pipeAgentStream options (opt-in — if not given, behavior is identical to before except for the id field). */
+export interface PipeAgentStreamOptions {
+    /**
+     * The last event id the client saw (resolved from the Last-Event-ID header or body.lastEventId).
+     * If given, events with id <= lastEventId are NOT WRITTEN (production still runs from the start — replay is cheap).
+     */
+    lastEventId?: number;
+}
+/** Stream fullStream as SSE, then send interrupt + done events. Returns a Hono Response. */
+export declare function pipeAgentStream(c: Context, runId: string, result: any, opts?: PipeAgentStreamOptions): Response;