@orthacms/copilot-server 0.0.0-reserve.0

package/dist/lib/chat/application/tool-permission.broker.d.ts

@@ -0,0 +1,118 @@
+import type { ToolPermissionDecision } from '@orthacms/copilot-domain';
+/**
+ * How long a parked run waits for an answer before giving up — **for the whole
+ * run**, not per call.
+ *
+ * The SSE stream heartbeats every 15s, so the connection itself will survive
+ * far longer than this; the limit is about the user, not the socket. Five
+ * minutes is "they went to look at the entry and came back".
+ *
+ * Per **run** rather than per **call** because a turn may ask about several
+ * calls, and the ceilings in `RunLimits` cannot bound any of it: the wall clock
+ * is checked at the top of a step and a park happens inside one. Charging each
+ * call its own five minutes made a single turn requesting thirty writes hold
+ * the connection, the generator and the model context for two and a half
+ * hours — while "they went to look and came back" is one absence, not thirty.
+ */
+export declare const DEFAULT_RUN_DECISION_BUDGET_MS: number;
+/** A decision, plus how it was reached — the timeout is not a user's `deny`. */
+export interface PermissionOutcome {
+    decision: ToolPermissionDecision;
+    /** True when nobody answered in time. */
+    timedOut: boolean;
+}
+/**
+ * Who a parked run belongs to. Only they may answer it.
+ *
+ * Both halves are load-bearing and neither is redundant. `WorkspaceGuard` on
+ * the answering route proves the caller belongs to *the workspace they named*,
+ * which says nothing about the run: a member of workspace B naming B passes it
+ * while answering a run parked in A. And `copilot:use` is held by every role,
+ * so a colleague in the same workspace passes every guard on the route.
+ */
+export interface RunOwner {
+    userId: string;
+    workspaceId: string;
+}
+/**
+ * Parks a run while its user decides whether one tool call may proceed.
+ *
+ * **In-memory, and that is a real deployment constraint, not an oversight.**
+ * The promise a run awaits lives in this process, so the `POST …/permission`
+ * that resolves it has to reach the same instance. A single-node self-hosted
+ * CMS — which is what this is — is fine. A horizontally scaled one needs sticky
+ * routing by `runId`, or this registry moved behind a shared channel. Say so in
+ * the deployment notes rather than discovering it as an occasional hang.
+ *
+ * Four things it has to get right. The first three are ways a run could
+ * otherwise be stranded forever; the fourth is who is allowed to end the wait.
+ *
+ * - **A timeout.** Documented above, and spent against a per-run budget. It
+ *   resolves as a refusal rather than throwing, so the model is told and the
+ *   answer still lands.
+ * - **Abort.** The user closing the window is the common case, and the engine's
+ *   `signal` fires; the waiter has to reject then, or the generator never
+ *   unwinds and the run leaks.
+ * - **Cleanup.** Every exit path clears the entry. A registry that only deletes
+ *   on the happy path grows one dangling promise per abandoned run.
+ * - **Ownership.** A `runId` is not a secret — it is handed to the client in
+ *   the `run-started` frame — and it is the *only* thing the answering route
+ *   used to key on. See {@link RunOwner}.
+ */
+export declare class ToolPermissionBroker {
+    private readonly logger;
+    /**
+     * The waiting budget, in ms. Set once from the plugin config at
+     * composition; {@link DEFAULT_RUN_DECISION_BUDGET_MS} when the operator
+     * said nothing.
+     */
+    private budgetMs;
+    /**
+     * Applies the operator's configured budget. Called by the plugin module at
+     * startup — a setter rather than constructor injection because the broker
+     * is also constructed directly in tests, where the default is what is
+     * wanted.
+     */
+    configure(budgetMs: number | undefined): void;
+    /**
+     * What is left of `runId`'s waiting budget, in ms — what the run engine puts
+     * on the permission frame as a deadline, so the prompt can show a countdown
+     * and warn before it expires instead of simply vanishing (`ORT-118`).
+     */
+    budgetRemaining(runId: string): number;
+    /** Waiters by `runId:callId`. */
+    private readonly waiting;
+    /** Milliseconds each run has already spent parked, and when it last did. */
+    private readonly spent;
+    /**
+     * Waits for the user's answer to one call.
+     *
+     * Resolves rather than rejects on a timeout, because a refusal is an
+     * ordinary tool error the model can report — the same treatment every other
+     * refused call gets. Only an abort rejects, and only because that means
+     * nobody is listening any more.
+     */
+    ask(runId: string, callId: string, owner: RunOwner, signal: AbortSignal): Promise<PermissionOutcome>;
+    /**
+     * Delivers a decision. Returns false when nothing was waiting, or when the
+     * caller does not own the parked run.
+     *
+     * **Both answer false, hence the same 404**, deliberately: whether a run
+     * exists is not something a caller who does not own it may learn, and the
+     * route's message ("no longer waiting for an answer") is true either way
+     * from where they stand.
+     */
+    decide(runId: string, callId: string, decision: ToolPermissionDecision, by: RunOwner): boolean;
+    /**
+     * Grants a parked call more time, at the user's request. Returns the new
+     * allowance in ms, or `null` when nothing is waiting or the caller does not
+     * own the run — the same conflation, for the same reason, as
+     * {@link decide}.
+     */
+    extend(runId: string, callId: string, by: RunOwner): number | null;
+    /** What is left of `runId`'s waiting budget, pruning stale entries first. */
+    private remainingBudget;
+    /** Charges `ms` of waiting to `runId`. */
+    private charge;
+}
+//# sourceMappingURL=tool-permission.broker.d.ts.map

