@timurproko/a1 0.1.8-dev.50ebb19 → 0.1.8-dev.510

package/dist/contracts/owned-ui/model.d.ts

@@ -0,0 +1,374 @@
+export declare const OWNED_UI_CONTRACT_VERSION: 1;
+export type OwnedUiSessionId = string;
+export type OwnedUiEntityId = string;
+export type OwnedUiCorrelationId = string;
+export type OwnedUiLifecycle = "starting" | "ready" | "busy" | "suspended" | "stopping" | "stopped" | "failed";
+export type OwnedUiBlockStatus = "live" | "finalized";
+export type OwnedUiTranscriptBlockKind = "user" | "assistant" | "thinking" | "tool-call" | "tool-result" | "retry" | "compaction" | "error" | "system" | "custom" | "bash";
+export type OwnedUiSeverity = "info" | "warning" | "error";
+export interface OwnedUiModelInfo {
+    readonly providerId: string;
+    readonly modelId: string;
+    readonly displayName: string;
+}
+export interface OwnedUiPromptSuggestionIdentity {
+    readonly sessionId: OwnedUiSessionId;
+    readonly sessionGeneration: number;
+    readonly runSequence: number;
+    readonly responseSequence: number;
+    readonly model: OwnedUiModelInfo;
+}
+export interface OwnedUiPromptSuggestionRequest {
+    readonly identity: OwnedUiPromptSuggestionIdentity;
+    readonly signal: AbortSignal;
+}
+export type OwnedUiPromptSuggestionReasoning = "ordinary" | "off" | "minimal" | "low" | "medium" | "high" | "xhigh" | "max" | "unavailable";
+export type OwnedUiPromptSuggestionResult = {
+    readonly identity: OwnedUiPromptSuggestionIdentity;
+} & ({
+    readonly outcome: "candidate";
+    readonly text: string;
+} | {
+    readonly outcome: "empty" | "rejected" | "provider-failure" | "unavailable" | "cancelled";
+    readonly text: null;
+});
+export type OwnedUiPromptSuggestionState = {
+    readonly status: "idle";
+} | {
+    readonly status: "generating";
+    readonly identity: OwnedUiPromptSuggestionIdentity;
+    readonly settled: boolean;
+} | {
+    readonly status: "prepared";
+    readonly identity: OwnedUiPromptSuggestionIdentity;
+    readonly text: string;
+} | {
+    readonly status: "available";
+    readonly identity: OwnedUiPromptSuggestionIdentity;
+    readonly text: string;
+};
+export interface OwnedUiPromptSuggestionGeneratorPort {
+    /** Request-local policy; never changes the primary session's thinking setting. */
+    suggestionReasoningPolicy?(): OwnedUiPromptSuggestionReasoning;
+    generate(request: OwnedUiPromptSuggestionRequest): Promise<OwnedUiPromptSuggestionResult>;
+}
+export type OwnedUiThinkingLevel = "off" | "minimal" | "low" | "medium" | "high" | "xhigh";
+export interface OwnedUiViewportSettings {
+    readonly scrollbarAppearance: "auto" | "always" | "hidden";
+    readonly scrollbarStyle: "thin" | "thick";
+    /** normal is baseline; fast is 2x normal; high is normal plus fast. */
+    readonly scrollbarSpeed: "normal" | "fast" | "high";
+}
+/** Narrow live settings boundary consumed by the bare-A1 shell composition. */
+export interface OwnedUiViewportSettingsPort {
+    snapshot(): OwnedUiViewportSettings;
+    onChange(listener: (settings: OwnedUiViewportSettings) => void): () => void;
+}
+/** Profile-local quit outro choice, read at the moment bare A1 quits. */
+export interface OwnedUiQuitOutroSettings {
+    /** False leaves the terminal immediately; true plays the shell's fixed effect. */
+    readonly enabled: boolean;
+}
+export interface OwnedUiQuitOutroSettingsPort {
+    snapshot(): OwnedUiQuitOutroSettings;
+}
+export interface OwnedUiTerminalSurface {
+    readonly columns: number;
+    readonly rows: number;
+    readonly focusedRegion: "transcript" | "editor" | "dialog" | "overlay" | "status";
+    readonly hardwareCursor: boolean;
+}
+export interface OwnedUiImageAttachment {
+    readonly type: "image";
+    readonly data: string;
+    readonly mimeType: string;
+}
+export interface OwnedUiEditorState {
+    readonly text: string;
+    readonly queuedSubmissions: readonly string[];
+    readonly selection: {
+        readonly start: number;
+        readonly end: number;
+    } | null;
+    readonly cursorOffset: number;
+    readonly historyRevision: number;
+    readonly submitEnabled: boolean;
+}
+export interface OwnedUiUsageView {
+    readonly input: number;
+    readonly output: number;
+    readonly cacheRead: number;
+    readonly cacheWrite: number;
+    readonly cost: number;
+    readonly latestCacheHitRate: number | null;
+    readonly latestPrompt?: {
+        readonly input: number;
+        readonly cacheRead: number;
+        readonly cacheWrite: number;
+    } | null;
+    readonly contextAvailable?: boolean;
+    readonly contextTokens: number | null;
+    readonly contextWindow: number;
+    readonly contextPercent: number | null;
+    readonly usingSubscription: boolean;
+    readonly autoCompactEnabled: boolean;
+}
+export interface OwnedUiFooterView {
+    readonly branch: string | null;
+    readonly sessionName: string | null;
+    readonly availableProviderCount: number;
+    readonly extensionStatuses: readonly (readonly [string, string])[];
+}
+export interface OwnedUiStatusView {
+    readonly title: string;
+    readonly workingMessage: string | null;
+    /** Estimated progress of the shown work state as an integer percent below 100, when the engine can measure it. */
+    readonly workingProgress?: number | null;
+    readonly diagnostics: readonly string[];
+    readonly badges: readonly string[];
+    readonly usage?: OwnedUiUsageView;
+    readonly footer?: OwnedUiFooterView;
+}
+export interface OwnedUiDialog {
+    readonly id: OwnedUiEntityId;
+    readonly title: string;
+    readonly kind: "choice" | "editor" | "settings" | "confirmation";
+    readonly payload: unknown;
+}
+export interface OwnedUiOverlay {
+    readonly id: OwnedUiEntityId;
+    readonly componentSlotId: OwnedUiEntityId;
+    readonly placement: "bottom" | "center";
+    readonly modal: boolean;
+    readonly payload: unknown;
+}
+export interface OwnedUiTranscriptImageReference {
+    readonly assetId: OwnedUiEntityId;
+    readonly mimeType: string;
+    readonly byteLength: number;
+    readonly source: "user" | "tool-result";
+}
+/** Argument generation and execution have distinct completion boundaries on one invocation. */
+export interface OwnedUiToolState {
+    readonly argsComplete: boolean;
+    readonly execution: "pending" | "running" | "succeeded" | "failed" | "aborted";
+}
+/** Vendor-neutral rendering metadata; text and image bytes are not duplicated here. */
+export type OwnedUiToolResultPart = {
+    readonly type: "text";
+    readonly start: number;
+    readonly end: number;
+} | {
+    readonly type: "image";
+    readonly imageIndex: number;
+};
+export interface OwnedUiToolRendering {
+    readonly arguments: unknown;
+    readonly result?: {
+        readonly content: readonly OwnedUiToolResultPart[];
+        readonly details?: unknown;
+    };
+    /** Visible bounded fallback, never a substitute operation outcome. */
+    readonly unavailable?: string;
+}
+export interface OwnedUiTranscriptBlock {
+    readonly id: OwnedUiEntityId;
+    readonly kind: OwnedUiTranscriptBlockKind;
+    readonly status: OwnedUiBlockStatus;
+    readonly revision: number;
+    readonly title: string | null;
+    readonly text: string;
+    readonly payload: unknown;
+    /** Tool-call message completion alone must not settle execution. */
+    readonly toolState?: OwnedUiToolState;
+    /** Authoritative renderer inputs, separate from diagnostic payloads. */
+    readonly toolRendering?: OwnedUiToolRendering;
+    /** Bounded opaque references; image bytes remain in the session-scoped engine asset store. */
+    readonly imageReferences?: readonly OwnedUiTranscriptImageReference[];
+}
+export type OwnedUiSlotId = "theme" | "transcript-block" | "tool-card" | "editor" | "status" | "command" | "selector" | "dialog" | "overlay" | "layout";
+export interface OwnedUiCustomization {
+    readonly id: OwnedUiEntityId;
+    readonly slot: OwnedUiSlotId;
+    readonly version: number;
+    readonly precedence: number;
+    readonly label: string;
+    readonly payload: unknown;
+}
+export interface OwnedUiDiagnostics {
+    readonly sequence: number;
+    readonly code: string;
+    readonly severity: OwnedUiSeverity;
+    readonly message: string;
+    readonly recoverable: boolean;
+}
+export interface OwnedUiSessionViewModel {
+    readonly contractVersion: typeof OWNED_UI_CONTRACT_VERSION;
+    readonly sessionId: OwnedUiSessionId;
+    readonly revision: number;
+    readonly lifecycle: OwnedUiLifecycle;
+    readonly transcript: readonly OwnedUiTranscriptBlock[];
+    readonly editor: OwnedUiEditorState;
+    readonly status: OwnedUiStatusView;
+    readonly terminal: OwnedUiTerminalSurface;
+    readonly activeModel: OwnedUiModelInfo | null;
+    readonly thinkingLevel: OwnedUiThinkingLevel;
+    readonly activeCommandIds: readonly OwnedUiCorrelationId[];
+    readonly dialog: OwnedUiDialog | null;
+    readonly overlay: OwnedUiOverlay | null;
+    readonly customizations: readonly OwnedUiCustomization[];
+    readonly diagnostics: readonly OwnedUiDiagnostics[];
+}
+export type OwnedUiCommand = {
+    readonly type: "prompt";
+    readonly correlationId: OwnedUiCorrelationId;
+    readonly sessionId: OwnedUiSessionId;
+    readonly text: string;
+    readonly images?: readonly OwnedUiImageAttachment[];
+} | {
+    readonly type: "steer" | "follow-up";
+    readonly correlationId: OwnedUiCorrelationId;
+    readonly sessionId: OwnedUiSessionId;
+    readonly text: string;
+    readonly images?: readonly OwnedUiImageAttachment[];
+} | {
+    readonly type: "abort" | "retry" | "compact" | "shutdown";
+    readonly correlationId: OwnedUiCorrelationId;
+    readonly sessionId: OwnedUiSessionId;
+} | {
+    readonly type: "set-model";
+    readonly correlationId: OwnedUiCorrelationId;
+    readonly sessionId: OwnedUiSessionId;
+    readonly model: OwnedUiModelInfo;
+} | {
+    readonly type: "set-thinking-level";
+    readonly correlationId: OwnedUiCorrelationId;
+    readonly sessionId: OwnedUiSessionId;
+    readonly thinkingLevel: OwnedUiThinkingLevel;
+} | {
+    readonly type: "new-session";
+    readonly correlationId: OwnedUiCorrelationId;
+    readonly sessionId: OwnedUiSessionId;
+} | {
+    readonly type: "resume-session";
+    readonly correlationId: OwnedUiCorrelationId;
+    readonly sessionId: OwnedUiSessionId;
+    readonly sessionPath: string;
+} | {
+    readonly type: "set-setting";
+    readonly correlationId: OwnedUiCorrelationId;
+    readonly sessionId: OwnedUiSessionId;
+    readonly key: string;
+    readonly value: unknown;
+} | {
+    readonly type: "apply-customization";
+    readonly correlationId: OwnedUiCorrelationId;
+    readonly sessionId: OwnedUiSessionId;
+    readonly customization: OwnedUiCustomization;
+} | {
+    readonly type: "remove-customization";
+    readonly correlationId: OwnedUiCorrelationId;
+    readonly sessionId: OwnedUiSessionId;
+    readonly customizationId: OwnedUiEntityId;
+} | {
+    readonly type: "resize-surface";
+    readonly correlationId: OwnedUiCorrelationId;
+    readonly sessionId: OwnedUiSessionId;
+    readonly surface: OwnedUiTerminalSurface;
+};
+export type OwnedUiCommandOutcome = "accepted" | "rejected" | "completed" | "failed" | "timed-out" | "cancelled";
+export type OwnedUiEvent = {
+    readonly type: "session-lifecycle";
+    readonly sessionId: OwnedUiSessionId;
+    readonly sequence: number;
+    readonly lifecycle: OwnedUiLifecycle;
+    readonly reason: string | null;
+} | {
+    readonly type: "session-view";
+    readonly sessionId: OwnedUiSessionId;
+    readonly sequence: number;
+    readonly view: OwnedUiSessionViewModel;
+} | {
+    readonly type: "transcript-block";
+    readonly sessionId: OwnedUiSessionId;
+    readonly sequence: number;
+    readonly block: OwnedUiTranscriptBlock;
+} | {
+    /** One completed assistant reply; never a tool row or transcript rebuild. */
+    readonly type: "assistant-message-completed";
+    readonly sessionId: OwnedUiSessionId;
+    readonly sequence: number;
+    readonly sessionGeneration: number;
+    readonly runSequence: number;
+    readonly responseSequence: number;
+    readonly model: OwnedUiModelInfo | null;
+    readonly assistantMessageCount: number;
+    readonly successful: boolean;
+    readonly stopReason: string | null;
+    readonly toolContinuation: boolean;
+} | {
+    /** A fresh agent run has started, used by follow-mode surfaces. */
+    readonly type: "agent-run-started";
+    readonly sessionId: OwnedUiSessionId;
+    readonly sequence: number;
+} | {
+    /** The final settlement of one run, after authoritative transcript reconciliation. */
+    readonly type: "agent-run-settled";
+    readonly sessionId: OwnedUiSessionId;
+    readonly sequence: number;
+    readonly sessionGeneration: number;
+    readonly runSequence: number;
+    readonly responseSequence: number;
+    readonly model: OwnedUiModelInfo | null;
+    readonly assistantMessageCount: number;
+    readonly successful: boolean;
+} | {
+    readonly type: "editor-state";
+    readonly sessionId: OwnedUiSessionId;
+    readonly sequence: number;
+    readonly editor: OwnedUiEditorState;
+} | {
+    readonly type: "status";
+    readonly sessionId: OwnedUiSessionId;
+    readonly sequence: number;
+    readonly status: OwnedUiStatusView;
+} | {
+    readonly type: "dialog";
+    readonly sessionId: OwnedUiSessionId;
+    readonly sequence: number;
+    readonly dialog: OwnedUiDialog | null;
+} | {
+    readonly type: "overlay";
+    readonly sessionId: OwnedUiSessionId;
+    readonly sequence: number;
+    readonly overlay: OwnedUiOverlay | null;
+} | {
+    readonly type: "command-outcome";
+    readonly sessionId: OwnedUiSessionId;
+    readonly sequence: number;
+    readonly correlationId: OwnedUiCorrelationId;
+    readonly outcome: OwnedUiCommandOutcome;
+    readonly diagnostic: string | null;
+} | {
+    readonly type: "customization";
+    readonly sessionId: OwnedUiSessionId;
+    readonly sequence: number;
+    readonly customizations: readonly OwnedUiCustomization[];
+} | {
+    readonly type: "terminal-surface";
+    readonly sessionId: OwnedUiSessionId;
+    readonly sequence: number;
+    readonly surface: OwnedUiTerminalSurface;
+} | {
+    readonly type: "diagnostic";
+    readonly sessionId: OwnedUiSessionId;
+    readonly sequence: number;
+    readonly diagnostic: OwnedUiDiagnostics;
+};
+export interface OwnedUiSnapshot {
+    readonly contractVersion: typeof OWNED_UI_CONTRACT_VERSION;
+    readonly snapshotId: OwnedUiEntityId;
+    readonly sessionId: OwnedUiSessionId;
+    readonly sequence: number;
+    readonly view: OwnedUiSessionViewModel;
+}

