agent-relay 7.1.1 → 8.0.2

package/dist/cli/lib/attach-view.d.ts.map

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

package/dist/cli/lib/attach-view.js

@@ -0,0 +1,244 @@
+/**
+ * `agent-relay view <name>` — read-only PTY stream client.
+ *
+ * Connects to a running broker's `/ws` WebSocket, filters the event stream
+ * for `worker_stream` frames matching the requested agent name, and writes
+ * each chunk's raw bytes to stdout (preserving ANSI escapes).
+ *
+ * No keystrokes are forwarded — the broker keeps doing whatever it's doing.
+ * Ctrl+C exits the client cleanly; the agent keeps running under the broker.
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+import WebSocket from 'ws';
+import { getProjectPaths } from '@agent-relay/config';
+import { captureAndRenderSnapshot, } from '../lib/attach.js';
+import { defaultExit, runSignalHandler } from '../lib/exit.js';
+function readConnectionFileFromDisk(stateDir) {
+    const connPath = path.join(stateDir, 'connection.json');
+    try {
+        const raw = fs.readFileSync(connPath, 'utf-8');
+        return JSON.parse(raw);
+    }
+    catch {
+        return null;
+    }
+}
+function defaultStateDir() {
+    // Match the Rust broker's discovery convention: `.agentworkforce/relay/` under the
+    // project root (resolved the same way the rest of the CLI does it).
+    const projectRoot = getProjectPaths().projectRoot;
+    return path.join(projectRoot, '.agentworkforce/relay');
+}
+function withDefaults(overrides = {}) {
+    return {
+        readConnectionFile: readConnectionFileFromDisk,
+        getDefaultStateDir: defaultStateDir,
+        env: process.env,
+        createWebSocket: (url, headers) => new WebSocket(url, { headers }),
+        writeChunk: (chunk) => {
+            process.stdout.write(chunk);
+        },
+        onSignal: (signal, handler) => {
+            const listener = () => runSignalHandler(handler);
+            process.on(signal, listener);
+            return () => process.off(signal, listener);
+        },
+        log: (...args) => console.error(...args),
+        error: (...args) => console.error(...args),
+        exit: defaultExit,
+        fetch: (input, init) => fetch(input, init),
+        captureAndRenderSnapshot,
+        ...overrides,
+    };
+}
+function isStringObject(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+function readString(obj, key) {
+    if (!isStringObject(obj))
+        return undefined;
+    const value = obj[key];
+    if (typeof value !== 'string')
+        return undefined;
+    const trimmed = value.trim();
+    return trimmed === '' ? undefined : trimmed;
+}
+/**
+ * Resolve the broker connection to use for `view`, in priority order:
+ *
+ *  1. `--broker-url` / `--api-key` CLI flags
+ *  2. `RELAY_BROKER_URL` / `RELAY_BROKER_API_KEY` environment variables
+ *  3. `<state-dir>/connection.json` (default `.agentworkforce/relay/connection.json`)
+ *
+ * Matches the resolution order used by `agent-relay-broker dump-pty` so users
+ * don't have to learn two patterns.
+ */
+export function resolveViewBrokerConnection(options, deps) {
+    const explicitUrl = trimOrUndefined(options.brokerUrl);
+    const envUrl = trimOrUndefined(deps.env.RELAY_BROKER_URL);
+    const stateDir = options.stateDir ? path.resolve(options.stateDir) : deps.getDefaultStateDir();
+    const connectionFile = deps.readConnectionFile(stateDir);
+    const fileUrl = readString(connectionFile, 'url');
+    const resolveApiKey = () => {
+        const explicit = trimOrUndefined(options.apiKey);
+        if (explicit)
+            return explicit;
+        const fromEnv = trimOrUndefined(deps.env.RELAY_BROKER_API_KEY);
+        if (fromEnv)
+            return fromEnv;
+        return readString(connectionFile, 'api_key');
+    };
+    const url = explicitUrl ?? envUrl ?? fileUrl;
+    if (!url)
+        return null;
+    return {
+        url: url.replace(/\/+$/, ''),
+        apiKey: resolveApiKey(),
+    };
+}
+function trimOrUndefined(value) {
+    const trimmed = value?.trim();
+    return trimmed ? trimmed : undefined;
+}
+/** Convert an `http(s)://host:port` base URL to the matching `ws(s)://…/ws`. */
+export function toWsUrl(baseUrl) {
+    return `${baseUrl.replace(/^http/, 'ws')}/ws`;
+}
+/**
+ * Inspect a single WebSocket message and, if it's a `worker_stream` event for
+ * the requested agent, return the raw chunk string. Returns `null` for events
+ * that don't match (other kinds, other agents, malformed JSON, etc.) so the
+ * caller can ignore them.
+ *
+ * Exported for unit testing the filter in isolation from any WebSocket.
+ */
+export function extractMatchingChunk(rawMessage, agentName) {
+    let parsed;
+    try {
+        parsed = JSON.parse(rawMessage);
+    }
+    catch {
+        return null;
+    }
+    if (!isStringObject(parsed))
+        return null;
+    if (parsed.kind !== 'worker_stream')
+        return null;
+    if (parsed.name !== agentName)
+        return null;
+    const chunk = parsed.chunk;
+    if (typeof chunk !== 'string')
+        return null;
+    return chunk;
+}
+/**
+ * Open the read-only view stream and run until the WebSocket closes, the
+ * caller signals SIGINT/SIGTERM, or an unrecoverable error occurs. Resolves
+ * with the exit code the CLI should propagate.
+ */
+export async function runViewSession(agentName, options, deps) {
+    // Normalize once so every downstream lookup, WS-event match, and
+    // error message uses the same value. A stray space in the raw input
+    // otherwise turns into a silent 404 (broker stores names verbatim).
+    const name = agentName.trim();
+    if (!name) {
+        deps.error('Error: agent name is required');
+        return 1;
+    }
+    const connection = resolveViewBrokerConnection(options, deps);
+    if (!connection) {
+        deps.error('Error: could not locate broker connection. Pass --broker-url, set RELAY_BROKER_URL, ' +
+            'or run from a directory containing .agentworkforce/relay/connection.json.');
+        return 1;
+    }
+    // Render the agent's current screen before the live stream begins, so
+    // the user sees what's there instead of staring at a blank terminal
+    // until the agent happens to produce more output. Hard errors
+    // (`not_found` / `no_pty`) abort — there's nothing meaningful to view.
+    // Transient errors (`unavailable` / `transport_error`) are surfaced as
+    // a warning and we fall through to the live stream; the agent may
+    // still produce useful output even if the snapshot couldn't be served.
+    const snapshot = await deps.captureAndRenderSnapshot({ url: connection.url, apiKey: connection.apiKey }, name, { fetch: deps.fetch, writeChunk: deps.writeChunk });
+    switch (snapshot.status) {
+        case 'ok':
+            break;
+        case 'not_found':
+            deps.error(`Error: ${snapshot.message ?? `no agent named '${name}'`}`);
+            return 1;
+        case 'no_pty':
+            deps.error(`Error: ${snapshot.message ?? `agent '${name}' has no PTY to view`}`);
+            return 1;
+        case 'unavailable':
+        case 'transport_error':
+            deps.log(`[view] could not capture initial screen (${snapshot.message ?? snapshot.status}); streaming live output only`);
+            break;
+    }
+    const wsUrl = toWsUrl(connection.url);
+    const headers = {};
+    if (connection.apiKey) {
+        headers['X-API-Key'] = connection.apiKey;
+    }
+    return new Promise((resolve) => {
+        let settled = false;
+        const cleanupSignals = [];
+        const finish = (code) => {
+            if (settled)
+                return;
+            settled = true;
+            for (const cleanup of cleanupSignals.splice(0)) {
+                try {
+                    cleanup();
+                }
+                catch {
+                    // best effort
+                }
+            }
+            try {
+                socket.close(1000, 'view client exiting');
+            }
+            catch {
+                // best effort — already closed
+            }
+            resolve(code);
+        };
+        const socket = deps.createWebSocket(wsUrl, headers);
+        for (const signal of ['SIGINT', 'SIGTERM']) {
+            const cleanup = deps.onSignal(signal, () => finish(0));
+            if (typeof cleanup === 'function')
+                cleanupSignals.push(cleanup);
+        }
+        socket.on('open', () => {
+            deps.log(`[view] streaming ${name} from ${connection.url} (Ctrl+C to exit)`);
+        });
+        socket.on('message', (data) => {
+            const text = typeof data === 'string' ? data : Buffer.isBuffer(data) ? data.toString('utf-8') : String(data);
+            const chunk = extractMatchingChunk(text, name);
+            if (chunk !== null) {
+                deps.writeChunk(chunk);
+            }
+        });
+        socket.on('error', (err) => {
+            deps.error(`[view] WebSocket error: ${err.message}`);
+            finish(1);
+        });
+        socket.on('close', (code, reason) => {
+            if (settled)
+                return;
+            const reasonText = reason && reason.length > 0 ? reason.toString('utf-8') : '';
+            if (code === 1000 || code === 1005) {
+                // Normal closure (server shut down or sent close frame without status)
+                finish(0);
+            }
+            else {
+                deps.error(`[view] connection closed (code: ${code}${reasonText ? `, reason: ${reasonText}` : ''})`);
+                finish(1);
+            }
+        });
+    });
+}
+/** Run a view session with default dependencies. Used by `runtime agent attach --mode view`. */
+export function attachView(name, options, overrides = {}) {
+    return runViewSession(name, options, withDefaults(overrides));
+}
+//# sourceMappingURL=attach-view.js.map