package/dist/lib/chat/application/tool-permission.broker.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tool-permission.broker.d.ts","sourceRoot":"","sources":["../../../../src/lib/chat/application/tool-permission.broker.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,0BAA0B,CAAC;AAEvE;;;;;;;;;;;;;;GAcG;AACH,eAAO,MAAM,8BAA8B,QAAa,CAAC;AAsBzD,gFAAgF;AAChF,MAAM,WAAW,iBAAiB;IAC9B,QAAQ,EAAE,sBAAsB,CAAC;IACjC,yCAAyC;IACzC,QAAQ,EAAE,OAAO,CAAC;CACrB;AAED;;;;;;;;GAQG;AACH,MAAM,WAAW,QAAQ;IACrB,MAAM,EAAE,MAAM,CAAC;IACf,WAAW,EAAE,MAAM,CAAC;CACvB;AAUD;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,qBACa,oBAAoB;IAC7B,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAyC;IAEhE;;;;OAIG;IACH,OAAO,CAAC,QAAQ,CAAkC;IAElD;;;;;OAKG;IACH,SAAS,CAAC,QAAQ,EAAE,MAAM,GAAG,SAAS,GAAG,IAAI;IAI7C;;;;OAIG;IACH,eAAe,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM;IAItC,iCAAiC;IACjC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAA6B;IAErD,4EAA4E;IAC5E,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAiD;IAEvE;;;;;;;OAOG;IACG,GAAG,CACL,KAAK,EAAE,MAAM,EACb,MAAM,EAAE,MAAM,EACd,KAAK,EAAE,QAAQ,EACf,MAAM,EAAE,WAAW,GACpB,OAAO,CAAC,iBAAiB,CAAC;IA6D7B;;;;;;;;OAQG;IACH,MAAM,CACF,KAAK,EAAE,MAAM,EACb,MAAM,EAAE,MAAM,EACd,QAAQ,EAAE,sBAAsB,EAChC,EAAE,EAAE,QAAQ,GACb,OAAO;IAoBV;;;;;OAKG;IACH,MAAM,CAAC,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,EAAE,EAAE,QAAQ,GAAG,MAAM,GAAG,IAAI;IAgBlE,6EAA6E;IAC7E,OAAO,CAAC,eAAe;IAUvB,0CAA0C;IAC1C,OAAO,CAAC,MAAM;CAOjB"}

package/dist/lib/chat/application/tool-permission.broker.js

