@12ui/design 0.2.91 → 0.2.93

package/dist/branch-local-call-wait.d.ts

@@ -0,0 +1,58 @@
+/**
+ * A local branch call whose `codex exec` child was spawned but whose process group never reached a record: the
+ * `branch execute` that dispatched it died between the spawn and the write (a screen's `onSpawn` into run.json, the
+ * planner's `persistMetadata` into the call's state). The child leads its own process group and runs on, but the
+ * resume has no group to wait on, so without this it would settle the call at once: a screen whose session is still
+ * being drawn finds nothing and fails for good, and a planner whose answer is moments away tells the person to start
+ * over, while the orphan's paid answer lands afterwards.
+ *
+ * Such a call is treated as possibly running. Its spawn time is the `startedAt` of its `invocation.json` (written as
+ * the last step before the spawn: a call without one was never spawned and is not waited for). The resume polls the
+ * call's own proof of completion (`finished`: the screen's session in the Codex home, the planner's answer file) until
+ * it shows, or until the window a call is allowed (`startedAt` + the call's timeout + the executor's stop grace)
+ * closes, and only then settles the call by the store's rule as before. Each wait is recorded in the call's folder
+ * (`call-wait.json`: `waiting` while it runs, then how it ended).
+ */
+export declare const CALL_WAIT_FILE = "call-wait.json";
+/** The executor stops a call at its timeout with SIGTERM and SIGKILLs it 5 s later; the window allows that too. */
+export declare const CALL_STOP_GRACE_MS = 5000;
+export type CallWait = {
+    callId: string;
+    /** From the call's spawn to the end of the window it is allowed. */
+    window: {
+        from: string;
+        until: string;
+    };
+    waitStartedAt: string;
+    /** `finished`: the call's completion showed; `window-elapsed`: it never did inside the window. */
+    outcome: 'waiting' | 'finished' | 'window-elapsed';
+    /** What showed the call finished. */
+    signal?: string;
+    waitEndedAt?: string;
+};
+export type UnrecordedCallWait = {
+    callDir: string;
+    /** The call's timeout: how long its executor lets it run. */
+    timeoutMs: number;
+    /** The call's own proof that it finished (what showed it), or null while it may still be running. */
+    finished: (context: {
+        startedAt: string;
+    }) => Promise<string | null>;
+    pollMs?: number;
+    now?: () => number;
+};
+/**
+ * Waits for a dispatched call that has no recorded process group. Null when there is nothing to wait for: no call,
+ * one already settled or never dispatched, one whose dispatching process saw it end (`completion.json`), or one never
+ * spawned (no `invocation.json`).
+ */
+export declare const waitForUnrecordedCall: (options: UnrecordedCallWait) => Promise<CallWait | null>;
+/**
+ * The proof a screen's image call finished: its session in the call's Codex home (by the thread id its events
+ * announced, else found by the call's own inputs, as the adoption finds it) records the generation's end or the
+ * turn's end.
+ */
+export declare const imageCallFinished: (callDir: string) => ({ startedAt }: {
+    startedAt: string;
+}) => Promise<string | null>;
+//# sourceMappingURL=branch-local-call-wait.d.ts.map

