@timurproko/a1 0.1.8-dev.49ff83a → 0.1.8-dev.508

package/dist/ui/components/visible-hyperlinks.d.ts

@@ -0,0 +1,26 @@
+export interface VisibleHyperlinkRange {
+    readonly from: number;
+    readonly to: number;
+    readonly target: string;
+    readonly kind: "explicit" | "candidate";
+}
+export interface VisibleHyperlinkRow {
+    readonly ranges: readonly VisibleHyperlinkRange[];
+    /**
+     * Whether the row declares a terminal hyperlink of its own. Only a declared link gives the
+     * terminal per-cell link identity that moving the row can misattribute, so movement safety
+     * asks this rather than counting ranges: a candidate range is host-hover text such as
+     * `obj.method` or `./src/index.ts`, which ordinary code produces on nearly every row.
+     */
+    readonly hasExplicitLink: boolean;
+    /** False for unclosed links, malformed escapes, images, or row-moving controls. */
+    readonly replaySafe: boolean;
+    readonly width: number;
+    /** Paint identity includes labels, not just targets; it never changes source bytes. */
+    readonly signature: string;
+}
+/**
+ * Reads final visible row geometry without decorating text. Candidate ranges
+ * only invalidate host-hover paint; they never invent an explicit link target.
+ */
+export declare function readVisibleHyperlinks(line: string, widthOf?: (text: string) => number): VisibleHyperlinkRow;

package/dist/ui/components/visible-hyperlinks.js