package/dist/cli/lib/attach-view.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"attach-view.js","sourceRoot":"","sources":["../../../src/cli/lib/attach-view.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,EAAE,MAAM,SAAS,CAAC;AACzB,OAAO,IAAI,MAAM,WAAW,CAAC;AAE7B,OAAO,SAAS,MAAM,IAAI,CAAC;AAE3B,OAAO,EAAE,eAAe,EAAE,MAAM,qBAAqB,CAAC;AAEtD,OAAO,EACL,wBAAwB,GAGzB,MAAM,kBAAkB,CAAC;AAC1B,OAAO,EAAE,WAAW,EAAE,gBAAgB,EAAE,MAAM,gBAAgB,CAAC;AA0D/D,SAAS,0BAA0B,CAAC,QAAgB;IAClD,MAAM,QAAQ,GAAG,IAAI,CAAC,IAAI,CAAC,QAAQ,EAAE,iBAAiB,CAAC,CAAC;IACxD,IAAI,CAAC;QACH,MAAM,GAAG,GAAG,EAAE,CAAC,YAAY,CAAC,QAAQ,EAAE,OAAO,CAAC,CAAC;QAC/C,OAAO,IAAI,CAAC,KAAK,CAAC,GAAG,CAAY,CAAC;IACpC,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,IAAI,CAAC;IACd,CAAC;AACH,CAAC;AAED,SAAS,eAAe;IACtB,mFAAmF;IACnF,oEAAoE;IACpE,MAAM,WAAW,GAAG,eAAe,EAAE,CAAC,WAAW,CAAC;IAClD,OAAO,IAAI,CAAC,IAAI,CAAC,WAAW,EAAE,uBAAuB,CAAC,CAAC;AACzD,CAAC;AAED,SAAS,YAAY,CAAC,YAAuC,EAAE;IAC7D,OAAO;QACL,kBAAkB,EAAE,0BAA0B;QAC9C,kBAAkB,EAAE,eAAe;QACnC,GAAG,EAAE,OAAO,CAAC,GAAG;QAChB,eAAe,EAAE,CAAC,GAAG,EAAE,OAAO,EAAE,EAAE,CAAC,IAAI,SAAS,CAAC,GAAG,EAAE,EAAE,OAAO,EAAE,CAAkB;QACnF,UAAU,EAAE,CAAC,KAAK,EAAE,EAAE;YACpB,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC;QAC9B,CAAC;QACD,QAAQ,EAAE,CAAC,MAAM,EAAE,OAAO,EAAE,EAAE;YAC5B,MAAM,QAAQ,GAAG,GAAG,EAAE,CAAC,gBAAgB,CAAC,OAAO,CAAC,CAAC;YACjD,OAAO,CAAC,EAAE,CAAC,MAAM,EAAE,QAAQ,CAAC,CAAC;YAC7B,OAAO,GAAG,EAAE,CAAC,OAAO,CAAC,GAAG,CAAC,MAAM,EAAE,QAAQ,CAAC,CAAC;QAC7C,CAAC;QACD,GAAG,EAAE,CAAC,GAAG,IAAe,EAAE,EAAE,CAAC,OAAO,CAAC,KAAK,CAAC,GAAG,IAAI,CAAC;QACnD,KAAK,EAAE,CAAC,GAAG,IAAe,EAAE,EAAE,CAAC,OAAO,CAAC,KAAK,CAAC,GAAG,IAAI,CAAC;QACrD,IAAI,EAAE,WAAW;QACjB,KAAK,EAAE,CAAC,KAAK,EAAE,IAAI,EAAE,EAAE,CAAC,KAAK,CAAC,KAAK,EAAE,IAAI,CAAC;QAC1C,wBAAwB;QACxB,GAAG,SAAS;KACb,CAAC;AACJ,CAAC;AAED,SAAS,cAAc,CAAC,KAAc;IACpC,OAAO,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,KAAK,IAAI,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC;AAC9E,CAAC;AAED,SAAS,UAAU,CAAC,GAAY,EAAE,GAAW;IAC3C,IAAI,CAAC,cAAc,CAAC,GAAG,CAAC;QAAE,OAAO,SAAS,CAAC;IAC3C,MAAM,KAAK,GAAG,GAAG,CAAC,GAAG,CAAC,CAAC;IACvB,IAAI,OAAO,KAAK,KAAK,QAAQ;QAAE,OAAO,SAAS,CAAC;IAChD,MAAM,OAAO,GAAG,KAAK,CAAC,IAAI,EAAE,CAAC;IAC7B,OAAO,OAAO,KAAK,EAAE,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,OAAO,CAAC;AAC9C,CAAC;AAED;;;;;;;;;GASG;AACH,MAAM,UAAU,2BAA2B,CACzC,OAAmE,EACnE,IAAsB;IAEtB,MAAM,WAAW,GAAG,eAAe,CAAC,OAAO,CAAC,SAAS,CAAC,CAAC;IACvD,MAAM,MAAM,GAAG,eAAe,CAAC,IAAI,CAAC,GAAG,CAAC,gBAAgB,CAAC,CAAC;IAC1D,MAAM,QAAQ,GAAG,OAAO,CAAC,QAAQ,CAAC,CAAC,CAAC,IAAI,CAAC,OAAO,CAAC,OAAO,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,kBAAkB,EAAE,CAAC;IAC/F,MAAM,cAAc,GAAG,IAAI,CAAC,kBAAkB,CAAC,QAAQ,CAAC,CAAC;IACzD,MAAM,OAAO,GAAG,UAAU,CAAC,cAAc,EAAE,KAAK,CAAC,CAAC;IAElD,MAAM,aAAa,GAAG,GAAuB,EAAE;QAC7C,MAAM,QAAQ,GAAG,eAAe,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC;QACjD,IAAI,QAAQ;YAAE,OAAO,QAAQ,CAAC;QAC9B,MAAM,OAAO,GAAG,eAAe,CAAC,IAAI,CAAC,GAAG,CAAC,oBAAoB,CAAC,CAAC;QAC/D,IAAI,OAAO;YAAE,OAAO,OAAO,CAAC;QAC5B,OAAO,UAAU,CAAC,cAAc,EAAE,SAAS,CAAC,CAAC;IAC/C,CAAC,CAAC;IAEF,MAAM,GAAG,GAAG,WAAW,IAAI,MAAM,IAAI,OAAO,CAAC;IAC7C,IAAI,CAAC,GAAG;QAAE,OAAO,IAAI,CAAC;IAEtB,OAAO;QACL,GAAG,EAAE,GAAG,CAAC,OAAO,CAAC,MAAM,EAAE,EAAE,CAAC;QAC5B,MAAM,EAAE,aAAa,EAAE;KACxB,CAAC;AACJ,CAAC;AAED,SAAS,eAAe,CAAC,KAAyB;IAChD,MAAM,OAAO,GAAG,KAAK,EAAE,IAAI,EAAE,CAAC;IAC9B,OAAO,OAAO,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,SAAS,CAAC;AACvC,CAAC;AAED,gFAAgF;AAChF,MAAM,UAAU,OAAO,CAAC,OAAe;IACrC,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC,OAAO,EAAE,IAAI,CAAC,KAAK,CAAC;AAChD,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,oBAAoB,CAAC,UAAkB,EAAE,SAAiB;IACxE,IAAI,MAAe,CAAC;IACpB,IAAI,CAAC;QACH,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,UAAU,CAAC,CAAC;IAClC,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,IAAI,CAAC;IACd,CAAC;IACD,IAAI,CAAC,cAAc,CAAC,MAAM,CAAC;QAAE,OAAO,IAAI,CAAC;IACzC,IAAI,MAAM,CAAC,IAAI,KAAK,eAAe;QAAE,OAAO,IAAI,CAAC;IACjD,IAAI,MAAM,CAAC,IAAI,KAAK,SAAS;QAAE,OAAO,IAAI,CAAC;IAC3C,MAAM,KAAK,GAAG,MAAM,CAAC,KAAK,CAAC;IAC3B,IAAI,OAAO,KAAK,KAAK,QAAQ;QAAE,OAAO,IAAI,CAAC;IAC3C,OAAO,KAAK,CAAC;AACf,CAAC;AAED;;;;GAIG;AACH,MAAM,CAAC,KAAK,UAAU,cAAc,CAClC,SAAiB,EACjB,OAAmE,EACnE,IAAsB;IAEtB,iEAAiE;IACjE,oEAAoE;IACpE,oEAAoE;IACpE,MAAM,IAAI,GAAG,SAAS,CAAC,IAAI,EAAE,CAAC;IAC9B,IAAI,CAAC,IAAI,EAAE,CAAC;QACV,IAAI,CAAC,KAAK,CAAC,+BAA+B,CAAC,CAAC;QAC5C,OAAO,CAAC,CAAC;IACX,CAAC;IAED,MAAM,UAAU,GAAG,2BAA2B,CAAC,OAAO,EAAE,IAAI,CAAC,CAAC;IAC9D,IAAI,CAAC,UAAU,EAAE,CAAC;QAChB,IAAI,CAAC,KAAK,CACR,sFAAsF;YACpF,2EAA2E,CAC9E,CAAC;QACF,OAAO,CAAC,CAAC;IACX,CAAC;IAED,sEAAsE;IACtE,oEAAoE;IACpE,8DAA8D;IAC9D,uEAAuE;IACvE,uEAAuE;IACvE,kEAAkE;IAClE,uEAAuE;IACvE,MAAM,QAAQ,GAAG,MAAM,IAAI,CAAC,wBAAwB,CAClD,EAAE,GAAG,EAAE,UAAU,CAAC,GAAG,EAAE,MAAM,EAAE,UAAU,CAAC,MAAM,EAAE,EAClD,IAAI,EACJ,EAAE,KAAK,EAAE,IAAI,CAAC,KAAK,EAAE,UAAU,EAAE,IAAI,CAAC,UAAU,EAAE,CACnD,CAAC;IACF,QAAQ,QAAQ,CAAC,MAAM,EAAE,CAAC;QACxB,KAAK,IAAI;YACP,MAAM;QACR,KAAK,WAAW;YACd,IAAI,CAAC,KAAK,CAAC,UAAU,QAAQ,CAAC,OAAO,IAAI,mBAAmB,IAAI,GAAG,EAAE,CAAC,CAAC;YACvE,OAAO,CAAC,CAAC;QACX,KAAK,QAAQ;YACX,IAAI,CAAC,KAAK,CAAC,UAAU,QAAQ,CAAC,OAAO,IAAI,UAAU,IAAI,sBAAsB,EAAE,CAAC,CAAC;YACjF,OAAO,CAAC,CAAC;QACX,KAAK,aAAa,CAAC;QACnB,KAAK,iBAAiB;YACpB,IAAI,CAAC,GAAG,CACN,4CAA4C,QAAQ,CAAC,OAAO,IAAI,QAAQ,CAAC,MAAM,+BAA+B,CAC/G,CAAC;YACF,MAAM;IACV,CAAC;IAED,MAAM,KAAK,GAAG,OAAO,CAAC,UAAU,CAAC,GAAG,CAAC,CAAC;IACtC,MAAM,OAAO,GAA2B,EAAE,CAAC;IAC3C,IAAI,UAAU,CAAC,MAAM,EAAE,CAAC;QACtB,OAAO,CAAC,WAAW,CAAC,GAAG,UAAU,CAAC,MAAM,CAAC;IAC3C,CAAC;IAED,OAAO,IAAI,OAAO,CAAS,CAAC,OAAO,EAAE,EAAE;QACrC,IAAI,OAAO,GAAG,KAAK,CAAC;QACpB,MAAM,cAAc,GAAsB,EAAE,CAAC;QAC7C,MAAM,MAAM,GAAG,CAAC,IAAY,EAAE,EAAE;YAC9B,IAAI,OAAO;gBAAE,OAAO;YACpB,OAAO,GAAG,IAAI,CAAC;YACf,KAAK,MAAM,OAAO,IAAI,cAAc,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,CAAC;gBAC/C,IAAI,CAAC;oBACH,OAAO,EAAE,CAAC;gBACZ,CAAC;gBAAC,MAAM,CAAC;oBACP,cAAc;gBAChB,CAAC;YACH,CAAC;YACD,IAAI,CAAC;gBACH,MAAM,CAAC,KAAK,CAAC,IAAI,EAAE,qBAAqB,CAAC,CAAC;YAC5C,CAAC;YAAC,MAAM,CAAC;gBACP,+BAA+B;YACjC,CAAC;YACD,OAAO,CAAC,IAAI,CAAC,CAAC;QAChB,CAAC,CAAC;QAEF,MAAM,MAAM,GAAG,IAAI,CAAC,eAAe,CAAC,KAAK,EAAE,OAAO,CAAC,CAAC;QAEpD,KAAK,MAAM,MAAM,IAAI,CAAC,QAAQ,EAAE,SAAS,CAAU,EAAE,CAAC;YACpD,MAAM,OAAO,GAAG,IAAI,CAAC,QAAQ,CAAC,MAAM,EAAE,GAAG,EAAE,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,CAAC;YACvD,IAAI,OAAO,OAAO,KAAK,UAAU;gBAAE,cAAc,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;QAClE,CAAC;QAED,MAAM,CAAC,EAAE,CAAC,MAAM,EAAE,GAAG,EAAE;YACrB,IAAI,CAAC,GAAG,CAAC,oBAAoB,IAAI,SAAS,UAAU,CAAC,GAAG,mBAAmB,CAAC,CAAC;QAC/E,CAAC,CAAC,CAAC;QAEH,MAAM,CAAC,EAAE,CAAC,SAAS,EAAE,CAAC,IAAI,EAAE,EAAE;YAC5B,MAAM,IAAI,GACR,OAAO,IAAI,KAAK,QAAQ,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,MAAM,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,QAAQ,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC;YAClG,MAAM,KAAK,GAAG,oBAAoB,CAAC,IAAI,EAAE,IAAI,CAAC,CAAC;YAC/C,IAAI,KAAK,KAAK,IAAI,EAAE,CAAC;gBACnB,IAAI,CAAC,UAAU,CAAC,KAAK,CAAC,CAAC;YACzB,CAAC;QACH,CAAC,CAAC,CAAC;QAEH,MAAM,CAAC,EAAE,CAAC,OAAO,EAAE,CAAC,GAAU,EAAE,EAAE;YAChC,IAAI,CAAC,KAAK,CAAC,2BAA2B,GAAG,CAAC,OAAO,EAAE,CAAC,CAAC;YACrD,MAAM,CAAC,CAAC,CAAC,CAAC;QACZ,CAAC,CAAC,CAAC;QAEH,MAAM,CAAC,EAAE,CAAC,OAAO,EAAE,CAAC,IAAY,EAAE,MAAc,EAAE,EAAE;YAClD,IAAI,OAAO;gBAAE,OAAO;YACpB,MAAM,UAAU,GAAG,MAAM,IAAI,MAAM,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,QAAQ,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC;YAC/E,IAAI,IAAI,KAAK,IAAI,IAAI,IAAI,KAAK,IAAI,EAAE,CAAC;gBACnC,uEAAuE;gBACvE,MAAM,CAAC,CAAC,CAAC,CAAC;YACZ,CAAC;iBAAM,CAAC;gBACN,IAAI,CAAC,KAAK,CAAC,mCAAmC,IAAI,GAAG,UAAU,CAAC,CAAC,CAAC,aAAa,UAAU,EAAE,CAAC,CAAC,CAAC,EAAE,GAAG,CAAC,CAAC;gBACrG,MAAM,CAAC,CAAC,CAAC,CAAC;YACZ,CAAC;QACH,CAAC,CAAC,CAAC;IACL,CAAC,CAAC,CAAC;AACL,CAAC;AAED,gGAAgG;AAChG,MAAM,UAAU,UAAU,CACxB,IAAY,EACZ,OAAmE,EACnE,YAAuC,EAAE;IAEzC,OAAO,cAAc,CAAC,IAAI,EAAE,OAAO,EAAE,YAAY,CAAC,SAAS,CAAC,CAAC,CAAC;AAChE,CAAC"}

