@oddkin/ai 0.0.0-stage → 1.0.0-beta.0

package/dist/controllers/index.d.ts

@@ -0,0 +1,22 @@
+/**
+ * `@oddkin/ai/controllers` — headless, DOM-free interaction behavior: conversation, composer,
+ * revision-bound documents, voice, announcement policy, lifecycle tables, and intent bindings.
+ */
+export { ConversationController } from './conversation.js';
+export type { ActionResult, ConversationControllerOptions, ControllerDiagnostic, SendInput, } from './conversation.js';
+export { ComposerController, matchesAccept } from './composer.js';
+export type { AttachmentState, AttachmentStatus, ComposerIssue, ComposerIssueCode, ComposerOptions, ComposerState, Submission, } from './composer.js';
+export { DocumentSession, captureSelection, fromCodePointOffset, isBoundary, isValidRange, toCodePointOffset, } from './document.js';
+export type { ApplyResult, DocumentState, EditProposal, ProposalStatus, TextRange, TextSelection, } from './document.js';
+export { diffLines, diffTokens, diffWords, lineTokens, wordTokens } from './diff.js';
+export type { DiffSegment } from './diff.js';
+export { VoiceController, createScriptedVoiceAdapter } from './voice.js';
+export type { ScriptedVoiceAdapter, VoiceAdapter, VoiceErrorCode, VoiceHandlers, VoiceScriptStep, VoiceSession, VoiceState, VoiceStatus, } from './voice.js';
+export { DEFAULT_ANNOUNCEMENTS, describeConversationChange, format } from './announcer.js';
+export type { AnnouncementLevel, AnnouncementStrings } from './announcer.js';
+export { APPROVAL_TRANSITIONS, ATTEMPT_TRANSITIONS, CONNECTION_TRANSITIONS, TOOL_TRANSITIONS, applyStopOutcome, canTransition, isActive, isTerminal, stopAfterTerminal, } from './transitions.js';
+export { bindIntents, controllerIntents } from './intents.js';
+export type { ControllerIntentOptions, IntentHandlers } from './intents.js';
+export { createConversationView, selectSource } from './external-store.js';
+export type { ConversationViewInput } from './external-store.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/controllers/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/controllers/index.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,OAAO,EAAE,sBAAsB,EAAE,MAAM,mBAAmB,CAAC;AAC3D,YAAY,EACV,YAAY,EACZ,6BAA6B,EAC7B,oBAAoB,EACpB,SAAS,GACV,MAAM,mBAAmB,CAAC;AAC3B,OAAO,EAAE,kBAAkB,EAAE,aAAa,EAAE,MAAM,eAAe,CAAC;AAClE,YAAY,EACV,eAAe,EACf,gBAAgB,EAChB,aAAa,EACb,iBAAiB,EACjB,eAAe,EACf,aAAa,EACb,UAAU,GACX,MAAM,eAAe,CAAC;AACvB,OAAO,EACL,eAAe,EACf,gBAAgB,EAChB,mBAAmB,EACnB,UAAU,EACV,YAAY,EACZ,iBAAiB,GAClB,MAAM,eAAe,CAAC;AACvB,YAAY,EACV,WAAW,EACX,aAAa,EACb,YAAY,EACZ,cAAc,EACd,SAAS,EACT,aAAa,GACd,MAAM,eAAe,CAAC;AACvB,OAAO,EAAE,SAAS,EAAE,UAAU,EAAE,SAAS,EAAE,UAAU,EAAE,UAAU,EAAE,MAAM,WAAW,CAAC;AACrF,YAAY,EAAE,WAAW,EAAE,MAAM,WAAW,CAAC;AAC7C,OAAO,EAAE,eAAe,EAAE,0BAA0B,EAAE,MAAM,YAAY,CAAC;AACzE,YAAY,EACV,oBAAoB,EACpB,YAAY,EACZ,cAAc,EACd,aAAa,EACb,eAAe,EACf,YAAY,EACZ,UAAU,EACV,WAAW,GACZ,MAAM,YAAY,CAAC;AACpB,OAAO,EAAE,qBAAqB,EAAE,0BAA0B,EAAE,MAAM,EAAE,MAAM,gBAAgB,CAAC;AAC3F,YAAY,EAAE,iBAAiB,EAAE,mBAAmB,EAAE,MAAM,gBAAgB,CAAC;AAC7E,OAAO,EACL,oBAAoB,EACpB,mBAAmB,EACnB,sBAAsB,EACtB,gBAAgB,EAChB,gBAAgB,EAChB,aAAa,EACb,QAAQ,EACR,UAAU,EACV,iBAAiB,GAClB,MAAM,kBAAkB,CAAC;AAC1B,OAAO,EAAE,WAAW,EAAE,iBAAiB,EAAE,MAAM,cAAc,CAAC;AAC9D,YAAY,EAAE,uBAAuB,EAAE,cAAc,EAAE,MAAM,cAAc,CAAC;AAC5E,OAAO,EAAE,sBAAsB,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAC;AAC3E,YAAY,EAAE,qBAAqB,EAAE,MAAM,qBAAqB,CAAC"}

package/dist/controllers/index.js

