@openagt/dashboard 0.0.0-stage → 0.8.0

package/dist/driver/cloud.js

@@ -0,0 +1,232 @@
+import { randomUUID } from 'node:crypto';
+import { nodeGitRunner } from '@gemstack/agent-data';
+import { errorMessage } from '../error-message.js';
+import { githubSlugFor } from '../dashboard/github.js';
+import { WEB_START_PREFIX } from '../dashboard/web-start-endpoints.js';
+import { makeEmit } from 'agent-driver';
+/**
+ * A {@link Driver} that hands the task to **Claude Code on the web** (#610): it has a cloud
+ * session created on claude.ai and returns its id and URL.
+ *
+ * The session is created by the browser extension, in the user's own signed-in browser,
+ * through claude.ai's repository picker (#1328): the run asks its daemon to queue the request
+ * — the repository, the pushed hand-off ref, the prompt — and the extension drives the page
+ * and reports the session it became. A session created that way is bound to the repository,
+ * so it can push its work and open its pull request; the CLI's own `--cloud` flag, the earlier
+ * mechanism, produced on some accounts a bundle upload that never could (#1320), and is gone.
+ * The account, the auth and the quota are the user's, exactly as with the local driver (#495).
+ *
+ * So a web run needs four things, and names whichever is missing: a daemon that spawned it
+ * (the daemon's URL travels in the run's environment), the browser bridge switched on, the
+ * extension present, and a GitHub remote for the picker to name.
+ *
+ * **What this target is, and is not.** It is a hand-off: the session runs on Anthropic's
+ * infrastructure, does its own git worktree and opens its own PR, at 0% local CPU — the
+ * whole point of #610. What it is not is a streamed peer like the local, device and
+ * Actions targets, and that is not a shortcut in this implementation but a property of
+ * the surface: a cloud session exposes **no read-back API** of any kind — no status, no
+ * transcript, no output endpoint, only the session URL. So the turn resolves once the
+ * session is created, and following the work happens on claude.ai, through the browser
+ * bridge's mirror and gate relay (#1237/#1554), or by pulling it back with
+ * `claude --teleport <id>`.
+ *
+ * For the same reason there is no `readCode`: the workspace lives in a cloud VM this
+ * machine never sees.
+ */
+export class CloudDriver {
+    opts;
+    id = 'claude-web';
+    constructor(opts = {}) {
+        this.opts = opts;
+    }
+    start(opts) {
+        return Promise.resolve(new CloudSession(this.opts, opts));
+    }
+}
+/** Counter feeding the per-process half of a session id. */
+let sessionCounter = 0;
+export const CLOUD_PROMPT_SEPARATOR = '===============================';
+/**
+ * The prompt handed to the cloud session (#1497): the task first, then every block The Framework
+ * injects — the framing, a per-call system — behind a labeled rule. On claude.ai this string is
+ * read by a human, and the task is what they open the session to find.
+ */
+export function cloudHandOffPrompt(task, ...injected) {
+    const blocks = injected.filter((part) => Boolean(part));
+    if (blocks.length === 0)
+        return task;
+    const rule = `\n\n\n${CLOUD_PROMPT_SEPARATOR}\n\n\n`;
+    const header = 'Instructions from The Framework, the tool that started this session:';
+    return `${task}${rule}${header}\n\n${blocks.join(rule)}`;
+}
+/** What a web run is missing when it cannot hand off, each named so the fix is the message. */
+const NO_DAEMON = '[framework] claude-web: this run was not started by a daemon, so nothing can hand it to the browser extension — start web runs from the dashboard.';
+const NO_REMOTE = '[framework] claude-web: no GitHub remote here — the cloud session is created on a repository the browser extension picks on claude.ai, so the project needs an `origin` on GitHub.';
+const NO_EXTENSION = '[framework] claude-web: no browser extension has spoken to this daemon recently — install or reload The Framework extension on a claude.ai tab (and keep the browser bridge on in Settings), then start the run again.';
+const BRIDGE_OFF = '[framework] claude-web: the browser bridge is off — turn it on in Settings so the extension can create the cloud session.';
+export class CloudSession {
+    config;
+    startOpts;
+    id;
+    cwd;
+    emit;
+    framing;
+    controllers = new Set();
+    disposed = false;
+    /** The cloud session this agent was handed to, once it exists. Set at most once. */
+    handedOff;
+    /** The hand-off anchor commit (#1601), once it is on origin. Set at most once, with the hand-off. */
+    anchorSha;
+    constructor(config, startOpts) {
+        this.config = config;
+        this.startOpts = startOpts;
+        const tag = (config.agentTag ?? (() => randomUUID().slice(0, 8)))();
+        this.id = `cloud-${++sessionCounter}-${tag}`;
+        this.cwd = startOpts.cwd;
+        this.emit = makeEmit(startOpts.onEvent, 'claude-web');
+        this.framing = startOpts.system;
+    }
+    async prompt(text, opts = {}) {
+        if (this.disposed)
+            throw new Error('[framework] claude-web session disposed');
+        const full = cloudHandOffPrompt(text, this.framing, opts.system);
+        this.emit({ type: 'start', prompt: full });
+        // Already handed off: say so and spend nothing. This is the guard that keeps one agent to
+        // one cloud session however many times the loop comes back round.
+        if (this.handedOff)
+            return this.report(this.handedOff, 'again');
+        const controller = new AbortController();
+        this.controllers.add(controller);
+        for (const signal of [this.startOpts.signal, opts.signal]) {
+            if (!signal)
+                continue;
+            if (signal.aborted) {
+                this.controllers.delete(controller);
+                throw new Error('[framework] claude-web prompt aborted');
+            }
+            signal.addEventListener('abort', () => controller.abort(), { once: true });
+        }
+        const timer = setTimeout(() => controller.abort(), this.config.timeoutMs ?? 120_000);
+        try {
+            const ext = this.config.extension;
+            if (!ext)
+                throw new Error(NO_DAEMON);
+            const git = this.config.git ?? nodeGitRunner();
+            const slug = await githubSlugFor(this.cwd, git);
+            if (!slug)
+                throw new Error(NO_REMOTE);
+            // The pre-hand-off push (#1320): the cloud session opens on a named origin ref, so the
+            // repository picker's branch list must offer this run's starting point. What gets pushed is
+            // not HEAD itself but the hand-off anchor (#1601): an empty commit on top of it, so the ref
+            // is recognizably this run's and a later sweep can tell it from a branch a person made.
+            // Minting and pushing are one step: a checkout that cannot mint an empty commit on its
+            // HEAD has no HEAD to push either. A push that fails fails the run — the session cannot
+            // open on a ref origin does not have.
+            let anchor;
+            try {
+                anchor = (await git(['commit-tree', 'HEAD^{tree}', '-p', 'HEAD', '-m', `[The Framework] web hand-off ${this.id}`], this.cwd)).trim();
+                await git(['push', 'origin', `${anchor}:refs/heads/${this.id}`], this.cwd);
+            }
+            catch (err) {
+                throw new Error(`[framework] claude-web: could not push the hand-off ref ${this.id} to origin (${errorMessage(err)}) — the cloud session opens on that ref, so the project needs a pushable GitHub remote.`);
+            }
+            const found = await this.createViaExtension(ext, `${slug.owner}/${slug.repo}`, this.id, full, this.startOpts.model, controller.signal);
+            this.anchorSha = anchor;
+            this.handedOff = found;
+            return this.report(found, 'first');
+        }
+        catch (err) {
+            // A user abort (Stop, the agent signal) lands here too; name it what it was.
+            if (this.startOpts.signal?.aborted || opts.signal?.aborted)
+                throw new Error('[framework] claude-web prompt aborted');
+            throw err;
+        }
+        finally {
+            clearTimeout(timer);
+            this.controllers.delete(controller);
+        }
+    }
+    /**
+     * Hand the session request to the daemon's start-queue and wait for the extension's word
+     * (#1328). Throws, naming the cure, when the daemon has no extension to ask (409) or the
+     * bridge is off (404); throws with the extension's own note when it tried and could not create
+     * the session; throws when the wait was aborted or timed out. The model the run was started
+     * with travels along (#1697): the extension picks it in claude.ai's model menu, so a web run
+     * honours the choice the way a local one does instead of dropping it on the page's default.
+     */
+    async createViaExtension(ext, repo, ref, prompt, model, signal) {
+        const doFetch = ext.fetch ?? fetch;
+        const base = ext.daemonUrl.replace(/\/+$/, '');
+        const headers = { authorization: `Bearer ${ext.token}` };
+        const queued = await doFetch(`${base}${WEB_START_PREFIX}`, {
+            method: 'POST',
+            headers: { ...headers, 'content-type': 'application/json' },
+            body: JSON.stringify({ repo, branch: ref, prompt, ...(model ? { model } : {}) }),
+            signal,
+        });
+        if (queued.status === 409)
+            throw new Error(NO_EXTENSION);
+        if (queued.status === 404)
+            throw new Error(BRIDGE_OFF);
+        if (!queued.ok)
+            throw new Error(`[framework] claude-web: the daemon refused the session request (${queued.status}): ${(await queued.text()).slice(0, 300)}`);
+        const { id } = (await queued.json());
+        this.emit({ type: 'notice', message: `[framework] claude-web: asked the browser extension to create the cloud session on ${repo} at ${ref}${model ? ` on ${model}` : ''} (request ${id}).` });
+        const pollMs = ext.pollMs ?? 2000;
+        for (;;) {
+            if (signal.aborted)
+                throw new Error('[framework] claude-web: gave up waiting for the browser extension to create the session.');
+            const res = await doFetch(`${base}${WEB_START_PREFIX}/${id}`, { headers, signal });
+            if (!res.ok)
+                throw new Error(`[framework] claude-web: lost the session request ${id} (${res.status})`);
+            const state = (await res.json());
+            if (state.state === 'created' && state.sessionId && state.url)
+                return { url: state.url, sessionId: state.sessionId };
+            if (state.state === 'failed') {
+                throw new Error(`[framework] claude-web: the browser extension could not create the session${state.note ? ` — ${state.note}` : ''}.`);
+            }
+            await new Promise(resolve => {
+                const t = setTimeout(resolve, pollMs);
+                signal.addEventListener('abort', () => { clearTimeout(t); resolve(); }, { once: true });
+            });
+        }
+    }
+    /**
+     * Report where this agent went. The `first` hand-off emits the `cloud <url>` action the agent
+     * view links through to — mirroring the Actions driver's `run <url>` — and a later pass
+     * says the work is already there, so a loop that keeps prompting cannot read the same turn
+     * as fresh progress and cannot spend a second session.
+     */
+    report(session, when) {
+        if (when === 'first')
+            this.emit({ type: 'action', label: `cloud ${session.url}` });
+        const summary = when === 'first'
+            ? ['Handed off to Claude Code on the web.', '', `View the session: ${session.url}`, `Continue it here: claude --teleport ${session.sessionId}`].join('\n')
+            : [
+                'This run was already handed off to Claude Code on the web, so there is nothing further to do here.',
+                'The work continues in that cloud session, which opens its own pull request.',
+                '',
+                `View the session: ${session.url}`,
+                `Continue it here: claude --teleport ${session.sessionId}`,
+            ].join('\n');
+        // The result also carries the session's real URL (#1317) and the hand-off anchor (#1601):
+        // the action above is what the agent view links through, the result is what reaches the meta.
+        this.emit({
+            type: 'result',
+            text: summary,
+            sessionId: session.sessionId,
+            sessionLink: session.url,
+            ...(this.anchorSha ? { anchorSha: this.anchorSha } : {}),
+        });
+        return { text: summary, sessionId: session.sessionId };
+    }
+    // No `readCode`: the cloud VM's workspace is not on this machine, and the branch it
+    // pushes is not known until it pushes one.
+    async dispose() {
+        this.disposed = true;
+        for (const controller of this.controllers)
+            controller.abort();
+        this.controllers.clear();
+    }
+}
+//# sourceMappingURL=cloud.js.map

