@honua/app-platform 0.0.20-alpha.0

package/operator/controllers/approval.js

@@ -0,0 +1,123 @@
+/**
+ * `ApprovalController` — loads the policy decision for an in-flight
+ * operation and exposes a single `confirm()` action when the gate is
+ * `pending`. The controller never short-circuits a deferred outcome
+ * to "approved"; it surfaces the server's verbatim decision.
+ *
+ * Audit entries returned with each decision are forwarded to the
+ * `OperatorTelemetry.after` hook as `approval-audit` events so partner
+ * observability stacks see the same evidence the server records. The
+ * server remains the canonical audit-of-record — client telemetry is
+ * observability, not evidence.
+ *
+ * @module
+ */
+import { HonuaOperatorApprovalError } from "../errors.js";
+import { ListenerBag, emitTelemetryEvent, withTelemetrySpan } from "./base.js";
+export class ApprovalController {
+    #client;
+    #telemetry;
+    #bag = new ListenerBag();
+    #seenAudit = new Set();
+    #decision;
+    // Bumped on every load() / confirm() entry so a slow approval call
+    // for operation A cannot resolve after the controller has moved on
+    // to operation B and emit a stale `loaded` / `confirmed` for A. The
+    // captured value is checked at resolution time; mismatch ⇒ drop.
+    #generation = 0;
+    constructor(options) {
+        this.#client = options.client;
+        this.#telemetry = options.telemetry;
+    }
+    get decision() {
+        return this.#decision;
+    }
+    on(listener) {
+        return this.#bag.on(listener);
+    }
+    async load(operationId, signal) {
+        const gen = ++this.#generation;
+        try {
+            const decision = await withTelemetrySpan(this.#telemetry, "approval-load", undefined, () => this.#client.operator.getApproval(operationId, signal), { operationId });
+            if (gen !== this.#generation) {
+                // Superseded by a newer load()/confirm(); drop without
+                // committing or emitting so a stale operationId does not
+                // overwrite the active decision.
+                return decision;
+            }
+            this.#decision = decision;
+            this.#fanOutAudit(decision);
+            this.#bag.emit({ kind: "loaded", decision });
+            return decision;
+        }
+        catch (error) {
+            const wrapped = error instanceof HonuaOperatorApprovalError
+                ? error
+                : new HonuaOperatorApprovalError("approval load failed", {
+                    cause: error,
+                    detail: { operationId },
+                });
+            if (gen === this.#generation) {
+                this.#bag.emit({ kind: "error", error: wrapped });
+            }
+            throw wrapped;
+        }
+    }
+    /**
+     * Confirm a `pending` approval. The controller refuses to invoke the
+     * server when the loaded decision is in any other state — preventing
+     * a UI from re-confirming an already granted/denied/deferred outcome.
+     * Returns the server's outcome unchanged.
+     */
+    async confirm(operationId, signal) {
+        if (!this.#decision || this.#decision.operationId !== operationId) {
+            throw new HonuaOperatorApprovalError("confirm requires a loaded decision for the same operation", {
+                detail: { operationId, decisionOperationId: this.#decision?.operationId },
+            });
+        }
+        if (this.#decision.state !== "pending") {
+            throw new HonuaOperatorApprovalError(`cannot confirm an approval in state "${this.#decision.state}"`, {
+                detail: { operationId, state: this.#decision.state },
+            });
+        }
+        const gen = ++this.#generation;
+        try {
+            const next = await withTelemetrySpan(this.#telemetry, "approval-confirm", undefined, () => this.#client.operator.confirmApproval(operationId, signal), { operationId });
+            if (gen !== this.#generation) {
+                return next;
+            }
+            this.#decision = next;
+            this.#fanOutAudit(next);
+            this.#bag.emit({ kind: "confirmed", decision: next });
+            return next;
+        }
+        catch (error) {
+            const wrapped = error instanceof HonuaOperatorApprovalError
+                ? error
+                : new HonuaOperatorApprovalError("approval confirm failed", {
+                    cause: error,
+                    detail: { operationId },
+                });
+            if (gen === this.#generation) {
+                this.#bag.emit({ kind: "error", error: wrapped });
+            }
+            throw wrapped;
+        }
+    }
+    #fanOutAudit(decision) {
+        for (const entry of decision.audit) {
+            const key = `${decision.operationId}|${entry.at}|${entry.actor}|${entry.action}`;
+            if (this.#seenAudit.has(key))
+                continue;
+            this.#seenAudit.add(key);
+            emitTelemetryEvent(this.#telemetry, "approval-audit", undefined, {
+                operationId: decision.operationId,
+                actor: entry.actor,
+                action: entry.action,
+                reason: entry.reason,
+                at: entry.at,
+            });
+            this.#bag.emit({ kind: "audit", entry, decision });
+        }
+    }
+}

package/operator/controllers/base.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Tiny shared subscribe/notify helper for operator controllers. Mirrors
+ * the listener-set pattern used by `HonuaMapRuntime` and
+ * `ExplorationContext` so a single embedder hook style works everywhere.
+ *
+ * @module
+ */
+import type { OperatorTelemetry, OperatorTelemetryKind } from "../telemetry.js";
+export type Unsubscribe = () => void;
+export declare class ListenerBag<E> {
+    #private;
+    on(listener: (event: E) => void): Unsubscribe;
+    emit(event: E): void;
+    clear(): void;
+    get size(): number;
+}
+/**
+ * Run an async operation with telemetry spans wrapped around it. Mirrors
+ * the before/after/error semantics of `HonuaRuntimeTelemetry`.
+ */
+export declare function withTelemetrySpan<T>(telemetry: OperatorTelemetry | undefined, kind: OperatorTelemetryKind, intentId: string | undefined, fn: () => Promise<T>, detail?: Record<string, unknown>): Promise<T>;
+/**
+ * Telemetry counterpart for synchronous events that have no
+ * before/after wrap (e.g. an audit-record fan-out).
+ */
+export declare function emitTelemetryEvent(telemetry: OperatorTelemetry | undefined, kind: OperatorTelemetryKind, intentId: string | undefined, detail?: Record<string, unknown>): void;
+//# sourceMappingURL=base.d.ts.map

package/operator/controllers/base.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"base.d.ts","sourceRoot":"","sources":["../../../../src/operator/controllers/base.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,KAAK,EAAE,iBAAiB,EAAE,qBAAqB,EAAyB,MAAM,iBAAiB,CAAC;AAEvG,MAAM,MAAM,WAAW,GAAG,MAAM,IAAI,CAAC;AAErC,qBAAa,WAAW,CAAC,CAAC;;IAGjB,EAAE,CAAC,QAAQ,EAAE,CAAC,KAAK,EAAE,CAAC,KAAK,IAAI,GAAG,WAAW;IAO7C,IAAI,CAAC,KAAK,EAAE,CAAC,GAAG,IAAI;IAIpB,KAAK,IAAI,IAAI;IAIpB,IAAW,IAAI,IAAI,MAAM,CAExB;CACF;AAED;;;GAGG;AACH,wBAAsB,iBAAiB,CAAC,CAAC,EACvC,SAAS,EAAE,iBAAiB,GAAG,SAAS,EACxC,IAAI,EAAE,qBAAqB,EAC3B,QAAQ,EAAE,MAAM,GAAG,SAAS,EAC5B,EAAE,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,EACpB,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAC/B,OAAO,CAAC,CAAC,CAAC,CAaZ;AAED;;;GAGG;AACH,wBAAgB,kBAAkB,CAChC,SAAS,EAAE,iBAAiB,GAAG,SAAS,EACxC,IAAI,EAAE,qBAAqB,EAC3B,QAAQ,EAAE,MAAM,GAAG,SAAS,EAC5B,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAC/B,IAAI,CAGN"}

package/operator/controllers/base.js

@@ -0,0 +1,53 @@
+/**
+ * Tiny shared subscribe/notify helper for operator controllers. Mirrors
+ * the listener-set pattern used by `HonuaMapRuntime` and
+ * `ExplorationContext` so a single embedder hook style works everywhere.
+ *
+ * @module
+ */
+export class ListenerBag {
+    #listeners = new Set();
+    on(listener) {
+        this.#listeners.add(listener);
+        return () => {
+            this.#listeners.delete(listener);
+        };
+    }
+    emit(event) {
+        for (const listener of [...this.#listeners])
+            listener(event);
+    }
+    clear() {
+        this.#listeners.clear();
+    }
+    get size() {
+        return this.#listeners.size;
+    }
+}
+/**
+ * Run an async operation with telemetry spans wrapped around it. Mirrors
+ * the before/after/error semantics of `HonuaRuntimeTelemetry`.
+ */
+export async function withTelemetrySpan(telemetry, kind, intentId, fn, detail) {
+    const span = { kind, intentId, startedAt: Date.now(), detail };
+    telemetry?.before?.(span);
+    try {
+        const result = await fn();
+        const finishedAt = Date.now();
+        telemetry?.after?.({ ...span, finishedAt, durationMs: finishedAt - span.startedAt });
+        return result;
+    }
+    catch (error) {
+        const finishedAt = Date.now();
+        telemetry?.error?.({ ...span, finishedAt, durationMs: finishedAt - span.startedAt, error });
+        throw error;
+    }
+}
+/**
+ * Telemetry counterpart for synchronous events that have no
+ * before/after wrap (e.g. an audit-record fan-out).
+ */
+export function emitTelemetryEvent(telemetry, kind, intentId, detail) {
+    const startedAt = Date.now();
+    telemetry?.after?.({ kind, intentId, startedAt, finishedAt: startedAt, durationMs: 0, detail });
+}

package/operator/controllers/builder-workspace.d.ts

@@ -0,0 +1,55 @@
+/**
+ * `BuilderWorkspaceController` — mirrors `MapWorkspaceController` for an
+ * `AppPackage`. The controller does not execute the app; it surfaces a
+ * `PreviewHandle` carrying the bundle URL the embedder mounts inside an
+ * `<iframe sandbox>`.
+ *
+ * @module
+ */
+import type { HonuaMapPackage } from "../../runtime/index.js";
+import type { OperatorClient } from "../client.js";
+import { HonuaOperatorAppError } from "../errors.js";
+import type { OperatorTelemetry } from "../telemetry.js";
+import type { AppPackage, ArtifactRef } from "../workspace/types.js";
+import { type Unsubscribe } from "./base.js";
+export interface PreviewHandle {
+    readonly url: string | undefined;
+    readonly assets: ReadonlyArray<ArtifactRef>;
+    readonly mapPackage: HonuaMapPackage | undefined;
+}
+export type BuilderWorkspaceEvent = {
+    kind: "package-loaded";
+    pkg: AppPackage;
+} | {
+    kind: "package-refined";
+    pkg: AppPackage;
+} | {
+    kind: "map-bound";
+    pkg: HonuaMapPackage;
+} | {
+    kind: "error";
+    error: HonuaOperatorAppError;
+};
+export interface BuilderWorkspaceControllerOptions {
+    client: OperatorClient;
+    telemetry?: OperatorTelemetry;
+    /**
+     * Optional adapter that picks the entry-point URL out of an
+     * `AppPackage`. Defaults to the first asset whose `kind === "app-package"`,
+     * falling back to the first asset with a `url`.
+     */
+    resolveEntryUrl?: (pkg: AppPackage) => string | undefined;
+}
+export declare class BuilderWorkspaceController {
+    #private;
+    constructor(options: BuilderWorkspaceControllerOptions);
+    get appPackage(): AppPackage | undefined;
+    on(listener: (event: BuilderWorkspaceEvent) => void): Unsubscribe;
+    bindIntent(intentId: string): void;
+    loadPackage(pkg: AppPackage): Promise<void>;
+    bindMapPackage(pkg: HonuaMapPackage): void;
+    preview(): PreviewHandle;
+    refine(prompt: string, signal?: AbortSignal): Promise<AppPackage>;
+    dispose(): void;
+}
+//# sourceMappingURL=builder-workspace.d.ts.map

package/operator/controllers/builder-workspace.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"builder-workspace.d.ts","sourceRoot":"","sources":["../../../../src/operator/controllers/builder-workspace.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,wBAAwB,CAAC;AAC9D,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,cAAc,CAAC;AACnD,OAAO,EAAE,qBAAqB,EAAE,MAAM,cAAc,CAAC;AACrD,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,iBAAiB,CAAC;AACzD,OAAO,KAAK,EAAE,UAAU,EAAE,WAAW,EAAE,MAAM,uBAAuB,CAAC;AACrE,OAAO,EAAe,KAAK,WAAW,EAAqB,MAAM,WAAW,CAAC;AAE7E,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,GAAG,EAAE,MAAM,GAAG,SAAS,CAAC;IACjC,QAAQ,CAAC,MAAM,EAAE,aAAa,CAAC,WAAW,CAAC,CAAC;IAC5C,QAAQ,CAAC,UAAU,EAAE,eAAe,GAAG,SAAS,CAAC;CAClD;AAED,MAAM,MAAM,qBAAqB,GAC7B;IAAE,IAAI,EAAE,gBAAgB,CAAC;IAAC,GAAG,EAAE,UAAU,CAAA;CAAE,GAC3C;IAAE,IAAI,EAAE,iBAAiB,CAAC;IAAC,GAAG,EAAE,UAAU,CAAA;CAAE,GAC5C;IAAE,IAAI,EAAE,WAAW,CAAC;IAAC,GAAG,EAAE,eAAe,CAAA;CAAE,GAC3C;IAAE,IAAI,EAAE,OAAO,CAAC;IAAC,KAAK,EAAE,qBAAqB,CAAA;CAAE,CAAC;AAEpD,MAAM,WAAW,iCAAiC;IAChD,MAAM,EAAE,cAAc,CAAC;IACvB,SAAS,CAAC,EAAE,iBAAiB,CAAC;IAC9B;;;;OAIG;IACH,eAAe,CAAC,EAAE,CAAC,GAAG,EAAE,UAAU,KAAK,MAAM,GAAG,SAAS,CAAC;CAC3D;AAQD,qBAAa,0BAA0B;;gBAclB,OAAO,EAAE,iCAAiC;IAM7D,IAAW,UAAU,IAAI,UAAU,GAAG,SAAS,CAE9C;IAEM,EAAE,CAAC,QAAQ,EAAE,CAAC,KAAK,EAAE,qBAAqB,KAAK,IAAI,GAAG,WAAW;IAIjE,UAAU,CAAC,QAAQ,EAAE,MAAM,GAAG,IAAI;IAI5B,WAAW,CAAC,GAAG,EAAE,UAAU,GAAG,OAAO,CAAC,IAAI,CAAC;IAqBjD,cAAc,CAAC,GAAG,EAAE,eAAe,GAAG,IAAI;IAK1C,OAAO,IAAI,aAAa;IAWlB,MAAM,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,UAAU,CAAC;IAiCvE,OAAO,IAAI,IAAI;CAOvB"}

package/operator/controllers/builder-workspace.js

@@ -0,0 +1,108 @@
+/**
+ * `BuilderWorkspaceController` — mirrors `MapWorkspaceController` for an
+ * `AppPackage`. The controller does not execute the app; it surfaces a
+ * `PreviewHandle` carrying the bundle URL the embedder mounts inside an
+ * `<iframe sandbox>`.
+ *
+ * @module
+ */
+import { HonuaOperatorAppError } from "../errors.js";
+import { ListenerBag, withTelemetrySpan } from "./base.js";
+const defaultEntryUrl = (pkg) => {
+    const appAsset = pkg.assets.find((asset) => asset.kind === "app-package" && asset.url);
+    if (appAsset?.url)
+        return appAsset.url;
+    return pkg.assets.find((asset) => asset.url)?.url;
+};
+export class BuilderWorkspaceController {
+    #client;
+    #telemetry;
+    #resolveEntryUrl;
+    #bag = new ListenerBag();
+    #pkg;
+    #boundMap;
+    #activeIntentId;
+    // Same generation pattern as the other controllers: bumped on
+    // every loadPackage()/refine()/dispose(), captured by each
+    // operation, and consulted at resolution time so an older
+    // refineApp() cannot overwrite a newer package.
+    #opGeneration = 0;
+    constructor(options) {
+        this.#client = options.client;
+        this.#telemetry = options.telemetry;
+        this.#resolveEntryUrl = options.resolveEntryUrl ?? defaultEntryUrl;
+    }
+    get appPackage() {
+        return this.#pkg;
+    }
+    on(listener) {
+        return this.#bag.on(listener);
+    }
+    bindIntent(intentId) {
+        this.#activeIntentId = intentId;
+    }
+    async loadPackage(pkg) {
+        const gen = ++this.#opGeneration;
+        // Clear the prior map binding eagerly so the next preview() call
+        // never returns a previous execution's map. The workspace re-binds
+        // the map within the same execution-success handler when the new
+        // result actually carries one; an app-only result therefore
+        // produces a preview with no `mapPackage`.
+        this.#boundMap = undefined;
+        return withTelemetrySpan(this.#telemetry, "app-load", this.#activeIntentId, async () => {
+            if (gen !== this.#opGeneration)
+                return;
+            this.#pkg = pkg;
+            this.#bag.emit({ kind: "package-loaded", pkg });
+        }, { appPackageId: pkg.id });
+    }
+    bindMapPackage(pkg) {
+        this.#boundMap = pkg;
+        this.#bag.emit({ kind: "map-bound", pkg });
+    }
+    preview() {
+        if (!this.#pkg) {
+            throw new HonuaOperatorAppError("preview called before loadPackage");
+        }
+        return {
+            url: this.#resolveEntryUrl(this.#pkg),
+            assets: this.#pkg.assets,
+            mapPackage: this.#boundMap,
+        };
+    }
+    async refine(prompt, signal) {
+        if (!this.#activeIntentId) {
+            throw new HonuaOperatorAppError("refine requires bindIntent before invocation");
+        }
+        const intentId = this.#activeIntentId;
+        const gen = ++this.#opGeneration;
+        return withTelemetrySpan(this.#telemetry, "app-refine", intentId, async () => {
+            try {
+                const next = await this.#client.operator.refineApp(intentId, prompt, signal);
+                if (gen !== this.#opGeneration)
+                    return next;
+                this.#pkg = next;
+                this.#bag.emit({ kind: "package-refined", pkg: next });
+                return next;
+            }
+            catch (error) {
+                const wrapped = new HonuaOperatorAppError("app refine failed", {
+                    intentId,
+                    cause: error,
+                    detail: { prompt },
+                });
+                if (gen === this.#opGeneration) {
+                    this.#bag.emit({ kind: "error", error: wrapped });
+                }
+                throw wrapped;
+            }
+        }, { prompt });
+    }
+    dispose() {
+        this.#opGeneration += 1;
+        this.#pkg = undefined;
+        this.#boundMap = undefined;
+        this.#activeIntentId = undefined;
+        this.#bag.clear();
+    }
+}

package/operator/controllers/chat.d.ts

@@ -0,0 +1,61 @@
+/**
+ * `ChatController` — turn ledger and intent-draft pump for the freeform
+ * request surface. The controller owns no streaming token assembly logic
+ * beyond accumulating `ChatChunk.delta` strings; the transport (an
+ * `AsyncIterable<ChatChunk>` from the `OperatorClient`) is responsible
+ * for chunking.
+ *
+ * @module
+ */
+import type { OperatorClient } from "../client.js";
+import { HonuaOperatorIntentError } from "../errors.js";
+import type { OperatorTelemetry } from "../telemetry.js";
+import type { AnalysisIntent, BuilderIntent, ConversationTurn } from "../workspace/types.js";
+import { type Unsubscribe } from "./base.js";
+export type ChatEvent = {
+    kind: "turn-updated";
+    turn: ConversationTurn;
+} | {
+    kind: "intent-drafted";
+    intent: AnalysisIntent | BuilderIntent;
+} | {
+    kind: "error";
+    error: HonuaOperatorIntentError;
+};
+export type DecorateTurn = (turn: ConversationTurn) => ConversationTurn;
+export interface ChatControllerOptions {
+    client: OperatorClient;
+    telemetry?: OperatorTelemetry;
+    /**
+     * Pure transformation applied to a turn snapshot before the
+     * `turn-updated` event fires. Cannot mutate controller state.
+     */
+    decorate?: DecorateTurn;
+    /** Fixture seam for deterministic ids in tests. */
+    generateTurnId?: () => string;
+    /** Fixture seam for deterministic timestamps in tests. */
+    now?: () => number;
+}
+export declare class ChatController {
+    #private;
+    constructor(options: ChatControllerOptions);
+    get turns(): ReadonlyArray<ConversationTurn>;
+    on(listener: (event: ChatEvent) => void): Unsubscribe;
+    abort(): void;
+    /**
+     * Send a freeform user message and stream the agent reply. Resolves
+     * with the final agent turn (intent draft inlined) when the stream
+     * completes; rejects with `HonuaOperatorIntentError` on transport
+     * failure.
+     *
+     * If a previous send is still in flight, it is aborted before this
+     * one starts. The active controller identity is the per-send token —
+     * stream updates, `intent-drafted`, and `error` emissions are gated
+     * on it so a slow earlier stream cannot drive workspace state back
+     * to a stale intent after a newer send has taken over.
+     */
+    send(text: string): Promise<ConversationTurn>;
+    /** Append a system message (e.g. an embedder-supplied notice). */
+    appendSystem(content: string): ConversationTurn;
+}
+//# sourceMappingURL=chat.d.ts.map

package/operator/controllers/chat.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"chat.d.ts","sourceRoot":"","sources":["../../../../src/operator/controllers/chat.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,KAAK,EAAa,cAAc,EAAE,MAAM,cAAc,CAAC;AAC9D,OAAO,EAAE,wBAAwB,EAAE,MAAM,cAAc,CAAC;AACxD,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,iBAAiB,CAAC;AACzD,OAAO,KAAK,EAAE,cAAc,EAAE,aAAa,EAAE,gBAAgB,EAAY,MAAM,uBAAuB,CAAC;AACvG,OAAO,EAAe,KAAK,WAAW,EAAqB,MAAM,WAAW,CAAC;AAE7E,MAAM,MAAM,SAAS,GACjB;IAAE,IAAI,EAAE,cAAc,CAAC;IAAC,IAAI,EAAE,gBAAgB,CAAA;CAAE,GAChD;IAAE,IAAI,EAAE,gBAAgB,CAAC;IAAC,MAAM,EAAE,cAAc,GAAG,aAAa,CAAA;CAAE,GAClE;IAAE,IAAI,EAAE,OAAO,CAAC;IAAC,KAAK,EAAE,wBAAwB,CAAA;CAAE,CAAC;AAEvD,MAAM,MAAM,YAAY,GAAG,CAAC,IAAI,EAAE,gBAAgB,KAAK,gBAAgB,CAAC;AAExE,MAAM,WAAW,qBAAqB;IACpC,MAAM,EAAE,cAAc,CAAC;IACvB,SAAS,CAAC,EAAE,iBAAiB,CAAC;IAC9B;;;OAGG;IACH,QAAQ,CAAC,EAAE,YAAY,CAAC;IACxB,mDAAmD;IACnD,cAAc,CAAC,EAAE,MAAM,MAAM,CAAC;IAC9B,0DAA0D;IAC1D,GAAG,CAAC,EAAE,MAAM,MAAM,CAAC;CACpB;AASD,qBAAa,cAAc;;gBAUN,OAAO,EAAE,qBAAqB;IAQjD,IAAW,KAAK,IAAI,aAAa,CAAC,gBAAgB,CAAC,CAElD;IAEM,EAAE,CAAC,QAAQ,EAAE,CAAC,KAAK,EAAE,SAAS,KAAK,IAAI,GAAG,WAAW;IAIrD,KAAK,IAAI,IAAI;IAKpB;;;;;;;;;;;OAWG;IACU,IAAI,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,gBAAgB,CAAC;IAuF1D,kEAAkE;IAC3D,YAAY,CAAC,OAAO,EAAE,MAAM,GAAG,gBAAgB;CAqBvD"}

package/operator/controllers/chat.js

@@ -0,0 +1,154 @@
+/**
+ * `ChatController` — turn ledger and intent-draft pump for the freeform
+ * request surface. The controller owns no streaming token assembly logic
+ * beyond accumulating `ChatChunk.delta` strings; the transport (an
+ * `AsyncIterable<ChatChunk>` from the `OperatorClient`) is responsible
+ * for chunking.
+ *
+ * @module
+ */
+import { HonuaOperatorIntentError } from "../errors.js";
+import { ListenerBag, withTelemetrySpan } from "./base.js";
+let chatTurnCounter = 0;
+function defaultTurnId() {
+    chatTurnCounter += 1;
+    return `turn-${Date.now().toString(36)}-${chatTurnCounter.toString(36)}`;
+}
+export class ChatController {
+    #client;
+    #telemetry;
+    #decorate;
+    #generateTurnId;
+    #now;
+    #bag = new ListenerBag();
+    #turns = [];
+    #abortController;
+    constructor(options) {
+        this.#client = options.client;
+        this.#telemetry = options.telemetry;
+        this.#decorate = options.decorate;
+        this.#generateTurnId = options.generateTurnId ?? defaultTurnId;
+        this.#now = options.now ?? (() => Date.now());
+    }
+    get turns() {
+        return this.#turns;
+    }
+    on(listener) {
+        return this.#bag.on(listener);
+    }
+    abort() {
+        this.#abortController?.abort();
+        this.#abortController = undefined;
+    }
+    /**
+     * Send a freeform user message and stream the agent reply. Resolves
+     * with the final agent turn (intent draft inlined) when the stream
+     * completes; rejects with `HonuaOperatorIntentError` on transport
+     * failure.
+     *
+     * If a previous send is still in flight, it is aborted before this
+     * one starts. The active controller identity is the per-send token —
+     * stream updates, `intent-drafted`, and `error` emissions are gated
+     * on it so a slow earlier stream cannot drive workspace state back
+     * to a stale intent after a newer send has taken over.
+     */
+    async send(text) {
+        this.#abortController?.abort();
+        const userTurn = this.#appendTurn({ role: "user", content: text });
+        const agentTurnId = this.#generateTurnId();
+        const startedAt = this.#now();
+        const agentIndex = this.#turns.push({
+            turnId: agentTurnId,
+            role: "agent",
+            content: "",
+            startedAt,
+        }) - 1;
+        this.#emitTurnUpdated(this.#turns[agentIndex]);
+        const controller = new AbortController();
+        this.#abortController = controller;
+        const signal = controller.signal;
+        const isCurrent = () => this.#abortController === controller;
+        try {
+            return await withTelemetrySpan(this.#telemetry, "chat-turn", undefined, async () => {
+                let intentDraft;
+                let accumulated = "";
+                let lastChunk;
+                for await (const chunk of this.#client.operator.chat(text, signal)) {
+                    if (!isCurrent())
+                        return this.#turns[agentIndex];
+                    lastChunk = chunk;
+                    accumulated += chunk.delta;
+                    if (chunk.intentDraft)
+                        intentDraft = chunk.intentDraft;
+                    const updated = {
+                        turnId: agentTurnId,
+                        role: "agent",
+                        content: accumulated,
+                        startedAt,
+                        ...(chunk.done ? { finishedAt: this.#now() } : {}),
+                        ...(intentDraft ? { intentDraft } : {}),
+                    };
+                    this.#turns[agentIndex] = updated;
+                    this.#emitTurnUpdated(updated);
+                    if (chunk.done)
+                        break;
+                }
+                if (!isCurrent())
+                    return this.#turns[agentIndex];
+                if (!lastChunk?.done) {
+                    // Stream ended without an explicit terminal chunk — close
+                    // the turn so consumers always observe a `finishedAt`.
+                    const closed = {
+                        ...this.#turns[agentIndex],
+                        finishedAt: this.#now(),
+                    };
+                    this.#turns[agentIndex] = closed;
+                    this.#emitTurnUpdated(closed);
+                }
+                if (intentDraft) {
+                    this.#bag.emit({ kind: "intent-drafted", intent: intentDraft });
+                }
+                // Touch userTurn so the variable is observed even when no
+                // intermediate observer reads it (silences strict-unused).
+                void userTurn;
+                return this.#turns[agentIndex];
+            }, { turnId: agentTurnId });
+        }
+        catch (error) {
+            const wrapped = error instanceof HonuaOperatorIntentError
+                ? error
+                : new HonuaOperatorIntentError("chat send failed", { cause: error, detail: { turnId: agentTurnId } });
+            // Only emit on the bag if this send still owns the surface; a
+            // superseded send is expected to throw (its consumer awaits the
+            // returned promise) but should not pollute the event stream.
+            if (isCurrent()) {
+                this.#bag.emit({ kind: "error", error: wrapped });
+            }
+            throw wrapped;
+        }
+        finally {
+            if (isCurrent())
+                this.#abortController = undefined;
+        }
+    }
+    /** Append a system message (e.g. an embedder-supplied notice). */
+    appendSystem(content) {
+        return this.#appendTurn({ role: "system", content });
+    }
+    #appendTurn(input) {
+        const turn = {
+            turnId: this.#generateTurnId(),
+            role: input.role,
+            content: input.content,
+            startedAt: this.#now(),
+            finishedAt: this.#now(),
+        };
+        this.#turns.push(turn);
+        this.#emitTurnUpdated(turn);
+        return turn;
+    }
+    #emitTurnUpdated(turn) {
+        const decorated = this.#decorate ? this.#decorate(turn) : turn;
+        this.#bag.emit({ kind: "turn-updated", turn: decorated });
+    }
+}

package/operator/controllers/clarification.d.ts

@@ -0,0 +1,52 @@
+/**
+ * `ClarificationController` — typed form derived from
+ * `intent.clarifications[]`. Submission is a pass-through to
+ * `OperatorClient.operator.clarify` and yields a fresh intent revision.
+ *
+ * @module
+ */
+import type { OperatorClient } from "../client.js";
+import { HonuaOperatorIntentError } from "../errors.js";
+import type { OperatorTelemetry } from "../telemetry.js";
+import type { AnalysisIntent, BuilderIntent, ClarificationField } from "../workspace/types.js";
+import { type Unsubscribe } from "./base.js";
+export interface ClarificationState {
+    readonly intent: AnalysisIntent | BuilderIntent | undefined;
+    readonly fields: ReadonlyArray<ClarificationField>;
+    readonly answers: ReadonlyMap<string, string>;
+    readonly submitting: boolean;
+}
+export type ClarificationEvent = {
+    kind: "loaded";
+    intent: AnalysisIntent | BuilderIntent;
+} | {
+    kind: "answer-changed";
+    fieldId: string;
+    value: string;
+} | {
+    kind: "submitted";
+    intent: AnalysisIntent | BuilderIntent;
+} | {
+    kind: "error";
+    error: HonuaOperatorIntentError;
+};
+export interface ClarificationControllerOptions {
+    client: OperatorClient;
+    telemetry?: OperatorTelemetry;
+}
+export declare class ClarificationController {
+    #private;
+    constructor(options: ClarificationControllerOptions);
+    get state(): ClarificationState;
+    on(listener: (event: ClarificationEvent) => void): Unsubscribe;
+    load(intent: AnalysisIntent | BuilderIntent): void;
+    setAnswer(fieldId: string, value: string): void;
+    /**
+     * Submit the current answers and resolve with the revised intent.
+     * Missing required answers reject with `HonuaOperatorIntentError`
+     * before any network call so the controller never depends on the
+     * server for required-field validation.
+     */
+    submit(signal?: AbortSignal): Promise<AnalysisIntent | BuilderIntent>;
+}
+//# sourceMappingURL=clarification.d.ts.map

package/operator/controllers/clarification.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"clarification.d.ts","sourceRoot":"","sources":["../../../../src/operator/controllers/clarification.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,cAAc,CAAC;AACnD,OAAO,EAAE,wBAAwB,EAAE,MAAM,cAAc,CAAC;AACxD,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,iBAAiB,CAAC;AACzD,OAAO,KAAK,EAAE,cAAc,EAAE,aAAa,EAAuB,kBAAkB,EAAE,MAAM,uBAAuB,CAAC;AACpH,OAAO,EAAe,KAAK,WAAW,EAAqB,MAAM,WAAW,CAAC;AAE7E,MAAM,WAAW,kBAAkB;IACjC,QAAQ,CAAC,MAAM,EAAE,cAAc,GAAG,aAAa,GAAG,SAAS,CAAC;IAC5D,QAAQ,CAAC,MAAM,EAAE,aAAa,CAAC,kBAAkB,CAAC,CAAC;IACnD,QAAQ,CAAC,OAAO,EAAE,WAAW,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC9C,QAAQ,CAAC,UAAU,EAAE,OAAO,CAAC;CAC9B;AAED,MAAM,MAAM,kBAAkB,GAC1B;IAAE,IAAI,EAAE,QAAQ,CAAC;IAAC,MAAM,EAAE,cAAc,GAAG,aAAa,CAAA;CAAE,GAC1D;IAAE,IAAI,EAAE,gBAAgB,CAAC;IAAC,OAAO,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,GAC1D;IAAE,IAAI,EAAE,WAAW,CAAC;IAAC,MAAM,EAAE,cAAc,GAAG,aAAa,CAAA;CAAE,GAC7D;IAAE,IAAI,EAAE,OAAO,CAAC;IAAC,KAAK,EAAE,wBAAwB,CAAA;CAAE,CAAC;AAEvD,MAAM,WAAW,8BAA8B;IAC7C,MAAM,EAAE,cAAc,CAAC;IACvB,SAAS,CAAC,EAAE,iBAAiB,CAAC;CAC/B;AAED,qBAAa,uBAAuB;;gBAaf,OAAO,EAAE,8BAA8B;IAK1D,IAAW,KAAK,IAAI,kBAAkB,CAOrC;IAEM,EAAE,CAAC,QAAQ,EAAE,CAAC,KAAK,EAAE,kBAAkB,KAAK,IAAI,GAAG,WAAW;IAI9D,IAAI,CAAC,MAAM,EAAE,cAAc,GAAG,aAAa,GAAG,IAAI;IAYlD,SAAS,CAAC,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,IAAI;IAetD;;;;;OAKG;IACU,MAAM,CAAC,MAAM,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,cAAc,GAAG,aAAa,CAAC;CAwDnF"}