@@ -0,0 +1,221 @@
+"use strict";
+var ToolPermissionBroker_1;
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ToolPermissionBroker = exports.DEFAULT_RUN_DECISION_BUDGET_MS = void 0;
+const tslib_1 = require("tslib");
+const common_1 = require("@nestjs/common");
+/**
+ * How long a parked run waits for an answer before giving up — **for the whole
+ * run**, not per call.
+ *
+ * The SSE stream heartbeats every 15s, so the connection itself will survive
+ * far longer than this; the limit is about the user, not the socket. Five
+ * minutes is "they went to look at the entry and came back".
+ *
+ * Per **run** rather than per **call** because a turn may ask about several
+ * calls, and the ceilings in `RunLimits` cannot bound any of it: the wall clock
+ * is checked at the top of a step and a park happens inside one. Charging each
+ * call its own five minutes made a single turn requesting thirty writes hold
+ * the connection, the generator and the model context for two and a half
+ * hours — while "they went to look and came back" is one absence, not thirty.
+ */
+exports.DEFAULT_RUN_DECISION_BUDGET_MS = 5 * 60_000;
+/**
+ * How much time one {@link ToolPermissionBroker.extend} grants.
+ *
+ * A full fresh budget rather than a token top-up: the user pressing "I need
+ * more time" is saying the first allowance was not enough, and WCAG 2.2.1 asks
+ * that a limit be extendable "at least ten times" over — which repeated
+ * extensions of the full amount satisfy without inventing a second number.
+ */
+const EXTENSION_MS = exports.DEFAULT_RUN_DECISION_BUDGET_MS;
+/**
+ * How long a run's spent budget is remembered after its last park.
+ *
+ * There is no "run ended" signal to clean up on — the generator simply stops
+ * asking — so entries are pruned opportunistically, on the next `ask`. Anything
+ * older than the budget can no longer constrain a live run, because a run that
+ * parked that long ago has already exhausted it.
+ */
+const BUDGET_TTL_MS = exports.DEFAULT_RUN_DECISION_BUDGET_MS;
+/**
+ * Parks a run while its user decides whether one tool call may proceed.
+ *
+ * **In-memory, and that is a real deployment constraint, not an oversight.**
+ * The promise a run awaits lives in this process, so the `POST …/permission`
+ * that resolves it has to reach the same instance. A single-node self-hosted
+ * CMS — which is what this is — is fine. A horizontally scaled one needs sticky
+ * routing by `runId`, or this registry moved behind a shared channel. Say so in
+ * the deployment notes rather than discovering it as an occasional hang.
+ *
+ * Four things it has to get right. The first three are ways a run could
+ * otherwise be stranded forever; the fourth is who is allowed to end the wait.
+ *
+ * - **A timeout.** Documented above, and spent against a per-run budget. It
+ *   resolves as a refusal rather than throwing, so the model is told and the
+ *   answer still lands.
+ * - **Abort.** The user closing the window is the common case, and the engine's
+ *   `signal` fires; the waiter has to reject then, or the generator never
+ *   unwinds and the run leaks.
+ * - **Cleanup.** Every exit path clears the entry. A registry that only deletes
+ *   on the happy path grows one dangling promise per abandoned run.
+ * - **Ownership.** A `runId` is not a secret — it is handed to the client in
+ *   the `run-started` frame — and it is the *only* thing the answering route
+ *   used to key on. See {@link RunOwner}.
+ */
+let ToolPermissionBroker = ToolPermissionBroker_1 = class ToolPermissionBroker {
+    logger = new common_1.Logger(ToolPermissionBroker_1.name);
+    /**
+     * The waiting budget, in ms. Set once from the plugin config at
+     * composition; {@link DEFAULT_RUN_DECISION_BUDGET_MS} when the operator
+     * said nothing.
+     */
+    budgetMs = exports.DEFAULT_RUN_DECISION_BUDGET_MS;
+    /**
+     * Applies the operator's configured budget. Called by the plugin module at
+     * startup — a setter rather than constructor injection because the broker
+     * is also constructed directly in tests, where the default is what is
+     * wanted.
+     */
+    configure(budgetMs) {
+        if (budgetMs !== undefined && budgetMs > 0)
+            this.budgetMs = budgetMs;
+    }
+    /**
+     * What is left of `runId`'s waiting budget, in ms — what the run engine puts
+     * on the permission frame as a deadline, so the prompt can show a countdown
+     * and warn before it expires instead of simply vanishing (`ORT-118`).
+     */
+    budgetRemaining(runId) {
+        return this.remainingBudget(runId);
+    }
+    /** Waiters by `runId:callId`. */
+    waiting = new Map();
+    /** Milliseconds each run has already spent parked, and when it last did. */
+    spent = new Map();
+    /**
+     * Waits for the user's answer to one call.
+     *
+     * Resolves rather than rejects on a timeout, because a refusal is an
+     * ordinary tool error the model can report — the same treatment every other
+     * refused call gets. Only an abort rejects, and only because that means
+     * nobody is listening any more.
+     */
+    async ask(runId, callId, owner, signal) {
+        const key = `${runId}:${callId}`;
+        const remaining = this.remainingBudget(runId);
+        if (remaining <= 0) {
+            // The run has already spent its whole waiting budget on earlier
+            // calls in this turn. Refusing straight away is the same outcome a
+            // timeout produces, without holding the connection for it.
+            this.logger.warn(`Run ${runId}: the waiting budget is exhausted; call ${callId} was refused without asking.`);
+            return { decision: 'deny', timedOut: true };
+        }
+        const askedAt = Date.now();
+        return new Promise((resolve, reject) => {
+            const settle = (outcome) => {
+                cleanup();
+                resolve(outcome);
+            };
+            let timer;
+            const expire = (after) => {
+                timer = setTimeout(() => {
+                    this.logger.warn(`Run ${runId}: nobody answered the permission request ` +
+                        `for call ${callId} within ${after}ms; refusing.`);
+                    settle({ decision: 'deny', timedOut: true });
+                }, after);
+            };
+            expire(remaining);
+            // Re-arms the timer and tells the caller how long they now have.
+            // The budget already spent is *not* refunded: this grants a fresh
+            // allowance rather than rewinding the clock, so a run cannot be
+            // held open indefinitely by a client that never stops asking
+            // without a user pressing the button each time.
+            const extend = () => {
+                clearTimeout(timer);
+                expire(EXTENSION_MS);
+                return EXTENSION_MS;
+            };
+            const onAbort = () => {
+                cleanup();
+                reject(signal.reason ?? new Error('aborted'));
+            };
+            const cleanup = () => {
+                clearTimeout(timer);
+                signal.removeEventListener('abort', onAbort);
+                this.waiting.delete(key);
+                this.charge(runId, Date.now() - askedAt);
+            };
+            if (signal.aborted) {
+                onAbort();
+                return;
+            }
+            signal.addEventListener('abort', onAbort, { once: true });
+            this.waiting.set(key, { owner, settle, extend });
+        });
+    }
+    /**
+     * Delivers a decision. Returns false when nothing was waiting, or when the
+     * caller does not own the parked run.
+     *
+     * **Both answer false, hence the same 404**, deliberately: whether a run
+     * exists is not something a caller who does not own it may learn, and the
+     * route's message ("no longer waiting for an answer") is true either way
+     * from where they stand.
+     */
+    decide(runId, callId, decision, by) {
+        const key = `${runId}:${callId}`;
+        const waiter = this.waiting.get(key);
+        if (!waiter) {
+            return false;
+        }
+        if (waiter.owner.userId !== by.userId ||
+            waiter.owner.workspaceId !== by.workspaceId) {
+            this.logger.warn(`Run ${runId}: user ${by.userId} tried to answer a permission ` +
+                'request for a run they do not own; refused.');
+            return false;
+        }
+        waiter.settle({ decision, timedOut: false });
+        return true;
+    }
+    /**
+     * Grants a parked call more time, at the user's request. Returns the new
+     * allowance in ms, or `null` when nothing is waiting or the caller does not
+     * own the run — the same conflation, for the same reason, as
+     * {@link decide}.
+     */
+    extend(runId, callId, by) {
+        const waiter = this.waiting.get(`${runId}:${callId}`);
+        if (!waiter)
+            return null;
+        if (waiter.owner.userId !== by.userId ||
+            waiter.owner.workspaceId !== by.workspaceId) {
+            this.logger.warn(`Run ${runId}: user ${by.userId} tried to extend a permission ` +
+                'request for a run they do not own; refused.');
+            return null;
+        }
+        return waiter.extend();
+    }
+    /** What is left of `runId`'s waiting budget, pruning stale entries first. */
+    remainingBudget(runId) {
+        const now = Date.now();
+        for (const [id, entry] of this.spent) {
+            if (now - entry.at > BUDGET_TTL_MS) {
+                this.spent.delete(id);
+            }
+        }
+        return this.budgetMs - (this.spent.get(runId)?.ms ?? 0);
+    }
+    /** Charges `ms` of waiting to `runId`. */
+    charge(runId, ms) {
+        const entry = this.spent.get(runId);
+        this.spent.set(runId, {
+            ms: (entry?.ms ?? 0) + Math.max(0, ms),
+            at: Date.now()
+        });
+    }
+};
+exports.ToolPermissionBroker = ToolPermissionBroker;
+exports.ToolPermissionBroker = ToolPermissionBroker = ToolPermissionBroker_1 = tslib_1.__decorate([
+    (0, common_1.Injectable)()
+], ToolPermissionBroker);

