@timurproko/a1 0.2.7-dev.1249 → 0.2.7-dev.1255

package/dist/foundation/resident-tabs/maintenance.d.ts

@@ -1,39 +0,0 @@
-import { type TerminalHostCommand } from "./ensure-terminal-host.js";
-export type MaintenanceAction = "list" | "stop" | "stop-all" | "host-status" | "host-stop" | "runtime-control";
-export type MaintenanceHostState = "none" | "running" | "stopped" | "unresponsive" | "incompatible" | "refused" | "unverifiable" | "unavailable";
-/** The versioned `a1 tabs` report: `a1-tabs-maintenance-v1`, as printed by the terminal host. */
-export interface MaintenanceReport {
-    readonly schema: "a1-tabs-maintenance-v1";
-    readonly command: string;
-    readonly host: MaintenanceHostState;
-    readonly stateDir?: string;
-    readonly result?: Record<string, unknown>;
-    readonly pid?: number;
-    readonly message?: string;
-    readonly releaseRoot?: string | null;
-    readonly terminatedUnresponsive?: number;
-    /** The terminal host's exit status: 0 success, 3 refused or failed, 4 another generation. */
-    readonly exitCode: number;
-}
-export interface MaintenanceOptions {
-    readonly action: MaintenanceAction;
-    readonly tabId?: string;
-    readonly profileRoot: string;
-    readonly dataDir: string;
-    readonly runtimeDir: string;
-    /** The first root is the invoking release; other roots never substitute for it. */
-    readonly releaseRoots: readonly string[];
-    readonly environment: NodeJS.ProcessEnv;
-    readonly platform?: NodeJS.Platform;
-    readonly architecture?: string;
-    readonly timeoutMs?: number;
-    readonly verify?: (addon: string, platform: NodeJS.Platform, architecture: string) => Promise<unknown>;
-    readonly run?: (command: TerminalHostCommand, arguments_: readonly string[], timeoutMs: number) => Promise<{
-        readonly code: number;
-        readonly stdout: string;
-    }>;
-}
-/** Runs maintenance only through the invoking release; another cohort is never a retry target. */
-export declare function runTerminalHostMaintenance(options: MaintenanceOptions): Promise<MaintenanceReport>;
-/** The largest maintenance report accepted from the terminal host. */
-export declare const MAX_MAINTENANCE_REPORT_BYTES: number;

package/dist/foundation/resident-tabs/maintenance.js