@@ -0,0 +1,14 @@
+/**
+ * `@oddkin/ai/controllers` — headless, DOM-free interaction behavior: conversation, composer,
+ * revision-bound documents, voice, announcement policy, lifecycle tables, and intent bindings.
+ */
+export { ConversationController } from './conversation.js';
+export { ComposerController, matchesAccept } from './composer.js';
+export { DocumentSession, captureSelection, fromCodePointOffset, isBoundary, isValidRange, toCodePointOffset, } from './document.js';
+export { diffLines, diffTokens, diffWords, lineTokens, wordTokens } from './diff.js';
+export { VoiceController, createScriptedVoiceAdapter } from './voice.js';
+export { DEFAULT_ANNOUNCEMENTS, describeConversationChange, format } from './announcer.js';
+export { APPROVAL_TRANSITIONS, ATTEMPT_TRANSITIONS, CONNECTION_TRANSITIONS, TOOL_TRANSITIONS, applyStopOutcome, canTransition, isActive, isTerminal, stopAfterTerminal, } from './transitions.js';
+export { bindIntents, controllerIntents } from './intents.js';
+export { createConversationView, selectSource } from './external-store.js';
+//# sourceMappingURL=index.js.map

package/dist/controllers/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/controllers/index.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,OAAO,EAAE,sBAAsB,EAAE,MAAM,mBAAmB,CAAC;AAO3D,OAAO,EAAE,kBAAkB,EAAE,aAAa,EAAE,MAAM,eAAe,CAAC;AAUlE,OAAO,EACL,eAAe,EACf,gBAAgB,EAChB,mBAAmB,EACnB,UAAU,EACV,YAAY,EACZ,iBAAiB,GAClB,MAAM,eAAe,CAAC;AASvB,OAAO,EAAE,SAAS,EAAE,UAAU,EAAE,SAAS,EAAE,UAAU,EAAE,UAAU,EAAE,MAAM,WAAW,CAAC;AAErF,OAAO,EAAE,eAAe,EAAE,0BAA0B,EAAE,MAAM,YAAY,CAAC;AAWzE,OAAO,EAAE,qBAAqB,EAAE,0BAA0B,EAAE,MAAM,EAAE,MAAM,gBAAgB,CAAC;AAE3F,OAAO,EACL,oBAAoB,EACpB,mBAAmB,EACnB,sBAAsB,EACtB,gBAAgB,EAChB,gBAAgB,EAChB,aAAa,EACb,QAAQ,EACR,UAAU,EACV,iBAAiB,GAClB,MAAM,kBAAkB,CAAC;AAC1B,OAAO,EAAE,WAAW,EAAE,iBAAiB,EAAE,MAAM,cAAc,CAAC;AAE9D,OAAO,EAAE,sBAAsB,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAC"}

package/dist/controllers/intents.d.ts

@@ -0,0 +1,61 @@
+/**
+ * Adapters between element intent events and whoever owns the state: an Oddkin controller or the
+ * application's own store. Elements only request; these bindings decide what a request does.
+ * DOM-free at import; `bindIntents` needs an `EventTarget` when called.
+ */
+import type { ActionResult, ConversationController } from './conversation.js';
+import type { ComposerController } from './composer.js';
+import type { ApprovalDecideDetail, FeedbackSubmitDetail, PromptSubmitDetail } from '../events.js';
+export interface IntentHandlers {
+    'odd-prompt-submit'(detail: PromptSubmitDetail, event: Event): void;
+    'odd-prompt-stop'(detail: {
+        attemptId: string | undefined;
+    }, event: Event): void;
+    'odd-history-request'(detail: {
+        conversationId: string;
+        beforeMessageId: string | undefined;
+    }, event: Event): void;
+    'odd-message-edit'(detail: {
+        messageId: string;
+        text: string;
+    }, event: Event): void;
+    'odd-message-regenerate'(detail: {
+        messageId: string;
+        attemptId: string;
+    }, event: Event): void;
+    'odd-attempt-retry'(detail: {
+        attemptId: string;
+    }, event: Event): void;
+    'odd-attempt-resume'(detail: {
+        attemptId: string;
+    }, event: Event): void;
+    'odd-branch-switch'(detail: {
+        messageId: string;
+        targetMessageId: string;
+    }, event: Event): void;
+    'odd-approval-decide'(detail: ApprovalDecideDetail, event: Event): void;
+    'odd-feedback-submit'(detail: FeedbackSubmitDetail, event: Event): void;
+    'odd-suggestion-submit'(detail: {
+        suggestionId: string;
+        prompt: string;
+    }, event: Event): void;
+    'odd-suggestion-select'(detail: {
+        suggestionId: string;
+        prompt: string;
+    }, event: Event): void;
+    'odd-tool-retry'(detail: {
+        toolCallId: string;
+    }, event: Event): void;
+}
+/** Listen for intent events on `target` (usually a surface's root element). Returns a release. */
+export declare function bindIntents(target: EventTarget, handlers: Partial<IntentHandlers>): () => void;
+export interface ControllerIntentOptions {
+    /** Called with every controller result, e.g. to surface `unavailable` or `stale` outcomes. */
+    readonly onResult?: (intent: keyof IntentHandlers, result: ActionResult) => void;
+}
+/**
+ * Handlers that route intents to a `ConversationController` (and the composer that produced the
+ * submission, so it is acknowledged or failed by id).
+ */
+export declare function controllerIntents(controller: ConversationController, composer?: ComposerController, options?: ControllerIntentOptions): Partial<IntentHandlers>;
+//# sourceMappingURL=intents.d.ts.map