package/dist/lib/chat/http/controllers/create-run.controller.d.ts

@@ -0,0 +1,30 @@
+import type { Response } from 'express';
+import { type PublicUser } from '@orthacms/identity-server';
+import { CreateRunDto } from '../../application/dto/create-run.dto';
+import { RunEngine } from '../../application/run-engine.service';
+import { ContentTypeSummaryService } from '../../application/content-type-summary.service';
+/**
+ * `POST /api/copilot/runs` — starts a turn and streams it back as Server-Sent
+ * Events (`docs/design/copilot.md` §5).
+ *
+ * **Every guard is explicit, and that is the point.** Only `AuthGuard` is
+ * global (`APP_GUARD`); `OriginGuard`, `PermissionsGuard` and `WorkspaceGuard`
+ * are per-controller decorators, so a copilot route that forgot
+ * `WorkspaceGuard` would authenticate fine, pass its permission check, and then
+ * run every tool with an **unvalidated** workspace id taken straight from a
+ * client header — silently unscoping the whole tool catalogue. The three below
+ * are, in order: reject cross-site POSTs, require `copilot:use`, and prove the
+ * caller is a member of the workspace they named.
+ *
+ * SSE on a POST rather than a GET + `EventSource`, because the turn has a body
+ * (the message and its context) and `EventSource` cannot send one. Verified to
+ * stream unbuffered through the admin's Vite dev proxy.
+ */
+export declare class CreateRunController {
+    private readonly engine;
+    private readonly types;
+    private readonly logger;
+    constructor(engine: RunEngine, types: ContentTypeSummaryService);
+    create(body: CreateRunDto, user: PublicUser, workspaceId: string, res: Response): Promise<void>;
+}
+//# sourceMappingURL=create-run.controller.d.ts.map