package/dist/contracts/owned-ui/prompt-history.d.ts

@@ -0,0 +1,55 @@
+export declare const PROMPT_HISTORY_EDITOR_REPLACEMENT: Readonly<{
+    readonly id: "persistent-prompt-history";
+    readonly kind: "replacement";
+    readonly slot: "editor";
+    readonly replaces: readonly string[];
+}>;
+export type PromptHistoryKind = "prompt" | "steer" | "follow-up" | "bash" | "slash";
+export interface PromptHistorySubmission {
+    readonly id: string;
+    readonly text: string;
+    readonly timestamp: number;
+    readonly kind: PromptHistoryKind;
+    readonly cwd?: string;
+    readonly sessionId?: string;
+}
+export interface PromptHistorySnapshot {
+    readonly revision: number;
+    readonly limit: number;
+    readonly entries: readonly {
+        readonly text: string;
+        readonly submissionId: string;
+    }[];
+}
+export type PromptHistoryFailure = "unavailable" | "busy" | "capacity" | "oversized" | "schema" | "corrupt" | "shutdown";
+export type PromptHistoryResult = "committed" | "skipped";
+export interface PromptHistoryPort {
+    start(): void;
+    record(submission: PromptHistorySubmission): Promise<PromptHistoryResult>;
+    refresh(): void;
+    onSnapshot(listener: (snapshot: PromptHistorySnapshot) => void): () => void;
+    onFailure(listener: (code: PromptHistoryFailure) => void): () => void;
+    close(): Promise<void>;
+}
+export interface PromptHistoryImageSidecarAttachment {
+    readonly type: "image";
+    readonly data: string;
+    readonly mimeType: string;
+}
+export interface PromptHistoryImageSidecarRecord {
+    readonly tag: string;
+    readonly data: string;
+    readonly mimeType: string;
+    readonly savedAt: string;
+}
+/** Per-profile durable payload store for image chip attachments referenced by history text.
+ * Writes MUST be idempotent and MUST NOT block a history row commit on failure; reads MUST
+ * treat every failure as "attachment unavailable" so rehydration silently strips the chip. */
+export interface PromptHistoryImageSidecarPort {
+    write(id: string, record: PromptHistoryImageSidecarRecord): void;
+    readAttachment(id: string): PromptHistoryImageSidecarAttachment | null;
+}
+export declare const PROMPT_HISTORY_MAX_ENTRY_BYTES: number;
+export declare const PROMPT_HISTORY_MAX_TEXT_BYTES: number;
+export declare const PROMPT_HISTORY_MAX_PENDING = 32;
+export declare function assertPromptHistorySubmission(value: unknown): asserts value is PromptHistorySubmission;