package/dist/branch-local-call-wait.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"branch-local-call-wait.d.ts","sourceRoot":"","sources":["../src/branch-local-call-wait.ts"],"names":[],"mappings":"AAMA;;;;;;;;;;;;;;GAcG;AAEH,eAAO,MAAM,cAAc,mBAAmB,CAAC;AAC/C,mHAAmH;AACnH,eAAO,MAAM,kBAAkB,OAAQ,CAAC;AAGxC,MAAM,MAAM,QAAQ,GAAG;IACrB,MAAM,EAAE,MAAM,CAAC;IACf,oEAAoE;IACpE,MAAM,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAE,CAAC;IACxC,aAAa,EAAE,MAAM,CAAC;IACtB,kGAAkG;IAClG,OAAO,EAAE,SAAS,GAAG,UAAU,GAAG,gBAAgB,CAAC;IACnD,qCAAqC;IACrC,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB,CAAC;AAgBF,MAAM,MAAM,kBAAkB,GAAG;IAC/B,OAAO,EAAE,MAAM,CAAC;IAChB,6DAA6D;IAC7D,SAAS,EAAE,MAAM,CAAC;IAClB,qGAAqG;IACrG,QAAQ,EAAE,CAAC,OAAO,EAAE;QAAE,SAAS,EAAE,MAAM,CAAA;KAAE,KAAK,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAAC;IACrE,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,GAAG,CAAC,EAAE,MAAM,MAAM,CAAC;CACpB,CAAC;AAEF;;;;GAIG;AACH,eAAO,MAAM,qBAAqB,GAAU,SAAS,kBAAkB,KAAG,OAAO,CAAC,QAAQ,GAAG,IAAI,CAyBhG,CAAC;AAsCF;;;;GAIG;AACH,eAAO,MAAM,iBAAiB,GAAI,SAAS,MAAM,MAAY,eAAe;IAAE,SAAS,EAAE,MAAM,CAAA;CAAE,KAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAaxH,CAAC"}

package/dist/branch-local-call-wait.js

@@ -0,0 +1,122 @@
+import { readFile, writeFile } from 'node:fs/promises';
+import path from 'node:path';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+import { unannouncedSessionFiles } from './branch-local-session-adoption.js';
+/**
+ * A local branch call whose `codex exec` child was spawned but whose process group never reached a record: the
+ * `branch execute` that dispatched it died between the spawn and the write (a screen's `onSpawn` into run.json, the
+ * planner's `persistMetadata` into the call's state). The child leads its own process group and runs on, but the
+ * resume has no group to wait on, so without this it would settle the call at once: a screen whose session is still
+ * being drawn finds nothing and fails for good, and a planner whose answer is moments away tells the person to start
+ * over, while the orphan's paid answer lands afterwards.
+ *
+ * Such a call is treated as possibly running. Its spawn time is the `startedAt` of its `invocation.json` (written as
+ * the last step before the spawn: a call without one was never spawned and is not waited for). The resume polls the
+ * call's own proof of completion (`finished`: the screen's session in the Codex home, the planner's answer file) until
+ * it shows, or until the window a call is allowed (`startedAt` + the call's timeout + the executor's stop grace)
+ * closes, and only then settles the call by the store's rule as before. Each wait is recorded in the call's folder
+ * (`call-wait.json`: `waiting` while it runs, then how it ended).
+ */
+export const CALL_WAIT_FILE = 'call-wait.json';
+/** The executor stops a call at its timeout with SIGTERM and SIGKILLs it 5 s later; the window allows that too. */
+export const CALL_STOP_GRACE_MS = 5_000;
+const POLL_MS = 1_000;
+const readJson = async (file) => {
+    try {
+        return JSON.parse(await readFile(file, 'utf8'));
+    }
+    catch (error) {
+        if (error.code === 'ENOENT')
+            return null;
+        throw error;
+    }
+};
+const record = async (callDir, wait) => {
+    await writeFile(path.join(callDir, CALL_WAIT_FILE), `${JSON.stringify(wait, null, 2)}\n`, { mode: 0o600 });
+    return wait;
+};
+/**
+ * Waits for a dispatched call that has no recorded process group. Null when there is nothing to wait for: no call,
+ * one already settled or never dispatched, one whose dispatching process saw it end (`completion.json`), or one never
+ * spawned (no `invocation.json`).
+ */
+export const waitForUnrecordedCall = async (options) => {
+    const now = options.now ?? Date.now;
+    const { callDir } = options;
+    const state = await readJson(path.join(callDir, 'state.json'));
+    if (state?.status !== 'dispatched')
+        return null;
+    if (await readJson(path.join(callDir, 'completion.json')))
+        return null;
+    const startedAt = (await readJson(path.join(callDir, 'invocation.json')))?.startedAt;
+    const from = typeof startedAt === 'string' ? Date.parse(startedAt) : Number.NaN;
+    if (Number.isNaN(from))
+        return null;
+    const until = from + options.timeoutMs + CALL_STOP_GRACE_MS;
+    const base = { callId: String(state.id), window: { from: startedAt, until: new Date(until).toISOString() }, waitStartedAt: new Date(now()).toISOString() };
+    let wait = await record(callDir, { ...base, outcome: 'waiting' });
+    for (;;) {
+        const signal = await options.finished({ startedAt: startedAt });
+        if (signal) {
+            wait = { ...base, outcome: 'finished', signal, waitEndedAt: new Date(now()).toISOString() };
+            break;
+        }
+        if (now() >= until) {
+            wait = { ...base, outcome: 'window-elapsed', waitEndedAt: new Date(now()).toISOString() };
+            break;
+        }
+        await new Promise((resolve) => { setTimeout(resolve, Math.max(0, Math.min(options.pollMs ?? POLL_MS, until - now()))); });
+    }
+    return record(callDir, wait);
+};
+const importRuntime = async () => {
+    const base = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..', 'runtime', 'codex-conversion', 'src');
+    const load = async (file) => await import(pathToFileURL(path.join(base, file)).href);
+    const modules = await Promise.all(['codex/caller-home.mjs', 'images/native-records.mjs'].map(load));
+    return Object.assign({}, ...modules);
+};
+/** Codex's own end-of-turn records in a session (`event_msg` payloads). */
+const TURN_END_EVENTS = new Set(['task_complete', 'turn_aborted']);
+/** A session is over once its image generation completed (with or without an image) or its turn ended. */
+const sessionEnded = (runtime, text) => {
+    try {
+        if (runtime.parseNativeRecords(text).generations.length > 0)
+            return true;
+    }
+    catch {
+        // Conflicting completions: the session is over, and the store's recovery reports it.
+        return true;
+    }
+    return text.split('\n').some((line) => {
+        if (!line.includes('"payload"'))
+            return false;
+        try {
+            return TURN_END_EVENTS.has(String(JSON.parse(line).payload?.type));
+        }
+        catch {
+            return false;
+        }
+    });
+};
+/**
+ * The proof a screen's image call finished: its session in the call's Codex home (by the thread id its events
+ * announced, else found by the call's own inputs, as the adoption finds it) records the generation's end or the
+ * turn's end.
+ */
+export const imageCallFinished = (callDir) => async ({ startedAt }) => {
+    const runtime = await importRuntime();
+    const state = await readJson(path.join(callDir, 'state.json'));
+    const home = state?.metadata?.home;
+    if (typeof home !== 'string')
+        return null;
+    const threadId = typeof state?.metadata?.threadId === 'string'
+        ? state.metadata.threadId
+        : await runtime.threadIdOf(path.join(callDir, 'events.jsonl'));
+    const files = threadId ? await runtime.callRollouts(home, threadId, [startedAt, Date.now()]) : await unannouncedSessionFiles(callDir);
+    for (const file of files) {
+        if (sessionEnded(runtime, await readFile(file, 'utf8')))
+            return 'session-ended';
+    }
+    return null;
+};
+//# sourceMappingURL=branch-local-call-wait.js.map