package/dist/cli/lib/attach.d.ts

@@ -0,0 +1,140 @@
+/**
+ * Shared helpers for attach-style CLI commands (`view`, `drive`,
+ * `passthrough`).
+ *
+ * - `captureAndRenderSnapshot` renders the agent's current visible screen
+ *   so the user doesn't attach to a quiet agent and stare at a blank
+ *   terminal until the next output.
+ * - `prepareAttachTarget` / `pickInitialTerminalRows` / `syncInitialPtySize`
+ *   / `switchInboundDeliveryModeOrAbort` / `captureInitialSnapshot` are
+ *   the take-over prep steps that `drive` and `passthrough` both run on
+ *   attach; centralised here so the two verbs stay in lockstep.
+ */
+import type { InboundDeliveryMode } from '@agent-relay/harness-driver';
+import { type BrokerConnection, type BrokerConnectionDeps, type BrokerConnectionOptions } from './broker-connection.js';
+/** Connection metadata used to call the broker's snapshot endpoint. */
+export interface AttachSnapshotConnection {
+    /** Broker base URL (no trailing slash). */
+    url: string;
+    /** Optional API key — added as an `X-API-Key` header if present. */
+    apiKey?: string;
+}
+/** Dependencies for `captureAndRenderSnapshot` — injected so tests don't hit
+ *  the network. */
+export interface AttachSnapshotDeps {
+    /** Native `fetch` by default; swapped out by tests. */
+    fetch: typeof globalThis.fetch;
+    /** Where the ANSI bytes get written. Typically `process.stdout.write`. */
+    writeChunk: (chunk: string) => void;
+}
+/** Outcome of a snapshot capture. Callers decide whether to bail or continue
+ *  on each variant — `view` aborts on `not_found` / `no_pty`, warns and
+ *  continues on `unavailable` / `transport_error`. */
+export interface AttachSnapshotResult {
+    status: 'ok' | 'not_found' | 'no_pty' | 'unavailable' | 'transport_error';
+    /** Grid dimensions as reported by the broker, if the call succeeded. */
+    rows?: number;
+    cols?: number;
+    /** Cursor position `[row, col]`, 1-indexed, if the call succeeded. */
+    cursor?: [number, number];
+    /** Human-readable detail for error variants. */
+    message?: string;
+}
+/**
+ * Fetch a worker's current visible screen as ANSI reproduction bytes and
+ * write them to the caller's output. Callers should invoke this BEFORE
+ * subscribing to the WebSocket event stream so the user sees the agent's
+ * current state before live deltas start arriving.
+ *
+ * There is a tiny window between the snapshot capture and the live stream
+ * starting in which the agent's output could be missed (≤10ms in practice).
+ * Most TUI agents repaint heavily so the next update overwrites anything
+ * lost; subscribe-first + buffer + drain would close the gap at the cost
+ * of risking double-application of bytes that arrive in both the snapshot
+ * and the buffered stream, which is the worse failure mode for TUIs.
+ *
+ * @returns A status describing the outcome. `ok` means the screen was
+ * rendered; other variants carry a message the caller can surface.
+ */
+export declare function captureAndRenderSnapshot(connection: AttachSnapshotConnection, agentName: string, deps: AttachSnapshotDeps): Promise<AttachSnapshotResult>;
+/** ----- Interactive attach prep helpers ----- */
+/** Validated attach target: trimmed agent name + resolved broker connection. */
+export interface AttachTarget {
+    name: string;
+    connection: BrokerConnection;
+}
+/** Dependencies for `prepareAttachTarget` — connection lookup + error sink. */
+export interface PrepareAttachTargetDeps extends BrokerConnectionDeps {
+    error: (...args: unknown[]) => void;
+}
+/**
+ * Trim the agent name and resolve the broker connection (flag → env →
+ * `connection.json`). Writes the appropriate error and returns `null` on
+ * either failure so every interactive attach verb rejects empty or
+ * unreachable targets consistently.
+ */
+export declare function prepareAttachTarget(agentName: string, options: BrokerConnectionOptions, deps: PrepareAttachTargetDeps): AttachTarget | null;
+/**
+ * Pick the status-line row. Prefers the LOCAL terminal's height (the
+ * status line must land where the human is looking) and falls back to
+ * the snapshot's PTY rows, then `undefined` so the renderer applies its
+ * own default.
+ */
+export declare function pickInitialTerminalRows(localSize: {
+    rows: number;
+    cols: number;
+} | null, snapshotRows: number | undefined): number | undefined;
+/**
+ * Sync the agent's PTY to the driver's local terminal size. tmux /
+ * screen / ssh all do this — without it a TUI in the agent renders into
+ * the size the PTY was spawned with, ignoring the human's viewport.
+ * Best-effort: a failure is annoying but not fatal. Skipped entirely
+ * when `localSize` is `null` (stdout isn't a TTY).
+ */
+export declare function syncInitialPtySize(connection: BrokerConnection, name: string, localSize: {
+    rows: number;
+    cols: number;
+} | null, verb: string, deps: {
+    fetch: typeof globalThis.fetch;
+    log: (...args: unknown[]) => void;
+}): Promise<void>;
+/**
+ * Read the worker's prior inbound delivery mode and flip it to
+ * `targetMode`. Returns the previous mode on success so the caller can
+ * restore it on detach; returns `null` (and writes an error) when the
+ * flip fails so the caller bails before touching the terminal.
+ *
+ * Non-404 errors are surfaced as `Error: could not ${actionPhrase}:
+ * ${message}` so callers pass verb-appropriate wording (e.g. "switch to
+ * manual_flush mode" or "ensure passthrough session"). 404s get a
+ * uniform "no agent named X" message.
+ */
+export declare function switchInboundDeliveryModeOrAbort(connection: BrokerConnection, name: string, targetMode: InboundDeliveryMode, actionPhrase: string, deps: {
+    fetch: typeof globalThis.fetch;
+    error: (...args: unknown[]) => void;
+}): Promise<{
+    previousMode: InboundDeliveryMode | null;
+} | null>;
+/** Dependencies for `captureInitialSnapshot`. `captureAndRenderSnapshot`
+ *  is injectable so tests can substitute a stub. */
+export interface CaptureInitialSnapshotDeps extends AttachSnapshotDeps {
+    log: (...args: unknown[]) => void;
+    error: (...args: unknown[]) => void;
+    captureAndRenderSnapshot?: typeof captureAndRenderSnapshot;
+}
+/**
+ * Render the agent's current visible screen, then dispatch on the
+ * outcome. Hard errors (`not_found`, `no_pty`) abort: this helper
+ * best-effort restores the prior delivery mode and writes the
+ * appropriate error before returning `null` so the caller bails.
+ * Transient errors warn and proceed. Returns `{ snapshotRows }` on the
+ * happy path so the caller can seed the status-line row fallback.
+ *
+ * `noPtyAction` is the verb phrase used in the no-PTY message
+ * (`agent 'X' has no PTY to ${noPtyAction}`) — e.g. "drive" or
+ * "attach to".
+ */
+export declare function captureInitialSnapshot(connection: BrokerConnection, name: string, previousMode: InboundDeliveryMode | null, verb: string, noPtyAction: string, deps: CaptureInitialSnapshotDeps): Promise<{
+    snapshotRows?: number;
+} | null>;
+//# sourceMappingURL=attach.d.ts.map

