@shardflux/cli 0.11.1 → 0.13.1

package/dist/browser-readers.js

@@ -0,0 +1,249 @@
+import { execFile } from 'node:child_process';
+import { createDecipheriv, createHash, pbkdf2Sync, timingSafeEqual } from 'node:crypto';
+import { cp, mkdtemp, readFile, readdir, rm, stat } from 'node:fs/promises';
+import { homedir, tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { DatabaseSync } from 'node:sqlite';
+import { promisify } from 'node:util';
+import { ClassicLevel } from 'classic-level';
+import { uncompress } from 'snappyjs';
+import { UsageError } from "./errors.js";
+const run = promisify(execFile);
+const apps = { chrome: ['Google/Chrome', 'Chrome'], arc: ['Arc/User Data', 'Arc'], brave: ['BraveSoftware/Brave-Browser', 'Brave'], edge: ['Microsoft Edge', 'Microsoft Edge'] };
+export { browserSessionNote } from "./browser-profile-copy.js";
+import { normalizeBrowserSite } from "./browser-sites.js";
+export { normalizeBrowserSite } from "./browser-sites.js";
+const domainMatches = (domain, host) => { const d = domain.replace(/^\./, '').toLowerCase(); return d === host || d.includes('.') && host.endsWith(`.${d}`); };
+const present = async (file) => { try {
+    return (await stat(file)).isFile();
+}
+catch {
+    return false;
+} };
+/** Called only by an explicit import. Tests pass a throwaway directory and synthetic key provider. */
+export async function browserDirectory(browser) {
+    if (browser === 'safari')
+        return join(homedir(), 'Library');
+    if (browser === 'firefox') {
+        const root = join(homedir(), 'Library/Application Support/Firefox');
+        const ini = await readFile(join(root, 'profiles.ini'), 'utf8');
+        const profiles = ini.split(/\r?\n\[/).map(s => ({ path: /^Path=(.+)$/m.exec(s)?.[1], relative: !/^IsRelative=0$/m.test(s), preferred: /^Default=1$/m.test(s) }));
+        const profile = profiles.find(p => p.path && p.preferred) ?? profiles.find(p => p.path);
+        if (!profile?.path)
+            throw new UsageError('No Firefox profile was found. Choose one with --profile-dir.');
+        return profile.relative ? join(root, profile.path) : profile.path;
+    }
+    const root = join(homedir(), 'Library/Application Support', apps[browser][0]);
+    const state = JSON.parse(await readFile(join(root, 'Local State'), 'utf8'));
+    const leaf = state.profile?.last_used ?? 'Default';
+    if (!/^(?:Default|Profile [0-9]+)$/.test(leaf))
+        throw new UsageError('Choose this browser profile with --profile-dir.');
+    return join(root, leaf);
+}
+export async function safeStorageKey(browser) {
+    if (process.platform !== 'darwin')
+        throw new UsageError('Local browser import uses macOS Safe Storage.');
+    try {
+        const { stdout } = await run('/usr/bin/security', ['find-generic-password', '-w', '-s', `${apps[browser][1]} Safe Storage`], { encoding: 'buffer', timeout: 30_000, maxBuffer: 65536 });
+        const password = Buffer.from(stdout);
+        stdout.fill(0);
+        if (password.at(-1) === 10)
+            return password.subarray(0, password.length - 1);
+        return password;
+    }
+    catch {
+        throw new UsageError('Allow access to the browser’s Safe Storage key in the macOS prompt, then retry import.');
+    }
+}
+export function decryptChromiumCookie(encrypted, password, host, version) {
+    const b = Buffer.from(encrypted);
+    if (b.subarray(0, 3).toString() !== 'v10')
+        throw new UsageError('This browser cookie encryption format is unsupported. Sign in through the workspace and use shard browser save.');
+    const key = pbkdf2Sync(password, 'saltysalt', 1003, 16, 'sha1');
+    let plain;
+    try {
+        const cipher = createDecipheriv('aes-128-cbc', key, Buffer.alloc(16, 32));
+        plain = Buffer.concat([cipher.update(b.subarray(3)), cipher.final()]);
+        if (version >= 24) {
+            const expected = createHash('sha256').update(host).digest();
+            if (plain.length < 32 || !timingSafeEqual(plain.subarray(0, 32), expected))
+                throw new Error('host binding');
+            return plain.subarray(32).toString('utf8');
+        }
+        return plain.toString('utf8');
+    }
+    catch {
+        throw new UsageError('The selected browser cookies could not be decrypted. Retry with the matching browser.');
+    }
+    finally {
+        key.fill(0);
+        plain?.fill(0);
+    }
+}
+function sqlRows(file, query, ...params) {
+    const db = new DatabaseSync(file, { readOnly: true });
+    try {
+        return db.prepare(query).all(...params);
+    }
+    finally {
+        db.close();
+    }
+}
+const n = (v) => Number(v);
+const text = (v) => typeof v === 'string' ? v : Buffer.from(v).toString('utf16le');
+const bytes = (v) => Buffer.from(v);
+export async function readBrowserState(browser, directory, rawSites, keyProvider = safeStorageKey) {
+    const sites = [...new Set(rawSites.map(normalizeBrowserSite))];
+    if (!sites.length)
+        throw new UsageError('Choose at least one site.');
+    const result = sites.map(site => ({ site, storage_state: { cookies: [], origins: [] } }));
+    let key;
+    try {
+        if (browser === 'safari') {
+            const file = join(directory, 'Cookies/Cookies.binarycookies');
+            const sandbox = join(directory, 'Containers/com.apple.Safari/Data/Library/Cookies/Cookies.binarycookies');
+            const cookies = readSafariCookies(await readFile(await present(file) ? file : sandbox));
+            for (const r of result)
+                r.storage_state.cookies = cookies.filter(c => domainMatches(c.domain, new URL(r.site).hostname));
+            await safariLocalStorage(directory, result);
+        }
+        else if (browser === 'firefox') {
+            const file = join(directory, 'cookies.sqlite');
+            for (const r of result) {
+                const host = new URL(r.site).hostname;
+                const domains = host.split('.').map((_, i, a) => a.slice(i).join('.')).filter(d => d === host || d.includes('.'));
+                const rows = sqlRows(file, `SELECT host,name,value,path,expiry,isSecure,isHttpOnly,sameSite FROM moz_cookies WHERE originAttributes='' AND host IN (${domains.flatMap(() => ['?', '?']).join(',')})`, ...domains.flatMap(d => [d, `.${d}`]));
+                r.storage_state.cookies = rows.map(c => ({ name: String(c.name), value: String(c.value), domain: String(c.host), path: String(c.path), expires: n(c.expiry), secure: !!c.isSecure, httpOnly: !!c.isHttpOnly, sameSite: n(c.sameSite) === 2 ? 'Strict' : n(c.sameSite) === 1 ? 'Lax' : 'None' }));
+            }
+            await firefoxLocalStorage(directory, result);
+        }
+        else {
+            const file = await present(join(directory, 'Network/Cookies')) ? join(directory, 'Network/Cookies') : join(directory, 'Cookies');
+            const version = n(sqlRows(file, "SELECT value FROM meta WHERE key='version'")[0]?.value);
+            const partitionColumn = sqlRows(file, 'PRAGMA table_info(cookies)').some(c => c.name === 'top_frame_site_key') ? 'top_frame_site_key' : "'' AS top_frame_site_key";
+            for (const r of result) {
+                const host = new URL(r.site).hostname;
+                const domains = host.split('.').map((_, i, a) => a.slice(i).join('.')).filter(d => d === host || d.includes('.'));
+                const rows = sqlRows(file, `SELECT host_key,name,value,encrypted_value,path,CAST(expires_utc AS TEXT) expires_utc,is_secure,is_httponly,samesite,${partitionColumn} FROM cookies WHERE host_key IN (${domains.flatMap(() => ['?', '?']).join(',')})`, ...domains.flatMap(d => [d, `.${d}`]));
+                for (const c of rows) {
+                    let value = String(c.value);
+                    if (bytes(c.encrypted_value).length) {
+                        key ??= await keyProvider(browser);
+                        value = decryptChromiumCookie(bytes(c.encrypted_value), key, String(c.host_key), version);
+                    }
+                    r.storage_state.cookies.push({ name: String(c.name), value, domain: String(c.host_key), path: String(c.path), expires: n(c.expires_utc) ? n(c.expires_utc) / 1e6 - 11644473600 : -1, secure: !!c.is_secure, httpOnly: !!c.is_httponly, sameSite: n(c.samesite) === 2 ? 'Strict' : n(c.samesite) === 1 ? 'Lax' : 'None', ...(typeof c.top_frame_site_key === 'string' && c.top_frame_site_key ? { partitionKey: c.top_frame_site_key } : {}) });
+                }
+            }
+            await chromiumLocalStorage(directory, result);
+        }
+        return result;
+    }
+    finally {
+        key?.fill(0);
+    }
+}
+const blinkString = (b) => { if (b[0] === 0)
+    return b.subarray(1).toString('utf16le'); if (b[0] === 1)
+    return b.subarray(1).toString('latin1'); throw new UsageError('This browser local storage encoding is unsupported.'); };
+async function chromiumLocalStorage(directory, result) {
+    const source = join(directory, 'Local Storage/leveldb');
+    try {
+        await stat(source);
+    }
+    catch {
+        return;
+    }
+    const tmp = await mkdtemp(join(tmpdir(), 'shard-browser-'));
+    await cp(source, join(tmp, 'leveldb'), { recursive: true }).catch(async (error) => { await rm(tmp, { recursive: true, force: true }); throw error; });
+    const db = new ClassicLevel(join(tmp, 'leveldb'), { keyEncoding: 'buffer', valueEncoding: 'buffer', createIfMissing: false });
+    try {
+        await db.open();
+        for (const r of result) {
+            const prefix = Buffer.from(`_${r.site}\0`), items = [];
+            for await (const [key, value] of db.iterator({ gte: prefix, lt: Buffer.concat([prefix.subarray(0, -1), Buffer.from([1])]) })) {
+                if (key.subarray(0, prefix.length).equals(prefix))
+                    items.push({ name: blinkString(key.subarray(prefix.length)), value: blinkString(value) });
+            }
+            if (items.length)
+                r.storage_state.origins.push({ origin: r.site, localStorage: items });
+        }
+    }
+    finally {
+        await db.close();
+        await rm(tmp, { recursive: true, force: true });
+    }
+}
+async function firefoxLocalStorage(directory, result) {
+    const base = join(directory, 'storage/default');
+    let dirs;
+    try {
+        dirs = await readdir(base);
+    }
+    catch {
+        return;
+    }
+    for (const r of result) {
+        const u = new URL(r.site), leaf = `${u.protocol.slice(0, -1)}+++${u.hostname}${u.port ? `+${u.port}` : ''}`;
+        // Container/partition origins carry a suffix and never join the default login.
+        if (!dirs.includes(leaf))
+            continue;
+        const file = join(base, leaf, 'ls/data.sqlite');
+        if (!await present(file))
+            continue;
+        const origin = sqlRows(file, 'SELECT origin FROM database')[0]?.origin;
+        if (origin !== r.site)
+            continue;
+        const items = sqlRows(file, 'SELECT key,value,conversion_type,compression_type FROM data').map(c => {
+            const value = n(c.compression_type) === 1 ? Buffer.from(uncompress(bytes(c.value))) : bytes(c.value);
+            if (![0, 1].includes(n(c.conversion_type)) || ![0, 1].includes(n(c.compression_type)))
+                throw new UsageError('This Firefox storage encoding is unsupported.');
+            return { name: String(c.key), value: value.toString(n(c.conversion_type) === 1 ? 'utf8' : 'utf16le') };
+        });
+        r.storage_state.origins.push({ origin: r.site, localStorage: items });
+    }
+}
+async function safariLocalStorage(directory, result) {
+    const base = join(directory, 'WebKit/com.apple.Safari/LocalStorage');
+    let files;
+    try {
+        files = await readdir(base);
+    }
+    catch {
+        return;
+    }
+    for (const r of result) {
+        const u = new URL(r.site), filename = `${u.protocol.slice(0, -1)}_${u.hostname}_${u.port || '0'}.localstorage`;
+        if (!files.includes(filename))
+            continue;
+        const items = sqlRows(join(base, filename), 'SELECT key,value FROM ItemTable').map(c => ({ name: text(c.key), value: text(c.value) }));
+        r.storage_state.origins.push({ origin: r.site, localStorage: items });
+    }
+}
+export function readSafariCookies(b) {
+    if (b.subarray(0, 4).toString() !== 'cook')
+        throw new UsageError('Invalid Safari cookie file.');
+    const cookies = [];
+    const pages = b.readUInt32BE(4);
+    if (pages > 100000 || 8 + pages * 4 > b.length)
+        throw new UsageError('Invalid Safari cookie file.');
+    let start = 8 + pages * 4;
+    for (let p = 0; p < pages; p++) {
+        const length = b.readUInt32BE(8 + p * 4), page = b.subarray(start, start + length);
+        start += length;
+        if (page.length !== length || length < 8)
+            throw new UsageError('Invalid Safari cookie page.');
+        const count = page.readUInt32LE(4);
+        if (8 + count * 4 > page.length)
+            throw new UsageError('Invalid Safari cookie page.');
+        for (let i = 0; i < count; i++) {
+            const offset = page.readUInt32LE(8 + i * 4), size = page.readUInt32LE(offset), c = page.subarray(offset, offset + size);
+            if (c.length !== size || size < 56)
+                throw new UsageError('Invalid Safari cookie record.');
+            const field = (at) => { const o = c.readUInt32LE(at), end = c.indexOf(0, o); if (o < 56 || end < o)
+                throw new UsageError('Invalid Safari cookie field.'); return c.subarray(o, end).toString(); };
+            const flags = c.readUInt32LE(8);
+            cookies.push({ domain: field(16), name: field(20), path: field(24), value: field(28), expires: c.readDoubleLE(40) + 978307200, secure: !!(flags & 1), httpOnly: !!(flags & 4), sameSite: 'None' });
+        }
+    }
+    return cookies;
+}

package/dist/browser-sites.d.ts

@@ -0,0 +1 @@
+export declare function normalizeBrowserSite(raw: string): string;

package/dist/browser-sites.js

@@ -0,0 +1,13 @@
+import { UsageError } from "./errors.js";
+export function normalizeBrowserSite(raw) {
+    let u;
+    try {
+        u = new URL(raw.includes('://') ? raw : `https://${raw}`);
+    }
+    catch {
+        throw new UsageError('site must be an HTTP or HTTPS origin');
+    }
+    if (!['http:', 'https:'].includes(u.protocol) || u.username || u.password || u.search || u.hash || u.pathname !== '/')
+        throw new UsageError('site must be an origin without credentials, a path or a query');
+    return u.origin;
+}

package/dist/claude-cloud-login.d.ts

@@ -0,0 +1,9 @@
+import type { AgentCredentialMetadata, Workspace } from '@shardflux/sdk';
+import type { Ctx } from './commands.js';
+export declare function requireClaudeTerminal(ctx: Ctx): void;
+export declare function cloudClaudeLogin(ctx: Ctx): Promise<AgentCredentialMetadata | undefined>;
+/** Parse only complete provider authorize links, including the native OSC-8 link. */
+export declare function claudeLoginUrls(output: string): string[];
+/** A transient Linux profile holds the initial pair; it is removed before an agent starts. */
+export declare function loginClaudeInWorkspace(ctx: Ctx, ws: Workspace): Promise<AgentCredentialMetadata>;
+export declare function ensureCloudClaude(ctx: Ctx, ws: Workspace): Promise<void>;

package/dist/claude-cloud-login.js

@@ -0,0 +1,143 @@
+import { ShardfluxApiError } from '@shardflux/sdk';
+import { UsageError } from "./errors.js";
+import { openUrl } from "./browser.js";
+import { attachTerminal, cellConnector, PtyOutputCursor } from "./agent-terminal.js";
+const NEED_TERMINAL = 'Claude sign-in needed. Run shard agents credentials login claude in a terminal.';
+const VERSION = '2.1.289';
+export function requireClaudeTerminal(ctx) {
+    if (ctx.json || !ctx.io.stdin.isTTY || !ctx.io.stdin.setRawMode || !ctx.io.stdin.on)
+        throw new UsageError(NEED_TERMINAL);
+}
+export async function cloudClaudeLogin(ctx) {
+    return (await ctx.cloud().agentCredentials.list()).find(row => row.app === 'claude' && row.scope === 'account' && row.status === 'ready');
+}
+/** Parse only complete provider authorize links, including the native OSC-8 link. */
+export function claudeLoginUrls(output) {
+    const urls = new Set();
+    // Native terminal OSC-8 links end at control bytes; reject partial frames.
+    // eslint-disable-next-line no-control-regex
+    for (const match of output.matchAll(/https:\/\/[^\s\x00-\x20]+(?=[\s\x00-\x20])/g)) {
+        try {
+            const url = new URL(match[0]);
+            if (['claude.com', 'claude.ai', 'platform.claude.com', 'console.anthropic.com'].includes(url.hostname) &&
+                url.pathname.endsWith('/oauth/authorize') && url.searchParams.get('code') === 'true')
+                urls.add(url.toString());
+        }
+        catch { /* fragmented terminal links wait for the next frame */ }
+    }
+    return [...urls];
+}
+function credentialFile(path, value, ctx) {
+    const raw = JSON.stringify(value), content_b64 = Buffer.from(raw).toString('base64');
+    const hide = (value) => {
+        if (typeof value === 'string')
+            ctx.addSecret(value);
+        else if (Array.isArray(value))
+            value.forEach(hide);
+        else if (value && typeof value === 'object')
+            Object.values(value).forEach(hide);
+    };
+    hide(value);
+    ctx.addSecret(raw);
+    ctx.addSecret(content_b64);
+    return { path, mode: '0600', content_b64 };
+}
+/** A transient Linux profile holds the initial pair; it is removed before an agent starts. */
+export async function loginClaudeInWorkspace(ctx, ws) {
+    requireClaudeTerminal(ctx);
+    const api = ctx.cloud().agentCredentials;
+    let claim;
+    try {
+        claim = await api.beginLogin(ws.id);
+    }
+    catch (error) {
+        if (error instanceof ShardfluxApiError && error.details?.reason === 'claude_already_signed_in') {
+            const ready = await cloudClaudeLogin(ctx);
+            if (ready)
+                return ready;
+        }
+        throw error;
+    }
+    const root = `/tmp/shard-claude-login-${claim.login_id}`;
+    const session = `claude-login-${claim.login_id}`;
+    const cell = ws.cell({ agentLabel: ctx.agentLabel, transitionTimeoutMs: ctx.wakeTimeoutMs });
+    let complete = false;
+    try {
+        await cell.files.mkdir(root, { parents: true, mode: '0700' });
+        const env = { HOME: root, CLAUDE_CONFIG_DIR: `${root}/.claude`, BROWSER: '/bin/false', DISABLE_AUTOUPDATER: '1' };
+        const version = await cell.exec.run(['claude', '--version'], { env, cwd: root, signal: ctx.signal, timeoutMs: 10_000 });
+        if (version.exitCode !== 0 || version.stdout.trim() !== `${VERSION} (Claude Code)`)
+            throw new UsageError(`Cloud Claude sign-in requires Claude Code ${VERSION} in the workspace image.`);
+        await cell.pty.open({ session_id: session, argv: ['claude', 'auth', 'login', '--claudeai'], env, cwd: root, rows: 24, cols: 100 });
+        const connect = cellConnector(cell, session);
+        const opened = new Set();
+        const cursor = new PtyOutputCursor();
+        let output = '';
+        const code = await attachTerminal({ io: ctx.io, signal: ctx.signal, wake: signal => ws.wake({ signal }), invalidate: () => { },
+            sleep: (ms, signal) => new Promise(resolve => {
+                const done = () => { clearTimeout(timer); signal.removeEventListener('abort', done); resolve(); };
+                const timer = setTimeout(done, ms);
+                signal.addEventListener('abort', done, { once: true });
+                if (signal.aborted)
+                    done();
+            }),
+            connect: async (offset, signal) => {
+                const connection = await connect(offset, signal);
+                return {
+                    input: bytes => connection.input(bytes), resize: (rows, cols) => connection.resize(rows, cols), close: () => connection.close(),
+                    messages: async function* () {
+                        for await (const message of connection.messages()) {
+                            const bytes = cursor.consume(message);
+                            if (bytes) {
+                                output = (output + bytes.toString()).slice(-16384);
+                                for (const url of claudeLoginUrls(output))
+                                    if (!opened.has(url)) {
+                                        opened.add(url);
+                                        openUrl(url, ctx.io.env);
+                                    }
+                            }
+                            yield message;
+                        }
+                    },
+                };
+            },
+        });
+        const ended = await cell.pty.get(session);
+        if (code !== 0 || ended.state !== 'exited' || ended.exit_code !== 0)
+            throw new UsageError('Claude cloud sign-in was interrupted. Run shard agents credentials login claude again.');
+        const credential = JSON.parse(await cell.files.readText(`${root}/.claude/.credentials.json`));
+        const config = JSON.parse(await cell.files.readText(`${root}/.claude/.claude.json`));
+        const files = [credentialFile('~/.claude/.credentials.json', credential, ctx), credentialFile('~/.claude.json', { oauthAccount: config.oauthAccount }, ctx)];
+        // Delete the initial refresh token and all native backups before network
+        // persistence. An upload error requires a new cloud login, never guest refresh.
+        await cell.files.remove(root, { recursive: true });
+        const metadata = await api.put('claude', files, { loginId: claim.login_id });
+        const access = Object.fromEntries(['accessToken', 'expiresAt', 'scopes', 'subscriptionType', 'rateLimitTier'].filter(key => key in credential.claudeAiOauth).map(key => [key, credential.claudeAiOauth[key]]));
+        await cell.files.write('/home/user/.claude/.credentials.json', JSON.stringify({ claudeAiOauth: access }), { mode: '0600', createParents: true });
+        let document = {}, revision = 'absent';
+        try {
+            const current = await cell.files.readWithInfo('/home/user/.claude.json');
+            document = JSON.parse(Buffer.from(current.data).toString());
+            if (!current.revision)
+                throw new UsageError('Claude account configuration has no safe content revision.');
+            revision = current.revision;
+        }
+        catch (error) {
+            if (!(error instanceof Error && 'status' in error && error.status === 404))
+                throw error;
+        }
+        await cell.files.patch({ path: '/home/user/.claude.json', content: JSON.stringify({ ...document, oauthAccount: config.oauthAccount }), expectedRevision: revision, mode: '0600', createParents: true }, { signal: ctx.signal });
+        complete = true;
+        return metadata;
+    }
+    finally {
+        await cell.pty.close(session).catch(() => undefined);
+        await cell.files.remove(root, { recursive: true }).catch(() => undefined);
+        if (!complete)
+            await api.cancelLogin(claim.login_id).catch(() => undefined);
+    }
+}
+export async function ensureCloudClaude(ctx, ws) {
+    if (!await cloudClaudeLogin(ctx))
+        await loginClaudeInWorkspace(ctx, ws);
+}

package/dist/command-center-actions.d.ts

@@ -0,0 +1,6 @@
+import type { Ctx, Handler } from './commands.js';
+import type { Values } from './args.js';
+/** L9 can register target-specific handlers after detecting the installed applications. */
+export declare function availableTargets(ctx: Ctx): Promise<string[]>;
+export declare function agentAction(ctx: Ctx, action: string, values: Values, args: string[]): Promise<number>;
+export declare const CENTER_HANDLERS: Record<string, Handler>;

package/dist/command-center-actions.js

@@ -0,0 +1,132 @@
+import { out, resolveWorkspace, str, waitTimeout, workspaceCaps } from "./commands.js";
+import { launchProject } from "./agent-commands.js";
+import { AgentStateStore } from "./agent-state.js";
+import { agentName } from "./command-center-model.js";
+import { json } from "./format.js";
+import { UsageError } from "./errors.js";
+import { cellConnector, PtyOutputCursor } from "./agent-terminal.js";
+import { rememberGitAgent } from "./agent-git-commands.js";
+import { agentName as gitAgentName } from "./agent-git.js";
+/** L9 can register target-specific handlers after detecting the installed applications. */
+export async function availableTargets(ctx) {
+    const { HANDLERS } = await import("./handlers.js");
+    const detect = HANDLERS['agents targets'];
+    if (!detect)
+        return ['terminal'];
+    let output = '';
+    const code = await detect({ ...ctx, json: true, io: { ...ctx.io, stdout: { write: chunk => { output += Buffer.from(chunk).toString(); return true; } } } }, {}, []);
+    if (code !== 0)
+        throw new Error('open target detection failed');
+    const result = JSON.parse(output);
+    return ['terminal', ...result.targets.filter(target => ['claude-desktop', 'codex-app', 'web'].includes(target) && HANDLERS[`agents open ${target}`])];
+}
+export async function agentAction(ctx, action, values, args) {
+    const { HANDLERS } = await import("./handlers.js");
+    const handler = HANDLERS[`agents ${action}`];
+    if (!handler)
+        throw new UsageError(`agents ${action} is unavailable in this CLI`);
+    return handler(ctx, values, args);
+}
+export const CENTER_HANDLERS = {
+    async 'agents new'(ctx, values, [ref]) {
+        if (values.name !== undefined || !ref || values.path !== undefined) {
+            return launchProject(ctx, { ...values, ...(ref && values.like === undefined ? { like: ref } : {}) }, [str(values.path) ?? './', ...(str(values.app) ? [str(values.app)] : [])]);
+        }
+        return agentAction(ctx, 'open', { ...values, in: 'terminal' }, [ref]);
+    },
+    async 'agents fork'(ctx, values, [ref, name]) {
+        if (!ref || !name || !/^[a-z0-9][a-z0-9._-]{0,63}$/.test(name))
+            throw new UsageError('agents fork requires a source and a new agent name');
+        gitAgentName(name);
+        const source = await resolveWorkspace(ctx, ref);
+        const key = `${source.labels.shard_project || source.key.split('/')[0]}/${name}`;
+        const labels = { ...source.labels, shard_project: source.labels.shard_project || source.key.split('/')[0], agent: name,
+            agent_pty_name: source.labels.agent_pty_name || agentName(source.key, source.labels) };
+        const caps = workspaceCaps(values);
+        const result = await ctx.cloud().workspaces.fork(source.id, { key, labels, ...(caps ? { caps } : {}) }, {
+            agentLabel: ctx.agentLabel, wait: values.wait === false ? false : { timeoutMs: waitTimeout(values), signal: ctx.signal },
+        });
+        const agent = result.operation.result?.agent;
+        const receipt = agent && typeof agent === 'object' ? agent : undefined;
+        if (result.operation.state === 'succeeded' && (!receipt ||
+            ['id', 'workspace_key', 'session_id'].some(field => typeof receipt[field] !== 'string' || !receipt[field]) ||
+            receipt.workspace_key !== key || !['working', 'waiting'].includes(String(receipt.state)))) {
+            throw new Error(`Fork ${key} has no independent agent session receipt`);
+        }
+        await ctx.cloud().workspaces.setRetention(result.workspace.id, { delete_after_idle_days: 7 });
+        await rememberGitAgent(ctx, result.workspace, './');
+        out(ctx, `Forked ${key}: operation ${result.operation.id} ${result.operation.state}\n`, { workspace: result.workspace.data, operation: result.operation, ...(agent ? { agent } : {}) });
+        return 0;
+    },
+    async 'agents park'(ctx, values, [ref]) {
+        if (!ref)
+            throw new UsageError('agents park requires an agent workspace key');
+        const { HANDLERS } = await import("./handlers.js");
+        return HANDLERS['workspaces suspend'](ctx, { ...values, 'when-idle': str(values['when-idle']) ?? '1s' }, [ref]);
+    },
+    async 'agents logs'(ctx, values, [ref]) {
+        if (!ref)
+            throw new UsageError('agents logs requires an agent workspace key');
+        if (values.app !== undefined && values.app !== 'claude' && values.app !== 'codex')
+            throw new UsageError('--app must be claude or codex');
+        const ws = await resolveWorkspace(ctx, ref);
+        const project = ws.labels.repo_remote || ws.labels.shard_project || ws.key;
+        const app = str(values.app) ?? new AgentStateStore(ctx.store.dir).app(project, ws.labels.app === 'codex' ? 'codex' : 'claude');
+        const id = `shard-${ws.labels.agent_pty_name || agentName(ws.key, ws.labels)}-${app}`;
+        const cell = ws.cell({ agentLabel: ctx.agentLabel, ...(ctx.wake ? {} : { wake: null }), transitionTimeoutMs: ctx.wakeTimeoutMs });
+        const offsetText = str(values.offset);
+        if (offsetText !== undefined && (!/^\d+$/.test(offsetText) || !Number.isSafeInteger(Number(offsetText))))
+            throw new UsageError('--offset must be a nonnegative safe integer');
+        const controller = new AbortController();
+        const signal = AbortSignal.any([ctx.signal, controller.signal]);
+        let connection;
+        const stop = () => { void connection?.close(); cell.close(); };
+        signal.addEventListener('abort', stop, { once: true });
+        let timer;
+        try {
+            if (signal.aborted)
+                return 130;
+            const session = await cell.pty.get(id);
+            if (signal.aborted)
+                return 130;
+            const cursor = new PtyOutputCursor();
+            cursor.offset = offsetText === undefined ? Math.max(0, session.output_size - 65_536) : Number(offsetText);
+            const decoder = new TextDecoder();
+            let output = '', exited = false;
+            const following = !ctx.json && values.follow === true;
+            if (!following)
+                timer = setTimeout(() => controller.abort(), 1500);
+            connection = await cellConnector(cell, id)(cursor.offset, signal);
+            for await (const message of connection.messages()) {
+                if (signal.aborted)
+                    break;
+                const bytes = cursor.consume(message);
+                if (bytes) {
+                    const text = decoder.decode(bytes, { stream: true });
+                    if (ctx.json)
+                        output += text;
+                    else
+                        ctx.io.stdout.write(text);
+                    if (!following && cursor.offset >= session.output_size)
+                        break;
+                }
+                if (message.type === 'exit') {
+                    exited = true;
+                    break;
+                }
+            }
+            const remainder = decoder.decode();
+            if (ctx.json)
+                ctx.io.stdout.write(json({ pty_id: id, output: output + remainder, nextOffset: cursor.offset, session, exited }));
+            else
+                ctx.io.stdout.write(remainder);
+            return 0;
+        }
+        finally {
+            clearTimeout(timer);
+            signal.removeEventListener('abort', stop);
+            await connection?.close();
+            cell.close();
+        }
+    },
+};

package/dist/command-center-keys.d.ts

@@ -0,0 +1,6 @@
+export type CenterKey = string;
+export declare class CenterKeys {
+    #private;
+    feed(chunk: Buffer | string): CenterKey[];
+    escape(): CenterKey[];
+}

package/dist/command-center-keys.js

@@ -0,0 +1,38 @@
+import { StringDecoder } from 'node:string_decoder';
+export class CenterKeys {
+    #pending = '';
+    #decoder = new StringDecoder('utf8');
+    feed(chunk) {
+        this.#pending += typeof chunk === 'string' ? chunk : this.#decoder.write(chunk);
+        const keys = [];
+        while (this.#pending) {
+            if (this.#pending[0] === '\x1b') {
+                if (this.#pending.length === 1 || /^\[[0-9;]*$/.test(this.#pending.slice(1)) || this.#pending === '\x1bO')
+                    break;
+                const sequence = /^(?:\[[0-9;]*|O)([A-Za-z~])/.exec(this.#pending.slice(1));
+                if (sequence) {
+                    this.#pending = this.#pending.slice(sequence[0].length + 1);
+                    if (sequence[1] === 'A')
+                        keys.push('up');
+                    if (sequence[1] === 'B')
+                        keys.push('down');
+                    continue;
+                }
+                this.#pending = this.#pending.slice(1);
+                keys.push('escape');
+                continue;
+            }
+            const ch = [...this.#pending][0];
+            this.#pending = this.#pending.slice(ch.length);
+            keys.push(ch === '\r' || ch === '\n' ? 'enter' : ch === '\x7f' || ch === '\b' ? 'backspace' : ch === '\x03' || ch === '\x04' ? 'quit' : ch);
+        }
+        return keys;
+    }
+    escape() {
+        if (this.#pending === '\x1b') {
+            this.#pending = '';
+            return ['escape'];
+        }
+        return [];
+    }
+}

package/dist/command-center-model.d.ts

@@ -0,0 +1,29 @@
+import type { BrowserProfile, Agent, WorkspaceView } from '@shardflux/sdk';
+import type { Ctx } from './commands.js';
+import { projectIdentity } from './project-identity.js';
+import type { SetupProgress } from './assisted-setup.js';
+export interface CenterData {
+    workspaces: WorkspaceView[];
+    agents: Agent[];
+    browserProfiles?: BrowserProfile[];
+    setups?: Record<string, SetupProgress>;
+}
+export type ProjectScope = ReturnType<typeof projectIdentity>;
+export interface CenterRow {
+    id: string;
+    project: string;
+    key: string;
+    agent?: Agent;
+    workspace?: WorkspaceView;
+    start?: boolean;
+    badge: string;
+    attention: number;
+    browserProfiles?: BrowserProfile[];
+    setup?: SetupProgress;
+}
+/** Older K5 captures used the workspace key as the agent label. K1 needs its leaf name. */
+export declare const agentName: (key: string, labels: Record<string, string>) => string;
+export declare const projectName: (key: string, labels: Record<string, string>) => string;
+export declare function loadCenter(ctx: Ctx): Promise<CenterData>;
+export declare function scopedProject(data: CenterData, scope: ProjectScope): string;
+export declare function centerRows(data: CenterData, scope?: ProjectScope, filter?: string): CenterRow[];