package/dist/driver/cloud.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cloud.js","sourceRoot":"","sources":["../../src/driver/cloud.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAA;AACxC,OAAO,EAAE,aAAa,EAAkB,MAAM,sBAAsB,CAAA;AACpE,OAAO,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAA;AAClD,OAAO,EAAE,aAAa,EAAE,MAAM,wBAAwB,CAAA;AACtD,OAAO,EAAE,gBAAgB,EAAE,MAAM,qCAAqC,CAAA;AACtE,OAAO,EAAE,QAAQ,EAAyH,MAAM,cAAc,CAAA;AAE9J;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,MAAM,OAAO,WAAW;IAEO,IAAI;IADxB,EAAE,GAAG,YAAY,CAAA;IAC1B,YAA6B,IAAI,GAAuB,EAAE;oBAA7B,IAAI;IAA4B,CAAC;IAE9D,KAAK,CAAC,IAAwB;QAC5B,OAAO,OAAO,CAAC,OAAO,CAAC,IAAI,YAAY,CAAC,IAAI,CAAC,IAAI,EAAE,IAAI,CAAC,CAAC,CAAA;IAC3D,CAAC;CAIF;AAmCD,4DAA4D;AAC5D,IAAI,cAAc,GAAG,CAAC,CAAA;AAEtB,MAAM,CAAC,MAAM,sBAAsB,GAAG,iCAAiC,CAAA;AAEvE;;;;GAIG;AACH,MAAM,UAAU,kBAAkB,CAAC,IAAY,EAAE,GAAG,QAAgC;IAClF,MAAM,MAAM,GAAG,QAAQ,CAAC,MAAM,CAAC,CAAC,IAAI,EAAkB,EAAE,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,CAAA;IACvE,IAAI,MAAM,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,IAAI,CAAA;IACpC,MAAM,IAAI,GAAG,SAAS,sBAAsB,QAAQ,CAAA;IACpD,MAAM,MAAM,GAAG,sEAAsE,CAAA;IACrF,OAAO,GAAG,IAAI,GAAG,IAAI,GAAG,MAAM,OAAO,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAA;AAC1D,CAAC;AAED,+FAA+F;AAC/F,MAAM,SAAS,GAAG,oJAAoJ,CAAA;AACtK,MAAM,SAAS,GAAG,oLAAoL,CAAA;AACtM,MAAM,YAAY,GAAG,wNAAwN,CAAA;AAC7O,MAAM,UAAU,GAAG,2HAA2H,CAAA;AAE9I,MAAM,OAAO,YAAY;IAaJ,MAAM;IACN,SAAS;IAbnB,EAAE,CAAQ;IACV,GAAG,CAAQ;IACH,IAAI,CAA8B;IAClC,OAAO,CAAoB;IAC3B,WAAW,GAAG,IAAI,GAAG,EAAmB,CAAA;IACjD,QAAQ,GAAG,KAAK,CAAA;IACxB,oFAAoF;IAC5E,SAAS,CAAgD;IACjE,qGAAqG;IAC7F,SAAS,CAAoB;IAErC,YACmB,MAA0B,EAC1B,SAA6B;sBAD7B,MAAM;yBACN,SAAS;QAE1B,MAAM,GAAG,GAAG,CAAC,MAAM,CAAC,QAAQ,IAAI,CAAC,GAAG,EAAE,CAAC,UAAU,EAAE,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,EAAE,CAAA;QACnE,IAAI,CAAC,EAAE,GAAG,SAAS,EAAE,cAAc,IAAI,GAAG,EAAE,CAAA;QAC5C,IAAI,CAAC,GAAG,GAAG,SAAS,CAAC,GAAG,CAAA;QACxB,IAAI,CAAC,IAAI,GAAG,QAAQ,CAAC,SAAS,CAAC,OAAO,EAAE,YAAY,CAAC,CAAA;QACrD,IAAI,CAAC,OAAO,GAAG,SAAS,CAAC,MAAM,CAAA;IACjC,CAAC;IAED,KAAK,CAAC,MAAM,CAAC,IAAY,EAAE,IAAI,GAAwB,EAAE;QACvD,IAAI,IAAI,CAAC,QAAQ;YAAE,MAAM,IAAI,KAAK,CAAC,yCAAyC,CAAC,CAAA;QAC7E,MAAM,IAAI,GAAG,kBAAkB,CAAC,IAAI,EAAE,IAAI,CAAC,OAAO,EAAE,IAAI,CAAC,MAAM,CAAC,CAAA;QAChE,IAAI,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,CAAC,CAAA;QAE1C,0FAA0F;QAC1F,kEAAkE;QAClE,IAAI,IAAI,CAAC,SAAS;YAAE,OAAO,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,SAAS,EAAE,OAAO,CAAC,CAAA;QAE/D,MAAM,UAAU,GAAG,IAAI,eAAe,EAAE,CAAA;QACxC,IAAI,CAAC,WAAW,CAAC,GAAG,CAAC,UAAU,CAAC,CAAA;QAChC,KAAK,MAAM,MAAM,IAAI,CAAC,IAAI,CAAC,SAAS,CAAC,MAAM,EAAE,IAAI,CAAC,MAAM,CAAC,EAAE,CAAC;YAC1D,IAAI,CAAC,MAAM;gBAAE,SAAQ;YACrB,IAAI,MAAM,CAAC,OAAO,EAAE,CAAC;gBACnB,IAAI,CAAC,WAAW,CAAC,MAAM,CAAC,UAAU,CAAC,CAAA;gBACnC,MAAM,IAAI,KAAK,CAAC,uCAAuC,CAAC,CAAA;YAC1D,CAAC;YACD,MAAM,CAAC,gBAAgB,CAAC,OAAO,EAAE,GAAG,EAAE,CAAC,UAAU,CAAC,KAAK,EAAE,EAAE,EAAE,IAAI,EAAE,IAAI,EAAE,CAAC,CAAA;QAC5E,CAAC;QACD,MAAM,KAAK,GAAG,UAAU,CAAC,GAAG,EAAE,CAAC,UAAU,CAAC,KAAK,EAAE,EAAE,IAAI,CAAC,MAAM,CAAC,SAAS,IAAI,OAAO,CAAC,CAAA;QAEpF,IAAI,CAAC;YACH,MAAM,GAAG,GAAG,IAAI,CAAC,MAAM,CAAC,SAAS,CAAA;YACjC,IAAI,CAAC,GAAG;gBAAE,MAAM,IAAI,KAAK,CAAC,SAAS,CAAC,CAAA;YACpC,MAAM,GAAG,GAAG,IAAI,CAAC,MAAM,CAAC,GAAG,IAAI,aAAa,EAAE,CAAA;YAC9C,MAAM,IAAI,GAAG,MAAM,aAAa,CAAC,IAAI,CAAC,GAAG,EAAE,GAAG,CAAC,CAAA;YAC/C,IAAI,CAAC,IAAI;gBAAE,MAAM,IAAI,KAAK,CAAC,SAAS,CAAC,CAAA;YAErC,uFAAuF;YACvF,4FAA4F;YAC5F,4FAA4F;YAC5F,wFAAwF;YACxF,uFAAuF;YACvF,wFAAwF;YACxF,sCAAsC;YACtC,IAAI,MAAc,CAAA;YAClB,IAAI,CAAC;gBACH,MAAM,GAAG,CAAC,MAAM,GAAG,CAAC,CAAC,aAAa,EAAE,aAAa,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,gCAAgC,IAAI,CAAC,EAAE,EAAE,CAAC,EAAE,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,IAAI,EAAE,CAAA;gBACpI,MAAM,GAAG,CAAC,CAAC,MAAM,EAAE,QAAQ,EAAE,GAAG,MAAM,eAAe,IAAI,CAAC,EAAE,EAAE,CAAC,EAAE,IAAI,CAAC,GAAG,CAAC,CAAA;YAC5E,CAAC;YAAC,OAAO,GAAG,EAAE,CAAC;gBACb,MAAM,IAAI,KAAK,CAAC,2DAA2D,IAAI,CAAC,EAAE,eAAe,YAAY,CAAC,GAAG,CAAC,yFAAyF,CAAC,CAAA;YAC9M,CAAC;YAED,MAAM,KAAK,GAAG,MAAM,IAAI,CAAC,kBAAkB,CAAC,GAAG,EAAE,GAAG,IAAI,CAAC,KAAK,IAAI,IAAI,CAAC,IAAI,EAAE,EAAE,IAAI,CAAC,EAAE,EAAE,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC,KAAK,EAAE,UAAU,CAAC,MAAM,CAAC,CAAA;YACtI,IAAI,CAAC,SAAS,GAAG,MAAM,CAAA;YACvB,IAAI,CAAC,SAAS,GAAG,KAAK,CAAA;YACtB,OAAO,IAAI,CAAC,MAAM,CAAC,KAAK,EAAE,OAAO,CAAC,CAAA;QACpC,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,6EAA6E;YAC7E,IAAI,IAAI,CAAC,SAAS,CAAC,MAAM,EAAE,OAAO,IAAI,IAAI,CAAC,MAAM,EAAE,OAAO;gBAAE,MAAM,IAAI,KAAK,CAAC,uCAAuC,CAAC,CAAA;YACpH,MAAM,GAAG,CAAA;QACX,CAAC;gBAAS,CAAC;YACT,YAAY,CAAC,KAAK,CAAC,CAAA;YACnB,IAAI,CAAC,WAAW,CAAC,MAAM,CAAC,UAAU,CAAC,CAAA;QACrC,CAAC;IACH,CAAC;IAED;;;;;;;OAOG;IACK,KAAK,CAAC,kBAAkB,CAC9B,GAAmB,EACnB,IAAY,EACZ,GAAW,EACX,MAAc,EACd,KAAyB,EACzB,MAAmB;QAEnB,MAAM,OAAO,GAAG,GAAG,CAAC,KAAK,IAAI,KAAK,CAAA;QAClC,MAAM,IAAI,GAAG,GAAG,CAAC,SAAS,CAAC,OAAO,CAAC,MAAM,EAAE,EAAE,CAAC,CAAA;QAC9C,MAAM,OAAO,GAAG,EAAE,aAAa,EAAE,UAAU,GAAG,CAAC,KAAK,EAAE,EAAE,CAAA;QACxD,MAAM,MAAM,GAAG,MAAM,OAAO,CAAC,GAAG,IAAI,GAAG,gBAAgB,EAAE,EAAE;YACzD,MAAM,EAAE,MAAM;YACd,OAAO,EAAE,EAAE,GAAG,OAAO,EAAE,cAAc,EAAE,kBAAkB,EAAE;YAC3D,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,EAAE,GAAG,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC;YAChF,MAAM;SACP,CAAC,CAAA;QACF,IAAI,MAAM,CAAC,MAAM,KAAK,GAAG;YAAE,MAAM,IAAI,KAAK,CAAC,YAAY,CAAC,CAAA;QACxD,IAAI,MAAM,CAAC,MAAM,KAAK,GAAG;YAAE,MAAM,IAAI,KAAK,CAAC,UAAU,CAAC,CAAA;QACtD,IAAI,CAAC,MAAM,CAAC,EAAE;YAAE,MAAM,IAAI,KAAK,CAAC,mEAAmE,MAAM,CAAC,MAAM,MAAM,CAAC,MAAM,MAAM,CAAC,IAAI,EAAE,CAAC,CAAC,KAAK,CAAC,CAAC,EAAE,GAAG,CAAC,EAAE,CAAC,CAAA;QAC5J,MAAM,EAAE,EAAE,EAAE,GAAG,CAAC,MAAM,MAAM,CAAC,IAAI,EAAE,CAAmB,CAAA;QACtD,IAAI,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,QAAQ,EAAE,OAAO,EAAE,sFAAsF,IAAI,OAAO,GAAG,GAAG,KAAK,CAAC,CAAC,CAAC,OAAO,KAAK,EAAE,CAAC,CAAC,CAAC,EAAE,aAAa,EAAE,IAAI,EAAE,CAAC,CAAA;QAE7L,MAAM,MAAM,GAAG,GAAG,CAAC,MAAM,IAAI,IAAI,CAAA;QACjC,SAAS,CAAC;YACR,IAAI,MAAM,CAAC,OAAO;gBAAE,MAAM,IAAI,KAAK,CAAC,0FAA0F,CAAC,CAAA;YAC/H,MAAM,GAAG,GAAG,MAAM,OAAO,CAAC,GAAG,IAAI,GAAG,gBAAgB,IAAI,EAAE,EAAE,EAAE,EAAE,OAAO,EAAE,MAAM,EAAE,CAAC,CAAA;YAClF,IAAI,CAAC,GAAG,CAAC,EAAE;gBAAE,MAAM,IAAI,KAAK,CAAC,oDAAoD,EAAE,KAAK,GAAG,CAAC,MAAM,GAAG,CAAC,CAAA;YACtG,MAAM,KAAK,GAAG,CAAC,MAAM,GAAG,CAAC,IAAI,EAAE,CAAuE,CAAA;YACtG,IAAI,KAAK,CAAC,KAAK,KAAK,SAAS,IAAI,KAAK,CAAC,SAAS,IAAI,KAAK,CAAC,GAAG;gBAAE,OAAO,EAAE,GAAG,EAAE,KAAK,CAAC,GAAG,EAAE,SAAS,EAAE,KAAK,CAAC,SAAS,EAAE,CAAA;YACpH,IAAI,KAAK,CAAC,KAAK,KAAK,QAAQ,EAAE,CAAC;gBAC7B,MAAM,IAAI,KAAK,CAAC,6EAA6E,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC,MAAM,KAAK,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC,EAAE,GAAG,CAAC,CAAA;YACvI,CAAC;YACD,MAAM,IAAI,OAAO,CAAO,OAAO,CAAC,EAAE;gBAChC,MAAM,CAAC,GAAG,UAAU,CAAC,OAAO,EAAE,MAAM,CAAC,CAAA;gBACrC,MAAM,CAAC,gBAAgB,CAAC,OAAO,EAAE,GAAG,EAAE,GAAG,YAAY,CAAC,CAAC,CAAC,CAAC,CAAC,OAAO,EAAE,CAAA,CAAC,CAAC,EAAE,EAAE,IAAI,EAAE,IAAI,EAAE,CAAC,CAAA;YACxF,CAAC,CAAC,CAAA;QACJ,CAAC;IACH,CAAC;IAED;;;;;OAKG;IACK,MAAM,CAAC,OAA2C,EAAE,IAAuB;QACjF,IAAI,IAAI,KAAK,OAAO;YAAE,IAAI,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,QAAQ,EAAE,KAAK,EAAE,SAAS,OAAO,CAAC,GAAG,EAAE,EAAE,CAAC,CAAA;QAClF,MAAM,OAAO,GACX,IAAI,KAAK,OAAO;YACd,CAAC,CAAC,CAAC,uCAAuC,EAAE,EAAE,EAAE,qBAAqB,OAAO,CAAC,GAAG,EAAE,EAAE,uCAAuC,OAAO,CAAC,SAAS,EAAE,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC;YAC1J,CAAC,CAAC;gBACE,oGAAoG;gBACpG,6EAA6E;gBAC7E,EAAE;gBACF,qBAAqB,OAAO,CAAC,GAAG,EAAE;gBAClC,uCAAuC,OAAO,CAAC,SAAS,EAAE;aAC3D,CAAC,IAAI,CAAC,IAAI,CAAC,CAAA;QAClB,0FAA0F;QAC1F,8FAA8F;QAC9F,IAAI,CAAC,IAAI,CAAC;YACR,IAAI,EAAE,QAAQ;YACd,IAAI,EAAE,OAAO;YACb,SAAS,EAAE,OAAO,CAAC,SAAS;YAC5B,WAAW,EAAE,OAAO,CAAC,GAAG;YACxB,GAAG,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC,CAAC,EAAE,SAAS,EAAE,IAAI,CAAC,SAAS,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;SACzD,CAAC,CAAA;QACF,OAAO,EAAE,IAAI,EAAE,OAAO,EAAE,SAAS,EAAE,OAAO,CAAC,SAAS,EAAE,CAAA;IACxD,CAAC;IAED,oFAAoF;IACpF,2CAA2C;IAE3C,KAAK,CAAC,OAAO;QACX,IAAI,CAAC,QAAQ,GAAG,IAAI,CAAA;QACpB,KAAK,MAAM,UAAU,IAAI,IAAI,CAAC,WAAW;YAAE,UAAU,CAAC,KAAK,EAAE,CAAA;QAC7D,IAAI,CAAC,WAAW,CAAC,KAAK,EAAE,CAAA;IAC1B,CAAC;CACF"}