package/dist/cli/lib/attach.d.ts.map

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

package/dist/cli/lib/attach.js

@@ -0,0 +1,203 @@
+/**
+ * Shared helpers for attach-style CLI commands (`view`, `drive`,
+ * `passthrough`).
+ *
+ * - `captureAndRenderSnapshot` renders the agent's current visible screen
+ *   so the user doesn't attach to a quiet agent and stare at a blank
+ *   terminal until the next output.
+ * - `prepareAttachTarget` / `pickInitialTerminalRows` / `syncInitialPtySize`
+ *   / `switchInboundDeliveryModeOrAbort` / `captureInitialSnapshot` are
+ *   the take-over prep steps that `drive` and `passthrough` both run on
+ *   attach; centralised here so the two verbs stay in lockstep.
+ */
+import { resolveBrokerConnection, } from './broker-connection.js';
+import { createBrokerClient, mapBrokerSdkFailure } from './attach-broker.js';
+/**
+ * Fetch a worker's current visible screen as ANSI reproduction bytes and
+ * write them to the caller's output. Callers should invoke this BEFORE
+ * subscribing to the WebSocket event stream so the user sees the agent's
+ * current state before live deltas start arriving.
+ *
+ * There is a tiny window between the snapshot capture and the live stream
+ * starting in which the agent's output could be missed (≤10ms in practice).
+ * Most TUI agents repaint heavily so the next update overwrites anything
+ * lost; subscribe-first + buffer + drain would close the gap at the cost
+ * of risking double-application of bytes that arrive in both the snapshot
+ * and the buffered stream, which is the worse failure mode for TUIs.
+ *
+ * @returns A status describing the outcome. `ok` means the screen was
+ * rendered; other variants carry a message the caller can surface.
+ */
+export async function captureAndRenderSnapshot(connection, agentName, deps) {
+    let body;
+    try {
+        body = await createBrokerClient(connection, deps.fetch).snapshot(agentName, 'ansi');
+    }
+    catch (err) {
+        const failure = mapBrokerSdkFailure(err);
+        if (failure.status === 404) {
+            return { status: 'not_found', message: `no agent named '${agentName}'` };
+        }
+        if (failure.status === 409) {
+            return {
+                status: 'no_pty',
+                message: `agent '${agentName}' has no PTY (headless worker — nothing to view)`,
+            };
+        }
+        if (failure.status === 0 || failure.status === 200) {
+            return { status: 'transport_error', message: failure.message };
+        }
+        return { status: 'unavailable', message: `snapshot returned HTTP ${failure.status}` };
+    }
+    if (typeof body !== 'object' || body === null) {
+        return { status: 'transport_error', message: 'snapshot response was not an object' };
+    }
+    const obj = body;
+    const screen = obj.screen;
+    if (typeof screen !== 'string') {
+        return { status: 'transport_error', message: "snapshot response missing 'screen' field" };
+    }
+    // Snapshot bytes are mostly ASCII (escape sequences) plus the cell
+    // characters which are valid Unicode codepoints (alacritty stores
+    // chars, not bytes). UTF-8 round-trips cleanly.
+    const decoded = Buffer.from(screen, 'base64').toString('utf-8');
+    deps.writeChunk(decoded);
+    const rows = typeof obj.rows === 'number' ? obj.rows : undefined;
+    const cols = typeof obj.cols === 'number' ? obj.cols : undefined;
+    const cursorRaw = Array.isArray(obj.cursor) ? obj.cursor : undefined;
+    const cursor = cursorRaw &&
+        cursorRaw.length === 2 &&
+        typeof cursorRaw[0] === 'number' &&
+        typeof cursorRaw[1] === 'number'
+        ? [cursorRaw[0], cursorRaw[1]]
+        : undefined;
+    return { status: 'ok', rows, cols, cursor };
+}
+/**
+ * Trim the agent name and resolve the broker connection (flag → env →
+ * `connection.json`). Writes the appropriate error and returns `null` on
+ * either failure so every interactive attach verb rejects empty or
+ * unreachable targets consistently.
+ */
+export function prepareAttachTarget(agentName, options, deps) {
+    const name = agentName.trim();
+    if (!name) {
+        deps.error('Error: agent name is required');
+        return null;
+    }
+    const connection = resolveBrokerConnection(options, deps);
+    if (!connection) {
+        deps.error('Error: could not locate broker connection. Pass --broker-url, set RELAY_BROKER_URL, ' +
+            'or run from a directory containing .agentworkforce/relay/connection.json.');
+        return null;
+    }
+    return { name, connection };
+}
+/**
+ * Pick the status-line row. Prefers the LOCAL terminal's height (the
+ * status line must land where the human is looking) and falls back to
+ * the snapshot's PTY rows, then `undefined` so the renderer applies its
+ * own default.
+ */
+export function pickInitialTerminalRows(localSize, snapshotRows) {
+    if (localSize)
+        return localSize.rows;
+    if (typeof snapshotRows === 'number' && snapshotRows > 0)
+        return snapshotRows;
+    return undefined;
+}
+/**
+ * Sync the agent's PTY to the driver's local terminal size. tmux /
+ * screen / ssh all do this — without it a TUI in the agent renders into
+ * the size the PTY was spawned with, ignoring the human's viewport.
+ * Best-effort: a failure is annoying but not fatal. Skipped entirely
+ * when `localSize` is `null` (stdout isn't a TTY).
+ */
+export async function syncInitialPtySize(connection, name, localSize, verb, deps) {
+    if (!localSize)
+        return;
+    try {
+        await createBrokerClient(connection, deps.fetch).resizePty(name, localSize.rows, localSize.cols);
+    }
+    catch (err) {
+        const failure = mapBrokerSdkFailure(err);
+        deps.log(`[${verb}] could not sync agent PTY size to local terminal (${failure.message ?? 'unknown'}); continuing`);
+    }
+}
+/**
+ * Read the worker's prior inbound delivery mode and flip it to
+ * `targetMode`. Returns the previous mode on success so the caller can
+ * restore it on detach; returns `null` (and writes an error) when the
+ * flip fails so the caller bails before touching the terminal.
+ *
+ * Non-404 errors are surfaced as `Error: could not ${actionPhrase}:
+ * ${message}` so callers pass verb-appropriate wording (e.g. "switch to
+ * manual_flush mode" or "ensure passthrough session"). 404s get a
+ * uniform "no agent named X" message.
+ */
+export async function switchInboundDeliveryModeOrAbort(connection, name, targetMode, actionPhrase, deps) {
+    let previousMode = null;
+    try {
+        previousMode = await createBrokerClient(connection, deps.fetch).getInboundDeliveryMode(name);
+    }
+    catch {
+        // Best-effort — fall through with null; the caller restores to
+        // `auto_inject` in that case so the queue can't grow indefinitely.
+    }
+    try {
+        await createBrokerClient(connection, deps.fetch).setInboundDeliveryMode(name, targetMode);
+        return { previousMode };
+    }
+    catch (err) {
+        const failure = mapBrokerSdkFailure(err);
+        if (failure.status === 404) {
+            deps.error(`Error: no agent named '${name}'`);
+        }
+        else {
+            deps.error(`Error: could not ${actionPhrase}: ${failure.message ?? 'unknown error'}`);
+        }
+        return null;
+    }
+}
+/**
+ * Render the agent's current visible screen, then dispatch on the
+ * outcome. Hard errors (`not_found`, `no_pty`) abort: this helper
+ * best-effort restores the prior delivery mode and writes the
+ * appropriate error before returning `null` so the caller bails.
+ * Transient errors warn and proceed. Returns `{ snapshotRows }` on the
+ * happy path so the caller can seed the status-line row fallback.
+ *
+ * `noPtyAction` is the verb phrase used in the no-PTY message
+ * (`agent 'X' has no PTY to ${noPtyAction}`) — e.g. "drive" or
+ * "attach to".
+ */
+export async function captureInitialSnapshot(connection, name, previousMode, verb, noPtyAction, deps) {
+    const render = deps.captureAndRenderSnapshot ?? captureAndRenderSnapshot;
+    const snapshot = await render({ url: connection.url, apiKey: connection.apiKey }, name, {
+        fetch: deps.fetch,
+        writeChunk: deps.writeChunk,
+    });
+    switch (snapshot.status) {
+        case 'ok':
+            return { snapshotRows: snapshot.rows };
+        case 'not_found':
+        case 'no_pty': {
+            try {
+                await createBrokerClient(connection, deps.fetch).setInboundDeliveryMode(name, previousMode ?? 'auto_inject');
+            }
+            catch {
+                // best-effort restore
+            }
+            const fallback = snapshot.status === 'not_found'
+                ? `no agent named '${name}'`
+                : `agent '${name}' has no PTY to ${noPtyAction}`;
+            deps.error(`Error: ${snapshot.message ?? fallback}`);
+            return null;
+        }
+        case 'unavailable':
+        case 'transport_error':
+            deps.log(`[${verb}] could not capture initial screen (${snapshot.message ?? snapshot.status}); streaming live output only`);
+            return { snapshotRows: snapshot.rows };
+    }
+}
+//# sourceMappingURL=attach.js.map