package/dist/controllers/intents.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"intents.d.ts","sourceRoot":"","sources":["../../src/controllers/intents.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,OAAO,KAAK,EAAE,YAAY,EAAE,sBAAsB,EAAE,MAAM,mBAAmB,CAAC;AAC9E,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,eAAe,CAAC;AACxD,OAAO,KAAK,EAAE,oBAAoB,EAAE,oBAAoB,EAAE,kBAAkB,EAAE,MAAM,cAAc,CAAC;AAEnG,MAAM,WAAW,cAAc;IAC7B,mBAAmB,CAAC,MAAM,EAAE,kBAAkB,EAAE,KAAK,EAAE,KAAK,GAAG,IAAI,CAAC;IACpE,iBAAiB,CAAC,MAAM,EAAE;QAAE,SAAS,EAAE,MAAM,GAAG,SAAS,CAAA;KAAE,EAAE,KAAK,EAAE,KAAK,GAAG,IAAI,CAAC;IACjF,qBAAqB,CACnB,MAAM,EAAE;QAAE,cAAc,EAAE,MAAM,CAAC;QAAC,eAAe,EAAE,MAAM,GAAG,SAAS,CAAA;KAAE,EACvE,KAAK,EAAE,KAAK,GACX,IAAI,CAAC;IACR,kBAAkB,CAAC,MAAM,EAAE;QAAE,SAAS,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAE,EAAE,KAAK,EAAE,KAAK,GAAG,IAAI,CAAC;IACpF,wBAAwB,CAAC,MAAM,EAAE;QAAE,SAAS,EAAE,MAAM,CAAC;QAAC,SAAS,EAAE,MAAM,CAAA;KAAE,EAAE,KAAK,EAAE,KAAK,GAAG,IAAI,CAAC;IAC/F,mBAAmB,CAAC,MAAM,EAAE;QAAE,SAAS,EAAE,MAAM,CAAA;KAAE,EAAE,KAAK,EAAE,KAAK,GAAG,IAAI,CAAC;IACvE,oBAAoB,CAAC,MAAM,EAAE;QAAE,SAAS,EAAE,MAAM,CAAA;KAAE,EAAE,KAAK,EAAE,KAAK,GAAG,IAAI,CAAC;IACxE,mBAAmB,CAAC,MAAM,EAAE;QAAE,SAAS,EAAE,MAAM,CAAC;QAAC,eAAe,EAAE,MAAM,CAAA;KAAE,EAAE,KAAK,EAAE,KAAK,GAAG,IAAI,CAAC;IAChG,qBAAqB,CAAC,MAAM,EAAE,oBAAoB,EAAE,KAAK,EAAE,KAAK,GAAG,IAAI,CAAC;IACxE,qBAAqB,CAAC,MAAM,EAAE,oBAAoB,EAAE,KAAK,EAAE,KAAK,GAAG,IAAI,CAAC;IACxE,uBAAuB,CAAC,MAAM,EAAE;QAAE,YAAY,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE,EAAE,KAAK,EAAE,KAAK,GAAG,IAAI,CAAC;IAC9F,uBAAuB,CAAC,MAAM,EAAE;QAAE,YAAY,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE,EAAE,KAAK,EAAE,KAAK,GAAG,IAAI,CAAC;IAC9F,gBAAgB,CAAC,MAAM,EAAE;QAAE,UAAU,EAAE,MAAM,CAAA;KAAE,EAAE,KAAK,EAAE,KAAK,GAAG,IAAI,CAAC;CACtE;AAED,kGAAkG;AAClG,wBAAgB,WAAW,CAAC,MAAM,EAAE,WAAW,EAAE,QAAQ,EAAE,OAAO,CAAC,cAAc,CAAC,GAAG,MAAM,IAAI,CAY9F;AAED,MAAM,WAAW,uBAAuB;IACtC,8FAA8F;IAC9F,QAAQ,CAAC,QAAQ,CAAC,EAAE,CAAC,MAAM,EAAE,MAAM,cAAc,EAAE,MAAM,EAAE,YAAY,KAAK,IAAI,CAAC;CAClF;AAED;;;GAGG;AACH,wBAAgB,iBAAiB,CAC/B,UAAU,EAAE,sBAAsB,EAClC,QAAQ,CAAC,EAAE,kBAAkB,EAC7B,OAAO,GAAE,uBAA4B,GACpC,OAAO,CAAC,cAAc,CAAC,CA2DzB"}

package/dist/controllers/intents.js