package/dist/lib/chat/http/controllers/create-run.controller.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"create-run.controller.d.ts","sourceRoot":"","sources":["../../../../../src/lib/chat/http/controllers/create-run.controller.ts"],"names":[],"mappings":"AAWA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,SAAS,CAAC;AACxC,OAAO,EAMH,KAAK,UAAU,EAClB,MAAM,2BAA2B,CAAC;AAEnC,OAAO,EAAE,YAAY,EAAE,MAAM,sCAAsC,CAAC;AACpE,OAAO,EAGH,SAAS,EAEZ,MAAM,sCAAsC,CAAC;AAE9C,OAAO,EAAE,yBAAyB,EAAE,MAAM,gDAAgD,CAAC;AAI3F;;;;;;;;;;;;;;;;GAgBG;AACH,qBAGa,mBAAmB;IAIxB,OAAO,CAAC,QAAQ,CAAC,MAAM;IACvB,OAAO,CAAC,QAAQ,CAAC,KAAK;IAJ1B,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAwC;gBAG1C,MAAM,EAAE,SAAS,EACjB,KAAK,EAAE,yBAAyB;IAkB/C,MAAM,CACA,IAAI,EAAE,YAAY,EACX,IAAI,EAAE,UAAU,EACX,WAAW,EAAE,MAAM,EAChC,GAAG,EAAE,QAAQ,GACrB,OAAO,CAAC,IAAI,CAAC;CA6FnB"}

package/dist/lib/chat/http/controllers/create-run.controller.js