package/dist/contracts/owned-ui/prompt-history.js

@@ -0,0 +1,23 @@
+export const PROMPT_HISTORY_EDITOR_REPLACEMENT = Object.freeze({
+    id: "persistent-prompt-history",
+    kind: "replacement",
+    slot: "editor",
+    replaces: Object.freeze(["current-session-history-source", "adjacent-duplicate-policy", "recall-caret-placement", "history-border"]),
+});
+export const PROMPT_HISTORY_MAX_ENTRY_BYTES = 1024 * 1024;
+export const PROMPT_HISTORY_MAX_TEXT_BYTES = 8 * 1024 * 1024;
+export const PROMPT_HISTORY_MAX_PENDING = 32;
+export function assertPromptHistorySubmission(value) {
+    if (typeof value !== "object" || value === null || Array.isArray(value))
+        throw new TypeError("Invalid history submission");
+    const item = value;
+    const allowed = new Set(["id", "text", "timestamp", "kind", "cwd", "sessionId"]);
+    if (Object.keys(item).some(key => !allowed.has(key))
+        || typeof item.id !== "string" || !/^[a-zA-Z0-9-]{1,128}$/.test(item.id)
+        || typeof item.text !== "string" || !item.text.trim() || item.text !== item.text.trim()
+        || typeof item.timestamp !== "number" || !Number.isSafeInteger(item.timestamp) || item.timestamp < 0
+        || typeof item.kind !== "string" || !["prompt", "steer", "follow-up", "bash", "slash"].includes(item.kind)
+        || item.cwd !== undefined && typeof item.cwd !== "string"
+        || item.sessionId !== undefined && typeof item.sessionId !== "string")
+        throw new TypeError("Invalid history submission");
+}