package/dist/driver/codex.d.ts

@@ -0,0 +1,99 @@
+import { type AgentCliParser, type SpawnLike } from './cli-session.js';
+import type { Driver, DriverEvent, DriverPromptOptions, DriverSession, DriverStartOptions, DriverTurn, DriverUsage } from './types.js';
+/**
+ * Codex's sandbox policy for the shell commands the model writes.
+ * `workspace-write` is our default: the agent can edit the workspace it was
+ * pointed at, but not the rest of the machine. It is the counterpart of Claude
+ * Code's `acceptEdits`, and the reason we never pass Codex's
+ * `--dangerously-bypass-approvals-and-sandbox`.
+ */
+export type CodexSandbox = 'read-only' | 'workspace-write' | 'danger-full-access';
+/** Options for {@link CodexDriver}. */
+export interface CodexDriverOptions {
+    /** CLI binary to spawn. Default `"codex"` (resolved on `PATH`). */
+    bin?: string;
+    /** Sandbox policy. Default `"workspace-write"`. */
+    sandbox?: CodexSandbox;
+    /** Extra CLI args appended verbatim (escape hatch). */
+    extraArgs?: string[];
+    /** Environment for the child process. Default `process.env`. */
+    env?: NodeJS.ProcessEnv;
+    /** `spawn` override for tests. Default `node:child_process.spawn`. */
+    spawn?: SpawnLike;
+}
+/**
+ * The second real {@link Driver} (#539): wraps the **Codex CLI** in its
+ * non-interactive mode (`codex exec --json`), on the user's own ChatGPT
+ * subscription — no API key (#495's "bring your own subscription").
+ *
+ * The seam always said "Claude Code today, Codex later", and this is that. Same
+ * black box: prompt it, let its own loop run, read the code it wrote.
+ *
+ * Three ways it differs from Claude Code, all of them the agent's business
+ * rather than ours:
+ *
+ * - **No system-prompt flag.** Codex has no `--append-system-prompt`, so the
+ *   framing is prepended to the prompt instead. Same words reach the agent.
+ * - **Tokens, no price.** Codex reports token counts but never a price, so usage
+ *   carries the counts and omits `costUsd` rather than claim a turn cost `$0`,
+ *   which would read as free (#540). The budget cap (#322) gates on a price, so
+ *   it cannot fire here; the CLI says so at startup instead of implying it.
+ * - **No quota read.** No `readQuota`, for the same reason: the seam is optional
+ *   precisely so an agent that can't report one simply doesn't.
+ */
+export declare class CodexDriver implements Driver {
+    private readonly opts;
+    readonly id = "codex";
+    constructor(opts?: CodexDriverOptions);
+    start(opts: DriverStartOptions): Promise<DriverSession>;
+}
+/** One workspace-bound Codex session. `prompt` is a fresh CLI invocation. */
+export declare class CodexSession implements DriverSession {
+    private readonly config;
+    private readonly startOpts;
+    readonly id: string;
+    readonly cwd: string;
+    constructor(config: CodexDriverOptions, startOpts: DriverStartOptions);
+    prompt(text: string, opts?: DriverPromptOptions): Promise<DriverTurn>;
+    readCode(path: string): Promise<string>;
+    dispose(): Promise<void>;
+    private buildArgs;
+}
+/**
+ * Parses Codex's `exec --json` output: one JSON event per line.
+ *
+ * The dialect, as observed on codex-cli 0.144.4:
+ * ```
+ * {"type":"thread.started","thread_id":"019f..."}
+ * {"type":"turn.started"}
+ * {"type":"item.completed","item":{"type":"agent_message","text":"..."}}
+ * {"type":"item.started","item":{"type":"file_change","status":"in_progress"}}
+ * {"type":"turn.completed","usage":{"input_tokens":12210,"output_tokens":5}}
+ * ```
+ */
+export declare class CodexJsonParser implements AgentCliParser {
+    private text;
+    private sessionId;
+    private usage;
+    push(line: string): DriverEvent[];
+    result(): DriverTurn;
+}
+/**
+ * Map Codex's `turn.completed` usage onto {@link DriverUsage}. The dialect is
+ * OpenAI's Responses API shape, flattened:
+ * `{input_tokens, cached_input_tokens, output_tokens, reasoning_output_tokens}`.
+ *
+ * Two things that shape the mapping, both verified against codex-cli 0.144.4:
+ *
+ * - `input_tokens` is the **total** input, cached included. Repeating one prompt
+ *   held it at 12218 while `cached_input_tokens` rose 9984 -> 12032; a non-cached
+ *   count would have fallen. So the uncached part is the difference, which is what
+ *   `inputTokens` means here.
+ * - `reasoning_output_tokens` is a **subset** of `output_tokens` (as
+ *   `cached_input_tokens` is of `input_tokens`), so adding it would double-count.
+ *
+ * No price, and no cache-*write* count: OpenAI caches implicitly and bills no
+ * separate write, so `cacheCreationTokens` is honestly 0 rather than a guess.
+ */
+export declare function parseCodexUsage(raw: unknown): DriverUsage | undefined;
+//# sourceMappingURL=codex.d.ts.map