@@ -0,0 +1,159 @@
+"use strict";
+var CreateRunController_1;
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CreateRunController = void 0;
+const tslib_1 = require("tslib");
+const common_1 = require("@nestjs/common");
+const swagger_1 = require("@nestjs/swagger");
+const identity_server_1 = require("@orthacms/identity-server");
+const workspaces_server_1 = require("@orthacms/workspaces-server");
+const create_run_dto_1 = require("../../application/dto/create-run.dto");
+const run_engine_service_1 = require("../../application/run-engine.service");
+const copilot_domain_1 = require("@orthacms/copilot-domain");
+const content_type_summary_service_1 = require("../../application/content-type-summary.service");
+const skill_catalog_service_1 = require("../../../skills/application/skill-catalog.service");
+const sse_stream_1 = require("../sse-stream");
+/**
+ * `POST /api/copilot/runs` — starts a turn and streams it back as Server-Sent
+ * Events (`docs/design/copilot.md` §5).
+ *
+ * **Every guard is explicit, and that is the point.** Only `AuthGuard` is
+ * global (`APP_GUARD`); `OriginGuard`, `PermissionsGuard` and `WorkspaceGuard`
+ * are per-controller decorators, so a copilot route that forgot
+ * `WorkspaceGuard` would authenticate fine, pass its permission check, and then
+ * run every tool with an **unvalidated** workspace id taken straight from a
+ * client header — silently unscoping the whole tool catalogue. The three below
+ * are, in order: reject cross-site POSTs, require `copilot:use`, and prove the
+ * caller is a member of the workspace they named.
+ *
+ * SSE on a POST rather than a GET + `EventSource`, because the turn has a body
+ * (the message and its context) and `EventSource` cannot send one. Verified to
+ * stream unbuffered through the admin's Vite dev proxy.
+ */
+let CreateRunController = CreateRunController_1 = class CreateRunController {
+    engine;
+    types;
+    logger = new common_1.Logger(CreateRunController_1.name);
+    constructor(engine, types) {
+        this.engine = engine;
+        this.types = types;
+    }
+    async create(body, user, workspaceId, res) {
+        const stream = new sse_stream_1.SseStream(res);
+        const abort = new AbortController();
+        // Wired before the first await: a client that gives up during setup
+        // must still cancel the run.
+        stream.onClientDisconnect(abort);
+        const typeSummaries = await this.types.summaries(workspaceId);
+        stream.open();
+        try {
+            const events = this.engine.run({
+                userId: user.id,
+                userEmail: user.email,
+                roleId: user.roleId,
+                workspaceId,
+                conversationId: body.conversationId,
+                message: body.message,
+                ...(body.attachments?.length
+                    ? {
+                        attachments: body.attachments.map((attachment) => attachment.assetId)
+                    }
+                    : {}),
+                ...(body.skills?.length
+                    ? { skills: body.skills.map((skill) => skill.name) }
+                    : {}),
+                context: body.context ?? {},
+                uiLocale: body.uiLocale ?? 'en',
+                ...(body.provider || body.model
+                    ? {
+                        choice: {
+                            ...(body.provider
+                                ? { provider: body.provider }
+                                : {}),
+                            ...(body.model ? { model: body.model } : {})
+                        }
+                    }
+                    : {}),
+                typeSummaries,
+                signal: abort.signal
+            });
+            for await (const event of events) {
+                stream.send(event);
+            }
+        }
+        catch (error) {
+            // The headers went out with `stream.open()`, so an error here can
+            // no longer become a status code — rethrowing would hand Nest's
+            // exception filter a response it cannot write to. It has to arrive
+            // as a frame instead, and be logged here rather than by the filter.
+            if (error instanceof run_engine_service_1.CopilotDisabledError) {
+                stream.send({
+                    type: 'error',
+                    message: 'Ortha AI is turned off for this deployment. An administrator can enable it.'
+                });
+            }
+            else if (error instanceof run_engine_service_1.AttachmentError ||
+                error instanceof skill_catalog_service_1.SkillResolutionError ||
+                error instanceof run_engine_service_1.UnknownModelChoiceError ||
+                error instanceof copilot_domain_1.UnknownModelError) {
+                // A bad attachment, an unavailable skill or a bad
+                // provider/model is the caller's
+                // mistake, and its own
+                // message already names what was asked for and what exists —
+                // far more useful than a generic failure, and safe to show
+                // because the catalogue is public to anyone with `copilot:use`.
+                stream.send({ type: 'error', message: error.message });
+            }
+            else {
+                this.logger.error('Copilot run failed after the stream was opened', error instanceof Error ? error.stack : String(error));
+                stream.send({
+                    type: 'error',
+                    message: 'Ortha AI could not complete this run.'
+                });
+            }
+            // Always terminate with `done`, whatever went wrong: the client's
+            // reducer keys "the turn is over" off this one frame, and a stream
+            // that just stops would leave the UI spinning forever.
+            stream.send({
+                type: 'done',
+                stopReason: 'error',
+                usage: { inputTokens: 0, outputTokens: 0 }
+            });
+        }
+        finally {
+            stream.close();
+        }
+    }
+};
+exports.CreateRunController = CreateRunController;
+tslib_1.__decorate([
+    (0, common_1.Post)('runs')
+    // The response is written by hand, so Nest must not also send one.
+    ,
+    (0, common_1.HttpCode)(common_1.HttpStatus.OK),
+    (0, swagger_1.ApiOperation)({
+        summary: 'Start a copilot run',
+        description: 'Streams the run back as Server-Sent Events: `run-started`, then any ' +
+            'number of `text-delta` / `tool-call` / `tool-result` frames, then exactly ' +
+            'one `done`. An `error` frame may precede `done`.'
+    }),
+    (0, swagger_1.ApiBody)({ type: create_run_dto_1.CreateRunDto }),
+    (0, swagger_1.ApiResponse)({
+        status: 200,
+        description: 'An event stream (`text/event-stream`).'
+    }),
+    tslib_1.__param(0, (0, common_1.Body)()),
+    tslib_1.__param(1, (0, identity_server_1.CurrentUser)()),
+    tslib_1.__param(2, (0, workspaces_server_1.CurrentWorkspace)()),
+    tslib_1.__param(3, (0, common_1.Res)()),
+    tslib_1.__metadata("design:type", Function),
+    tslib_1.__metadata("design:paramtypes", [create_run_dto_1.CreateRunDto, Object, String, Object]),
+    tslib_1.__metadata("design:returntype", Promise)
+], CreateRunController.prototype, "create", null);
+exports.CreateRunController = CreateRunController = CreateRunController_1 = tslib_1.__decorate([
+    (0, common_1.UseGuards)(identity_server_1.OriginGuard, identity_server_1.PermissionsGuard, workspaces_server_1.WorkspaceGuard),
+    (0, identity_server_1.RequirePermissions)(identity_server_1.PERMISSIONS.COPILOT_USE),
+    (0, common_1.Controller)('copilot'),
+    tslib_1.__metadata("design:paramtypes", [run_engine_service_1.RunEngine,
+        content_type_summary_service_1.ContentTypeSummaryService])
+], CreateRunController);