@@ -0,0 +1,97 @@
+import { displayWidth } from "./text.js";
+/** Linear tokenization: a valid large OSC target must not exhaust the regular-expression engine's stack. */
+function* rowTokens(line) {
+    const oscBoundary = /[\u0007\u001b]/g;
+    for (let offset = 0; offset < line.length;) {
+        if (line.charCodeAt(offset) !== 27) {
+            const next = line.indexOf("\u001b", offset);
+            const end = next < 0 ? line.length : next;
+            yield line.slice(offset, end);
+            offset = end;
+            continue;
+        }
+        let end = offset + 1;
+        if (line[offset + 1] === "[") {
+            let cursor = offset + 2;
+            while (line.charCodeAt(cursor) >= 0x30 && line.charCodeAt(cursor) <= 0x3f)
+                cursor++;
+            while (line.charCodeAt(cursor) >= 0x20 && line.charCodeAt(cursor) <= 0x2f)
+                cursor++;
+            if (line.charCodeAt(cursor) >= 0x40 && line.charCodeAt(cursor) <= 0x7e)
+                end = cursor + 1;
+        }
+        else if (line[offset + 1] === "]") {
+            // Performance: search for one boundary, not a quantified alternation over the entire URI.
+            oscBoundary.lastIndex = offset + 2;
+            const boundary = oscBoundary.exec(line);
+            if (boundary?.[0] === "\u0007")
+                end = boundary.index + 1;
+            else if (boundary !== null && line[boundary.index + 1] === "\\")
+                end = boundary.index + 2;
+        }
+        yield line.slice(offset, end);
+        offset = end;
+    }
+}
+const SGR = /^\u001b\[[\d;:]*m$/u;
+const SEMANTIC_ZONE = /^\u001b\]133;[ABC](?:\u0007|\u001b\\)$/u;
+// Platform: this is a conservative cleanup detector, NOT a link-activation
+// parser. Hosts recognize URLs, domains and file-like labels without OSC 8.
+const CANDIDATE = /(?:[a-z][a-z\d+.-]*:\/\/[^\s<>"']+|www\.[^\s<>"']+|(?:[a-z]:[\\/]|\.{1,2}[\\/])[^\s<>"']+|[\p{L}\p{N}_-]+(?:\.\p{L}[\p{L}\p{N}_-]+)+(?:[\\/][^\s<>"']+)?)/giu;
+/**
+ * Reads final visible row geometry without decorating text. Candidate ranges
+ * only invalidate host-hover paint; they never invent an explicit link target.
+ */
+export function readVisibleHyperlinks(line, widthOf = displayWidth) {
+    const ranges = [];
+    let plain = "";
+    let column = 0;
+    let active;
+    let replaySafe = true;
+    const finish = () => {
+        if (active !== undefined && column > active.from) {
+            ranges.push({ from: active.from, to: column, target: active.target, kind: "explicit" });
+        }
+        active = undefined;
+    };
+    for (const token of rowTokens(line)) {
+        if (token.startsWith("\u001b")) {
+            const separator = token.startsWith("\u001b]8;") ? token.indexOf(";", 4) : -1;
+            if (separator !== -1) {
+                finish();
+                const target = token.slice(separator + 1, token.endsWith("\u0007") ? -1 : -2);
+                if (target)
+                    active = { from: column, target };
+            }
+            else if (!SGR.test(token) && !SEMANTIC_ZONE.test(token))
+                replaySafe = false;
+        }
+        else {
+            if (/[\u0000-\u001f\u007f]/u.test(token))
+                replaySafe = false;
+            plain += token;
+            column += widthOf(token);
+        }
+    }
+    if (active !== undefined) {
+        replaySafe = false;
+        finish();
+    }
+    for (const match of plain.matchAll(CANDIDATE)) {
+        const from = widthOf(plain.slice(0, match.index));
+        const to = from + widthOf(match[0]);
+        if (!ranges.some(range => from < range.to && to > range.from)) {
+            ranges.push({ from, to, target: match[0], kind: "candidate" });
+        }
+    }
+    ranges.sort((left, right) => left.from - right.from);
+    return {
+        ranges,
+        hasExplicitLink: ranges.some(range => range.kind === "explicit"),
+        replaySafe,
+        width: column,
+        // Rationale: a path with spaces or a wrapped host match may extend beyond
+        // the conservative candidate. Changes anywhere in that row invalidate it.
+        signature: ranges.length === 0 ? "" : JSON.stringify([ranges, plain]),
+    };
+}

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

@@ -0,0 +1,141 @@
+export declare const OWNED_UI_SETTINGS_VERSION = 6;
+export type OwnedUiSettingValue = string | number | boolean;
+export type OwnedUiSettingApplication = "live" | "restart";
+export interface OwnedUiSettingDeclaration {
+    readonly id: string;
+    /** Optional presentation label; the id remains the persistence key. */
+    readonly label?: string;
+    /** Optional settings-screen group for related owned controls. */
+    readonly section?: {
+        readonly id: string;
+        readonly title: string;
+    };
+    readonly description: string;
+    readonly application: OwnedUiSettingApplication;
+    readonly defaultValue: OwnedUiSettingValue;
+    readonly allowedValues: readonly OwnedUiSettingValue[];
+}
+/** Playback lengths the quit outro offers, in milliseconds. */
+export declare const QUIT_EFFECT_DURATIONS_MS: readonly number[];
+/**
+ * Every A1 setting, keyed by its id. The table is the one declaration: ids, defaults, and allowed
+ * values are read from it, and `OwnedSettingValueOf` derives each getter's type from it.
+ */
+export declare const OWNED_SETTING_DECLARATIONS: Readonly<{
+    readonly quitAnimation: Readonly<{
+        id: "quitAnimation";
+        label: "Exit animation";
+        section: Readonly<{
+            id: "generic";
+            title: "Generic";
+        }>;
+        description: "Play the quit effect when the session quits. Off returns to the terminal immediately.";
+        application: "live";
+        defaultValue: true;
+        allowedValues: readonly [true, false];
+    }>;
+    readonly scrollbarAppearance: Readonly<{
+        id: "scrollbarAppearance";
+        label: "Scrollbar mode";
+        section: Readonly<{
+            id: "scroll";
+            title: "Scroll";
+        }>;
+        description: "When the session transcript scrollbar is visible.";
+        application: "live";
+        defaultValue: "auto";
+        allowedValues: readonly ["auto", "always", "hidden"];
+    }>;
+    readonly scrollbarStyle: Readonly<{
+        id: "scrollbarStyle";
+        label: "Scrollbar style";
+        section: Readonly<{
+            id: "scroll";
+            title: "Scroll";
+        }>;
+        description: "Visual weight of the session transcript scrollbar.";
+        application: "live";
+        defaultValue: "thin";
+        allowedValues: readonly ["thin", "thick"];
+    }>;
+    readonly scrollbarSpeed: Readonly<{
+        id: "scrollbarSpeed";
+        label: "Speed";
+        section: Readonly<{
+            id: "scroll";
+            title: "Scroll";
+        }>;
+        description: "Distance moved by each session transcript wheel event.";
+        application: "live";
+        defaultValue: "normal";
+        allowedValues: readonly ["normal", "fast", "high"];
+    }>;
+    readonly promptHistoryEnabled: Readonly<{
+        id: "promptHistoryEnabled";
+        label: "Persistent history";
+        section: Readonly<{
+            id: "history";
+            title: "History";
+        }>;
+        description: "Retain reusable prompts across sessions. Applies on next start; disabling does not erase saved history or stop existing instances.";
+        application: "restart";
+        defaultValue: true;
+        allowedValues: readonly [true, false];
+    }>;
+    readonly promptHistoryMaxItems: Readonly<{
+        id: "promptHistoryMaxItems";
+        label: "History limit";
+        section: Readonly<{
+            id: "history";
+            title: "History";
+        }>;
+        description: "Maximum recent unique prompts after next start. Byte limits also apply; increasing the limit cannot restore pruned entries.";
+        application: "restart";
+        defaultValue: 100;
+        allowedValues: readonly [10, 20, 30, 40, 50, 60, 70, 80, 90, 100];
+    }>;
+    readonly quitEffect: Readonly<{
+        id: "quitEffect";
+        label: "Effect";
+        section: Readonly<{
+            id: "quit";
+            title: "Quit";
+        }>;
+        description: "Animation played over the last screen when the session quits.";
+        application: "live";
+        defaultValue: "fall";
+        allowedValues: readonly ["fall", "dissolve", "starburst", "waves"];
+    }>;
+    readonly quitEffectDurationMs: Readonly<{
+        id: "quitEffectDurationMs";
+        label: "Duration";
+        section: Readonly<{
+            id: "quit";
+            title: "Quit";
+        }>;
+        description: "Milliseconds the quit animation plays before the terminal is restored.";
+        application: "live";
+        defaultValue: 800;
+        allowedValues: readonly number[];
+    }>;
+    readonly promptSuggestions: Readonly<{
+        id: "promptSuggestions";
+        label: "Prompt suggestions";
+        section: Readonly<{
+            id: "agent";
+            title: "Agent";
+        }>;
+        description: "Predict likely next prompts with one additional background request using the selected model.";
+        application: "live";
+        defaultValue: true;
+        allowedValues: readonly [true, false];
+    }>;
+}>;
+export type OwnedSettingId = keyof typeof OWNED_SETTING_DECLARATIONS;
+/** The value type a setting's declaration allows: a literal union for a choice, `number` for a stepped range. */
+export type OwnedSettingValueOf<Id extends OwnedSettingId> = (typeof OWNED_SETTING_DECLARATIONS)[Id]["allowedValues"][number];
+/** The declarations in declaration order, for resolution, persistence, and the settings screen. */
+export declare const OWNED_UI_SETTING_DECLARATIONS: readonly OwnedUiSettingDeclaration[];
+export declare function isOwnedSettingId(id: string): id is OwnedSettingId;
+export declare function assertOwnedUiSettingDeclarations(declarations: readonly OwnedUiSettingDeclaration[]): void;
+export declare function findOwnedUiSettingDeclaration(declarations: readonly OwnedUiSettingDeclaration[], id: string): OwnedUiSettingDeclaration | null;

package/dist/ui/settings/declarations.js

@@ -0,0 +1,135 @@
+export const OWNED_UI_SETTINGS_VERSION = 6;
+const MAX_ID_LENGTH = 64;
+const ID_PATTERN = /^[a-z][a-z0-9]*(?:[A-Z][a-z0-9]*)*$/;
+/** Declared first so the settings screen opens on it; sections follow first-declaration order. */
+const GENERIC_SECTION = Object.freeze({ id: "generic", title: "Generic" });
+const SCROLL_SECTION = Object.freeze({ id: "scroll", title: "Scroll" });
+const QUIT_SECTION = Object.freeze({ id: "quit", title: "Quit" });
+/** Playback lengths the quit outro offers, in milliseconds. */
+export const QUIT_EFFECT_DURATIONS_MS = Object.freeze(Array.from({ length: 18 }, (_, index) => 300 + index * 100));
+/**
+ * Every A1 setting, keyed by its id. The table is the one declaration: ids, defaults, and allowed
+ * values are read from it, and `OwnedSettingValueOf` derives each getter's type from it.
+ */
+export const OWNED_SETTING_DECLARATIONS = Object.freeze({
+    quitAnimation: Object.freeze({
+        id: "quitAnimation",
+        label: "Exit animation",
+        section: GENERIC_SECTION,
+        description: "Play the quit effect when the session quits. Off returns to the terminal immediately.",
+        application: "live",
+        defaultValue: true,
+        allowedValues: Object.freeze([true, false]),
+    }),
+    scrollbarAppearance: Object.freeze({
+        id: "scrollbarAppearance",
+        label: "Scrollbar mode",
+        section: SCROLL_SECTION,
+        description: "When the session transcript scrollbar is visible.",
+        application: "live",
+        defaultValue: "auto",
+        allowedValues: Object.freeze(["auto", "always", "hidden"]),
+    }),
+    scrollbarStyle: Object.freeze({
+        id: "scrollbarStyle",
+        label: "Scrollbar style",
+        section: SCROLL_SECTION,
+        description: "Visual weight of the session transcript scrollbar.",
+        application: "live",
+        defaultValue: "thin",
+        allowedValues: Object.freeze(["thin", "thick"]),
+    }),
+    scrollbarSpeed: Object.freeze({
+        id: "scrollbarSpeed",
+        label: "Speed",
+        section: SCROLL_SECTION,
+        description: "Distance moved by each session transcript wheel event.",
+        application: "live",
+        defaultValue: "normal",
+        allowedValues: Object.freeze(["normal", "fast", "high"]),
+    }),
+    promptHistoryEnabled: Object.freeze({
+        id: "promptHistoryEnabled",
+        label: "Persistent history",
+        section: Object.freeze({ id: "history", title: "History" }),
+        description: "Retain reusable prompts across sessions. Applies on next start; disabling does not erase saved history or stop existing instances.",
+        application: "restart",
+        defaultValue: true,
+        allowedValues: Object.freeze([true, false]),
+    }),
+    promptHistoryMaxItems: Object.freeze({
+        id: "promptHistoryMaxItems",
+        label: "History limit",
+        section: Object.freeze({ id: "history", title: "History" }),
+        description: "Maximum recent unique prompts after next start. Byte limits also apply; increasing the limit cannot restore pruned entries.",
+        application: "restart",
+        defaultValue: 100,
+        allowedValues: Object.freeze([10, 20, 30, 40, 50, 60, 70, 80, 90, 100]),
+    }),
+    quitEffect: Object.freeze({
+        id: "quitEffect",
+        label: "Effect",
+        section: QUIT_SECTION,
+        description: "Animation played over the last screen when the session quits.",
+        application: "live",
+        defaultValue: "fall",
+        allowedValues: Object.freeze(["fall", "dissolve", "starburst", "waves"]),
+    }),
+    quitEffectDurationMs: Object.freeze({
+        id: "quitEffectDurationMs",
+        label: "Duration",
+        section: QUIT_SECTION,
+        description: "Milliseconds the quit animation plays before the terminal is restored.",
+        application: "live",
+        defaultValue: 800,
+        allowedValues: QUIT_EFFECT_DURATIONS_MS,
+    }),
+    promptSuggestions: Object.freeze({
+        id: "promptSuggestions",
+        label: "Prompt suggestions",
+        section: Object.freeze({ id: "agent", title: "Agent" }),
+        description: "Predict likely next prompts with one additional background request using the selected model.",
+        application: "live",
+        defaultValue: true,
+        allowedValues: Object.freeze([true, false]),
+    }),
+});
+/** The declarations in declaration order, for resolution, persistence, and the settings screen. */
+export const OWNED_UI_SETTING_DECLARATIONS = Object.freeze(Object.values(OWNED_SETTING_DECLARATIONS));
+export function isOwnedSettingId(id) {
+    return Object.hasOwn(OWNED_SETTING_DECLARATIONS, id);
+}
+export function assertOwnedUiSettingDeclarations(declarations) {
+    const seen = new Set();
+    for (const declaration of declarations) {
+        if (!ID_PATTERN.test(declaration.id) || declaration.id.length > MAX_ID_LENGTH) {
+            throw new Error(`owned UI setting id is not a bounded camelCase identifier: ${declaration.id}`);
+        }
+        if (seen.has(declaration.id))
+            throw new Error(`duplicate owned UI setting id: ${declaration.id}`);
+        seen.add(declaration.id);
+        if (declaration.label !== undefined && declaration.label.trim().length === 0) {
+            throw new Error(`owned UI setting has an empty label: ${declaration.id}`);
+        }
+        if (declaration.section !== undefined
+            && (declaration.section.id.trim().length === 0 || declaration.section.title.trim().length === 0)) {
+            throw new Error(`owned UI setting has an invalid section: ${declaration.id}`);
+        }
+        if (declaration.description.trim().length === 0) {
+            throw new Error(`owned UI setting has no description: ${declaration.id}`);
+        }
+        if (declaration.allowedValues.length === 0) {
+            throw new Error(`owned UI setting declares no allowed values: ${declaration.id}`);
+        }
+        const types = new Set(declaration.allowedValues.map(value => typeof value));
+        if (types.size !== 1) {
+            throw new Error(`owned UI setting mixes allowed value types: ${declaration.id}`);
+        }
+        if (!declaration.allowedValues.includes(declaration.defaultValue)) {
+            throw new Error(`owned UI setting default is not an allowed value: ${declaration.id}`);
+        }
+    }
+}
+export function findOwnedUiSettingDeclaration(declarations, id) {
+    return declarations.find(declaration => declaration.id === id) ?? null;
+}

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

@@ -0,0 +1,10 @@
+export { OWNED_SETTING_DECLARATIONS, OWNED_UI_SETTINGS_VERSION, OWNED_UI_SETTING_DECLARATIONS, QUIT_EFFECT_DURATIONS_MS, assertOwnedUiSettingDeclarations, findOwnedUiSettingDeclaration, isOwnedSettingId, } from "./declarations.js";
+export type { OwnedSettingId, OwnedSettingValueOf, OwnedUiSettingApplication, OwnedUiSettingDeclaration, OwnedUiSettingValue } from "./declarations.js";
+export { OWNED_UI_SETTINGS_MIGRATIONS, assertOwnedUiSettingsMigrations, migrationsFrom } from "./migrations.js";
+export type { OwnedUiSettingsMigration } from "./migrations.js";
+export { documentFrom, parseOwnedUiSettingsDocument, resolveOwnedUiSettings, settingValue } from "./resolution.js";
+export type { OwnedUiResolvedSetting, OwnedUiSettingSource, OwnedUiSettingsDocument, OwnedUiSettingsNotice, OwnedUiSettingsNoticeCode, OwnedUiSettingsResolution, ResolveOwnedUiSettingsInput, } from "./resolution.js";
+export { AGENT_SECTION_ID, buildOwnedUiSettingsSections, findOwnedUiSettingsEntry } from "./sections.js";
+export type { AgentSettingsSnapshot, BuildOwnedUiSettingsSectionsInput, OwnedUiSettingsBackend, OwnedUiSettingsEntry, OwnedUiSettingsSection, } from "./sections.js";
+export { OwnedSettingsManager } from "./manager.js";
+export type { OwnedSettingsManagerOptions, OwnedUiSettingsChangeOutcome, OwnedUiSettingsListener } from "./manager.js";

package/dist/ui/settings/index.js

@@ -0,0 +1,5 @@
+export { OWNED_SETTING_DECLARATIONS, OWNED_UI_SETTINGS_VERSION, OWNED_UI_SETTING_DECLARATIONS, QUIT_EFFECT_DURATIONS_MS, assertOwnedUiSettingDeclarations, findOwnedUiSettingDeclaration, isOwnedSettingId, } from "./declarations.js";
+export { OWNED_UI_SETTINGS_MIGRATIONS, assertOwnedUiSettingsMigrations, migrationsFrom } from "./migrations.js";
+export { documentFrom, parseOwnedUiSettingsDocument, resolveOwnedUiSettings, settingValue } from "./resolution.js";
+export { AGENT_SECTION_ID, buildOwnedUiSettingsSections, findOwnedUiSettingsEntry } from "./sections.js";
+export { OwnedSettingsManager } from "./manager.js";

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

@@ -0,0 +1,54 @@
+import type { AgentJsonValue, AgentSettingApplicationBoundary, AgentSettingsPort } from "../../contracts/agent-engine/index.js";
+import { type OwnedSettingId, type OwnedSettingValueOf, type OwnedUiSettingDeclaration, type OwnedUiSettingValue } from "./declarations.js";
+import { type OwnedUiSettingsMigration } from "./migrations.js";
+import { type OwnedUiSettingsResolution } from "./resolution.js";
+import { type OwnedUiSettingsBackend, type OwnedUiSettingsSection } from "./sections.js";
+export interface OwnedSettingsManagerOptions {
+    /** A1 configuration root. Settings live under `<configDir>/settings/`. */
+    readonly configDir: string;
+    readonly profileId: string;
+    readonly declarations?: readonly OwnedUiSettingDeclaration[];
+    readonly migrations?: readonly OwnedUiSettingsMigration[];
+    readonly agent?: AgentSettingsPort | null;
+    readonly agentProvider?: () => AgentSettingsPort | null;
+    readonly hiddenAgentSettingIds?: readonly string[];
+}
+export interface OwnedUiSettingsChangeOutcome {
+    readonly status: "applied" | "deferred" | "unavailable" | "failed";
+    readonly applied: boolean;
+    /** Compatibility projection for existing A1 restart-bound declarations. */
+    readonly pendingRestart: boolean;
+    readonly application: AgentSettingApplicationBoundary | null;
+    readonly storedValue: AgentJsonValue | null;
+    readonly effectiveValue: AgentJsonValue | null;
+    readonly limitationReason: string | null;
+    readonly failure: string | null;
+}
+export type OwnedUiSettingsListener = (manager: OwnedSettingsManager) => void;
+/**
+ * One profile's A1 settings: resolves the declaration table against the stored document,
+ * persists each accepted change atomically without discarding unknown keys, offers the
+ * grouped sections a surface presents, and routes every accepted change only to its
+ * owning backend, with agent settings reached through the engine settings port.
+ */
+export declare class OwnedSettingsManager {
+    #private;
+    constructor(options: OwnedSettingsManagerOptions);
+    get file(): string;
+    get resolution(): OwnedUiSettingsResolution;
+    /** Reads and resolves the stored document. Never throws: every failure becomes a notice. */
+    read(): OwnedUiSettingsResolution;
+    load(): Promise<void>;
+    sections(): readonly OwnedUiSettingsSection[];
+    /**
+     * The value in effect for a declared setting, typed by its declaration. A restart-bound
+     * setting reads as the value the session started with until the next start.
+     */
+    value<Id extends OwnedSettingId>(id: Id): OwnedSettingValueOf<Id>;
+    /** The value in effect for any setting id, or null when nothing declares it. */
+    valueOf(id: string): OwnedUiSettingValue | null;
+    pendingValue(id: string): OwnedUiSettingValue | null;
+    onChange(listener: OwnedUiSettingsListener): () => void;
+    changeStructured(backend: OwnedUiSettingsBackend, id: string, value: Readonly<Record<string, unknown>>): Promise<OwnedUiSettingsChangeOutcome>;
+    change(backend: OwnedUiSettingsBackend, id: string, value: OwnedUiSettingValue): Promise<OwnedUiSettingsChangeOutcome>;
+}