package/dist/driver/codex.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"codex.d.ts","sourceRoot":"","sources":["../../src/driver/codex.ts"],"names":[],"mappings":"AACA,OAAO,EAAiB,KAAK,cAAc,EAAE,KAAK,SAAS,EAAE,MAAM,kBAAkB,CAAA;AAErF,OAAO,KAAK,EAAE,MAAM,EAAE,WAAW,EAAE,mBAAmB,EAAE,aAAa,EAAE,kBAAkB,EAAE,UAAU,EAAE,WAAW,EAAE,MAAM,YAAY,CAAA;AAEtI;;;;;;GAMG;AACH,MAAM,MAAM,YAAY,GAAG,WAAW,GAAG,iBAAiB,GAAG,oBAAoB,CAAA;AAEjF,uCAAuC;AACvC,MAAM,WAAW,kBAAkB;IACjC,mEAAmE;IACnE,GAAG,CAAC,EAAE,MAAM,CAAA;IACZ,mDAAmD;IACnD,OAAO,CAAC,EAAE,YAAY,CAAA;IACtB,uDAAuD;IACvD,SAAS,CAAC,EAAE,MAAM,EAAE,CAAA;IACpB,gEAAgE;IAChE,GAAG,CAAC,EAAE,MAAM,CAAC,UAAU,CAAA;IACvB,sEAAsE;IACtE,KAAK,CAAC,EAAE,SAAS,CAAA;CAClB;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,qBAAa,WAAY,YAAW,MAAM;IAE5B,OAAO,CAAC,QAAQ,CAAC,IAAI;IADjC,QAAQ,CAAC,EAAE,WAAU;IACrB,YAA6B,IAAI,GAAE,kBAAuB,EAAI;IAE9D,KAAK,CAAC,IAAI,EAAE,kBAAkB,GAAG,OAAO,CAAC,aAAa,CAAC,CAEtD;CACF;AAID,6EAA6E;AAC7E,qBAAa,YAAa,YAAW,aAAa;IAK9C,OAAO,CAAC,QAAQ,CAAC,MAAM;IACvB,OAAO,CAAC,QAAQ,CAAC,SAAS;IAL5B,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAA;IACnB,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAA;IAEpB,YACmB,MAAM,EAAE,kBAAkB,EAC1B,SAAS,EAAE,kBAAkB,EAI/C;IAED,MAAM,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,GAAE,mBAAwB,GAAG,OAAO,CAAC,UAAU,CAAC,CAiBxE;IAED,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAEtC;IAED,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC,CAGvB;IAED,OAAO,CAAC,SAAS;CASlB;AAED;;;;;;;;;;;GAWG;AACH,qBAAa,eAAgB,YAAW,cAAc;IACpD,OAAO,CAAC,IAAI,CAAK;IACjB,OAAO,CAAC,SAAS,CAAoB;IACrC,OAAO,CAAC,KAAK,CAAyB;IAEtC,IAAI,CAAC,IAAI,EAAE,MAAM,GAAG,WAAW,EAAE,CA4ChC;IAED,MAAM,IAAI,UAAU,CAQnB;CACF;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,eAAe,CAAC,GAAG,EAAE,OAAO,GAAG,WAAW,GAAG,SAAS,CAerE"}