@@ -1,75 +0,0 @@
-import { constants } from "node:fs";
-import { access } from "node:fs/promises";
-import { PRODUCT_IDENTITY } from "../../product-identity.js";
-import { runBoundedHostCommand } from "./bounded-host-command.js";
-import { resolveTerminalHostEntryPath, resolveTerminalHostPath } from "./ensure-terminal-host.js";
-import { verifyTerminalHostArtifact } from "./terminal-host-artifact.js";
-/** Runs maintenance only through the invoking release; another cohort is never a retry target. */
-export async function runTerminalHostMaintenance(options) {
-    const platform = options.platform ?? process.platform;
-    const architecture = options.architecture ?? process.arch;
-    const command = await firstVerifiedHost(options, options.releaseRoots.slice(0, 1), platform, architecture);
-    if (command === undefined)
-        return unavailable(options.action, "the invoking release has no verified terminal host");
-    return await invoke(options, command);
-}
-function arguments_(options) {
-    const command = options.action === "stop" ? ["stop", options.tabId ?? ""] : [options.action];
-    return ["tabs", ...command, "--profile", options.profileRoot, "--data-dir", options.dataDir, "--runtime-dir", options.runtimeDir];
-}
-async function invoke(options, command) {
-    const timeoutMs = options.timeoutMs ?? 120_000;
-    try {
-        const run = options.run ?? ((host, argumentsValue, limit) => runHost(host, argumentsValue, limit, options.environment));
-        const result = await run(command, arguments_(options), timeoutMs);
-        const line = result.stdout.trim().split(/\r?\n/u).at(-1) ?? "";
-        const parsed = JSON.parse(line);
-        if (parsed.schema !== "a1-tabs-maintenance-v1" || typeof parsed.host !== "string")
-            throw new Error("malformed maintenance report");
-        return { ...parsed, exitCode: result.code };
-    }
-    catch (error) {
-        return unavailable(options.action, `terminal host maintenance failed: ${error instanceof Error ? error.message : String(error)}`);
-    }
-}
-async function firstVerifiedHost(options, roots, platform, architecture) {
-    const override = options.environment[PRODUCT_IDENTITY.environment.developmentInstanceId]
-        ? options.environment[PRODUCT_IDENTITY.environment.terminalHostPath]?.trim()
-        : undefined;
-    if (override) {
-        const entry = roots[0] === undefined ? undefined : resolveTerminalHostEntryPath(roots[0]);
-        if (entry === undefined)
-            return undefined;
-        try {
-            await Promise.all([access(override, constants.R_OK), access(entry, constants.R_OK)]);
-            return { executable: process.execPath, entry };
-        }
-        catch {
-            return undefined;
-        }
-    }
-    for (const root of roots) {
-        const addon = resolveTerminalHostPath(root, {}, platform, architecture);
-        try {
-            await (options.verify ?? verifyTerminalHostArtifact)(addon, platform, architecture);
-            return { executable: process.execPath, entry: resolveTerminalHostEntryPath(root) };
-        }
-        catch {
-            // Invariant: a missing or altered invoking artifact fails closed.
-        }
-    }
-    return undefined;
-}
-function unavailable(action, message) {
-    return { schema: "a1-tabs-maintenance-v1", command: action, host: "unavailable", message, exitCode: 3 };
-}
-/** The largest maintenance report accepted from the terminal host. */
-export const MAX_MAINTENANCE_REPORT_BYTES = 4 * 1024 * 1024;
-async function runHost(command, arguments_, timeoutMs, environment) {
-    return await runBoundedHostCommand(command, arguments_, {
-        environment,
-        maxStdoutBytes: MAX_MAINTENANCE_REPORT_BYTES,
-        timeoutMs,
-        label: "terminal host maintenance",
-    });
-}

package/dist/foundation/resident-tabs/progress-observation-schema.d.ts

@@ -1,34 +0,0 @@
-/** Payload-free fixture schema; type-only imports keep it outside the evaluated startup graph. */
-export type ResidentInputPhase = "receipt" | "semantic-start" | "semantic-end" | "composition-start" | "composition-end" | "write-start" | "write-end";
-export interface ProgressFields {
-    readonly eventSequence?: number;
-    readonly revision?: number;
-    readonly geometryGeneration?: number;
-    readonly bytes?: number;
-    readonly count?: number;
-    readonly eventKind?: string;
-    readonly frameId?: number;
-    readonly renderCause?: string;
-    readonly fragmentCount?: number;
-    readonly transactionKind?: "synchronized-output" | "ordinary";
-}
-export interface ProgressRecord extends ProgressFields {
-    readonly schema: "a1-resident-progress-observation-v1";
-    readonly runId: string;
-    readonly role: "child";
-    readonly stage: "engine-delivery" | "child-render-write" | "child-input-phase";
-    readonly pid: number;
-    readonly processInstance: string;
-    readonly timestampUnixUs: number;
-    readonly clockErrorUs: number;
-    readonly sequence: number;
-    readonly tabId: string;
-    readonly incarnation: number;
-    readonly lostBefore: number;
-}
-export interface ResidentProgressObserverPort {
-    readonly tabId: string;
-    engineDelivery(event: unknown): void;
-    inputPhase?(phase: ResidentInputPhase, revision: number): void;
-    childRenderWrite(bytes: number, fragments: number, transaction: "synchronized-output" | "ordinary", frameId?: number, renderCause?: string): void;
-}

package/dist/foundation/resident-tabs/progress-observation-schema.js

@@ -1 +0,0 @@
-export {};

package/dist/foundation/resident-tabs/progress-observation.d.ts

@@ -1,4 +0,0 @@
-import type { ResidentProgressObserverPort } from "./progress-observation-schema.js";
-export type { ResidentProgressObserverPort } from "./progress-observation-schema.js";
-/** Opt-in payload-free child observer; ordinary launches return null. */
-export declare function residentProgressObserver(environment?: NodeJS.ProcessEnv): ResidentProgressObserverPort | null;

package/dist/foundation/resident-tabs/progress-observation.js