@@ -0,0 +1,68 @@
+/** Listen for intent events on `target` (usually a surface's root element). Returns a release. */
+export function bindIntents(target, handlers) {
+    const releases = [];
+    for (const [type, handler] of Object.entries(handlers)) {
+        if (typeof handler !== 'function')
+            continue;
+        const listener = (event) => handler(event.detail, event);
+        target.addEventListener(type, listener);
+        releases.push(() => target.removeEventListener(type, listener));
+    }
+    return () => {
+        for (const release of releases.splice(0))
+            release();
+    };
+}
+/**
+ * Handlers that route intents to a `ConversationController` (and the composer that produced the
+ * submission, so it is acknowledged or failed by id).
+ */
+export function controllerIntents(controller, composer, options = {}) {
+    const report = (intent) => (result) => options.onResult?.(intent, result);
+    return {
+        'odd-prompt-submit': (detail) => {
+            const files = detail.attachments.map((a) => ({
+                type: 'file',
+                id: a.id,
+                name: a.name,
+                mediaType: a.mediaType,
+                size: a.size,
+                ...(a.url ? { url: a.url } : {}),
+            }));
+            void controller.send({ text: detail.text, files }).then((result) => {
+                if (composer) {
+                    if (result.ok)
+                        composer.acknowledge(detail.submissionId);
+                    else
+                        composer.fail(detail.submissionId, result.error ?? {
+                            code: `ai.send.${result.reason}`,
+                            message: 'The message could not be sent.',
+                            retryable: true,
+                        });
+                }
+                report('odd-prompt-submit')(result);
+            });
+        },
+        'odd-prompt-stop': (detail) => void controller.stop(detail.attemptId).then(report('odd-prompt-stop')),
+        'odd-history-request': () => void controller.loadHistory().then(report('odd-history-request')),
+        'odd-message-edit': (detail) => void controller.edit(detail.messageId, detail.text).then(report('odd-message-edit')),
+        'odd-message-regenerate': (detail) => void controller.regenerate(detail.messageId).then(report('odd-message-regenerate')),
+        'odd-attempt-retry': (detail) => void controller.retry(detail.attemptId).then(report('odd-attempt-retry')),
+        'odd-attempt-resume': (detail) => void controller.resume(detail.attemptId).then(report('odd-attempt-resume')),
+        'odd-branch-switch': (detail) => report('odd-branch-switch')(controller.switchBranch(detail.targetMessageId)),
+        'odd-approval-decide': (detail) => void controller
+            .decide(detail.approvalId, detail.revision, detail.decision, detail.reason)
+            .then(report('odd-approval-decide')),
+        'odd-feedback-submit': (detail) => void controller
+            .submitFeedback({
+            messageId: detail.messageId,
+            rating: detail.rating,
+            reasons: [...detail.reasons],
+            ...(detail.comment ? { comment: detail.comment } : {}),
+        })
+            .then(report('odd-feedback-submit')),
+        'odd-suggestion-submit': (detail) => void controller.send({ text: detail.prompt }).then(report('odd-suggestion-submit')),
+        'odd-suggestion-select': (detail) => composer?.setText(detail.prompt),
+    };
+}
+//# sourceMappingURL=intents.js.map

package/dist/controllers/intents.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"intents.js","sourceRoot":"","sources":["../../src/controllers/intents.ts"],"names":[],"mappings":"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"}

package/dist/controllers/transitions.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Lifecycle transition tables. Transport, attempt, tool, approval, and stop state are separate
+ * machines; one never implies another (finishing tool arguments is not execution, approval is
+ * not success, a closed connection is not completion). Pure and DOM-free; the controller and
+ * docs/architecture/ai-interaction.md §5 use the same tables.
+ */
+import type { ApprovalStatus, AttemptStatus, ConnectionState, StopOutcome, StopState, ToolStatus } from '../contracts/types.js';
+type Table<S extends string> = Readonly<Record<S, readonly S[]>>;
+export declare const ATTEMPT_TRANSITIONS: Table<AttemptStatus>;
+export declare const TOOL_TRANSITIONS: Table<ToolStatus>;
+export declare const APPROVAL_TRANSITIONS: Table<ApprovalStatus>;
+export declare const CONNECTION_TRANSITIONS: Table<ConnectionState>;
+export declare function canTransition<S extends string>(table: Table<S>, from: S, to: S): boolean;
+/** The underlying work has ended (as reported by the backend, not inferred from a closed stream). */
+export declare const isTerminal: (status: AttemptStatus) => boolean;
+/** Work may still be running remotely. `interrupted` means the client lost track of it. */
+export declare const isActive: (status: AttemptStatus) => boolean;
+export declare const TOOL_SETTLED: ReadonlySet<ToolStatus>;
+/**
+ * Apply a stop response to an attempt. `rejected` means the stop request itself failed.
+ * A stop that arrives after completion never rewrites the completed status.
+ *
+ * | Outcome            | Attempt not terminal      | Attempt already terminal          |
+ * | ------------------ | ------------------------- | --------------------------------- |
+ * | `cancelled`        | status → cancelled; stop → confirmed | status kept; stop → confirmed if cancelled, else too-late |
+ * | `already-finished` | status kept (await the terminal event); stop → too-late | status kept; stop → too-late |
+ * | `not-found`/`unknown` | status kept; stop → unknown | status kept; stop → unknown |
+ * | rejected           | status kept; stop → failed | status kept; stop → failed |
+ */
+export declare function applyStopOutcome(status: AttemptStatus, outcome: StopOutcome | 'rejected'): {
+    status: AttemptStatus;
+    stop: StopState;
+};
+/** Stop state after a terminal event arrives while a stop may be pending. */
+export declare function stopAfterTerminal(stop: StopState, terminal: AttemptStatus): StopState;
+export {};
+//# sourceMappingURL=transitions.d.ts.map

package/dist/controllers/transitions.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"transitions.d.ts","sourceRoot":"","sources":["../../src/controllers/transitions.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,OAAO,KAAK,EACV,cAAc,EACd,aAAa,EACb,eAAe,EACf,WAAW,EACX,SAAS,EACT,UAAU,EACX,MAAM,uBAAuB,CAAC;AAE/B,KAAK,KAAK,CAAC,CAAC,SAAS,MAAM,IAAI,QAAQ,CAAC,MAAM,CAAC,CAAC,EAAE,SAAS,CAAC,EAAE,CAAC,CAAC,CAAC;AAEjE,eAAO,MAAM,mBAAmB,EAAE,KAAK,CAAC,aAAa,CAkBpD,CAAC;AAEF,eAAO,MAAM,gBAAgB,EAAE,KAAK,CAAC,UAAU,CAiB9C,CAAC;AAEF,eAAO,MAAM,oBAAoB,EAAE,KAAK,CAAC,cAAc,CAStD,CAAC;AAEF,eAAO,MAAM,sBAAsB,EAAE,KAAK,CAAC,eAAe,CAOzD,CAAC;AAEF,wBAAgB,aAAa,CAAC,CAAC,SAAS,MAAM,EAAE,KAAK,EAAE,KAAK,CAAC,CAAC,CAAC,EAAE,IAAI,EAAE,CAAC,EAAE,EAAE,EAAE,CAAC,GAAG,OAAO,CAExF;AAGD,qGAAqG;AACrG,eAAO,MAAM,UAAU,WAAY,aAAa,KAAG,OAA+B,CAAC;AACnF,2FAA2F;AAC3F,eAAO,MAAM,QAAQ,WAAY,aAAa,KAAG,OAIpB,CAAC;AAE9B,eAAO,MAAM,YAAY,EAAE,WAAW,CAAC,UAAU,CAK/C,CAAC;AAEH;;;;;;;;;;GAUG;AACH,wBAAgB,gBAAgB,CAC9B,MAAM,EAAE,aAAa,EACrB,OAAO,EAAE,WAAW,GAAG,UAAU,GAChC;IAAE,MAAM,EAAE,aAAa,CAAC;IAAC,IAAI,EAAE,SAAS,CAAA;CAAE,CAc5C;AAED,6EAA6E;AAC7E,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,SAAS,EAAE,QAAQ,EAAE,aAAa,GAAG,SAAS,CAGrF"}

