@timurproko/a1 0.1.8-dev.151 → 0.1.8-dev.182

package/dist/integrations/pi/session-ui/session-viewport-controller.js

@@ -1,4 +1,4 @@
-import { TranscriptViewport, routeMouseInput, scrollForTrackPage, scrollForThumbRow, scrollbarSelectionRows, scrollbarWheelRows, } from "../../../ui/components/index.js";
+import { TranscriptViewport, hyperlinkTargetAtColumn, routeMouseInput, scrollForTrackPage, scrollForThumbRow, scrollbarSelectionRows, scrollbarWheelRows, } from "../../../ui/components/index.js";
 /**
  * Owns the stateful interaction policy of the bare-A1 session viewport. The
  * shell root supplies semantic rows and dock geometry; this controller owns
@@ -24,6 +24,8 @@ export class SessionViewportController {
     #editorPointerFrame;
     #selectionAutoScrollTimer;
     #selectionAutoScrollPointer;
+    #pointerPosition;
+    #hoveredHyperlinkKey;
     #activityTimer;
     constructor(options) {
         this.#enabled = options.enabled;
@@ -45,7 +47,17 @@ export class SessionViewportController {
     }
     compose(input) {
         this.#viewport.setConfig(this.#config);
-        return this.#viewport.compose(input);
+        const frame = this.#viewport.compose(input);
+        if (this.#pointerPosition !== undefined && !this.#viewport.selectionActive && !this.#editorPointerSelecting) {
+            const next = this.#hyperlinkKeyAt(frame, this.#pointerPosition.column, this.#pointerPosition.row);
+            if (this.#hoveredHyperlinkKey !== undefined && next !== this.#hoveredHyperlinkKey) {
+                // Windows Terminal can leave its solid native-hover underline behind
+                // when a following viewport moves the link away from a stationary pointer.
+                this.#requestRender(true);
+            }
+            this.#hoveredHyperlinkKey = next;
+        }
+        return frame;
     }
     /** Returns true when document wrapping may have changed. */
     setConfig(config) {
@@ -76,6 +88,8 @@ export class SessionViewportController {
         this.#stopSelectionAutoScroll();
         this.#editorPointerSelecting = false;
         this.#editorPointerFrame = undefined;
+        this.#pointerPosition = undefined;
+        this.#hoveredHyperlinkKey = undefined;
         this.#viewport.reset();
     }
     clearPointerState() {
@@ -84,6 +98,8 @@ export class SessionViewportController {
         this.#dockPointerSuppressed = false;
         this.#editorPointerSelecting = false;
         this.#editorPointerFrame = undefined;
+        this.#pointerPosition = undefined;
+        this.#hoveredHyperlinkKey = undefined;
         this.#stopSelectionAutoScroll();
         this.#viewport.clearSelection();
         this.#viewport.clearTransient();
@@ -160,6 +176,16 @@ export class SessionViewportController {
             const overBottom = hits.bottom !== null && event.row === hits.bottom.row
                 && event.column >= hits.bottom.columnStart && event.column <= hits.bottom.columnEnd;
             if (event.kind === "motion") {
+                this.#pointerPosition = { column: event.column, row: event.row };
+                if (!this.#viewport.selectionActive && !this.#editorPointerSelecting) {
+                    const nextHyperlink = this.#hyperlinkKeyAt(frame, event.column, event.row);
+                    if (this.#hoveredHyperlinkKey !== undefined && nextHyperlink !== this.#hoveredHyperlinkKey) {
+                        // A forced redraw overwrites Windows Terminal's cached solid hover
+                        // underline exactly once when the pointer leaves or changes links.
+                        forceRepaint = true;
+                    }
+                    this.#hoveredHyperlinkKey = nextHyperlink;
+                }
                 this.#viewport.setRailHovered(overRail);
                 this.#viewport.setStickyHovered(overSticky);
                 this.#viewport.setBottomHovered(overBottom);
@@ -307,6 +333,12 @@ export class SessionViewportController {
             this.#requestRender(forceRepaint);
         return routed;
     }
+    #hyperlinkKeyAt(frame, column, row) {
+        if (row < 1 || row > frame.rows.length || column < 1)
+            return undefined;
+        const target = hyperlinkTargetAtColumn(frame.rows[row - 1] ?? "", column - 1);
+        return target === undefined ? undefined : `${row}\u0000${target}`;
+    }
     #updateSelectionAutoScroll(column, row, viewportHeight) {
         const beyondEdge = row <= 1 || row > viewportHeight;
         if (!beyondEdge) {

package/dist/integrations/pi/session-ui/system-clipboard.d.ts

@@ -1,4 +1,9 @@
 import type { PiShellClipboardContent } from "../components/index.js";
+export interface SystemClipboardImageReader {
+    hasImage(): boolean;
+    getImageBinary?(): Promise<readonly number[]>;
+    getImageBase64?(): Promise<string>;
+}
 /** Load the native adapter during shell startup so the first paste is warm. */
 export declare function preloadSystemClipboard(): void;
 /**
@@ -7,5 +12,9 @@ export declare function preloadSystemClipboard(): void;
  * unavailable clipboard simply makes the paste action a no-op.
  */
 export declare function readSystemClipboardContent(): Promise<PiShellClipboardContent | null>;
+export declare function readSystemClipboardImage(reader: SystemClipboardImageReader): Promise<{
+    readonly data: string;
+    readonly mimeType: string;
+} | null>;
 export declare function readSystemClipboardText(): Promise<string | null>;
 export declare function writeSystemClipboardText(text: string): Promise<void>;

package/dist/integrations/pi/session-ui/system-clipboard.js

@@ -1,4 +1,5 @@
 import { execFile } from "node:child_process";
+import { canonicalizeClipboardImage } from "./clipboard-image.js";
 const MAX_CLIPBOARD_BYTES = 16 * 1024 * 1024;
 let nativeClipboardPromise;
 let pendingClipboardWrite = Promise.resolve();
@@ -22,11 +23,9 @@ export async function readSystemClipboardContent() {
                 if (files !== null)
                     return { kind: "text", text: files };
             }
-            if (native.hasImage()) {
-                const data = await native.getImageBase64();
-                if (data.length > 0)
-                    return { kind: "image", data, mimeType: "image/png" };
-            }
+            const image = await readSystemClipboardImage(native);
+            if (image !== null)
+                return { kind: "image", ...image };
         }
         catch {
             // Fall through to text and platform readers.
@@ -35,6 +34,36 @@ export async function readSystemClipboardContent() {
     const text = await readSystemClipboardText();
     return text === null ? null : { kind: "text", text };
 }
+export async function readSystemClipboardImage(reader) {
+    if (!reader.hasImage())
+        return null;
+    if (reader.getImageBinary !== undefined) {
+        try {
+            const bytes = await reader.getImageBinary();
+            if (bytes.length > 0 && bytes.every(byte => Number.isInteger(byte) && byte >= 0 && byte <= 255)) {
+                return canonicalizeClipboardImage({
+                    data: Buffer.from(bytes).toString("base64"),
+                    mimeType: "image/png",
+                });
+            }
+        }
+        catch {
+            // Older or partially available native bindings may still expose base64.
+        }
+    }
+    if (reader.getImageBase64 !== undefined) {
+        try {
+            return canonicalizeClipboardImage({
+                data: await reader.getImageBase64(),
+                mimeType: "image/png",
+            });
+        }
+        catch {
+            // Fall through to the caller's text path.
+        }
+    }
+    return null;
+}
 export async function readSystemClipboardText() {
     // Ctrl+C/Ctrl+X and Ctrl+V can arrive in adjacent input turns. Serialize the
     // read behind our native write so paste never observes the previous value.

package/dist/integrations/pi/tui-runtime/adapter.d.ts

@@ -31,7 +31,11 @@ export declare class PiTuiRuntimeAdapter {
     switchMode(mode: "regular" | "fullscreen"): boolean;
     setHardwareCursor(enabled: boolean): void;
     getHardwareCursor(): boolean;
+    setClearOnShrink(enabled: boolean): void;
+    getClearOnShrink(): boolean;
+    setTerminalProgress(active: boolean): void;
     setTitle(title: string): void;
+    writeAfterStop(text: string): void;
     invalidate(): void;
     requestRender(force?: boolean): void;
     renderNow(force?: boolean): void;

package/dist/integrations/pi/tui-runtime/adapter.js

@@ -97,6 +97,7 @@ export class PiTuiRuntimeAdapter {
     #state = "idle";
     #stopPromise;
     #rootDisposed = false;
+    #terminalProgress = false;
     constructor(options) {
         this.#root = options.root;
         this.#terminal = options.terminal ?? new ProcessTerminal();
@@ -301,9 +302,26 @@ export class PiTuiRuntimeAdapter {
     getHardwareCursor() {
         return this.#tui.getShowHardwareCursor();
     }
+    setClearOnShrink(enabled) {
+        this.#tui.setClearOnShrink(enabled);
+    }
+    getClearOnShrink() {
+        return this.#tui.getClearOnShrink();
+    }
+    setTerminalProgress(active) {
+        if (this.#terminalProgress === active)
+            return;
+        this.#terminal.setProgress(active);
+        this.#terminalProgress = active;
+    }
     setTitle(title) {
         this.#terminal.setTitle(title);
     }
+    writeAfterStop(text) {
+        if (this.#state !== "stopped")
+            throw new Error("terminal output requires a stopped Pi TUI runtime");
+        this.#terminal.write(text);
+    }
     invalidate() {
         this.#tui.invalidate();
         if (this.active)
@@ -322,6 +340,7 @@ export class PiTuiRuntimeAdapter {
             return this.#stopPromise;
         if (this.#state === "idle") {
             this.#state = "stopped";
+            this.#clearTerminalProgress();
             this.#preInputListeners.clear();
             this.#disposeRoot();
             return Promise.resolve();
@@ -354,6 +373,7 @@ export class PiTuiRuntimeAdapter {
             this.#bestEffortTerminalRestore();
         }
         finally {
+            this.#clearTerminalProgress();
             this.#disposeComponents();
         }
         this.#state = failure === undefined ? "stopped" : "failed";
@@ -459,7 +479,15 @@ export class PiTuiRuntimeAdapter {
             this.#bestEffortTerminalRestore();
         }
     }
+    #clearTerminalProgress() {
+        try {
+            this.#terminal.setProgress(false);
+        }
+        catch { }
+        this.#terminalProgress = false;
+    }
     #bestEffortTerminalRestore() {
+        this.#clearTerminalProgress();
         try {
             this.#terminal.showCursor();
         }

package/dist/native/darwin-arm64/manifest.json

@@ -5,7 +5,7 @@
   "platform": "darwin",
   "architecture": "arm64",
   "capability": "unsupported",
-  "builtAt": "2026-08-28T10:16:08.776Z",
+  "builtAt": "2026-08-28T18:22:44.284Z",
   "artifact": {
     "filename": "process-guardian",
     "sha256": "7524bf568992517f50ed53196c861c5edeba0d7275633bb4735ab45bd5963a28",

package/dist/native/linux-x64/manifest.json

@@ -5,7 +5,7 @@
   "platform": "linux",
   "architecture": "x64",
   "capability": "supported",
-  "builtAt": "2026-08-28T10:16:08.593Z",
+  "builtAt": "2026-08-28T18:22:55.678Z",
   "artifact": {
     "filename": "process-guardian",
     "sha256": "ee8a00eaaf79c707459bbbfb52518e9739314967049fbe5fa625f36ce33db9ee",

package/dist/native/win32-x64/manifest.json

@@ -5,10 +5,10 @@
   "platform": "win32",
   "architecture": "x64",
   "capability": "supported",
-  "builtAt": "2026-08-28T10:16:41.229Z",
+  "builtAt": "2026-08-28T18:23:19.899Z",
   "artifact": {
     "filename": "process-guardian.exe",
-    "sha256": "8daa77c737ea8f96eb022fce63a25a4fce3e5d15c409201712a7f36853c8e8e4",
+    "sha256": "20d36267095f117000abb65e7e2edf9c2a6bd300ee2bd6368b544d823017e5c9",
     "size": 177664
   },
   "provenance": {

package/dist/ui/components/spans.d.ts

@@ -12,6 +12,8 @@ export declare function overlaySpan(line: string, from: number, to: number, span
  */
 /** Wraps visible columns `[from,to)` in an explicit OSC 8 hyperlink. */
 export declare function hyperlinkSgrSpan(line: string, from: number, to: number, target: string, widthOf?: (text: string) => number): string;
+/** Returns the OSC 8 target painted at a zero-based visible terminal column. */
+export declare function hyperlinkTargetAtColumn(line: string, targetColumn: number, widthOf?: (text: string) => number): string | undefined;
 /**
  * Gives existing and bare web links explicit, tightly bounded OSC 8 regions so
  * the terminal owns dotted-idle/solid-hover decoration without leaking hover

package/dist/ui/components/spans.js

@@ -93,6 +93,31 @@ export function hyperlinkSgrSpan(line, from, to, target, widthOf = displayWidth)
         output += off;
     return output;
 }
+/** Returns the OSC 8 target painted at a zero-based visible terminal column. */
+export function hyperlinkTargetAtColumn(line, targetColumn, widthOf = displayWidth) {
+    if (targetColumn < 0)
+        return undefined;
+    let hyperlinkTarget;
+    let column = 0;
+    for (const token of line.split(ANSI_SPLIT)) {
+        if (!token)
+            continue;
+        const link = HYPERLINK.exec(token);
+        if (link) {
+            hyperlinkTarget = (link[1] ?? "") || undefined;
+            continue;
+        }
+        if (token.startsWith("\u001b"))
+            continue;
+        for (const { segment } of GRAPHEMES.segment(token)) {
+            const width = widthOf(segment);
+            if (targetColumn >= column && targetColumn < column + width)
+                return hyperlinkTarget;
+            column += width;
+        }
+    }
+    return undefined;
+}
 /**
  * Gives existing and bare web links explicit, tightly bounded OSC 8 regions so
  * the terminal owns dotted-idle/solid-hover decoration without leaking hover

package/dist/ui/components/text.js

@@ -7,6 +7,15 @@
 const ANSI_PATTERN = /\[[0-9;:?]*[ -/]*[@-~]|\][^]*(?:|\\)|[@-Z\\-_]/g;
 const SEGMENTER = new Intl.Segmenter(undefined, { granularity: "grapheme" });
 const WORD_SEGMENTER = new Intl.Segmenter(undefined, { granularity: "word" });
+/**
+ * Recommended-for-general-interchange emoji. Terminals give every one of these
+ * two columns wherever its code points sit, so the wide blocks in
+ * `codePointWidth` cannot carry the measurement alone: a lone U+26A1 or any
+ * U+FE0F presentation sequence escapes them and would measure one column short.
+ */
+const RGI_EMOJI_PATTERN = /^\p{RGI_Emoji}$/v;
+/** Columns a terminal advances for a tab, matching the host runtime. */
+const TAB_WIDTH = 3;
 /** Removes styling sequences so only visible characters remain. */
 export function stripAnsi(text) {
     return text.replace(ANSI_PATTERN, "");
@@ -50,13 +59,26 @@ function codePointWidth(codePoint) {
         return 2;
     if (codePoint >= 0x20000 && codePoint <= 0x3fffd)
         return 2;
-    // Control characters occupy nothing.
+    // A tab advances to the host runtime's stop; other control characters occupy nothing.
+    if (codePoint === 0x09)
+        return TAB_WIDTH;
     if (codePoint < 0x20 || (codePoint >= 0x7f && codePoint < 0xa0))
         return 0;
     return 1;
 }
-/** Width of one grapheme cluster: the widest code point it contains, marks excluded. */
+/** Cheap pre-filter: only clusters that could be emoji pay for the RGI test. */
+function couldBeEmoji(grapheme) {
+    const codePoint = grapheme.codePointAt(0) ?? 0;
+    return ((codePoint >= 0x1f000 && codePoint <= 0x1fbff) ||
+        (codePoint >= 0x2300 && codePoint <= 0x23ff) ||
+        (codePoint >= 0x2600 && codePoint <= 0x27bf) ||
+        (codePoint >= 0x2b00 && codePoint <= 0x2bff) ||
+        grapheme.length > 1);
+}
+/** Width of one grapheme cluster: two for emoji, else the widest code point it contains. */
 function graphemeWidth(grapheme) {
+    if (couldBeEmoji(grapheme) && RGI_EMOJI_PATTERN.test(grapheme))
+        return 2;
     let width = 0;
     for (const character of grapheme) {
         width = Math.max(width, codePointWidth(character.codePointAt(0) ?? 0));

package/dist/ui/settings/sections.d.ts

@@ -1,3 +1,4 @@
+import type { AgentSettingApplicationBoundary, AgentSettingDescriptor } from "../../contracts/agent-engine/index.js";
 import type { OwnedUiSettingValue } from "./declarations.js";
 import type { OwnedUiSettingsResolution } from "./resolution.js";
 export type OwnedUiSettingsBackend = "a1" | "agent";
@@ -9,9 +10,13 @@ export interface OwnedUiSettingsEntry {
     readonly description: string | null;
     /** Present when the value is a scalar the surface can offer as a choice. */
     readonly value: OwnedUiSettingValue | null;
-    /** Raw value as reported by its backend, for entries the surface can only display. */
+    /** Raw stored value as reported by its backend, for entries the surface can only display. */
     readonly rawValue: unknown;
+    readonly storedValue: unknown;
+    readonly effectiveValue: unknown;
     readonly editable: boolean;
+    readonly available: boolean;
+    readonly limitationReason: string | null;
     readonly choices: readonly OwnedUiSettingValue[] | null;
     /** True when the value is a structured object edited through its own surface. */
     readonly structured: boolean;
@@ -26,7 +31,7 @@ export interface OwnedUiSettingsEntry {
         readonly fallback: boolean;
     }[];
     readonly origin: "default" | "stored" | "engine";
-    readonly application: "live" | "restart" | "engine";
+    readonly application: AgentSettingApplicationBoundary;
 }
 export interface OwnedUiSettingsSection {
     readonly id: string;
@@ -38,23 +43,7 @@ export interface OwnedUiSettingsSection {
     readonly readOnlyReason: string | null;
 }
 export interface AgentSettingsSnapshot {
-    readonly descriptors: readonly {
-        readonly key: string;
-        readonly valueType: "boolean" | "number" | "string" | "enum" | "json";
-        readonly writable: boolean;
-        readonly choices?: readonly unknown[];
-        readonly label?: string;
-        readonly description?: string;
-        readonly minimum?: number;
-        readonly maximum?: number;
-        readonly flags?: readonly {
-            readonly key: string;
-            readonly label: string;
-            readonly description: string;
-            readonly fallback: boolean;
-        }[];
-    }[];
-    readonly values: Readonly<Record<string, unknown>>;
+    readonly descriptors: readonly AgentSettingDescriptor[];
     /** Whether the engine advertises settings write capability at all. */
     readonly writeAdvertised: boolean;
     /** Set when the engine could not report its settings. */

package/dist/ui/settings/sections.js

@@ -12,14 +12,18 @@ export function buildOwnedUiSettingsSections(input) {
             description: setting.declaration.description,
             value: setting.value,
             rawValue: setting.value,
+            storedValue: setting.value,
+            effectiveValue: setting.value,
             editable: true,
+            available: true,
+            limitationReason: null,
             structured: false,
             minimum: null,
             maximum: null,
             flags: [],
             choices: setting.declaration.allowedValues,
             origin: setting.source,
-            application: setting.declaration.application,
+            application: setting.declaration.application === "restart" ? "next-start" : "live",
         });
         grouped.set(section.id, group);
     }
@@ -51,7 +55,7 @@ function agentSection(snapshot) {
         return frozenSection("The agent engine reported no settings", null, []);
     }
     const entries = snapshot.descriptors.map(descriptor => {
-        const raw = Object.hasOwn(snapshot.values, descriptor.key) ? snapshot.values[descriptor.key] : null;
+        const raw = descriptor.storedValue;
         return {
             id: descriptor.key,
             label: descriptor.label ?? null,
@@ -59,9 +63,13 @@ function agentSection(snapshot) {
             description: descriptor.description ?? null,
             value: scalar(raw),
             rawValue: raw,
+            storedValue: descriptor.storedValue,
+            effectiveValue: descriptor.effectiveValue,
+            available: descriptor.available,
+            limitationReason: descriptor.limitationReason,
             // A structured value is editable through its own surface rather than a
             // value menu, so it stays reachable instead of being reported as fixed.
-            editable: snapshot.writeAdvertised && descriptor.writable,
+            editable: snapshot.writeAdvertised && descriptor.writable && descriptor.available,
             structured: descriptor.valueType === "json",
             minimum: descriptor.minimum ?? null,
             maximum: descriptor.maximum ?? null,
@@ -70,7 +78,7 @@ function agentSection(snapshot) {
             // so it opens the same menu as any other enumerated setting.
             choices: descriptor.valueType === "boolean" ? BOOLEAN_CHOICES : choicesOf(descriptor.choices),
             origin: "engine",
-            application: "engine",
+            application: descriptor.application,
         };
     });
     const readOnlyReason = snapshot.writeAdvertised

package/dist/ui/settings/session.d.ts

@@ -1,46 +1,36 @@
-import type { AgentSettingsPort } from "../../contracts/agent-engine/index.js";
+import type { AgentJsonValue, AgentSettingApplicationBoundary, AgentSettingsPort } from "../../contracts/agent-engine/index.js";
 import type { OwnedUiSettingValue } from "./declarations.js";
 import type { OwnedUiSettingsResolution } from "./resolution.js";
 import { type OwnedUiSettingsBackend, type OwnedUiSettingsSection } from "./sections.js";
 import type { OwnedUiSettingsStore } from "./store.js";
 export interface OwnedUiSettingsChangeOutcome {
+    readonly status: "applied" | "deferred" | "unavailable" | "failed";
     readonly applied: boolean;
-    /** True when the value is stored but only takes effect on the next start. */
+    /** Compatibility projection for existing A1 restart-bound declarations. */
     readonly pendingRestart: boolean;
-    /** Present when the change could not be persisted; the surface must not show it as saved. */
+    readonly application: AgentSettingApplicationBoundary | null;
+    readonly storedValue: AgentJsonValue | null;
+    readonly effectiveValue: AgentJsonValue | null;
+    readonly limitationReason: string | null;
     readonly failure: string | null;
 }
 export interface OwnedUiSettingsSessionOptions {
     readonly store: OwnedUiSettingsStore;
-    /** Null when no engine is attached; the Agent section then reports itself unavailable. */
     readonly agent?: AgentSettingsPort | null;
-    /**
-     * Resolves the port at load time instead of construction time, for an engine
-     * whose runtime is not up yet. Takes precedence over `agent`.
-     */
     readonly agentProvider?: () => AgentSettingsPort | null;
-    /** Agent-owned controls fixed by this product surface and therefore omitted. */
     readonly hiddenAgentSettingIds?: readonly string[];
 }
 export type OwnedUiSettingsListener = (session: OwnedUiSettingsSession) => void;
-/**
- * Holds the resolved settings for one owned UI session and routes every accepted
- * change to the backend that owns it: A1 settings to the A1 document, agent
- * settings to the engine settings port. Neither backend ever sees the other's value.
- */
+/** Routes every accepted setting change only to its owning backend. */
 export declare class OwnedUiSettingsSession {
     #private;
     constructor(options: OwnedUiSettingsSessionOptions);
     get resolution(): OwnedUiSettingsResolution;
-    /** Reads the engine's settings so the Agent section can be built. Never throws. */
     load(): Promise<void>;
     sections(): readonly OwnedUiSettingsSection[];
-    /** Resolved value of an A1 setting, or null when it is not declared. */
     value(id: string): OwnedUiSettingValue | null;
-    /** Value stored this session but not yet in effect, for a restart-required setting. */
     pendingValue(id: string): OwnedUiSettingValue | null;
     onChange(listener: OwnedUiSettingsListener): () => void;
-    /** Writes a structured value, which only an engine-backed setting can hold. */
     changeStructured(backend: OwnedUiSettingsBackend, id: string, value: Readonly<Record<string, unknown>>): Promise<OwnedUiSettingsChangeOutcome>;
     change(backend: OwnedUiSettingsBackend, id: string, value: OwnedUiSettingValue): Promise<OwnedUiSettingsChangeOutcome>;
 }