package/dist/contracts/owned-ui/prompt-suggestions.d.ts

@@ -0,0 +1,3 @@
+export declare const CONTEXTUAL_PROMPT_SUGGESTION_INSTRUCTION = "[NEXT USER INPUT]\nPredict the one short response the user is most likely to type next.\nUse the user's recent intent and writing style. Prefer a concrete continuation such as approving an offered action, choosing an offered option, running a requested check, committing, or pushing.\nPrefer a clearly offered next action consistent with the user's recent intent. An optional alternative alone does not make that continuation unclear.\nFor example, after the user accepted merged work, \"Say archive it\" with an optional \"let me test\" alternative favors: archive it.\nDo not favor archival if the user required testing first and that testing remains outstanding. Do not invent approval or select the first of equally unresolved choices.\nReturn nothing when the next input is genuinely unclear, the previous response failed, or required assessment or correction remains outstanding.\nDo not answer as the assistant. Do not add a label, explanation, quotation marks, Markdown, or multiple sentences.\nReturn only 2-12 words, except a natural one-word command or answer is allowed.";
+/** Converts untrusted model output into one inert, bounded user-voice candidate. */
+export declare function normalizePromptSuggestionCandidate(candidate: string | null | undefined): string | null;

package/dist/contracts/owned-ui/prompt-suggestions.js