package/dist/controllers/transitions.js

@@ -0,0 +1,106 @@
+export const ATTEMPT_TRANSITIONS = {
+    submitted: [
+        'accepted',
+        'streaming',
+        'awaiting-input',
+        'completed',
+        'cancelled',
+        'failed',
+        'interrupted',
+    ],
+    accepted: ['streaming', 'awaiting-input', 'completed', 'cancelled', 'failed', 'interrupted'],
+    streaming: ['awaiting-input', 'completed', 'cancelled', 'failed', 'interrupted'],
+    'awaiting-input': ['streaming', 'completed', 'cancelled', 'failed', 'interrupted'],
+    // A resumed stream may continue or end an interrupted attempt.
+    interrupted: ['streaming', 'awaiting-input', 'completed', 'cancelled', 'failed'],
+    completed: [],
+    cancelled: [],
+    failed: [],
+};
+export const TOOL_TRANSITIONS = {
+    'input-streaming': ['input-available', 'output-error', 'cancelled'],
+    'input-available': [
+        'awaiting-approval',
+        'executing',
+        'output-available',
+        'output-error',
+        'denied',
+        'cancelled',
+    ],
+    'awaiting-approval': ['executing', 'output-available', 'output-error', 'denied', 'cancelled'],
+    executing: ['output-available', 'output-error', 'cancelled'],
+    // A host retry runs the tool again.
+    'output-error': ['executing'],
+    'output-available': [],
+    denied: [],
+    cancelled: [],
+};
+export const APPROVAL_TRANSITIONS = {
+    // approved/rejected directly: decided elsewhere (another client or an automatic policy).
+    requested: ['decision-pending', 'approved', 'rejected', 'expired', 'superseded'],
+    'decision-pending': ['approved', 'rejected', 'decision-failed', 'expired', 'superseded'],
+    'decision-failed': ['decision-pending', 'approved', 'rejected', 'expired', 'superseded'],
+    approved: [],
+    rejected: [],
+    expired: [],
+    superseded: [],
+};
+export const CONNECTION_TRANSITIONS = {
+    idle: ['connecting', 'open', 'closed'],
+    connecting: ['open', 'closed', 'disconnected'],
+    open: ['closed', 'disconnected'],
+    disconnected: ['reconnecting'],
+    closed: ['reconnecting'],
+    reconnecting: ['open', 'closed', 'disconnected'],
+};
+export function canTransition(table, from, to) {
+    return from === to || table[from].includes(to);
+}
+const TERMINAL = new Set(['completed', 'cancelled', 'failed']);
+/** The underlying work has ended (as reported by the backend, not inferred from a closed stream). */
+export const isTerminal = (status) => TERMINAL.has(status);
+/** Work may still be running remotely. `interrupted` means the client lost track of it. */
+export const isActive = (status) => status === 'submitted' ||
+    status === 'accepted' ||
+    status === 'streaming' ||
+    status === 'awaiting-input';
+export const TOOL_SETTLED = new Set([
+    'output-available',
+    'output-error',
+    'denied',
+    'cancelled',
+]);
+/**
+ * Apply a stop response to an attempt. `rejected` means the stop request itself failed.
+ * A stop that arrives after completion never rewrites the completed status.
+ *
+ * | Outcome            | Attempt not terminal      | Attempt already terminal          |
+ * | ------------------ | ------------------------- | --------------------------------- |
+ * | `cancelled`        | status → cancelled; stop → confirmed | status kept; stop → confirmed if cancelled, else too-late |
+ * | `already-finished` | status kept (await the terminal event); stop → too-late | status kept; stop → too-late |
+ * | `not-found`/`unknown` | status kept; stop → unknown | status kept; stop → unknown |
+ * | rejected           | status kept; stop → failed | status kept; stop → failed |
+ */
+export function applyStopOutcome(status, outcome) {
+    const terminal = isTerminal(status);
+    switch (outcome) {
+        case 'cancelled':
+            if (!terminal)
+                return { status: 'cancelled', stop: 'confirmed' };
+            return { status, stop: status === 'cancelled' ? 'confirmed' : 'too-late' };
+        case 'already-finished':
+            return { status, stop: 'too-late' };
+        case 'not-found':
+        case 'unknown':
+            return { status, stop: 'unknown' };
+        case 'rejected':
+            return { status, stop: 'failed' };
+    }
+}
+/** Stop state after a terminal event arrives while a stop may be pending. */
+export function stopAfterTerminal(stop, terminal) {
+    if (stop !== 'requested')
+        return stop;
+    return terminal === 'cancelled' ? 'confirmed' : 'too-late';
+}
+//# sourceMappingURL=transitions.js.map