package/dist/driver/codex.js

@@ -0,0 +1,190 @@
+import { spawn as nodeSpawn } from 'node:child_process';
+import { runCliSession } from './cli-session.js';
+import { combineFraming, combineSignals, makeEmit, readWorkspaceFile } from './session-support.js';
+/**
+ * The second real {@link Driver} (#539): wraps the **Codex CLI** in its
+ * non-interactive mode (`codex exec --json`), on the user's own ChatGPT
+ * subscription — no API key (#495's "bring your own subscription").
+ *
+ * The seam always said "Claude Code today, Codex later", and this is that. Same
+ * black box: prompt it, let its own loop run, read the code it wrote.
+ *
+ * Three ways it differs from Claude Code, all of them the agent's business
+ * rather than ours:
+ *
+ * - **No system-prompt flag.** Codex has no `--append-system-prompt`, so the
+ *   framing is prepended to the prompt instead. Same words reach the agent.
+ * - **Tokens, no price.** Codex reports token counts but never a price, so usage
+ *   carries the counts and omits `costUsd` rather than claim a turn cost `$0`,
+ *   which would read as free (#540). The budget cap (#322) gates on a price, so
+ *   it cannot fire here; the CLI says so at startup instead of implying it.
+ * - **No quota read.** No `readQuota`, for the same reason: the seam is optional
+ *   precisely so an agent that can't report one simply doesn't.
+ */
+export class CodexDriver {
+    opts;
+    id = 'codex';
+    constructor(opts = {}) {
+        this.opts = opts;
+    }
+    start(opts) {
+        return Promise.resolve(new CodexSession(this.opts, opts));
+    }
+}
+let sessionCounter = 0;
+/** One workspace-bound Codex session. `prompt` is a fresh CLI invocation. */
+export class CodexSession {
+    config;
+    startOpts;
+    id;
+    cwd;
+    constructor(config, startOpts) {
+        this.config = config;
+        this.startOpts = startOpts;
+        this.cwd = startOpts.cwd;
+        this.id = `codex-${++sessionCounter}`;
+    }
+    prompt(text, opts = {}) {
+        // Codex takes no system-prompt flag, so the framing rides in front of the
+        // prompt. Blank-line separated, so it reads as its own block.
+        const framing = combineFraming(this.startOpts.system, opts.system);
+        const prompt = framing ? `${framing}\n\n${text}` : text;
+        return runCliSession({
+            bin: this.config.bin ?? 'codex',
+            args: this.buildArgs(),
+            cwd: this.cwd,
+            env: this.config.env ?? process.env,
+            prompt,
+            spawn: this.config.spawn ?? nodeSpawn,
+            emit: makeEmit(this.startOpts.onEvent, 'codex'),
+            signals: combineSignals(this.startOpts.signal, opts.signal),
+            parser: new CodexJsonParser(),
+            driver: 'codex',
+        });
+    }
+    readCode(path) {
+        return readWorkspaceFile(this.cwd, path);
+    }
+    dispose() {
+        // Each prompt spawns and reaps its own process; nothing durable to free.
+        return Promise.resolve();
+    }
+    buildArgs() {
+        // No prompt argument: it goes over stdin, so a long one never hits the
+        // arg-length limit. `--skip-git-repo-check` because Codex otherwise refuses
+        // to run outside a git repo, and a workspace may legitimately not be one yet.
+        const args = ['exec', '--json', '--skip-git-repo-check', '--sandbox', this.config.sandbox ?? 'workspace-write', '-C', this.cwd];
+        if (this.startOpts.model)
+            args.push('-m', this.startOpts.model);
+        if (this.config.extraArgs)
+            args.push(...this.config.extraArgs);
+        return args;
+    }
+}
+/**
+ * Parses Codex's `exec --json` output: one JSON event per line.
+ *
+ * The dialect, as observed on codex-cli 0.144.4:
+ * ```
+ * {"type":"thread.started","thread_id":"019f..."}
+ * {"type":"turn.started"}
+ * {"type":"item.completed","item":{"type":"agent_message","text":"..."}}
+ * {"type":"item.started","item":{"type":"file_change","status":"in_progress"}}
+ * {"type":"turn.completed","usage":{"input_tokens":12210,"output_tokens":5}}
+ * ```
+ */
+export class CodexJsonParser {
+    text = '';
+    sessionId;
+    usage;
+    push(line) {
+        let obj;
+        try {
+            obj = JSON.parse(line);
+        }
+        catch {
+            return []; // Banners and other noise: not every line is an event.
+        }
+        // `null` parses, so the catch above lets it through and every field read below throws — from
+        // inside a readline handler, where nothing catches it. Noise is noise whatever it parses to.
+        if (typeof obj !== 'object' || obj === null)
+            return [];
+        const type = obj['type'];
+        if (type === 'thread.started') {
+            const id = obj['thread_id'];
+            if (typeof id === 'string')
+                this.sessionId = id;
+            return [];
+        }
+        if (type === 'turn.completed') {
+            const usage = parseCodexUsage(obj['usage']);
+            if (usage)
+                this.usage = usage;
+            return [];
+        }
+        const item = obj['item'];
+        if (typeof item !== 'object' || item === null)
+            return [];
+        const itemObj = item;
+        const itemType = itemObj['type'];
+        if (itemType === 'agent_message' && type === 'item.completed') {
+            const text = itemObj['text'];
+            if (typeof text !== 'string')
+                return [];
+            // Codex narrates in several messages; the last is its answer, and the
+            // rest are progress. Keep the last as the turn, stream them all.
+            this.text = text;
+            return [{ type: 'text', text }];
+        }
+        // Any other item is the agent using a tool. We surface the kind only, never
+        // the arguments: the seam is the code and the outcome, not the tool calls.
+        if (type === 'item.started' && typeof itemType === 'string') {
+            return [{ type: 'action', label: itemType }];
+        }
+        return [];
+    }
+    result() {
+        // Tokens but no `costUsd`: Codex prices nothing, and a `$0` would read as free
+        // rather than as "we don't know" (#540).
+        return {
+            text: this.text,
+            ...(this.sessionId ? { sessionId: this.sessionId } : {}),
+            ...(this.usage ? { usage: this.usage } : {}),
+        };
+    }
+}
+/**
+ * Map Codex's `turn.completed` usage onto {@link DriverUsage}. The dialect is
+ * OpenAI's Responses API shape, flattened:
+ * `{input_tokens, cached_input_tokens, output_tokens, reasoning_output_tokens}`.
+ *
+ * Two things that shape the mapping, both verified against codex-cli 0.144.4:
+ *
+ * - `input_tokens` is the **total** input, cached included. Repeating one prompt
+ *   held it at 12218 while `cached_input_tokens` rose 9984 -> 12032; a non-cached
+ *   count would have fallen. So the uncached part is the difference, which is what
+ *   `inputTokens` means here.
+ * - `reasoning_output_tokens` is a **subset** of `output_tokens` (as
+ *   `cached_input_tokens` is of `input_tokens`), so adding it would double-count.
+ *
+ * No price, and no cache-*write* count: OpenAI caches implicitly and bills no
+ * separate write, so `cacheCreationTokens` is honestly 0 rather than a guess.
+ */
+export function parseCodexUsage(raw) {
+    if (typeof raw !== 'object' || raw === null)
+        return undefined;
+    const usage = raw;
+    const num = (key) => {
+        const value = usage[key];
+        return typeof value === 'number' && Number.isFinite(value) && value >= 0 ? value : 0;
+    };
+    const input = num('input_tokens');
+    const cached = Math.min(num('cached_input_tokens'), input);
+    return {
+        inputTokens: input - cached,
+        outputTokens: num('output_tokens'),
+        cacheReadTokens: cached,
+        cacheCreationTokens: 0,
+    };
+}
+//# sourceMappingURL=codex.js.map

