@timurproko/a1 0.1.8-dev.3b54f21 → 0.1.8-dev.407

package/dist/{src/foundation/owned-ui-contracts → contracts/owned-ui}/model.d.ts

@@ -11,13 +11,70 @@ export interface OwnedUiModelInfo {
     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;
+}
 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[];
@@ -75,6 +132,35 @@ export interface OwnedUiOverlay {
     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;
@@ -83,6 +169,12 @@ export interface OwnedUiTranscriptBlock {
     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 {
@@ -122,11 +214,13 @@ export type OwnedUiCommand = {
     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;
@@ -189,6 +283,35 @@ export type OwnedUiEvent = {
     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;

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/{src/foundation/owned-ui-contracts → contracts/owned-ui}/validation.d.ts

@@ -1,6 +1,10 @@
-import { type OwnedUiCommand, type OwnedUiCustomization, type OwnedUiDiagnostics, type OwnedUiEditorState, type OwnedUiEvent, type OwnedUiSessionViewModel, type OwnedUiSnapshot, type OwnedUiStatusView, type OwnedUiTerminalSurface, type OwnedUiTranscriptBlock } from "./model.js";
+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;

package/dist/{src/foundation/owned-ui-contracts → contracts/owned-ui}/validation.js

@@ -1,4 +1,5 @@
 import { OWNED_UI_CONTRACT_VERSION, } from "./model.js";
+import { assertPromptImages } from "./image-attachments.js";
 const MAX_ID_LENGTH = 128;
 const MAX_LABEL_LENGTH = 256;
 const MAX_MESSAGE_LENGTH = 4_096;
@@ -12,6 +13,8 @@ const MAX_QUEUE = 32;
 const MAX_BADGES = 32;
 const MAX_STATUS_DIAGNOSTICS = 32;
 const MAX_ACTIVE_COMMANDS = 64;
+const IMAGE_REFERENCE_SOURCES = new Set(["user", "tool-result"]);
+const TOOL_EXECUTIONS = new Set(["pending", "running", "succeeded", "failed", "aborted"]);
 const BLOCK_KINDS = new Set([
     "user",
     "assistant",
@@ -53,6 +56,9 @@ export function assertOwnedUiCommand(command) {
         case "steer":
         case "follow-up":
             assertBoundedText(command.text, "owned-UI prompt text", MAX_TEXT_BYTES);
+            if (command.images !== undefined) {
+                assertPromptImages(command.images);
+            }
             return;
         case "abort":
         case "retry":
@@ -103,6 +109,31 @@ export function assertOwnedUiEvent(event) {
         case "transcript-block":
             assertOwnedUiTranscriptBlock(event.block);
             return;
+        case "assistant-message-completed":
+            assertNonNegativeInteger(event.sessionGeneration, "owned-UI assistant response session generation");
+            assertNonNegativeInteger(event.runSequence, "owned-UI assistant response run sequence");
+            assertNonNegativeInteger(event.responseSequence, "owned-UI assistant response sequence");
+            assertNonNegativeInteger(event.assistantMessageCount, "owned-UI assistant response count");
+            if (event.model !== null)
+                assertOwnedUiModelInfo(event.model);
+            if (typeof event.successful !== "boolean")
+                throw new TypeError("owned-UI assistant response success state is invalid");
+            assertOptionalText(event.stopReason, "owned-UI assistant response stop reason", MAX_LABEL_LENGTH);
+            if (typeof event.toolContinuation !== "boolean")
+                throw new TypeError("owned-UI assistant response tool-continuation state is invalid");
+            return;
+        case "agent-run-started":
+            return;
+        case "agent-run-settled":
+            assertNonNegativeInteger(event.sessionGeneration, "owned-UI settlement session generation");
+            assertNonNegativeInteger(event.runSequence, "owned-UI settlement run sequence");
+            assertNonNegativeInteger(event.responseSequence, "owned-UI settlement response sequence");
+            assertNonNegativeInteger(event.assistantMessageCount, "owned-UI settlement assistant message count");
+            if (event.model !== null)
+                assertOwnedUiModelInfo(event.model);
+            if (typeof event.successful !== "boolean")
+                throw new TypeError("owned-UI settlement success state is invalid");
+            return;
         case "editor-state":
             assertOwnedUiEditorState(event.editor);
             return;
@@ -138,6 +169,45 @@ export function assertOwnedUiEvent(event) {
             throw new TypeError("owned-UI event type is unknown");
     }
 }
+export function assertOwnedUiPromptSuggestionIdentity(identity) {
+    assertId(identity.sessionId, "prompt-suggestion session id");
+    assertNonNegativeInteger(identity.sessionGeneration, "prompt-suggestion session generation");
+    assertNonNegativeInteger(identity.runSequence, "prompt-suggestion run sequence");
+    assertNonNegativeInteger(identity.responseSequence, "prompt-suggestion response sequence");
+    assertOwnedUiModelInfo(identity.model);
+}
+export function assertOwnedUiPromptSuggestionRequest(request) {
+    assertOwnedUiPromptSuggestionIdentity(request.identity);
+    if (typeof request.signal !== "object" || request.signal === null
+        || typeof request.signal.aborted !== "boolean"
+        || typeof request.signal.addEventListener !== "function") {
+        throw new TypeError("prompt-suggestion abort signal is invalid");
+    }
+}
+export function assertOwnedUiPromptSuggestionResult(result) {
+    assertOwnedUiPromptSuggestionIdentity(result.identity);
+    if (result.outcome === "candidate") {
+        assertPromptSuggestionText(result.text, false);
+        if (!result.text.trim())
+            throw new TypeError("prompt-suggestion candidate is empty");
+    }
+    else if (!["empty", "rejected", "provider-failure", "unavailable", "cancelled"].includes(result.outcome) || result.text !== null) {
+        throw new TypeError("prompt-suggestion outcome is invalid");
+    }
+}
+export function assertOwnedUiPromptSuggestionState(state) {
+    if (state.status === "idle")
+        return;
+    if (state.status !== "generating" && state.status !== "prepared" && state.status !== "available") {
+        throw new TypeError("prompt-suggestion state is invalid");
+    }
+    assertOwnedUiPromptSuggestionIdentity(state.identity);
+    if (state.status === "generating" && typeof state.settled !== "boolean") {
+        throw new TypeError("prompt-suggestion settlement state is invalid");
+    }
+    if (state.status === "prepared" || state.status === "available")
+        assertPromptSuggestionText(state.text, false);
+}
 export function assertOwnedUiSessionViewModel(view) {
     if (view.contractVersion !== OWNED_UI_CONTRACT_VERSION) {
         throw new TypeError("unsupported owned-UI contract version");
@@ -149,9 +219,7 @@ export function assertOwnedUiSessionViewModel(view) {
     assertOwnedUiStatusView(view.status);
     assertOwnedUiTerminalSurface(view.terminal);
     if (view.activeModel !== null) {
-        assertId(view.activeModel.providerId, "owned-UI provider id");
-        assertId(view.activeModel.modelId, "owned-UI model id");
-        assertBoundedText(view.activeModel.displayName, "owned-UI model display name", MAX_LABEL_LENGTH);
+        assertOwnedUiModelInfo(view.activeModel);
     }
     assertEnum(view.thinkingLevel, THINKING_LEVELS, "owned-UI thinking level");
     assertCollection(view.activeCommandIds, "owned-UI active commands", MAX_ACTIVE_COMMANDS);
@@ -210,7 +278,52 @@ export function assertOwnedUiTranscriptBlock(block) {
     assertNonNegativeInteger(block.revision, "owned-UI transcript block revision");
     assertOptionalText(block.title, "owned-UI transcript block title", MAX_LABEL_LENGTH);
     assertPossiblyEmptyText(block.text, "owned-UI transcript block text", MAX_TEXT_BYTES);
-    assertJsonValue(block.payload, "owned-UI transcript block payload", MAX_PAYLOAD_BYTES);
+    assertJsonValue(block.toolRendering === undefined ? block.payload : {
+        payload: block.payload, toolRendering: block.toolRendering,
+    }, "owned-UI transcript block payload", MAX_PAYLOAD_BYTES);
+    if (block.toolRendering !== undefined) {
+        if (block.kind !== "tool-call" && block.kind !== "tool-result")
+            throw new TypeError("owned-UI tool rendering requires a tool block");
+        assertJsonValue(block.toolRendering.arguments, "owned-UI tool arguments", MAX_PAYLOAD_BYTES);
+        if (block.toolRendering.unavailable !== undefined) {
+            assertBoundedText(block.toolRendering.unavailable, "owned-UI rendering fallback", MAX_MESSAGE_LENGTH);
+        }
+        if (block.toolRendering.result !== undefined) {
+            const result = block.toolRendering.result;
+            assertCollection(result.content, "owned-UI tool result parts", MAX_PAYLOAD_BYTES);
+            for (const part of result.content) {
+                if (part.type === "text") {
+                    assertIntegerInRange(part.start, 0, block.text.length, "owned-UI tool text start");
+                    assertIntegerInRange(part.end, part.start, block.text.length, "owned-UI tool text end");
+                }
+                else if (part.type === "image") {
+                    assertIntegerInRange(part.imageIndex, 0, (block.imageReferences?.length ?? 0) - 1, "owned-UI tool image index");
+                }
+                else
+                    throw new TypeError("owned-UI tool result part is invalid");
+            }
+        }
+    }
+    if (block.toolState !== undefined) {
+        if (block.kind !== "tool-call" && block.kind !== "tool-result")
+            throw new TypeError("owned-UI tool state requires a tool block");
+        if (typeof block.toolState.argsComplete !== "boolean")
+            throw new TypeError("owned-UI tool argument completion is invalid");
+        assertEnum(block.toolState.execution, TOOL_EXECUTIONS, "owned-UI tool execution state");
+        const settled = block.toolState.execution !== "pending" && block.toolState.execution !== "running";
+        if (settled !== (block.status === "finalized"))
+            throw new TypeError("owned-UI tool execution finality is inconsistent");
+    }
+    if (block.imageReferences !== undefined) {
+        assertCollection(block.imageReferences, "owned-UI transcript image references", 16);
+        for (const reference of block.imageReferences) {
+            assertId(reference.assetId, "owned-UI transcript image asset id");
+            if (!/^image\/[a-z0-9.+-]+$/i.test(reference.mimeType))
+                throw new TypeError("owned-UI transcript image MIME type is invalid");
+            assertIntegerInRange(reference.byteLength, 1, 20 * 1024 * 1024, "owned-UI transcript image byte length");
+            assertEnum(reference.source, IMAGE_REFERENCE_SOURCES, "owned-UI transcript image source");
+        }
+    }
 }
 export function assertOwnedUiEditorState(editor) {
     assertPossiblyEmptyText(editor.text, "owned-UI editor text", MAX_TEXT_BYTES);
@@ -306,6 +419,11 @@ export function assertOwnedUiDiagnostics(diagnostic) {
     if (typeof diagnostic.recoverable !== "boolean")
         throw new TypeError("owned-UI diagnostic recoverability is invalid");
 }
+function assertOwnedUiModelInfo(model) {
+    assertId(model.providerId, "owned-UI provider id");
+    assertId(model.modelId, "owned-UI model id");
+    assertBoundedText(model.displayName, "owned-UI model display name", MAX_LABEL_LENGTH);
+}
 function assertOwnedUiDialog(dialog) {
     assertId(dialog.id, "owned-UI dialog id");
     assertBoundedText(dialog.title, "owned-UI dialog title", MAX_LABEL_LENGTH);
@@ -356,6 +474,13 @@ function assertOptionalText(value, name, maximumBytes) {
         return;
     assertBoundedText(value, name, maximumBytes);
 }
+function assertPromptSuggestionText(value, allowEmpty) {
+    if (value === null)
+        return;
+    if (typeof value !== "string" || value.includes("\0") || (!allowEmpty && value.length === 0) || [...value].length >= 100) {
+        throw new TypeError("prompt-suggestion text is invalid");
+    }
+}
 function assertCollection(value, name, maximum) {
     if (!Array.isArray(value) || value.length > maximum)
         throw new RangeError(`${name} exceeds its maximum length`);

package/dist/{src/foundation/presentation-contracts → contracts/presentation}/index.d.ts

@@ -6,6 +6,14 @@ export interface PresentationComponentPort {
     setFocused?(focused: boolean): void;
     dispose?(): void;
 }
+/** A painted input surface in terminal coordinates (one-based, inclusive bounds). */
+export interface PresentationPointerSurface {
+    readonly component: PresentationComponentPort;
+    readonly columnStart: number;
+    readonly columnEnd: number;
+    readonly rowStart: number;
+    readonly rowEnd: number;
+}
 export interface PresentationEditorPort extends PresentationComponentPort {
     getText(): string;
     setText(text: string): void;

package/dist/{src/features → features}/launch/development-launch.js

@@ -8,8 +8,16 @@ export function resolveDevelopmentLaunchEnvironment(canonicalPackageRoot, releas
     const instanceId = selectedInstanceId
         ? createHash("sha256").update(selectedInstanceId).digest("hex").slice(0, 16)
         : randomUUID().replaceAll("-", "").slice(0, 16);
-    const developmentRoot = resolve(source[PRODUCT_IDENTITY.environment.developmentRoot]
-        ?? join(temporaryDirectory, PRODUCT_IDENTITY.state.developmentDirectory, checkoutId, releaseId, "instances", instanceId));
+    const checkoutRoot = resolve(temporaryDirectory, PRODUCT_IDENTITY.state.developmentDirectory, checkoutId);
+    const selectedDevelopmentRoot = source[PRODUCT_IDENTITY.environment.developmentRoot];
+    const developmentRoot = resolve(selectedDevelopmentRoot
+        ?? join(checkoutRoot, releaseId, "instances", instanceId));
+    // Rationale: runtime/data remain instance-isolated, but product settings are user
+    // preferences and must survive a fresh local launch (and a rebuilt candidate).
+    // An explicit development root retains its historical self-contained policy.
+    const persistentConfigDir = selectedDevelopmentRoot
+        ? join(developmentRoot, "config")
+        : join(checkoutRoot, "config");
     const dataDir = resolve(source[PRODUCT_IDENTITY.environment.dataDir] ?? join(developmentRoot, "data"));
     return {
         checkoutId,
@@ -19,7 +27,7 @@ export function resolveDevelopmentLaunchEnvironment(canonicalPackageRoot, releas
         environment: {
             ...source,
             [PRODUCT_IDENTITY.environment.developmentInstanceId]: instanceId,
-            [PRODUCT_IDENTITY.environment.configDir]: resolve(source[PRODUCT_IDENTITY.environment.configDir] ?? join(developmentRoot, "config")),
+            [PRODUCT_IDENTITY.environment.configDir]: resolve(source[PRODUCT_IDENTITY.environment.configDir] ?? persistentConfigDir),
             [PRODUCT_IDENTITY.environment.dataDir]: dataDir,
             [PRODUCT_IDENTITY.environment.runtimeDir]: resolve(source[PRODUCT_IDENTITY.environment.runtimeDir] ?? join(developmentRoot, "runtime")),
             [PRODUCT_IDENTITY.environment.databasePath]: resolve(source[PRODUCT_IDENTITY.environment.databasePath] ?? join(dataDir, PRODUCT_IDENTITY.endpoint.databaseFilename)),

package/dist/{src/features → features}/launch/index.d.ts

@@ -3,5 +3,4 @@ export * from "./initialize-profile.js";
 export * from "./intent.js";
 export * from "./profile-paths.js";
 export * from "./prepare-launch.js";
-export * from "./profiles.js";
 export * from "./runtime-selection.js";

package/dist/{src/features → features}/launch/index.js

@@ -3,5 +3,4 @@ export * from "./initialize-profile.js";
 export * from "./intent.js";
 export * from "./profile-paths.js";
 export * from "./prepare-launch.js";
-export * from "./profiles.js";
 export * from "./runtime-selection.js";