package/dist/controllers/transitions.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"transitions.js","sourceRoot":"","sources":["../../src/controllers/transitions.ts"],"names":[],"mappings":"AAiBA,MAAM,CAAC,MAAM,mBAAmB,GAAyB;IACvD,SAAS,EAAE;QACT,UAAU;QACV,WAAW;QACX,gBAAgB;QAChB,WAAW;QACX,WAAW;QACX,QAAQ;QACR,aAAa;KACd;IACD,QAAQ,EAAE,CAAC,WAAW,EAAE,gBAAgB,EAAE,WAAW,EAAE,WAAW,EAAE,QAAQ,EAAE,aAAa,CAAC;IAC5F,SAAS,EAAE,CAAC,gBAAgB,EAAE,WAAW,EAAE,WAAW,EAAE,QAAQ,EAAE,aAAa,CAAC;IAChF,gBAAgB,EAAE,CAAC,WAAW,EAAE,WAAW,EAAE,WAAW,EAAE,QAAQ,EAAE,aAAa,CAAC;IAClF,+DAA+D;IAC/D,WAAW,EAAE,CAAC,WAAW,EAAE,gBAAgB,EAAE,WAAW,EAAE,WAAW,EAAE,QAAQ,CAAC;IAChF,SAAS,EAAE,EAAE;IACb,SAAS,EAAE,EAAE;IACb,MAAM,EAAE,EAAE;CACX,CAAC;AAEF,MAAM,CAAC,MAAM,gBAAgB,GAAsB;IACjD,iBAAiB,EAAE,CAAC,iBAAiB,EAAE,cAAc,EAAE,WAAW,CAAC;IACnE,iBAAiB,EAAE;QACjB,mBAAmB;QACnB,WAAW;QACX,kBAAkB;QAClB,cAAc;QACd,QAAQ;QACR,WAAW;KACZ;IACD,mBAAmB,EAAE,CAAC,WAAW,EAAE,kBAAkB,EAAE,cAAc,EAAE,QAAQ,EAAE,WAAW,CAAC;IAC7F,SAAS,EAAE,CAAC,kBAAkB,EAAE,cAAc,EAAE,WAAW,CAAC;IAC5D,oCAAoC;IACpC,cAAc,EAAE,CAAC,WAAW,CAAC;IAC7B,kBAAkB,EAAE,EAAE;IACtB,MAAM,EAAE,EAAE;IACV,SAAS,EAAE,EAAE;CACd,CAAC;AAEF,MAAM,CAAC,MAAM,oBAAoB,GAA0B;IACzD,yFAAyF;IACzF,SAAS,EAAE,CAAC,kBAAkB,EAAE,UAAU,EAAE,UAAU,EAAE,SAAS,EAAE,YAAY,CAAC;IAChF,kBAAkB,EAAE,CAAC,UAAU,EAAE,UAAU,EAAE,iBAAiB,EAAE,SAAS,EAAE,YAAY,CAAC;IACxF,iBAAiB,EAAE,CAAC,kBAAkB,EAAE,UAAU,EAAE,UAAU,EAAE,SAAS,EAAE,YAAY,CAAC;IACxF,QAAQ,EAAE,EAAE;IACZ,QAAQ,EAAE,EAAE;IACZ,OAAO,EAAE,EAAE;IACX,UAAU,EAAE,EAAE;CACf,CAAC;AAEF,MAAM,CAAC,MAAM,sBAAsB,GAA2B;IAC5D,IAAI,EAAE,CAAC,YAAY,EAAE,MAAM,EAAE,QAAQ,CAAC;IACtC,UAAU,EAAE,CAAC,MAAM,EAAE,QAAQ,EAAE,cAAc,CAAC;IAC9C,IAAI,EAAE,CAAC,QAAQ,EAAE,cAAc,CAAC;IAChC,YAAY,EAAE,CAAC,cAAc,CAAC;IAC9B,MAAM,EAAE,CAAC,cAAc,CAAC;IACxB,YAAY,EAAE,CAAC,MAAM,EAAE,QAAQ,EAAE,cAAc,CAAC;CACjD,CAAC;AAEF,MAAM,UAAU,aAAa,CAAmB,KAAe,EAAE,IAAO,EAAE,EAAK;IAC7E,OAAO,IAAI,KAAK,EAAE,IAAI,KAAK,CAAC,IAAI,CAAC,CAAC,QAAQ,CAAC,EAAE,CAAC,CAAC;AACjD,CAAC;AAED,MAAM,QAAQ,GAA+B,IAAI,GAAG,CAAC,CAAC,WAAW,EAAE,WAAW,EAAE,QAAQ,CAAC,CAAC,CAAC;AAC3F,qGAAqG;AACrG,MAAM,CAAC,MAAM,UAAU,GAAG,CAAC,MAAqB,EAAW,EAAE,CAAC,QAAQ,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC;AACnF,2FAA2F;AAC3F,MAAM,CAAC,MAAM,QAAQ,GAAG,CAAC,MAAqB,EAAW,EAAE,CACzD,MAAM,KAAK,WAAW;IACtB,MAAM,KAAK,UAAU;IACrB,MAAM,KAAK,WAAW;IACtB,MAAM,KAAK,gBAAgB,CAAC;AAE9B,MAAM,CAAC,MAAM,YAAY,GAA4B,IAAI,GAAG,CAAC;IAC3D,kBAAkB;IAClB,cAAc;IACd,QAAQ;IACR,WAAW;CACZ,CAAC,CAAC;AAEH;;;;;;;;;;GAUG;AACH,MAAM,UAAU,gBAAgB,CAC9B,MAAqB,EACrB,OAAiC;IAEjC,MAAM,QAAQ,GAAG,UAAU,CAAC,MAAM,CAAC,CAAC;IACpC,QAAQ,OAAO,EAAE,CAAC;QAChB,KAAK,WAAW;YACd,IAAI,CAAC,QAAQ;gBAAE,OAAO,EAAE,MAAM,EAAE,WAAW,EAAE,IAAI,EAAE,WAAW,EAAE,CAAC;YACjE,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,KAAK,WAAW,CAAC,CAAC,CAAC,WAAW,CAAC,CAAC,CAAC,UAAU,EAAE,CAAC;QAC7E,KAAK,kBAAkB;YACrB,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,UAAU,EAAE,CAAC;QACtC,KAAK,WAAW,CAAC;QACjB,KAAK,SAAS;YACZ,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,SAAS,EAAE,CAAC;QACrC,KAAK,UAAU;YACb,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,QAAQ,EAAE,CAAC;IACtC,CAAC;AACH,CAAC;AAED,6EAA6E;AAC7E,MAAM,UAAU,iBAAiB,CAAC,IAAe,EAAE,QAAuB;IACxE,IAAI,IAAI,KAAK,WAAW;QAAE,OAAO,IAAI,CAAC;IACtC,OAAO,QAAQ,KAAK,WAAW,CAAC,CAAC,CAAC,WAAW,CAAC,CAAC,CAAC,UAAU,CAAC;AAC7D,CAAC"}