package/dist/lib/chat/http/controllers/get-conversation.controller.d.ts

@@ -0,0 +1,22 @@
+import { type PublicUser } from '@orthacms/identity-server';
+import { ConversationRepository, type ConversationView, type MessageView } from '../../infrastructure/persistence/conversation.repository';
+/** A thread plus its transcript. */
+export interface ConversationDetail {
+    conversation: ConversationView;
+    messages: MessageView[];
+}
+/**
+ * `GET /api/copilot/conversations/:id` — one thread and its transcript, so a
+ * reopened panel or a reloaded tab renders what was persisted rather than only
+ * what streamed.
+ *
+ * A thread the caller doesn't own is a **404, not a 403** — the repository
+ * filters on user and workspace and reports "not found" either way, so an id
+ * cannot be probed for existence.
+ */
+export declare class GetConversationController {
+    private readonly conversations;
+    constructor(conversations: ConversationRepository);
+    get(id: string, user: PublicUser, workspaceId: string): Promise<ConversationDetail>;
+}
+//# sourceMappingURL=get-conversation.controller.d.ts.map

package/dist/lib/chat/http/controllers/get-conversation.controller.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"get-conversation.controller.d.ts","sourceRoot":"","sources":["../../../../../src/lib/chat/http/controllers/get-conversation.controller.ts"],"names":[],"mappings":"AAQA,OAAO,EAKH,KAAK,UAAU,EAClB,MAAM,2BAA2B,CAAC;AAEnC,OAAO,EACH,sBAAsB,EACtB,KAAK,gBAAgB,EACrB,KAAK,WAAW,EACnB,MAAM,0DAA0D,CAAC;AAElE,oCAAoC;AACpC,MAAM,WAAW,kBAAkB;IAC/B,YAAY,EAAE,gBAAgB,CAAC;IAC/B,QAAQ,EAAE,WAAW,EAAE,CAAC;CAC3B;AAED;;;;;;;;GAQG;AACH,qBAGa,yBAAyB;IACtB,OAAO,CAAC,QAAQ,CAAC,aAAa;gBAAb,aAAa,EAAE,sBAAsB;IAM5D,GAAG,CACuB,EAAE,EAAE,MAAM,EACvB,IAAI,EAAE,UAAU,EACX,WAAW,EAAE,MAAM,GACxC,OAAO,CAAC,kBAAkB,CAAC;CAWjC"}

package/dist/lib/chat/http/controllers/get-conversation.controller.js

