@zenera/server 0.0.0-stage → 1.2.0

package/README.md

@@ -1,3 +1,246 @@
-# Temporary Holding Version
+# @zenera/server
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+A project's chats over HTTP, for every user its host vouches for: the server
+the agent image runs. Each turn opens the project with
+[`@zenera/engine`](../engine), streams its events as
+[AG-UI](https://docs.ag-ui.com), and runs the agents' commands in a sandbox —
+under bubblewrap inside the agent image, with podman anywhere else, as `zen run`.
+
+```sh
+zen server start --insecure                            # try it here: tokens read, not checked
+zen server token --user ann                            # a token such a server takes
+zen server start --jwt-public-key app.pub.pem          # behind zenera-app
+zen server start --container --insecure                # in the project's agent image, under bwrap
+zen server check                                       # could it start here?
+zen server status                                      # a running one's report
+```
+
+With `--insecure`, startup prints a ready-to-open HTTP link to the bundled
+React chat page served at `/chat`. It includes the server address and an unsigned JWT in the
+fragment (not a query parameter); the page removes the fragment and keeps the
+token only in memory. The default browser user is `local`; use `--user ann` to
+test another user's sessions. The same works with `--container`: the outer CLI
+prints the host's published address and port. HTTP links preserve the fragment
+when opened from a terminal on macOS, unlike file-document links.
+The fragment ends with `&open=1` so terminal link detection preserves the unsigned
+JWT's trailing dot.
+The page route is public only in insecure mode; API requests still require a JWT.
+Secure mode does not expose the page. It remains a single compiled HTML asset,
+with no frontend dependencies or separate UI server needed at runtime.
+
+Startup uses an aligned, colored summary for the project, HTTP address, auth,
+sandbox, state directory, image and browser user. Container builds show one
+updating, width-limited line with a spinner and elapsed build time by default,
+even during quiet steps; piped logs retain only the final
+progress line. Warnings and errors remain visible in both cases.
+Use `zen server start --container --verbose` for every build line, grouped by
+stage and colored by severity. This applies to both the sandbox base image and
+the agent image. Colors honor `NO_COLOR` and normal terminal detection.
+The image reports listener readiness without repeating the host's summary or
+insecure warning; container startup and HTTP readiness are distinct messages.
+
+The HTML contains its JavaScript, React components and CSS; it needs no frontend
+server or CDN. It reuses ZeneraLite's chat messages, composer, tool cards and
+AG-UI reducer. It lists sessions, loads history, streams turns, follows active
+runs, cancels runs and deletes sessions. Connected-account actions still need
+zenera-app. Reopen the printed link after a page reload, or paste a dev JWT into
+the connection form: tokens are deliberately not saved in browser storage.
+
+Local files send `Origin: null`. Only insecure servers allow that origin and
+its GET/POST/DELETE preflights with Authorization and JSON headers; actual API
+requests still require a token. Secure servers do not enable this CORS access.
+A browser may ask you to allow local-network access.
+
+```ts
+import { createServer } from '@zenera/server';
+
+const server = createServer({
+    projectId: 'p1',
+    projectDir: '/project',
+    root: '/state',
+    auth: {
+        mode: 'jwt',
+        publicKey: process.env.ZEN_SERVER_JWT_PUBLIC_KEY!,
+        issuer: 'zenera-app',
+        audience: 'zenera-runtime',
+    },
+});
+await server.listen({ port: 3000, host: '0.0.0.0' });
+```
+
+## Who is calling: a JWT per request
+
+Every request but `/healthz` carries `Authorization: Bearer <jwt>`, signed by the
+host (zenera-app) for that one request with its Ed25519 key. The server holds
+only the public key (`--jwt-public-key <file>` or `$ZEN_SERVER_JWT_PUBLIC_KEY`),
+so neither it nor a sandboxed command that reaches its port can make one.
+
+| Claim                   | Checked                                                                     |
+| ----------------------- | --------------------------------------------------------------------------- |
+| alg                     | `EdDSA` only                                                                |
+| `iss`                   | `zenera-app` (`--jwt-issuer`)                                               |
+| `aud`                   | `zenera-runtime` (`--jwt-audience`)                                         |
+| `iat`                   | at most 2 minutes old, 30 s of clock skew                                   |
+| `prj`                   | this server's project id                                                    |
+| `req`                   | `"<METHOD> <url>"` of this very request: a token seen in transit is no good |
+| `sub`                   | the user, required                                                          |
+| `thr`                   | when there, must be the thread in the URL                                   |
+| `role`, `email`, `name` | when there, handed to the run as the user's (`zenera` library)              |
+
+Logging people in and deciding who may use which project stay in front of the
+server (zenera-app); the server only trusts what it signed.
+
+**`--insecure`** is for trying a server on your machine: tokens are read, not
+checked (any signature or none, any age, any project or request), but `sub` is
+still required — `zen server token --user ann` prints one. It listens on
+loopback only, and is refused inside the agent image unless whoever runs the
+container says so (`ZEN_SERVER_INSECURE_LOCAL=1`, which `--container` sets while
+publishing the port on loopback only).
+
+## Root: every user in a folder of their own
+
+```
+<root>/server.json                                  {version, projectId}: this server's
+<root>/users/<user>/memory/                         the user's graph, shared by their chats
+<root>/users/<user>/sessions/<thread>/.data/        the session's state (its conversation)
+<root>/users/<user>/sessions/<thread>/runs/         the engine's record of each run
+<root>/users/<user>/sessions/<thread>/workspace/    what the agent reads and writes
+<root>/users/<user>/sessions/<thread>/agui/         each run's AG-UI events
+```
+
+- `--root` / `$ZEN_SERVER_ROOT`, else `~/.zenera/neo/servers/<project>`; `/state`
+  in the agent image. `server.json` makes it one project's: a root of another
+  project, or of a newer layout, is refused.
+- `<user>` is `sub` as it is when it is a safe path segment (a UUID lower-cased),
+  else `u-<sha256>`. A thread is one path segment (letters, digits, `_`, `-`).
+- **Memory seed**: the first time a user needs a memory, it is copied from the
+  seed — the project's own (`memory:` in agents.yaml), `--memory-seed <dir>`, or
+  none (`--no-memory-seed`, everyone starts empty). From then on it is theirs:
+  their chats share it, other users never see it, and the seed is not read again.
+  The host CLI captures the initial seed at startup, including committed SQLite
+  WAL data and attached files. Later seed changes only affect the next server
+  start; existing user memories are never replaced.
+  With `--container`, this snapshot is mounted at `/seed:ro` in rollback-journal
+  mode, so SQLite can read it without creating WAL/SHM files on the read-only
+  project mount. The temporary snapshot is removed after the server stops
+  (also on failed startup); private user memories remain in the server root.
+  Snapshot file permissions allow image UID 10001 to read it even with rootful
+  podman; the private server root still controls host access.
+  If the container cannot be stopped, the CLI reports that error and retains
+  its snapshot rather than removing memory that the container may still need.
+
+## Routes
+
+| Route                                            | What                                                         |
+| ------------------------------------------------ | ------------------------------------------------------------ |
+| `GET /healthz`                                   | For probes; no token                                         |
+| `GET /api/status`                                | Versions, auth, sandbox (and why not), image identity, root  |
+| `GET /api/activity`                              | Whether a run is going, for idle stop                        |
+| `GET /api/sessions`                              | The caller's sessions, newest activity first                 |
+| `GET /api/sessions/:tid`                         | The chat so far, as AG-UI events                             |
+| `POST /api/sessions/:tid/runs`                   | A turn (or AG-UI `resume` entries), streamed as SSE          |
+| `GET /api/sessions/:tid/runs/:runId/events`      | Follow a run, or replay one that ended                       |
+| `POST /api/sessions/:tid/runs/:runId/cancel`     | Stop it                                                      |
+| `DELETE /api/sessions/:tid`                      | The thread and its files                                     |
+| `/api/sessions/:tid/{runs,…/trace,memory}` debug | With `debug: true` only: recorded runs, traces, memory graph |
+
+Every session route is the caller's own: `:tid` is looked up under their folder.
+The list returns `{ sessions: [{ id, title, createdAt, updatedAt, running }] }`;
+`running` is `{ runId }` or `null`, and titles come from the engine's session
+metadata (falling back to the ID). A thread-scoped token lists only its thread.
+Listing does not create sessions or memory. A new session is still created on
+its first turn.
+
+A run belongs to the server, not the request: it goes on when the caller leaves
+and can be followed again. At most `maxRuns` (`ZEN_RUNTIME_MAX_RUNS`, 4) run at
+once, `maxUserRuns` (`ZEN_RUNTIME_MAX_USER_RUNS`, 2) per user. An
+`x-zenera-mcp-token` header on a run is handed to the run's MCP plugin
+(`ZEN_PLUGINS`, `ZEN_MCP_BROKER_URL`).
+
+## Sandbox
+
+Chosen once, at start:
+
+- **podman** — anywhere but the agent image, as `zen run`: a container per
+  session on this machine. `zen server start` readies podman as `zen run` does,
+  and a turn pulls or builds the image it needs.
+- **bwrap** — inside the agent image, which ships `/opt/zenera/bin/bwrap` and is
+  itself the container: each command under bubblewrap. Commands see the image
+  (what the project's `sandbox/Dockerfile` installed, with its `ENV`), their own
+  workspace and home, and the `zenera` library; never the root (other chats,
+  other users, memories), the seed, the zen home, the project (its `.env`), the
+  server's install, `/state` or `/run/secrets`.
+
+`--sandbox` or `$ZEN_SERVER_SANDBOX` overrides the choice; `createServer` takes
+`sandbox: 'podman' | 'bwrap' | factory` and an optional `preflight`. A sandbox
+plugin in `ZEN_PLUGINS` never replaces it.
+
+The `zenera` library (Python and Node: `identity()`, `require_identity()`) is one
+shared read-only directory mounted at `/opt/zenera/runtime` for every session —
+built into the agent image, or written once per content under the zen home.
+
+`zen server start` refuses to listen when commands have nowhere to run (podman
+not answering, bwrap unable to isolate), when the image was built for another
+project environment (`ZEN_IMAGE_BUILD` / `ZEN_IMAGE_BASE`), or when the root is
+another project's.
+
+## `--container`
+
+`zen server start --container` runs the server in the project's agent image on
+this machine, with podman:
+
+1. The project's sandbox image is readied as for `zen run` (`sandbox/Dockerfile`).
+2. The agent image is built on it: this zen's packages (`npm pack` of the ones
+   installed), Node in `/opt/zenera`, a static bwrap, the `zenera` library, the
+   sandbox image's `ENV` (so commands get it under bwrap). Tagged
+   `localhost/zenera-agent:<hash>`; built again only when something changed, or
+   with `--rebuild`.
+3. `podman run`: the project read-only at `/project`, the root at `/state`, the
+   port published on `--host` (loopback by default), the auth flags and model
+   keys and provider settings passed through by environment name, credential files
+   mounted as private Podman secrets, logs followed;
+   Ctrl-C stops it.
+
+The server runs as numeric UID/GID **10001**, with `HOME=/home/zenera`, not
+as root or as the sandbox base image's `USER`. Commands inherit that UID unless
+the project's sandbox config explicitly selects another user. Rootless podman
+uses `--userns keep-id:uid=10001,gid=10001`: existing host-owned state stays
+writable, without changing its ownership. With rootful podman, the host must
+provide a state directory writable by UID/GID 10001; ownership is not changed
+automatically. Project and seed mounts must also be readable by that user.
+The container drops all capabilities and disables privilege escalation;
+bwrap uses unprivileged user namespaces.
+
+For Kubernetes, set `runAsNonRoot: true`, `runAsUser: 10001`,
+`runAsGroup: 10001`, `fsGroup: 10001` for the state PVC, and
+`allowPrivilegeEscalation: false` with all capabilities dropped. The node's
+security policy must allow bwrap's unprivileged user namespaces; startup
+reports a failed probe rather than running commands without isolation.
+
+Model keys come from the keyring (`zen key …`) and the environment, as for any
+run, including the project's `.env`; in the agent image, the environment.
+Vertex project, location and quota project, and the Bifrost endpoint, are forwarded
+alongside keys. Explicit `GOOGLE_APPLICATION_CREDENTIALS` takes precedence over
+ambient gcloud application-default credentials.
+
+File credentials use ephemeral Podman secrets readable only by UID 10001. The
+server stages them in its private container home before opening engines, allowing
+bwrap to bind container-owned files when the project's keys policy permits it.
+They are not embedded in the image, argv, workspaces or persistent user state.
+Secrets are removed after confirmed shutdown or failed startup; a failed stop
+retains them and the memory seed until the container can be stopped. Failed secret
+cleanup is reported with a manual removal command.
+
+## Rebuilding the standalone page
+
+The source and build live in ZeneraLite's `services/zenera-app`. Run there:
+
+```sh
+npm run build:chat -- --output /path/to/ZeneraNeo/packages/cli/assets/chat.html
+```
+
+Without `--output`, the result is `dist/chat.html`. If a sibling `../ZeneraNeo`
+checkout exists next to ZeneraLite, the build also copies the result into its
+`packages/cli/assets/chat.html` automatically, including when `--output` is used.
+Without that sibling, only the requested output is written. The CLI package includes
+the compiled asset; ZeneraNeo needs no frontend build dependencies.

package/dist/agui.d.ts

@@ -0,0 +1,29 @@
+import { type AGUIEvent, type Interrupt, type TokenUsage as AguiUsage, type RunAgentInput } from '@ag-ui/core';
+import type { AgentEvent, AgentState, Payload, TokenUsage } from '@zenera/neo';
+export declare const MAX_TOOL_OUTPUT = 8000;
+export declare function clip(text: string, max?: number): string;
+export type Resolve = (payload: Payload) => Promise<string>;
+/**
+ * The calls a suspended run waits on, as AG-UI interrupts. The id is zenera-app's interrupt id
+ * when the tool got one (it resumes the run by it), else the call id; `toolCallId` ties it to the
+ * tool card; `metadata` is what the tool said about it (server, icon, ...), for that card.
+ */
+export declare function interruptsOf(state: AgentState): Interrupt[];
+export interface TranslatorOptions {
+    threadId: string;
+    runId: string;
+    resolve: Resolve;
+    newId?: () => string;
+}
+export declare class AguiTranslator {
+    #private;
+    constructor(opts: TranslatorOptions);
+    get done(): boolean;
+    /** The run's input goes with it: a replayed run then shows what it answered. */
+    started(input?: RunAgentInput): AGUIEvent[];
+    translate(ev: AgentEvent): Promise<AGUIEvent[]>;
+    /** The end of a run that stopped without a run_finished: an exception or a cancel. */
+    fail(err: unknown, code?: string): AGUIEvent[];
+}
+export declare function toAguiUsage(u: TokenUsage): AguiUsage;
+//# sourceMappingURL=agui.d.ts.map

package/dist/agui.js

@@ -0,0 +1,333 @@
+// AG-UI for a @zenera/neo run. neo streams bare deltas plus a checkpoint per model call, tool
+// call, hand-off and branch; AG-UI wants every text, reasoning and tool-call stream opened and
+// closed around them. One translator per run keeps that bookkeeping, per branch.
+//   AguiTranslator  - neo AgentEvent -> AG-UI events, in order (await each call before the next)
+//   clip            - the cap on tool output sent to a browser
+//   interruptsOf    - what a suspended run waits for, as AG-UI interrupts (RUN_FINISHED outcome)
+import { EventType, } from '@ag-ui/core';
+import { randomUUID } from 'node:crypto';
+export const MAX_TOOL_OUTPUT = 8000;
+export function clip(text, max = MAX_TOOL_OUTPUT) {
+    return text.length > max
+        ? `${text.slice(0, max)}\n… ${text.length - max} more characters`
+        : text;
+}
+/**
+ * The calls a suspended run waits on, as AG-UI interrupts. The id is zenera-app's interrupt id
+ * when the tool got one (it resumes the run by it), else the call id; `toolCallId` ties it to the
+ * tool card; `metadata` is what the tool said about it (server, icon, ...), for that card.
+ */
+export function interruptsOf(state) {
+    // `suspended` is newer than some @zenera/neo typings this compiles against.
+    const suspended = state.suspended ?? [];
+    return suspended.map((raw) => {
+        const s = raw;
+        const data = s.data && typeof s.data === 'object' ? s.data : undefined;
+        return {
+            id: typeof data?.interruptId === 'string' ? data.interruptId : s.callId,
+            reason: s.reason,
+            ...(s.message ? { message: s.message } : {}),
+            toolCallId: s.callId,
+            ...(s.responseSchema ? { responseSchema: s.responseSchema } : {}),
+            ...(data ? { metadata: data } : {}),
+        };
+    });
+}
+export class AguiTranslator {
+    #threadId;
+    #runId;
+    #resolve;
+    #newId;
+    #lanes = new Map();
+    // fork node id -> the tool call that asked for it
+    #forks = new Map();
+    #agent;
+    #done = false;
+    constructor(opts) {
+        this.#threadId = opts.threadId;
+        this.#runId = opts.runId;
+        this.#resolve = opts.resolve;
+        this.#newId = opts.newId ?? randomUUID;
+    }
+    get done() {
+        return this.#done;
+    }
+    /** The run's input goes with it: a replayed run then shows what it answered. */
+    started(input) {
+        return [
+            {
+                type: EventType.RUN_STARTED,
+                threadId: this.#threadId,
+                runId: this.#runId,
+                ...(input ? { input } : {}),
+            },
+        ];
+    }
+    async translate(ev) {
+        if (this.#done)
+            return [];
+        const out = [];
+        const lane = this.#lane(ev.branch?.runId);
+        const sub = lane.subagentRunId ? { subagentRunId: lane.subagentRunId } : {};
+        // A continued session sends no run_created, so the first trunk event opens the step.
+        if (!ev.branch && !this.#agent) {
+            this.#agent = ev.agent;
+            out.push({ type: EventType.STEP_STARTED, stepName: ev.agent });
+        }
+        switch (ev.type) {
+            case 'thinking_delta': {
+                if (!ev.delta)
+                    break;
+                this.#endText(lane, out);
+                if (!lane.reasoning) {
+                    lane.reasoning = this.#newId();
+                    out.push({ type: EventType.REASONING_START, messageId: lane.reasoning, ...sub }, {
+                        type: EventType.REASONING_MESSAGE_START,
+                        messageId: lane.reasoning,
+                        role: 'reasoning',
+                        ...sub,
+                    });
+                }
+                out.push({
+                    type: EventType.REASONING_MESSAGE_CONTENT,
+                    messageId: lane.reasoning,
+                    delta: ev.delta,
+                    ...sub,
+                });
+                break;
+            }
+            case 'text_delta':
+                if (!ev.delta)
+                    break;
+                this.#endReasoning(lane, out);
+                this.#text(lane, ev.agent, ev.delta, out);
+                lane.streamedText = true;
+                break;
+            case 'tool_call_detected':
+                this.#endReasoning(lane, out);
+                this.#startTool(lane, ev.callId, ev.name, out);
+                break;
+            case 'tool_args_delta':
+                if (!lane.tools.has(ev.callId))
+                    this.#startTool(lane, ev.callId, ev.name, out);
+                if (ev.delta) {
+                    out.push({
+                        type: EventType.TOOL_CALL_ARGS,
+                        toolCallId: ev.callId,
+                        delta: ev.delta,
+                        ...sub,
+                    });
+                }
+                break;
+            case 'before_llm_call':
+                lane.streamedText = false;
+                lane.tools.clear();
+                break;
+            case 'after_llm_call': {
+                this.#endReasoning(lane, out);
+                // A model that does not stream says everything here, at once.
+                if (!lane.streamedText) {
+                    const text = await this.#resolve(ev.node.text);
+                    if (text.trim())
+                        this.#text(lane, ev.agent, text, out);
+                }
+                this.#endText(lane, out, { model: ev.node.model, usage: ev.node.usage });
+                for (const call of ev.node.toolCalls) {
+                    if (!lane.tools.has(call.callId)) {
+                        this.#startTool(lane, call.callId, call.name, out);
+                        const args = await this.#resolve(call.args);
+                        if (args) {
+                            out.push({
+                                type: EventType.TOOL_CALL_ARGS,
+                                toolCallId: call.callId,
+                                delta: args,
+                                ...sub,
+                            });
+                        }
+                    }
+                    out.push({ type: EventType.TOOL_CALL_END, toolCallId: call.callId, ...sub });
+                }
+                lane.tools.clear();
+                break;
+            }
+            case 'after_tool_call': {
+                const content = clip(await this.#resolve(ev.node.result));
+                out.push({
+                    type: EventType.TOOL_CALL_RESULT,
+                    messageId: this.#newId(),
+                    toolCallId: ev.node.callId,
+                    content,
+                    role: 'tool',
+                    ...sub,
+                    ...(ev.node.isError ? { metadata: { isError: true } } : {}),
+                });
+                break;
+            }
+            case 'handoff':
+                this.#endReasoning(lane, out);
+                this.#endText(lane, out);
+                out.push({ type: EventType.STEP_FINISHED, stepName: ev.from, ...sub }, { type: EventType.STEP_STARTED, stepName: ev.to, ...sub });
+                if (!ev.branch)
+                    this.#agent = ev.to;
+                break;
+            case 'before_fork':
+                this.#forks.set(ev.node.id, ev.node.callId);
+                break;
+            case 'branch_started': {
+                const parentToolCallId = this.#forks.get(ev.child.forkId);
+                out.push({
+                    type: EventType.SUBAGENT_STARTED,
+                    subagentRunId: ev.child.runId,
+                    name: ev.child.name,
+                    description: ev.childState.agentName,
+                    ...(lane.subagentRunId ? { parentSubagentRunId: lane.subagentRunId } : {}),
+                    ...(parentToolCallId ? { parentToolCallId } : {}),
+                });
+                break;
+            }
+            case 'branch_finished': {
+                const child = this.#lane(ev.child.runId);
+                this.#endReasoning(child, out);
+                this.#endText(child, out);
+                this.#lanes.delete(ev.child.runId);
+                if (ev.status === 'ok') {
+                    out.push({ type: EventType.SUBAGENT_FINISHED, subagentRunId: ev.child.runId });
+                }
+                else {
+                    out.push({
+                        type: EventType.SUBAGENT_ERROR,
+                        subagentRunId: ev.child.runId,
+                        message: ev.childState.error ?? `branch ${ev.child.name} ${ev.status}`,
+                        code: ev.status,
+                    });
+                }
+                break;
+            }
+            case 'run_finished':
+                // A branch's own end is reported by branch_finished on its parent.
+                if (!ev.branch)
+                    out.push(...this.#finish(ev.result));
+                break;
+            default:
+                break;
+        }
+        return out;
+    }
+    /** The end of a run that stopped without a run_finished: an exception or a cancel. */
+    fail(err, code = 'error') {
+        if (this.#done)
+            return [];
+        const out = this.#closeAll();
+        this.#done = true;
+        if (this.#agent)
+            out.push({ type: EventType.STEP_FINISHED, stepName: this.#agent });
+        const message = err instanceof Error ? err.message : String(err);
+        out.push({ type: EventType.RUN_ERROR, message, code });
+        return out;
+    }
+    #finish(result) {
+        const out = this.#closeAll();
+        this.#done = true;
+        if (this.#agent)
+            out.push({ type: EventType.STEP_FINISHED, stepName: this.#agent });
+        const usage = [toAguiUsage(result.usage)];
+        if (result.stopReason === 'failed') {
+            out.push({
+                type: EventType.RUN_ERROR,
+                message: result.state.error ?? 'the run failed',
+                code: 'failed',
+                usage,
+            });
+            return out;
+        }
+        out.push({
+            type: EventType.RUN_FINISHED,
+            threadId: this.#threadId,
+            runId: this.#runId,
+            outcome: result.stopReason === 'aborted'
+                ? { type: 'cancelled' }
+                : // 'suspended' is newer than some @zenera/neo typings this compiles against.
+                    result.stopReason === 'suspended'
+                        ? { type: 'interrupt', interrupts: interruptsOf(result.state) }
+                        : { type: 'success' },
+            result: { agent: result.agent },
+            usage,
+        });
+        return out;
+    }
+    #closeAll() {
+        const out = [];
+        for (const lane of this.#lanes.values()) {
+            this.#endReasoning(lane, out);
+            this.#endText(lane, out);
+            const sub = lane.subagentRunId ? { subagentRunId: lane.subagentRunId } : {};
+            for (const callId of lane.tools.keys()) {
+                out.push({ type: EventType.TOOL_CALL_END, toolCallId: callId, ...sub });
+            }
+            lane.tools.clear();
+        }
+        return out;
+    }
+    #lane(subagentRunId) {
+        const key = subagentRunId ?? '';
+        let lane = this.#lanes.get(key);
+        if (!lane) {
+            lane = { subagentRunId, streamedText: false, tools: new Map() };
+            this.#lanes.set(key, lane);
+        }
+        return lane;
+    }
+    #text(lane, agent, delta, out) {
+        const sub = lane.subagentRunId ? { subagentRunId: lane.subagentRunId } : {};
+        if (!lane.text) {
+            lane.text = this.#newId();
+            out.push({
+                type: EventType.TEXT_MESSAGE_START,
+                messageId: lane.text,
+                role: 'assistant',
+                name: agent,
+                ...sub,
+            });
+        }
+        out.push({ type: EventType.TEXT_MESSAGE_CONTENT, messageId: lane.text, delta, ...sub });
+    }
+    #endText(lane, out, call) {
+        if (!lane.text)
+            return;
+        const sub = lane.subagentRunId ? { subagentRunId: lane.subagentRunId } : {};
+        out.push({
+            type: EventType.TEXT_MESSAGE_END,
+            messageId: lane.text,
+            ...sub,
+            ...(call ? { metadata: { model: call.model, usage: toAguiUsage(call.usage) } } : {}),
+        });
+        lane.text = undefined;
+    }
+    #endReasoning(lane, out) {
+        if (!lane.reasoning)
+            return;
+        const sub = lane.subagentRunId ? { subagentRunId: lane.subagentRunId } : {};
+        out.push({ type: EventType.REASONING_MESSAGE_END, messageId: lane.reasoning, ...sub }, { type: EventType.REASONING_END, messageId: lane.reasoning, ...sub });
+        lane.reasoning = undefined;
+    }
+    #startTool(lane, callId, name, out) {
+        lane.tools.set(callId, { name });
+        out.push({
+            type: EventType.TOOL_CALL_START,
+            toolCallId: callId,
+            toolCallName: name,
+            ...(lane.text ? { parentMessageId: lane.text } : {}),
+            ...(lane.subagentRunId ? { subagentRunId: lane.subagentRunId } : {}),
+        });
+    }
+}
+export function toAguiUsage(u) {
+    return {
+        inputTokens: u.inputTokens,
+        outputTokens: u.outputTokens,
+        totalTokens: u.inputTokens + u.outputTokens,
+        reasoningTokens: u.reasoningTokens,
+        cachedInputTokens: u.cachedInputTokens,
+    };
+}
+//# sourceMappingURL=agui.js.map

package/dist/auth.d.ts

@@ -0,0 +1,16 @@
+import type { NextFunction, Request, Response } from 'express';
+import { type JWTPayload } from 'jose';
+export interface CallerClaims extends JWTPayload {
+    sub: string;
+    prj?: string;
+    req?: string;
+    thr?: string;
+    role?: string;
+    email?: string;
+    name?: string;
+}
+export declare function verifyCaller(req: Request): Promise<CallerClaims>;
+export declare function requireCaller(): (req: Request, res: Response, next: NextFunction) => Promise<void>;
+/** A token an `insecure` server takes: the claims, no signature. */
+export declare function unsignedToken(claims: Record<string, unknown>): string;
+//# sourceMappingURL=auth.d.ts.map