@@ -0,0 +1,44 @@
+export const CONTEXTUAL_PROMPT_SUGGESTION_INSTRUCTION = `[NEXT USER INPUT]
+Predict the one short response the user is most likely to type next.
+Use the user's recent intent and writing style. Prefer a concrete continuation such as approving an offered action, choosing an offered option, running a requested check, committing, or pushing.
+Prefer a clearly offered next action consistent with the user's recent intent. An optional alternative alone does not make that continuation unclear.
+For example, after the user accepted merged work, "Say archive it" with an optional "let me test" alternative favors: archive it.
+Do not favor archival if the user required testing first and that testing remains outstanding. Do not invent approval or select the first of equally unresolved choices.
+Return nothing when the next input is genuinely unclear, the previous response failed, or required assessment or correction remains outstanding.
+Do not answer as the assistant. Do not add a label, explanation, quotation marks, Markdown, or multiple sentences.
+Return only 2-12 words, except a natural one-word command or answer is allowed.`;
+const ALLOWED_SINGLE_WORDS = new Set([
+    "yes", "yeah", "yep", "sure", "ok", "okay", "no",
+    "continue", "apply", "commit", "push", "deploy", "test", "check", "stop", "exit", "quit",
+]);
+/** Converts untrusted model output into one inert, bounded user-voice candidate. */
+export function normalizePromptSuggestionCandidate(candidate) {
+    if (typeof candidate !== "string")
+        return null;
+    const suggestion = candidate.trim();
+    if (suggestion.length === 0 || [...suggestion].length >= 100)
+        return null;
+    if (/[\p{C}\r\n\t]/u.test(suggestion))
+        return null;
+    if (/[\*`#]|__|~~/.test(suggestion))
+        return null;
+    if (/[.!?]\s+\S/u.test(suggestion))
+        return null;
+    const lower = suggestion.toLowerCase();
+    if (/^(api error:|prompt is too long|request timed out|invalid api key|image was too large)/.test(lower))
+        return null;
+    if (lower === "done" || /^(nothing to suggest|no suggestion|stay silent|silence\b)/.test(lower))
+        return null;
+    if (/^\w+:\s/u.test(suggestion))
+        return null;
+    if (/^(let me|i(?:'|’)ll|i(?:'|’)ve|i(?:'|’)m|i can|i would|i think|here(?:'|’)s|here is|here are|you can|you should|you could|sure,|of course|certainly)\b/i.test(suggestion))
+        return null;
+    if (/\b(thanks|thank you|looks good|sounds good|that works|that worked|nice|great|perfect|awesome|excellent)\b/i.test(suggestion))
+        return null;
+    const words = suggestion.split(/\s+/u);
+    if (words.length > 12)
+        return null;
+    if (words.length === 1 && !suggestion.startsWith("/") && !ALLOWED_SINGLE_WORDS.has(lower))
+        return null;
+    return suggestion;
+}

package/dist/contracts/owned-ui/suggestion-diagnostics.d.ts

@@ -0,0 +1,22 @@
+import type { OwnedUiPromptSuggestionReasoning } from "./model.js";
+export declare const SUGGESTION_DECISION_REASONS: readonly ["disabled", "disposed", "early-conversation", "no-model", "failed-response", "incomplete-response", "tool-continuation", "replacement-input", "modal", "draft", "not-ready", "not-focused", "autocomplete", "prompt-mode", "presentation-unavailable", "ineligible", "stale-identity"];
+export type SuggestionDecisionReason = typeof SUGGESTION_DECISION_REASONS[number];
+export type SuggestionDecision = SuggestionDecisionReason | null;
+export declare const SUGGESTION_DIAGNOSTIC_EVENTS: readonly ["skipped", "started", "displayed", "empty", "rejected", "provider-failure", "unavailable", "timeout", "cancelled", "stale-result", "presentation-blocked", "late-result-discarded"];
+export type SuggestionDiagnosticEvent = typeof SUGGESTION_DIAGNOSTIC_EVENTS[number];
+/** Metadata only: never carry a session path, prompt, candidate, or raw error. */
+export interface SuggestionDiagnosticRecord {
+    readonly event: SuggestionDiagnosticEvent;
+    readonly reason?: SuggestionDecisionReason;
+    readonly session: number;
+    readonly run: number;
+    readonly response: number;
+    readonly request: number;
+    readonly provider: string;
+    readonly model: string;
+    readonly reasoning: OwnedUiPromptSuggestionReasoning;
+    readonly elapsedMs: number;
+}
+export interface SuggestionDiagnosticObserver {
+    record(record: SuggestionDiagnosticRecord): void;
+}

package/dist/contracts/owned-ui/suggestion-diagnostics.js

@@ -0,0 +1,9 @@
+export const SUGGESTION_DECISION_REASONS = [
+    "disabled", "disposed", "early-conversation", "no-model", "failed-response", "incomplete-response",
+    "tool-continuation", "replacement-input", "modal", "draft", "not-ready", "not-focused",
+    "autocomplete", "prompt-mode", "presentation-unavailable", "ineligible", "stale-identity",
+];
+export const SUGGESTION_DIAGNOSTIC_EVENTS = [
+    "skipped", "started", "displayed", "empty", "rejected", "provider-failure", "unavailable",
+    "timeout", "cancelled", "stale-result", "presentation-blocked", "late-result-discarded",
+];

package/dist/contracts/owned-ui/transcript-lifecycle.d.ts

@@ -0,0 +1,5 @@
+import type { OwnedUiToolState, OwnedUiTranscriptBlock } from "./model.js";
+/** Compatibility for existing owned components/fixtures without explicit execution state. */
+export declare function transcriptToolState(block: OwnedUiTranscriptBlock): OwnedUiToolState | undefined;
+/** Within a session generation, reject obsolete phases as well as obsolete revisions. */
+export declare function acceptsTranscriptUpdate(current: OwnedUiTranscriptBlock, next: OwnedUiTranscriptBlock): boolean;

package/dist/contracts/owned-ui/transcript-lifecycle.js

@@ -0,0 +1,33 @@
+/** Compatibility for existing owned components/fixtures without explicit execution state. */
+export function transcriptToolState(block) {
+    if (block.kind !== "tool-call" && block.kind !== "tool-result")
+        return undefined;
+    if (block.toolState !== undefined)
+        return block.toolState;
+    const payload = typeof block.payload === "object" && block.payload !== null ? block.payload : {};
+    const isError = "isError" in payload && payload.isError === true;
+    const partial = "partialResult" in payload && payload.partialResult === true;
+    return {
+        argsComplete: block.status === "finalized" || "argsComplete" in payload && payload.argsComplete === true,
+        execution: block.kind === "tool-result"
+            ? block.status === "live" ? "running" : isError ? "failed" : "succeeded"
+            : partial ? "running" : "pending",
+    };
+}
+/** Within a session generation, reject obsolete phases as well as obsolete revisions. */
+export function acceptsTranscriptUpdate(current, next) {
+    if (current.id !== next.id || current.revision > next.revision)
+        return false;
+    const before = transcriptToolState(current);
+    const after = transcriptToolState(next);
+    if (before !== undefined && after !== undefined) {
+        const rank = (state) => state.execution === "pending" ? 0 : state.execution === "running" ? 1 : 2;
+        if (rank(after) < rank(before))
+            return false;
+        if (before.argsComplete && !after.argsComplete && rank(after) < 2)
+            return false;
+        // Compatibility: a legacy finalized call declaration only closed arguments. Actual result finality is a barrier.
+        return !(current.status === "finalized" && next.status === "live" && before.execution !== "pending");
+    }
+    return !(current.status === "finalized" && next.status === "live");
+}

package/dist/contracts/owned-ui/validation.d.ts

@@ -0,0 +1,15 @@
+import { type OwnedUiCommand, type OwnedUiCustomization, type OwnedUiDiagnostics, type OwnedUiEditorState, type OwnedUiEvent, type OwnedUiPromptSuggestionIdentity, type OwnedUiPromptSuggestionRequest, type OwnedUiPromptSuggestionResult, type OwnedUiPromptSuggestionState, type OwnedUiSessionViewModel, type OwnedUiSnapshot, type OwnedUiStatusView, type OwnedUiTerminalSurface, type OwnedUiTranscriptBlock } from "./model.js";
+export declare function assertOwnedUiCommand(command: OwnedUiCommand): void;
+export declare function assertOwnedUiEvent(event: OwnedUiEvent): void;
+export declare function assertOwnedUiPromptSuggestionIdentity(identity: OwnedUiPromptSuggestionIdentity): void;
+export declare function assertOwnedUiPromptSuggestionRequest(request: OwnedUiPromptSuggestionRequest): void;
+export declare function assertOwnedUiPromptSuggestionResult(result: OwnedUiPromptSuggestionResult): void;
+export declare function assertOwnedUiPromptSuggestionState(state: OwnedUiPromptSuggestionState): void;
+export declare function assertOwnedUiSessionViewModel(view: OwnedUiSessionViewModel): void;
+export declare function assertOwnedUiSnapshot(snapshot: OwnedUiSnapshot): void;
+export declare function assertOwnedUiCustomization(customization: OwnedUiCustomization): void;
+export declare function assertOwnedUiTranscriptBlock(block: OwnedUiTranscriptBlock): void;
+export declare function assertOwnedUiEditorState(editor: OwnedUiEditorState): void;
+export declare function assertOwnedUiStatusView(status: OwnedUiStatusView): void;
+export declare function assertOwnedUiTerminalSurface(surface: OwnedUiTerminalSurface): void;
+export declare function assertOwnedUiDiagnostics(diagnostic: OwnedUiDiagnostics): void;