package/dist/controllers/voice.d.ts

@@ -0,0 +1,81 @@
+/**
+ * Voice capture and transcription with replaceable adapters. The controller owns one session at
+ * a time, ignores callbacks from ended sessions, and releases the session on stop, cancel, and
+ * dispose. Browser speech recognition is one optional adapter (`@oddkin/ai/voice/web-speech`);
+ * recorder-plus-transcription and scripted adapters use the same contract. DOM-free.
+ * Contract: docs/architecture/ai-interaction.md §8.4.
+ */
+import { type Readable } from '@oddkin/core/reactive';
+import type { TranscriptSegment } from '../contracts/types.js';
+export type VoiceStatus = 'unsupported' | 'idle' | 'requesting-permission' | 'recording' | 'processing' | 'denied' | 'unavailable' | 'interrupted' | 'error';
+export type VoiceErrorCode = 'permission-denied' | 'no-device' | 'network' | 'interrupted' | 'other';
+export interface VoiceHandlers {
+    /** Capture started (permission granted, device open). */
+    started(): void;
+    interim(text: string): void;
+    final(text: string): void;
+    /** Recording ended; transcription of buffered audio may still follow. */
+    processing(): void;
+    /** The session ended. `stopped` after final results, `cancelled` on discard. */
+    ended(reason: 'stopped' | 'cancelled' | 'error', error?: VoiceErrorCode): void;
+}
+export interface VoiceSession {
+    /** Finish: deliver remaining final text, then end with `stopped`. */
+    stop(): void;
+    /** Discard: release resources immediately; no further callbacks. */
+    cancel(): void;
+}
+export interface VoiceAdapter {
+    /** Feature detection result; false makes the voice capability unavailable. */
+    readonly supported: boolean;
+    start(handlers: VoiceHandlers): VoiceSession;
+}
+export interface VoiceState {
+    readonly status: VoiceStatus;
+    readonly interim: string;
+    readonly segments: readonly TranscriptSegment[];
+    readonly error?: VoiceErrorCode | undefined;
+}
+export declare class VoiceController {
+    #private;
+    readonly state: Readable<VoiceState>;
+    constructor(adapter?: VoiceAdapter);
+    getSnapshot(): VoiceState;
+    /** Replace the adapter; any running session is cancelled. */
+    setAdapter(adapter: VoiceAdapter | undefined): void;
+    get active(): boolean;
+    start(): boolean;
+    /** Finish recording and keep the final transcript. */
+    stop(): void;
+    /** Discard the current recording and interim text; final segments already received stay. */
+    cancel(): void;
+    /** Replace or edit the transcript (user edits). */
+    setSegments(segments: readonly TranscriptSegment[]): void;
+    clear(): void;
+    dispose(): void;
+}
+/** One step of a scripted session: wait `after` ms, then deliver one result or outcome. */
+export type VoiceScriptStep = {
+    readonly after: number;
+    readonly interim: string;
+} | {
+    readonly after: number;
+    readonly final: string;
+} | {
+    readonly after: number;
+    readonly error: VoiceErrorCode;
+};
+export interface ScriptedVoiceAdapter extends VoiceAdapter {
+    /** Timers and sessions currently held (zero after every session ends). */
+    readonly openResources: number;
+}
+/**
+ * A deterministic adapter for tests and demos (clearly simulated). `denyPermission` and
+ * `noDevice` reproduce the matching failures before capture starts.
+ */
+export declare function createScriptedVoiceAdapter(script: readonly VoiceScriptStep[], options?: {
+    denyPermission?: boolean;
+    noDevice?: boolean;
+    permissionDelay?: number;
+}): ScriptedVoiceAdapter;
+//# sourceMappingURL=voice.d.ts.map

package/dist/controllers/voice.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"voice.d.ts","sourceRoot":"","sources":["../../src/controllers/voice.ts"],"names":[],"mappings":"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"}