@@ -1,150 +0,0 @@
-import { randomUUID } from "node:crypto";
-import { appendFile, mkdir } from "node:fs/promises";
-import { join } from "node:path";
-import { performance } from "node:perf_hooks";
-import { PRODUCT_IDENTITY } from "../../product-identity.js";
-const OBSERVATION_DIRECTORY_ENV = PRODUCT_IDENTITY.environment.residentProgressObservationDir;
-const OBSERVATION_RUN_ENV = PRODUCT_IDENTITY.environment.residentProgressRunId;
-const MAX_PENDING_BYTES = 256 * 1024;
-class ResidentProgressObserver {
-    #directory;
-    #runId;
-    #tabId;
-    #incarnation;
-    #processInstance;
-    #path;
-    #sequence = 0;
-    #engineSequence = 0;
-    #pendingBytes = 0;
-    #lost = 0;
-    #writing = false;
-    #pending = [];
-    #scheduled = false;
-    #directoryReady = false;
-    #failed = false;
-    get tabId() { return this.#tabId; }
-    constructor(directory, runId, tabId, incarnation) {
-        this.#directory = directory;
-        this.#runId = runId;
-        this.#tabId = tabId;
-        this.#incarnation = incarnation;
-        this.#processInstance = `${process.pid}-${randomUUID()}`;
-        this.#path = join(directory, `child-${this.#processInstance}.jsonl`);
-    }
-    engineDelivery(event) {
-        this.#engineSequence += 1;
-        this.#observe("engine-delivery", {
-            eventSequence: this.#engineSequence,
-            eventKind: eventKind(event),
-            count: 1,
-        });
-    }
-    inputPhase(phase, revision) {
-        this.#observe("child-input-phase", { eventKind: phase, revision, count: 1 });
-    }
-    childRenderWrite(bytes, fragments, transaction, frameId, renderCause) {
-        this.#observe("child-render-write", {
-            eventSequence: this.#engineSequence,
-            bytes,
-            count: 1,
-            fragmentCount: fragments,
-            transactionKind: transaction,
-            ...(frameId === undefined ? {} : { frameId }),
-            ...(renderCause === undefined ? {} : { renderCause }),
-        });
-    }
-    #observe(stage, fields) {
-        if (this.#failed)
-            return;
-        const lostBefore = this.#lost;
-        const record = {
-            schema: "a1-resident-progress-observation-v1",
-            runId: this.#runId,
-            role: "child",
-            stage,
-            pid: process.pid,
-            processInstance: this.#processInstance,
-            timestampUnixUs: Math.round((performance.timeOrigin + performance.now()) * 1_000),
-            // Rationale: epoch-calibrated timeOrigin retains conservative cross-process clock error.
-            clockErrorUs: 1_000,
-            sequence: ++this.#sequence,
-            tabId: this.#tabId,
-            incarnation: this.#incarnation,
-            lostBefore,
-            ...fields,
-        };
-        const line = `${JSON.stringify(record)}\n`;
-        const length = Buffer.byteLength(line);
-        if (this.#pendingBytes + length > MAX_PENDING_BYTES) {
-            this.#lost = lostBefore + 1;
-            return;
-        }
-        this.#lost = 0;
-        this.#pendingBytes += length;
-        this.#pending.push(line);
-        this.#schedule();
-    }
-    #schedule() {
-        if (this.#scheduled || this.#writing || this.#failed)
-            return;
-        this.#scheduled = true;
-        // Performance: check-phase batches yield to input and amortize file opens and promises.
-        setImmediate(() => { this.#scheduled = false; void this.#flush(); });
-    }
-    async #flush() {
-        if (this.#failed || this.#pending.length === 0)
-            return;
-        this.#writing = true;
-        const batch = this.#pending.join("");
-        this.#pending = [];
-        // Rationale: cap pending only.
-        this.#pendingBytes = 0;
-        try {
-            if (!this.#directoryReady) {
-                await mkdir(this.#directory, { recursive: true });
-                this.#directoryReady = true;
-            }
-            await appendFile(this.#path, batch, "utf8");
-        }
-        catch {
-            this.#failed = true;
-            this.#pending = [];
-        }
-        finally {
-            this.#writing = false;
-            if (this.#pending.length > 0)
-                this.#schedule();
-        }
-    }
-}
-let observer;
-/** Opt-in payload-free child observer; ordinary launches return null. */
-export function residentProgressObserver(environment = process.env) {
-    if (environment === process.env && observer !== undefined)
-        return observer;
-    const directory = environment[OBSERVATION_DIRECTORY_ENV];
-    const runId = environment[OBSERVATION_RUN_ENV];
-    const tabId = environment[PRODUCT_IDENTITY.environment.residentProgressTabId];
-    const incarnation = Number(environment[PRODUCT_IDENTITY.environment.residentProgressTabIncarnation]);
-    const value = directory && runId && runId.length <= 128 && tabId && Number.isSafeInteger(incarnation) && incarnation >= 0
-        ? new ResidentProgressObserver(directory, runId, tabId, incarnation)
-        : null;
-    if (environment === process.env) {
-        observer = value;
-        // Security: keep evidence paths and identity private; erase them before extensions/tools inherit env.
-        for (const name of [
-            OBSERVATION_DIRECTORY_ENV,
-            OBSERVATION_RUN_ENV,
-            PRODUCT_IDENTITY.environment.residentProgressTabId,
-            PRODUCT_IDENTITY.environment.residentProgressTabIncarnation,
-        ])
-            delete process.env[name];
-    }
-    return value;
-}
-function eventKind(event) {
-    if (typeof event !== "object" || event === null)
-        return "unknown";
-    const value = event.type;
-    return typeof value === "string" && /^[a-z][a-z0-9_-]{0,63}$/iu.test(value) ? value : "unknown";
-}

package/dist/foundation/resident-tabs/prompt-journal.d.ts

@@ -1,63 +0,0 @@
-import { ResidentTabFaultInjection } from "./fault-injection.js";
-export interface SubmittedPromptRecord {
-    readonly type: "submitted";
-    readonly id: string;
-    readonly sessionId: string;
-    readonly sessionFile: string | null;
-    readonly incarnation: number;
-    readonly fileExisted: boolean;
-    readonly kind: "prompt" | "steer" | "follow-up";
-    readonly text: string;
-    readonly at: string;
-}
-export interface CorrelatedPromptRecord {
-    readonly type: "correlated";
-    readonly id: string;
-    readonly entryId: string;
-}
-export interface SettledPromptRecord {
-    readonly type: "settled";
-    readonly id: string;
-    readonly entryId: string;
-}
-export interface RetiredPromptRecord {
-    readonly type: "retired";
-    readonly id: string;
-}
-export type PromptJournalRecord = SubmittedPromptRecord | CorrelatedPromptRecord | SettledPromptRecord | RetiredPromptRecord;
-export interface PromptSubmission {
-    readonly sessionId: string;
-    readonly sessionFile: string | null;
-    readonly incarnation: number;
-    readonly fileExisted: boolean;
-    readonly kind: SubmittedPromptRecord["kind"];
-    readonly text: string;
-}
-export interface SessionJournalEntry {
-    readonly entryId: string;
-    readonly text: string;
-    readonly settled: boolean;
-}
-export interface PendingPrompt {
-    readonly submitted: SubmittedPromptRecord;
-    readonly correlatedEntryId?: string;
-}
-export declare class PromptJournal {
-    #private;
-    readonly path: string;
-    constructor(path: string, options?: {
-        readonly faults?: ResidentTabFaultInjection;
-        readonly maximumBytes?: number;
-    });
-    initialize(): Promise<void>;
-    submit(submission: PromptSubmission): Promise<SubmittedPromptRecord>;
-    adopt(record: SubmittedPromptRecord): Promise<boolean>;
-    correlate(id: string, entryId: string): Promise<void>;
-    settle(id: string, entryId: string): Promise<void>;
-    retire(id: string): Promise<void>;
-    read(): Promise<readonly PromptJournalRecord[]>;
-    pending(sessionEntries?: readonly SessionJournalEntry[]): Promise<readonly PendingPrompt[]>;
-    compactIfRetired(): Promise<boolean>;
-}
-export declare function classifyMissingSession(record: SubmittedPromptRecord, sessionExists: boolean): "available" | "first-turn" | "missing-transcript";
-export declare function removeJournalTemporary(path: string): Promise<void>;

package/dist/foundation/resident-tabs/prompt-journal.js

@@ -1,213 +0,0 @@
-import { randomUUID } from "node:crypto";
-import { chmod, mkdir, open, readFile, rename, stat, unlink } from "node:fs/promises";
-import { dirname } from "node:path";
-import { ResidentTabFaultInjection } from "./fault-injection.js";
-const MAX_JOURNAL_BYTES = 8 * 1024 * 1024;
-const MAX_RECORD_BYTES = 2 * 1024 * 1024;
-export class PromptJournal {
-    path;
-    #faults;
-    #maximumBytes;
-    #operation = Promise.resolve();
-    #retired = new Set();
-    constructor(path, options = {}) {
-        this.path = path;
-        this.#faults = options.faults ?? new ResidentTabFaultInjection();
-        this.#maximumBytes = options.maximumBytes ?? MAX_JOURNAL_BYTES;
-    }
-    async initialize() {
-        await secureDirectory(dirname(this.path));
-        const handle = await open(this.path, "a", 0o600);
-        await handle.close();
-        if (process.platform !== "win32")
-            await chmod(this.path, 0o600);
-        for (const record of await this.read())
-            if (record.type === "retired")
-                this.#retired.add(record.id);
-    }
-    async submit(submission) {
-        const record = {
-            type: "submitted",
-            id: randomUUID(),
-            ...submission,
-            at: new Date().toISOString(),
-        };
-        await this.#append(record, "journal-before-append", "journal-after-append", "journal-after-sync");
-        return record;
-    }
-    async adopt(record) {
-        if ((await this.read()).some(existing => existing.type === "submitted" && existing.id === record.id))
-            return false;
-        await this.#append(record, "journal-before-append", "journal-after-append", "journal-after-sync");
-        return true;
-    }
-    async correlate(id, entryId) {
-        await this.#append({ type: "correlated", id, entryId }, "journal-before-correlation", "journal-after-correlation");
-    }
-    async settle(id, entryId) {
-        await this.#append({ type: "settled", id, entryId }, "journal-before-settled-record", "journal-after-settled-record");
-    }
-    async retire(id) {
-        if (this.#retired.has(id))
-            return;
-        await this.#append({ type: "retired", id }, "journal-during-retirement");
-        this.#retired.add(id);
-    }
-    async read() {
-        let text;
-        try {
-            text = await readFile(this.path, "utf8");
-        }
-        catch (error) {
-            if (error.code === "ENOENT")
-                return [];
-            throw error;
-        }
-        const records = [];
-        const lines = text.split("\n");
-        for (let index = 0; index < lines.length; index += 1) {
-            const line = lines[index];
-            if (!line)
-                continue;
-            try {
-                const value = JSON.parse(line);
-                records.push(decodeRecord(value));
-            }
-            catch (error) {
-                if (index === lines.length - 1 && !text.endsWith("\n"))
-                    break;
-                throw error;
-            }
-        }
-        return records;
-    }
-    async pending(sessionEntries = []) {
-        const states = new Map();
-        const settled = new Set();
-        const retired = new Set();
-        for (const record of await this.read()) {
-            if (record.type === "submitted")
-                states.set(record.id, { submitted: record });
-            else if (record.type === "correlated") {
-                const state = states.get(record.id);
-                if (state !== undefined)
-                    states.set(record.id, { ...state, correlatedEntryId: record.entryId });
-            }
-            else if (record.type === "settled")
-                settled.add(record.id);
-            else
-                retired.add(record.id);
-        }
-        const byId = new Map(sessionEntries.map(entry => [entry.entryId, entry]));
-        const pending = [];
-        const claimedEntries = new Set();
-        for (const [id, state] of states) {
-            if (retired.has(id) || settled.has(id)) {
-                await this.retire(id);
-                continue;
-            }
-            const correlated = state.correlatedEntryId === undefined ? undefined : byId.get(state.correlatedEntryId);
-            const textMatch = correlated ?? sessionEntries.find(entry => entry.text === state.submitted.text && !claimedEntries.has(entry.entryId));
-            if (textMatch !== undefined)
-                claimedEntries.add(textMatch.entryId);
-            if (textMatch?.settled === true)
-                await this.retire(id);
-            else
-                pending.push(state);
-        }
-        return pending;
-    }
-    async compactIfRetired() {
-        if ((await this.pending()).length !== 0)
-            return false;
-        await this.#serialize(async () => {
-            this.#faults.at("journal-during-compaction");
-            const temporary = `${this.path}.tmp-${process.pid}-${randomUUID()}`;
-            const handle = await open(temporary, "wx", 0o600);
-            try {
-                await handle.sync();
-            }
-            finally {
-                await handle.close();
-            }
-            await rename(temporary, this.path);
-            await syncDirectory(dirname(this.path));
-        });
-        return true;
-    }
-    async #append(record, ...points) {
-        const line = `${JSON.stringify(record)}\n`;
-        const bytes = Buffer.byteLength(line);
-        if (bytes > MAX_RECORD_BYTES)
-            throw new Error("resident prompt journal record exceeds its size limit");
-        await this.#serialize(async () => {
-            for (const point of points.slice(0, 1))
-                this.#faults.at(point);
-            const current = await stat(this.path).then(value => value.size, error => error.code === "ENOENT" ? 0 : Promise.reject(error));
-            if (current + bytes > this.#maximumBytes)
-                throw new Error("resident prompt journal is full");
-            const handle = await open(this.path, "a", 0o600);
-            try {
-                await handle.write(line, undefined, "utf8");
-                if (points[1] !== undefined)
-                    this.#faults.at(points[1]);
-                await handle.sync();
-                if (points[2] !== undefined)
-                    this.#faults.at(points[2]);
-            }
-            finally {
-                await handle.close();
-            }
-        });
-    }
-    async #serialize(operation) {
-        const next = this.#operation.then(operation, operation);
-        this.#operation = next.catch(() => undefined);
-        await next;
-    }
-}
-export function classifyMissingSession(record, sessionExists) {
-    if (sessionExists)
-        return "available";
-    return record.fileExisted ? "missing-transcript" : "first-turn";
-}
-function decodeRecord(value) {
-    if (typeof value !== "object" || value === null)
-        throw new Error("invalid resident prompt journal record");
-    const record = value;
-    if (typeof record.id !== "string" || record.id.length === 0)
-        throw new Error("invalid resident prompt journal id");
-    if (record.type === "submitted") {
-        if (typeof record.sessionId !== "string" || !(typeof record.sessionFile === "string" || record.sessionFile === null)
-            || typeof record.incarnation !== "number" || typeof record.fileExisted !== "boolean"
-            || !["prompt", "steer", "follow-up"].includes(String(record.kind)) || typeof record.text !== "string" || typeof record.at !== "string") {
-            throw new Error("invalid submitted prompt journal record");
-        }
-        return record;
-    }
-    if ((record.type === "correlated" || record.type === "settled") && typeof record.entryId === "string")
-        return record;
-    if (record.type === "retired")
-        return record;
-    throw new Error("invalid resident prompt journal record type");
-}
-async function secureDirectory(path) {
-    await mkdir(path, { recursive: true, mode: 0o700 });
-    if (process.platform !== "win32")
-        await chmod(path, 0o700);
-}
-async function syncDirectory(path) {
-    if (process.platform === "win32")
-        return;
-    const handle = await open(path, "r");
-    try {
-        await handle.sync();
-    }
-    finally {
-        await handle.close();
-    }
-}
-export async function removeJournalTemporary(path) {
-    await unlink(path).catch(error => { if (error.code !== "ENOENT")
-        throw error; });
-}

package/dist/foundation/resident-tabs/protocol.d.ts

@@ -1,12 +0,0 @@
-export interface ResidentEnvelope<T = Readonly<Record<string, unknown>>> {
-    readonly type: string;
-    readonly requestId?: number;
-    readonly body: T;
-}
-/** Generation-1 MessagePack named-map codec. It intentionally supports only bridge-safe values. */
-export declare function encodeResidentFrame(value: ResidentEnvelope): Buffer;
-export declare function decodeResidentPayload(payload: Uint8Array): ResidentEnvelope;
-export declare class ResidentFrameDecoder {
-    #private;
-    push(chunk: Uint8Array): readonly ResidentEnvelope[];
-}