@@ -0,0 +1,50 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.GetConversationController = void 0;
+const tslib_1 = require("tslib");
+const common_1 = require("@nestjs/common");
+const swagger_1 = require("@nestjs/swagger");
+const identity_server_1 = require("@orthacms/identity-server");
+const workspaces_server_1 = require("@orthacms/workspaces-server");
+const conversation_repository_1 = require("../../infrastructure/persistence/conversation.repository");
+/**
+ * `GET /api/copilot/conversations/:id` — one thread and its transcript, so a
+ * reopened panel or a reloaded tab renders what was persisted rather than only
+ * what streamed.
+ *
+ * A thread the caller doesn't own is a **404, not a 403** — the repository
+ * filters on user and workspace and reports "not found" either way, so an id
+ * cannot be probed for existence.
+ */
+let GetConversationController = class GetConversationController {
+    conversations;
+    constructor(conversations) {
+        this.conversations = conversations;
+    }
+    async get(id, user, workspaceId) {
+        const conversation = await this.conversations.findOrFail(id, user.id, workspaceId);
+        return {
+            conversation,
+            messages: await this.conversations.messages(conversation.id)
+        };
+    }
+};
+exports.GetConversationController = GetConversationController;
+tslib_1.__decorate([
+    (0, common_1.Get)('conversations/:id'),
+    (0, swagger_1.ApiOperation)({
+        summary: 'Get one copilot conversation and its transcript'
+    }),
+    tslib_1.__param(0, (0, common_1.Param)('id', common_1.ParseUUIDPipe)),
+    tslib_1.__param(1, (0, identity_server_1.CurrentUser)()),
+    tslib_1.__param(2, (0, workspaces_server_1.CurrentWorkspace)()),
+    tslib_1.__metadata("design:type", Function),
+    tslib_1.__metadata("design:paramtypes", [String, Object, String]),
+    tslib_1.__metadata("design:returntype", Promise)
+], GetConversationController.prototype, "get", null);
+exports.GetConversationController = GetConversationController = tslib_1.__decorate([
+    (0, common_1.UseGuards)(identity_server_1.PermissionsGuard, workspaces_server_1.WorkspaceGuard),
+    (0, identity_server_1.RequirePermissions)(identity_server_1.PERMISSIONS.COPILOT_USE),
+    (0, common_1.Controller)('copilot'),
+    tslib_1.__metadata("design:paramtypes", [conversation_repository_1.ConversationRepository])
+], GetConversationController);

package/dist/lib/chat/http/controllers/list-conversations.controller.d.ts

@@ -0,0 +1,20 @@
+import { type PublicUser } from '@orthacms/identity-server';
+import { ConversationRepository, type ConversationView } from '../../infrastructure/persistence/conversation.repository';
+import { ListConversationsQueryDto } from '../../application/dto/list-conversations-query.dto';
+/**
+ * `GET /api/copilot/conversations` — the signed-in user's threads in the open
+ * workspace, most recently used first.
+ *
+ * No `OriginGuard`: it guards state-changing requests, and this reads. The
+ * scoping that matters is in the repository, which filters on user **and**
+ * workspace — the guard proves the caller belongs to the workspace, and the
+ * query proves the threads belong to the caller.
+ */
+export declare class ListConversationsController {
+    private readonly conversations;
+    constructor(conversations: ConversationRepository);
+    list(query: ListConversationsQueryDto, user: PublicUser, workspaceId: string): Promise<{
+        items: ConversationView[];
+    }>;
+}
+//# sourceMappingURL=list-conversations.controller.d.ts.map

package/dist/lib/chat/http/controllers/list-conversations.controller.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"list-conversations.controller.d.ts","sourceRoot":"","sources":["../../../../../src/lib/chat/http/controllers/list-conversations.controller.ts"],"names":[],"mappings":"AAEA,OAAO,EAKH,KAAK,UAAU,EAClB,MAAM,2BAA2B,CAAC;AAEnC,OAAO,EACH,sBAAsB,EACtB,KAAK,gBAAgB,EACxB,MAAM,0DAA0D,CAAC;AAClE,OAAO,EAAE,yBAAyB,EAAE,MAAM,oDAAoD,CAAC;AAE/F;;;;;;;;GAQG;AACH,qBAGa,2BAA2B;IACxB,OAAO,CAAC,QAAQ,CAAC,aAAa;gBAAb,aAAa,EAAE,sBAAsB;IAI5D,IAAI,CACG,KAAK,EAAE,yBAAyB,EAC1B,IAAI,EAAE,UAAU,EACX,WAAW,EAAE,MAAM,GACxC,OAAO,CAAC;QAAE,KAAK,EAAE,gBAAgB,EAAE,CAAA;KAAE,CAAC;CAS5C"}