package/dist/driver/codex.js.map

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

package/dist/driver/fake.d.ts

@@ -0,0 +1,54 @@
+import type { Driver, DriverPromptOptions, DriverSession, DriverStartOptions, DriverTurn, DriverUsage } from './types.js';
+/** One scripted turn the {@link FakeDriver} replays. */
+export interface FakeTurn {
+    /** The final assistant text. */
+    text: string;
+    /** Tool names to emit as `action` events before the result (visual only). */
+    actions?: string[];
+    /** Token + cost accounting to report for this turn (#322). Omitted = no usage. */
+    usage?: DriverUsage;
+}
+/** Options for {@link FakeDriver}. */
+export interface FakeDriverOptions {
+    /**
+     * Scripted turns, consumed in order across all `prompt` calls of a session.
+     * Once exhausted the last one repeats, so a short script never starves a
+     * longer run. Ignored when {@link respond} is set.
+     */
+    turns?: FakeTurn[];
+    /** Answer dynamically from the prompt. Takes precedence over {@link turns}. */
+    respond?: (prompt: string, index: number) => FakeTurn | string;
+    /** Files each session is pre-seeded with, exposed via {@link DriverSession.readCode}. */
+    files?: Record<string, string>;
+    /** Session id to report (default `"fake-session"`). */
+    sessionId?: string;
+}
+/**
+ * An in-memory {@link Driver} for tests and `FRAMEWORK_FAKE` runs: it never spawns a
+ * process, replays scripted turns deterministically, and emits the same
+ * {@link DriverEvent} shape a real driver does. Mirrors `AiFake` /
+ * `FakeRunner`, so the whole flow runs offline with no CLI and no model.
+ */
+export declare class FakeDriver implements Driver {
+    private readonly opts;
+    readonly id = "fake";
+    constructor(opts?: FakeDriverOptions);
+    start(opts: DriverStartOptions): Promise<FakeDriverSession>;
+}
+/** A single {@link FakeDriver} session. Records every prompt for assertions. */
+export declare class FakeDriverSession implements DriverSession {
+    private readonly config;
+    private readonly startOpts;
+    readonly id: string;
+    readonly cwd: string;
+    /** Every prompt this session received, in order. */
+    readonly prompts: string[];
+    private index;
+    constructor(config: FakeDriverOptions, startOpts: DriverStartOptions);
+    prompt(text: string, opts?: DriverPromptOptions): Promise<DriverTurn>;
+    readCode(path: string): Promise<string>;
+    dispose(): Promise<void>;
+    private resolveTurn;
+    private emit;
+}
+//# sourceMappingURL=fake.d.ts.map