package/dist/controllers/voice.js

@@ -0,0 +1,180 @@
+/**
+ * Voice capture and transcription with replaceable adapters. The controller owns one session at
+ * a time, ignores callbacks from ended sessions, and releases the session on stop, cancel, and
+ * dispose. Browser speech recognition is one optional adapter (`@oddkin/ai/voice/web-speech`);
+ * recorder-plus-transcription and scripted adapters use the same contract. DOM-free.
+ * Contract: docs/architecture/ai-interaction.md §8.4.
+ */
+import { signal } from '@oddkin/core/reactive';
+import { createId } from '../internal/ids.js';
+const STATUS_FOR_ERROR = {
+    'permission-denied': 'denied',
+    'no-device': 'unavailable',
+    network: 'error',
+    interrupted: 'interrupted',
+    other: 'error',
+};
+export class VoiceController {
+    #state;
+    state;
+    #adapter;
+    #session;
+    #generation = 0;
+    constructor(adapter) {
+        this.#adapter = adapter;
+        this.#state = signal({
+            status: adapter?.supported ? 'idle' : 'unsupported',
+            interim: '',
+            segments: [],
+        });
+        this.state = this.#state;
+    }
+    getSnapshot() {
+        return this.#state.peek();
+    }
+    /** Replace the adapter; any running session is cancelled. */
+    setAdapter(adapter) {
+        this.cancel();
+        this.#adapter = adapter;
+        this.#set({ status: adapter?.supported ? 'idle' : 'unsupported', interim: '' });
+    }
+    get active() {
+        return this.#session !== undefined;
+    }
+    start() {
+        const adapter = this.#adapter;
+        if (!adapter?.supported || this.#session)
+            return false;
+        const generation = ++this.#generation;
+        const live = () => generation === this.#generation;
+        this.#set({ status: 'requesting-permission', interim: '', error: undefined });
+        const session = adapter.start({
+            started: () => live() && this.#set({ status: 'recording' }),
+            interim: (text) => live() && this.#set({ interim: text }),
+            final: (text) => {
+                if (!live() || !text)
+                    return;
+                const now = this.#state.peek();
+                this.#set({
+                    interim: '',
+                    segments: [...now.segments, { id: createId('segment'), text, final: true }],
+                });
+            },
+            processing: () => live() && this.#set({ status: 'processing' }),
+            ended: (reason, error) => {
+                if (!live())
+                    return;
+                this.#session = undefined;
+                this.#generation++;
+                if (reason === 'error')
+                    this.#set({
+                        status: STATUS_FOR_ERROR[error ?? 'other'],
+                        interim: '',
+                        error: error ?? 'other',
+                    });
+                else
+                    this.#set({ status: 'idle', interim: '' });
+            },
+        });
+        // An adapter may end synchronously (e.g. no device); never keep a dead session.
+        if (live())
+            this.#session = session;
+        return true;
+    }
+    /** Finish recording and keep the final transcript. */
+    stop() {
+        this.#session?.stop();
+    }
+    /** Discard the current recording and interim text; final segments already received stay. */
+    cancel() {
+        const session = this.#session;
+        if (!session)
+            return;
+        this.#session = undefined;
+        this.#generation++;
+        session.cancel();
+        this.#set({ status: 'idle', interim: '' });
+    }
+    /** Replace or edit the transcript (user edits). */
+    setSegments(segments) {
+        this.#set({ segments });
+    }
+    clear() {
+        this.#set({ segments: [], interim: '' });
+    }
+    dispose() {
+        this.cancel();
+        this.#adapter = undefined;
+    }
+    #set(patch) {
+        this.#state.value = { ...this.#state.peek(), ...patch };
+    }
+}
+/**
+ * A deterministic adapter for tests and demos (clearly simulated). `denyPermission` and
+ * `noDevice` reproduce the matching failures before capture starts.
+ */
+export function createScriptedVoiceAdapter(script, options = {}) {
+    let open = 0;
+    return {
+        supported: true,
+        get openResources() {
+            return open;
+        },
+        start(handlers) {
+            const timers = new Set();
+            let ended = false;
+            open++;
+            const schedule = (ms, fn) => {
+                const id = setTimeout(() => {
+                    timers.delete(id);
+                    if (!ended)
+                        fn();
+                }, ms);
+                timers.add(id);
+            };
+            const finish = (reason, error) => {
+                if (ended)
+                    return;
+                ended = true;
+                for (const id of timers)
+                    clearTimeout(id);
+                timers.clear();
+                open--;
+                if (reason !== 'cancelled')
+                    handlers.ended(reason, error);
+            };
+            schedule(options.permissionDelay ?? 0, () => {
+                if (options.denyPermission)
+                    return finish('error', 'permission-denied');
+                if (options.noDevice)
+                    return finish('error', 'no-device');
+                handlers.started();
+                let at = 0;
+                for (const step of script) {
+                    at += step.after;
+                    schedule(at, () => {
+                        if ('interim' in step)
+                            handlers.interim(step.interim);
+                        else if ('final' in step)
+                            handlers.final(step.final);
+                        else
+                            finish('error', step.error);
+                    });
+                }
+            });
+            return {
+                stop() {
+                    if (ended)
+                        return;
+                    handlers.processing();
+                    schedule(0, () => finish('stopped'));
+                },
+                cancel() {
+                    finish('cancelled');
+                },
+            };
+        },
+    };
+}
+//# sourceMappingURL=voice.js.map

package/dist/controllers/voice.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"voice.js","sourceRoot":"","sources":["../../src/controllers/voice.ts"],"names":[],"mappings":"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"}