package/dist/cli/lib/attach.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"attach.js","sourceRoot":"","sources":["../../../src/cli/lib/attach.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAIH,OAAO,EACL,uBAAuB,GAIxB,MAAM,wBAAwB,CAAC;AAChC,OAAO,EAAE,kBAAkB,EAAE,mBAAmB,EAAE,MAAM,oBAAoB,CAAC;AAiC7E;;;;;;;;;;;;;;;GAeG;AACH,MAAM,CAAC,KAAK,UAAU,wBAAwB,CAC5C,UAAoC,EACpC,SAAiB,EACjB,IAAwB;IAExB,IAAI,IAAa,CAAC;IAClB,IAAI,CAAC;QACH,IAAI,GAAG,MAAM,kBAAkB,CAAC,UAAU,EAAE,IAAI,CAAC,KAAK,CAAC,CAAC,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC,CAAC;IACtF,CAAC;IAAC,OAAO,GAAY,EAAE,CAAC;QACtB,MAAM,OAAO,GAAG,mBAAmB,CAAC,GAAG,CAAC,CAAC;QACzC,IAAI,OAAO,CAAC,MAAM,KAAK,GAAG,EAAE,CAAC;YAC3B,OAAO,EAAE,MAAM,EAAE,WAAW,EAAE,OAAO,EAAE,mBAAmB,SAAS,GAAG,EAAE,CAAC;QAC3E,CAAC;QACD,IAAI,OAAO,CAAC,MAAM,KAAK,GAAG,EAAE,CAAC;YAC3B,OAAO;gBACL,MAAM,EAAE,QAAQ;gBAChB,OAAO,EAAE,UAAU,SAAS,kDAAkD;aAC/E,CAAC;QACJ,CAAC;QACD,IAAI,OAAO,CAAC,MAAM,KAAK,CAAC,IAAI,OAAO,CAAC,MAAM,KAAK,GAAG,EAAE,CAAC;YACnD,OAAO,EAAE,MAAM,EAAE,iBAAiB,EAAE,OAAO,EAAE,OAAO,CAAC,OAAO,EAAE,CAAC;QACjE,CAAC;QACD,OAAO,EAAE,MAAM,EAAE,aAAa,EAAE,OAAO,EAAE,0BAA0B,OAAO,CAAC,MAAM,EAAE,EAAE,CAAC;IACxF,CAAC;IAED,IAAI,OAAO,IAAI,KAAK,QAAQ,IAAI,IAAI,KAAK,IAAI,EAAE,CAAC;QAC9C,OAAO,EAAE,MAAM,EAAE,iBAAiB,EAAE,OAAO,EAAE,qCAAqC,EAAE,CAAC;IACvF,CAAC;IACD,MAAM,GAAG,GAAG,IAA+B,CAAC;IAC5C,MAAM,MAAM,GAAG,GAAG,CAAC,MAAM,CAAC;IAC1B,IAAI,OAAO,MAAM,KAAK,QAAQ,EAAE,CAAC;QAC/B,OAAO,EAAE,MAAM,EAAE,iBAAiB,EAAE,OAAO,EAAE,0CAA0C,EAAE,CAAC;IAC5F,CAAC;IAED,mEAAmE;IACnE,kEAAkE;IAClE,gDAAgD;IAChD,MAAM,OAAO,GAAG,MAAM,CAAC,IAAI,CAAC,MAAM,EAAE,QAAQ,CAAC,CAAC,QAAQ,CAAC,OAAO,CAAC,CAAC;IAChE,IAAI,CAAC,UAAU,CAAC,OAAO,CAAC,CAAC;IAEzB,MAAM,IAAI,GAAG,OAAO,GAAG,CAAC,IAAI,KAAK,QAAQ,CAAC,CAAC,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC,CAAC,SAAS,CAAC;IACjE,MAAM,IAAI,GAAG,OAAO,GAAG,CAAC,IAAI,KAAK,QAAQ,CAAC,CAAC,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC,CAAC,SAAS,CAAC;IACjE,MAAM,SAAS,GAAG,KAAK,CAAC,OAAO,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC,CAAC,SAAS,CAAC;IACrE,MAAM,MAAM,GACV,SAAS;QACT,SAAS,CAAC,MAAM,KAAK,CAAC;QACtB,OAAO,SAAS,CAAC,CAAC,CAAC,KAAK,QAAQ;QAChC,OAAO,SAAS,CAAC,CAAC,CAAC,KAAK,QAAQ;QAC9B,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,EAAE,SAAS,CAAC,CAAC,CAAC,CAAC;QAC9B,CAAC,CAAC,SAAS,CAAC;IAEhB,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,MAAM,EAAE,CAAC;AAC9C,CAAC;AAeD;;;;;GAKG;AACH,MAAM,UAAU,mBAAmB,CACjC,SAAiB,EACjB,OAAgC,EAChC,IAA6B;IAE7B,MAAM,IAAI,GAAG,SAAS,CAAC,IAAI,EAAE,CAAC;IAC9B,IAAI,CAAC,IAAI,EAAE,CAAC;QACV,IAAI,CAAC,KAAK,CAAC,+BAA+B,CAAC,CAAC;QAC5C,OAAO,IAAI,CAAC;IACd,CAAC;IACD,MAAM,UAAU,GAAG,uBAAuB,CAAC,OAAO,EAAE,IAAI,CAAC,CAAC;IAC1D,IAAI,CAAC,UAAU,EAAE,CAAC;QAChB,IAAI,CAAC,KAAK,CACR,sFAAsF;YACpF,2EAA2E,CAC9E,CAAC;QACF,OAAO,IAAI,CAAC;IACd,CAAC;IACD,OAAO,EAAE,IAAI,EAAE,UAAU,EAAE,CAAC;AAC9B,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,uBAAuB,CACrC,SAAgD,EAChD,YAAgC;IAEhC,IAAI,SAAS;QAAE,OAAO,SAAS,CAAC,IAAI,CAAC;IACrC,IAAI,OAAO,YAAY,KAAK,QAAQ,IAAI,YAAY,GAAG,CAAC;QAAE,OAAO,YAAY,CAAC;IAC9E,OAAO,SAAS,CAAC;AACnB,CAAC;AAED;;;;;;GAMG;AACH,MAAM,CAAC,KAAK,UAAU,kBAAkB,CACtC,UAA4B,EAC5B,IAAY,EACZ,SAAgD,EAChD,IAAY,EACZ,IAA2E;IAE3E,IAAI,CAAC,SAAS;QAAE,OAAO;IACvB,IAAI,CAAC;QACH,MAAM,kBAAkB,CAAC,UAAU,EAAE,IAAI,CAAC,KAAK,CAAC,CAAC,SAAS,CAAC,IAAI,EAAE,SAAS,CAAC,IAAI,EAAE,SAAS,CAAC,IAAI,CAAC,CAAC;IACnG,CAAC;IAAC,OAAO,GAAY,EAAE,CAAC;QACtB,MAAM,OAAO,GAAG,mBAAmB,CAAC,GAAG,CAAC,CAAC;QACzC,IAAI,CAAC,GAAG,CACN,IAAI,IAAI,sDAAsD,OAAO,CAAC,OAAO,IAAI,SAAS,eAAe,CAC1G,CAAC;IACJ,CAAC;AACH,CAAC;AAED;;;;;;;;;;GAUG;AACH,MAAM,CAAC,KAAK,UAAU,gCAAgC,CACpD,UAA4B,EAC5B,IAAY,EACZ,UAA+B,EAC/B,YAAoB,EACpB,IAA6E;IAE7E,IAAI,YAAY,GAA+B,IAAI,CAAC;IACpD,IAAI,CAAC;QACH,YAAY,GAAG,MAAM,kBAAkB,CAAC,UAAU,EAAE,IAAI,CAAC,KAAK,CAAC,CAAC,sBAAsB,CAAC,IAAI,CAAC,CAAC;IAC/F,CAAC;IAAC,MAAM,CAAC;QACP,+DAA+D;QAC/D,mEAAmE;IACrE,CAAC;IACD,IAAI,CAAC;QACH,MAAM,kBAAkB,CAAC,UAAU,EAAE,IAAI,CAAC,KAAK,CAAC,CAAC,sBAAsB,CAAC,IAAI,EAAE,UAAU,CAAC,CAAC;QAC1F,OAAO,EAAE,YAAY,EAAE,CAAC;IAC1B,CAAC;IAAC,OAAO,GAAY,EAAE,CAAC;QACtB,MAAM,OAAO,GAAG,mBAAmB,CAAC,GAAG,CAAC,CAAC;QACzC,IAAI,OAAO,CAAC,MAAM,KAAK,GAAG,EAAE,CAAC;YAC3B,IAAI,CAAC,KAAK,CAAC,0BAA0B,IAAI,GAAG,CAAC,CAAC;QAChD,CAAC;aAAM,CAAC;YACN,IAAI,CAAC,KAAK,CAAC,oBAAoB,YAAY,KAAK,OAAO,CAAC,OAAO,IAAI,eAAe,EAAE,CAAC,CAAC;QACxF,CAAC;QACD,OAAO,IAAI,CAAC;IACd,CAAC;AACH,CAAC;AAUD;;;;;;;;;;;GAWG;AACH,MAAM,CAAC,KAAK,UAAU,sBAAsB,CAC1C,UAA4B,EAC5B,IAAY,EACZ,YAAwC,EACxC,IAAY,EACZ,WAAmB,EACnB,IAAgC;IAEhC,MAAM,MAAM,GAAG,IAAI,CAAC,wBAAwB,IAAI,wBAAwB,CAAC;IACzE,MAAM,QAAQ,GAAG,MAAM,MAAM,CAAC,EAAE,GAAG,EAAE,UAAU,CAAC,GAAG,EAAE,MAAM,EAAE,UAAU,CAAC,MAAM,EAAE,EAAE,IAAI,EAAE;QACtF,KAAK,EAAE,IAAI,CAAC,KAAK;QACjB,UAAU,EAAE,IAAI,CAAC,UAAU;KAC5B,CAAC,CAAC;IACH,QAAQ,QAAQ,CAAC,MAAM,EAAE,CAAC;QACxB,KAAK,IAAI;YACP,OAAO,EAAE,YAAY,EAAE,QAAQ,CAAC,IAAI,EAAE,CAAC;QACzC,KAAK,WAAW,CAAC;QACjB,KAAK,QAAQ,CAAC,CAAC,CAAC;YACd,IAAI,CAAC;gBACH,MAAM,kBAAkB,CAAC,UAAU,EAAE,IAAI,CAAC,KAAK,CAAC,CAAC,sBAAsB,CACrE,IAAI,EACJ,YAAY,IAAI,aAAa,CAC9B,CAAC;YACJ,CAAC;YAAC,MAAM,CAAC;gBACP,sBAAsB;YACxB,CAAC;YACD,MAAM,QAAQ,GACZ,QAAQ,CAAC,MAAM,KAAK,WAAW;gBAC7B,CAAC,CAAC,mBAAmB,IAAI,GAAG;gBAC5B,CAAC,CAAC,UAAU,IAAI,mBAAmB,WAAW,EAAE,CAAC;YACrD,IAAI,CAAC,KAAK,CAAC,UAAU,QAAQ,CAAC,OAAO,IAAI,QAAQ,EAAE,CAAC,CAAC;YACrD,OAAO,IAAI,CAAC;QACd,CAAC;QACD,KAAK,aAAa,CAAC;QACnB,KAAK,iBAAiB;YACpB,IAAI,CAAC,GAAG,CACN,IAAI,IAAI,uCAAuC,QAAQ,CAAC,OAAO,IAAI,QAAQ,CAAC,MAAM,+BAA+B,CAClH,CAAC;YACF,OAAO,EAAE,YAAY,EAAE,QAAQ,CAAC,IAAI,EAAE,CAAC;IAC3C,CAAC;AACH,CAAC"}