package/dist/branch-local-call-wait.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"branch-local-call-wait.js","sourceRoot":"","sources":["../src/branch-local-call-wait.ts"],"names":[],"mappings":"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"}

package/dist/branch-local-client.d.ts

@@ -0,0 +1,108 @@
+import { type BranchCell, type BranchPlan, type BranchReferenceRole } from './branch-core/index.js';
+import { type BranchRunClient, type BranchRunEnvelope } from './branch-client.js';
+import { type CodexProcessOptions } from './slate-image-executor.js';
+/**
+ * The branch build process on the person's own Codex, behind the same four
+ * methods the hosted client answers (`BranchRunClient`), so `executeBranchRun`,
+ * the dispatch loop, the records and both workspaces' followers run unchanged.
+ * Every decision is the hosted one, from the shared branch core: the planner
+ * call (branch-local-plan.ts) and its parse with the bounded retry, the trim,
+ * derived chrome, canvases and slots, the dispatch gates (a continuation waits
+ * for its preceding viewport, a footer for the footer seed unless the seed
+ * failed), the reference order (approved design, preceding viewport, footer
+ * seed) and the per-screen prompt rebuilt from the references that arrived.
+ * Each screen is one native Codex image call through the workspace's own
+ * executor (`drawOptionWithCodex`: the prompt copied verbatim into the image
+ * tool, one more sample only when the tool refused the first).
+ *
+ * State lives in `<branchDir>/local/`: `run.json` (the ledger: plan, cells and
+ * every slot's status, call id, prompt and references), `winner.<ext>`,
+ * `screens/<slot>.png` (each delivered screen: the bytes the board receives
+ * and the bytes a later screen is conditioned on) and `calls/` (the run-store
+ * custody of every Codex call). Call ids are stable (`branch-plan:<run>:<n>`,
+ * `branch:<run>:<slot>`), so a resumed run settles each call by the store's
+ * rule — an answer that landed is reused, a dispatched call is recovered from
+ * its own session or refused — and never pays for one twice.
+ */
+export declare const LOCAL_BRANCH_DIRECTORY = "local";
+type SlotStatus = 'pending' | 'dispatched' | 'succeeded' | 'failed';
+type LocalSlot = {
+    status: SlotStatus;
+    callId?: string;
+    /** The image prompt this slot's call sends, as built at its first dispatch. */
+    prompt?: string;
+    /** The references that call sends, in order: `winner`, then slots. */
+    references?: Array<{
+        role: BranchReferenceRole;
+        key: string;
+    }>;
+    pgid?: number;
+    /** The call `pgid` belongs to (the slot's first call or its one retry). */
+    pgidCallId?: string;
+    dispatchedAt?: string;
+    settledAt?: string;
+    error?: {
+        code: string;
+        message: string;
+    };
+    screen?: {
+        sha256: string;
+        width: number;
+        height: number;
+    };
+    codex?: Record<string, unknown>;
+};
+export type LocalBranchRun = {
+    version: 1;
+    engine: 'codex';
+    runId: string;
+    runKey: string;
+    concept: string;
+    aspect: 'landscape' | 'portrait' | 'square';
+    maxScreens?: number;
+    createdAt: string;
+    winner: {
+        file: string;
+        sha256: string;
+        mediaType: string;
+        width: number;
+        height: number;
+    };
+    planner: {
+        calls: Array<{
+            callId: string;
+            reused: boolean;
+            parseError?: string;
+        }>;
+    };
+    plan: BranchPlan;
+    cells: BranchCell[];
+    footerSeedSlot: string | null;
+    slots: Record<string, LocalSlot>;
+};
+export declare const localBranchRunId: (runKey: string) => string;
+export declare const localBranchCallId: (runId: string, slot: string) => string;
+export declare const localBranchDirectory: (branchDir: string) => string;
+/** The run as the hosted create route projects it (workers/api/src/create/runEnvelope.ts). */
+export declare const localBranchEnvelope: (run: LocalBranchRun, inFlight?: ReadonlySet<string>) => BranchRunEnvelope;
+/** The recorded run of a local branch, read only (`12ui next` refreshes a codex run from it). */
+export declare const readLocalBranchEnvelope: (branchDir: string) => Promise<BranchRunEnvelope | null>;
+export type LocalBranchClientOptions = {
+    /** The branch run's folder (`<run-dir>/branch`). */
+    branchDir: string;
+    /** The environment Codex is resolved from (`CODEX_HOME`, `TWELVE_UI_CODEX_BIN`, `PATH`); never passed to it whole. */
+    env: NodeJS.ProcessEnv;
+    processOptions?: CodexProcessOptions;
+    /** How long one call may run before it is stopped: the planner's turn and each screen's image call. */
+    timeouts?: {
+        planMs?: number;
+        imageMs?: number;
+    };
+};
+export type LocalBranchClient = BranchRunClient & {
+    /** Releases the run folder's lock (also released when the process exits). */
+    close: () => void;
+};
+export declare const createLocalBranchClient: (options: LocalBranchClientOptions) => LocalBranchClient;
+export {};
+//# sourceMappingURL=branch-local-client.d.ts.map

package/dist/branch-local-client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"branch-local-client.d.ts","sourceRoot":"","sources":["../src/branch-local-client.ts"],"names":[],"mappings":"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"}