package/dist/driver/fake.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"fake.d.ts","sourceRoot":"","sources":["../../src/driver/fake.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,MAAM,EAAe,mBAAmB,EAAE,aAAa,EAAE,kBAAkB,EAAE,UAAU,EAAE,WAAW,EAAE,MAAM,YAAY,CAAA;AAGtI,wDAAwD;AACxD,MAAM,WAAW,QAAQ;IACvB,gCAAgC;IAChC,IAAI,EAAE,MAAM,CAAA;IACZ,6EAA6E;IAC7E,OAAO,CAAC,EAAE,MAAM,EAAE,CAAA;IAClB,kFAAkF;IAClF,KAAK,CAAC,EAAE,WAAW,CAAA;CACpB;AAED,sCAAsC;AACtC,MAAM,WAAW,iBAAiB;IAChC;;;;OAIG;IACH,KAAK,CAAC,EAAE,QAAQ,EAAE,CAAA;IAClB,+EAA+E;IAC/E,OAAO,CAAC,EAAE,CAAC,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,KAAK,QAAQ,GAAG,MAAM,CAAA;IAC9D,yFAAyF;IACzF,KAAK,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;IAC9B,uDAAuD;IACvD,SAAS,CAAC,EAAE,MAAM,CAAA;CACnB;AAMD;;;;;GAKG;AACH,qBAAa,UAAW,YAAW,MAAM;IAE3B,OAAO,CAAC,QAAQ,CAAC,IAAI;IADjC,QAAQ,CAAC,EAAE,UAAS;IACpB,YAA6B,IAAI,GAAE,iBAAsB,EAAI;IAG7D,KAAK,CAAC,IAAI,EAAE,kBAAkB,GAAG,OAAO,CAAC,iBAAiB,CAAC,CAE1D;CACF;AAED,gFAAgF;AAChF,qBAAa,iBAAkB,YAAW,aAAa;IAQnD,OAAO,CAAC,QAAQ,CAAC,MAAM;IACvB,OAAO,CAAC,QAAQ,CAAC,SAAS;IAR5B,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAA;IACnB,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAA;IACpB,oDAAoD;IACpD,QAAQ,CAAC,OAAO,EAAE,MAAM,EAAE,CAAK;IAC/B,OAAO,CAAC,KAAK,CAAI;IAEjB,YACmB,MAAM,EAAE,iBAAiB,EACzB,SAAS,EAAE,kBAAkB,EAI/C;IAED,MAAM,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,GAAE,mBAAwB,GAAG,OAAO,CAAC,UAAU,CAAC,CAcxE;IAED,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAItC;IAED,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC,CAEvB;IAED,OAAO,CAAC,WAAW;IAOnB,OAAO,CAAC,IAAI;CAGb"}