@shardflux/cli 0.11.1 → 0.13.1

package/dist/commands.js

@@ -1,3 +1,5 @@
+import { agentReachability } from "./agent-reachability.js";
+import { vaultType, vaultValue, SECRET_SECURITY_NOTE } from "./vault.js";
 /**
  * Command implementations of the project-key commands (workspaces, files, operations, secrets, templates, usage).
  * Everything goes through @shardflux/sdk (the same client, retries, idempotency keys, operation polling and
@@ -6,6 +8,7 @@
  * joins both tables.
  */
 import { computerStreamCache } from "./computer-stream-cache.js";
+import { agentConfigLikeSecrets, syncAgentConfig } from "./agent-config-sync.js";
 import { randomUUID } from 'node:crypto';
 import { access, readFile, writeFile } from 'node:fs/promises';
 import { basename, dirname, resolve as resolvePath } from 'node:path';
@@ -17,7 +20,7 @@ import { updateCheckDisabled } from "./update-check.js";
 import { initTemplateYaml, recipeYaml } from "./template-yaml.js";
 import { BuildTimer, buildTimingJson, buildTimingText, progressLine } from "./timing.js";
 import { timingJson } from "./timing.js";
-import { bindingsText, buildTable, buildText, changesTable, diffSummaryText, diffTable, draftText, draftStateTable, executionJson, executionSummary, fileInfoText, fileTable, languageTable, json, kv, memoryGrowText, burstText, modeText, operationDetail, pairs, resizeJson, resizeText, operationTable, packageTable, searchText, secretAccessTable, secretDetail, secretTable, secretVersionTable, sessionTable, durableText, exposedPortText, portTable, suspendRequestText, suspendWhenIdleText, templateDetailText, templateEntryText, templateFileTable, templateTable, time, usageEstimateText, usageSeriesText, usageText, workspaceDetail, workspaceTable, } from "./format.js";
+import { table, bindingsText, buildTable, buildText, changesTable, diffSummaryText, diffTable, draftText, draftStateTable, executionJson, executionSummary, fileInfoText, fileTable, languageTable, json, kv, memoryGrowText, burstText, modeText, operationDetail, pairs, resizeJson, resizeText, operationTable, packageTable, searchText, secretAccessTable, secretDetail, secretTable, secretVersionTable, sessionTable, durableText, exposedPortText, portTable, suspendRequestText, suspendWhenIdleText, templateDetailText, templateEntryText, templateFileTable, templateTable, time, usageEstimateText, usageSeriesText, usageText, workspaceDetail, workspaceTable, } from "./format.js";
 const DEFAULT_WAIT_MS = 300_000;
 const MAX_JSON_OUTPUT = 16 * 1024 * 1024;
 const MAX_STDIN = 1024 * 1024;
@@ -54,6 +57,23 @@ function withTiming(ctx, machine) {
 export function out(ctx, human, machine) {
     ctx.io.stdout.write(ctx.json ? json(withTiming(ctx, machine)) : human);
 }
+export function openVolumes(values) {
+    if (values.length === 0)
+        return undefined;
+    const mounts = {};
+    for (const value of values) {
+        const match = /^([a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?):(\/[^:]+)(?::(ro|rw))?$/.exec(value);
+        if (!match)
+            throw new UsageError('--volume expects name:/absolute/path[:ro]');
+        const [, name, path, mode] = match;
+        if (Object.hasOwn(mounts, path))
+            throw new UsageError(`--volume names mount ${path} twice`);
+        if (Object.values(mounts).some((v) => (typeof v === 'string' ? v : v.name) === name))
+            throw new UsageError(`--volume names volume ${name} twice`);
+        mounts[path] = mode ? { name: name, mode: mode } : name;
+    }
+    return mounts;
+}
 function caps(values) {
     const c = {};
     const cpu = str(values['cpu-millis']);
@@ -105,7 +125,7 @@ function resizeParams(values) {
  * The caps of `workspaces open` and `workspaces fork` (0.8.0): the resource caps plus the memory allocation. Given caps
  * replace the stored ones, so they are sent only when a flag was given.
  */
-function workspaceCaps(values) {
+export function workspaceCaps(values) {
     const c = caps(values) ?? {};
     const mode = oneOf(values, 'allocation-mode', ALLOCATION_MODES);
     const held = str(values['memory-held']);
@@ -651,9 +671,23 @@ function imageOpts(values) {
 function lookOpts(values) {
     const shotTo = str(values.screenshot);
     const settle = str(values.settle);
+    const pixelText = str(values['pixel-predicate']);
+    let pixelPredicate;
+    if (pixelText !== undefined) {
+        try {
+            pixelPredicate = JSON.parse(pixelText);
+        }
+        catch {
+            throw new UsageError('--pixel-predicate must be a JSON object');
+        }
+        if (!pixelPredicate || typeof pixelPredicate !== 'object' || Array.isArray(pixelPredicate))
+            throw new UsageError('--pixel-predicate must be a JSON object');
+        if (shotTo === undefined || settle !== undefined || str(values.format) === 'jpeg')
+            throw new UsageError('--pixel-predicate requires --screenshot, PNG and no --settle');
+    }
     if (settle !== undefined && (!/^\d+$/.test(settle.trim()) || Number(settle) > 10_000))
         throw new UsageError(`--settle must be 0 to 10000 milliseconds (got "${settle}")`);
-    return { shotTo, req: { screenshot: shotTo !== undefined, ...(settle !== undefined ? { settle_ms: Number(settle) } : {}), ...imageOpts(values) } };
+    return { shotTo, req: { screenshot: shotTo !== undefined, ...(pixelPredicate ? { pixel_predicate: pixelPredicate } : {}), ...(settle !== undefined ? { settle_ms: Number(settle) } : {}), ...imageOpts(values) } };
 }
 /** A screen coordinate argument (pixels from the top-left). */
 function pixel(text, name) {
@@ -687,7 +721,9 @@ async function runComputer(ctx, ref, actions, look) {
     });
     const tail = `cursor ${r.cursor[0]},${r.cursor[1]} on a ${r.display.width}x${r.display.height} screen${look.shotTo !== undefined && r.screenshot ? `; screenshot written to ${look.shotTo}` : ''}`;
     out(ctx, `${lines.join('\n')}${lines.length ? '\n' : ''}${tail}\n`, r);
-    return r.results.every((x) => x.ok) ? 0 : 1;
+    if (r.pixel_completion && !r.pixel_completion.matched)
+        ctx.io.stderr.write(`Pixel condition failed: ${r.pixel_completion.reason}; input results above say which actions ran.\n`);
+    return r.results.every((x) => x.ok) && r.pixel_completion?.matched !== false ? 0 : 1;
 }
 async function computerWorkspace(ctx, ref) {
     const ws = await resolveWorkspace(ctx, ref);
@@ -748,7 +784,41 @@ function lifecycleText(verb, w, op) {
     return `${verb} ${w.key !== undefined ? `${w.key} (${w.id})` : w.id}: operation ${op.id} ${op.kind} ${op.state}${op.state_reason ? ` (${op.state_reason})` : ''}\n${finished ? durableText(op) : `wait with: shard operations wait ${op.id}\n`}`;
 }
 /** The project-key commands; handlers.ts adds the account plane's. */
+function agentGrace(text) {
+    if (!/^[0-9]+$/.test(text) || Number(text) > 3600)
+        throw new UsageError('--agent-idle-grace-seconds must be 0–3600');
+    return Number(text);
+}
 export const KEY_HANDLERS = {
+    async 'agents list'(ctx, values) {
+        const state = str(values.state);
+        if (state && !['working', 'waiting', 'exited'].includes(state))
+            throw new UsageError('--state must be working, waiting or exited');
+        const labels = {};
+        for (const pair of strs(values.label)) {
+            const i = pair.indexOf('=');
+            if (i < 1)
+                throw new UsageError('--label must be key=value');
+            labels[pair.slice(0, i)] = pair.slice(i + 1);
+        }
+        const opts = {
+            ...(state ? { state: state } : {}), labels,
+            ...(str(values.limit) ? { limit: parsePositiveInt(str(values.limit), 'limit', 200) } : {}),
+        };
+        const rows = [];
+        let cursor = str(values.cursor);
+        let next;
+        do {
+            const page = await ctx.cloud().agents.list({ ...opts, ...(cursor ? { cursor } : {}) });
+            rows.push(...page.data);
+            next = page.nextCursor;
+            cursor = next ?? undefined;
+        } while (values.all === true && cursor);
+        out(ctx, rows.length ? table(['WORKSPACE', 'APP', 'STATE', 'TITLE'], rows.map(a => [a.workspace_key, a.app, a.state, a.title])) : 'No agent sessions.\n', { data: rows, next_cursor: next });
+        if (!ctx.json && next)
+            ctx.io.stderr.write(`more: shard agents list --cursor ${next}\n`);
+        return 0;
+    },
     async login(ctx) {
         const p = await principal(ctx);
         const where = ctx.apiKey().source === 'env'
@@ -977,8 +1047,10 @@ export const KEY_HANDLERS = {
     },
     async 'workspaces open'(ctx, values, [key]) {
         const template = str(values.template);
-        if (!template)
-            throw new UsageError('--template <slug> is required for "shard workspaces open"');
+        const like = str(values.like);
+        if (!template && !like)
+            throw new UsageError('--template <slug> or --like <id|key> is required for "shard workspaces open"');
+        const volumes = openVolumes(strs(values.volume));
         const c = workspaceCaps(values);
         const bind = secretNames(strs(values.secret), '--secret');
         const lifetime = oneOf(values, 'lifetime', LIFETIMES);
@@ -994,14 +1066,19 @@ export const KEY_HANDLERS = {
         const cloud = ctx.cloud();
         // The SDK's waited open: the server holds the request until the workspace is ready (Prefer: wait), then the SDK
         // polls for what is left of --timeout; one trace (ws.lastTiming) covers all of it.
+        const openSecrets = bind.length ? bind : like ? await agentConfigLikeSecrets(ctx, like) : undefined;
         const ws = await waited(ctx, 'the open continues server side (open the key again to keep waiting).', () => cloud.workspaces.open({
             key: key,
-            template,
+            ...(template ? { template } : {}),
+            ...(like ? { like } : {}),
+            ...(volumes ? { volumes } : {}),
             ...(str(values.labels) !== undefined ? { labels: labelMap(str(values.labels)) } : {}),
             ...(str(values['delete-after-idle']) !== undefined ? { retention: openRetentionDays(str(values['delete-after-idle'])) } : {}),
+            ...agentReachability(values),
+            ...(str(values['agent-idle-grace-seconds']) !== undefined ? { agentIdleGraceSeconds: agentGrace(str(values['agent-idle-grace-seconds'])) } : {}),
             ...(str(values['idle-policy']) ? { idlePolicy: str(values['idle-policy']) } : {}),
             ...(c ? { caps: c } : {}),
-            ...(bind.length ? { secrets: bind } : {}),
+            ...(openSecrets ? { secrets: openSecrets } : {}),
             ...(inputs ? { inputs } : {}),
             ...(lifetime ? { lifetime } : {}),
             ...(mode ? { mode } : {}),
@@ -1010,6 +1087,8 @@ export const KEY_HANDLERS = {
             wait: values.wait === false ? false : { timeoutMs, signal: ctx.signal },
         }));
         const op = ws.activeOperation;
+        if (ws.ready && ws.mode === 'processful' && ws.labels.shard_project)
+            await syncAgentConfig(ctx, ws);
         const view = ws.data;
         const human = ws.ready
             ? `Workspace ${ws.key} (${ws.id}) is ready.\n${workspaceDetail(view)}`
@@ -1055,6 +1134,8 @@ export const KEY_HANDLERS = {
     },
     async 'workspaces get'(ctx, _values, [ref]) {
         const ws = await resolveWorkspace(ctx, ref);
+        if (!UUID.test(ref))
+            await ws.refresh();
         out(ctx, workspaceDetail(ws.data), ws.data);
         return 0;
     },
@@ -1177,6 +1258,14 @@ export const KEY_HANDLERS = {
         }
         return code;
     },
+    async 'files read-many'(ctx, values, [ref]) {
+        const paths = Array.isArray(values.path) ? values.path.map(String) : typeof values.path === 'string' ? [values.path] : [];
+        const ws = await resolveWorkspace(ctx, ref);
+        const result = await cellOf(ctx, ws).files.readSealedMany(paths, { generation: str(values.generation) });
+        const wire = { ...result, items: result.items.map(item => item.data === undefined ? item : { ...item, data: Buffer.from(item.data).toString('base64') }) };
+        ctx.io.stdout.write(json(withTiming(ctx, wire)));
+        return result.complete ? 0 : 1;
+    },
     async 'files read'(ctx, values, [ref, path]) {
         const ws = await resolveWorkspace(ctx, ref);
         const bytes = await cellOf(ctx, ws).files.read(path);
@@ -1985,6 +2074,13 @@ export const KEY_HANDLERS = {
             throw new UsageError('<text> must not be empty');
         return runComputer(ctx, ref, [{ action: 'type', text }], lookOpts(values));
     },
+    async 'workspaces computer paste-text'(ctx, values, [ref, source]) {
+        const text = source === '-' ? Buffer.from(await readInput(ctx, '-', 256 << 10, 'text')).toString('utf8') : source;
+        if (text === '')
+            throw new UsageError('<text> must not be empty');
+        const chord = str(values['paste-chord']);
+        return runComputer(ctx, ref, [{ action: 'pasteText', text, ...(chord !== undefined ? { paste_chord: chord } : {}) }], lookOpts(values));
+    },
     async 'workspaces computer key'(ctx, values, [ref, keys]) {
         const repeat = str(values.repeat) !== undefined ? parsePositiveInt(str(values.repeat), 'repeat', 100) : undefined;
         return runComputer(ctx, ref, [{ action: 'key', text: keys, ...(repeat !== undefined ? { repeat } : {}) }], lookOpts(values));
@@ -2101,6 +2197,25 @@ export const KEY_HANDLERS = {
         out(ctx, bindingsText(b), b);
         return 0;
     },
+    async 'secrets import'(ctx, values, names) {
+        const from = vaultType(str(values.from));
+        const alias = str(values.as);
+        const keychain = str(values.keychain);
+        if (alias && names.length !== 1)
+            throw new UsageError('--as requires exactly one item');
+        if (keychain && from !== 'keychain')
+            throw new UsageError('--keychain applies to the keychain vault');
+        const targets = secretNames(names.map(n => alias ?? n), '--as');
+        const project = (await principal(ctx)).project_id;
+        const imported = [];
+        for (const [i, name] of names.entries()) {
+            const value = await vaultValue(from, name, { signal: ctx.signal, ...(keychain ? { keychain } : {}) });
+            ctx.addSecret(value);
+            imported.push(await ctx.cloud().secrets.create(project, { name: targets[i], value }));
+        }
+        out(ctx, `Imported ${imported.map(s => s.name).join(', ')}. ${SECRET_SECURITY_NOTE}\n`, { data: imported, security_note: SECRET_SECURITY_NOTE });
+        return 0;
+    },
     async 'secrets create'(ctx, values, [name]) {
         if (!SECRET_NAME.test(name))
             throw new UsageError(`<name> must be an environment variable name like OPENAI_API_KEY (^[A-Z_][A-Z0-9_]*$), got "${name}"`);

package/dist/credential-prompts.d.ts

@@ -0,0 +1,22 @@
+import type { CredentialRequest, Workspace } from '@shardflux/sdk';
+import type { Ctx, Handler } from './commands.js';
+import type { Vault } from './vault.js';
+type Selection = {
+    vault: Vault;
+    item: string;
+    always: boolean;
+    fields: CredentialRequest['fields'];
+};
+export declare class SiteVaultStore {
+    readonly file: string;
+    constructor(directory: string);
+    key(api: string, project: string, site: string): string;
+    read(): Record<string, Selection>;
+    get(api: string, project: string, site: string): Selection | undefined;
+    save(api: string, project: string, site: string, selection: Selection): void;
+}
+export declare function approveCredential(ctx: Ctx, request: CredentialRequest, selection: Selection, remember?: boolean): Promise<void>;
+export declare function configureCredentialFill(ctx: Ctx, ws: Workspace): Promise<boolean>;
+export declare function watchCredentialPrompts(ctx: Ctx, ws: Workspace, ask: (message: string) => Promise<string>, signal: AbortSignal): Promise<void>;
+export declare const CREDENTIAL_HANDLERS: Record<string, Handler>;
+export {};

package/dist/credential-prompts.js

@@ -0,0 +1,193 @@
+import { chmodSync, existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { ShardfluxApiError, sealCredential } from '@shardflux/sdk';
+import { resolveWorkspace } from "./commands.js";
+import { str } from "./commands.js";
+import { UsageError } from "./errors.js";
+import { REMEMBERED_SECURITY_NOTE, VAULT_SECURITY_NOTE, vaultCredential, vaultType } from "./vault.js";
+export class SiteVaultStore {
+    file;
+    constructor(directory) {
+        this.file = join(directory, 'site-vaults.json');
+    }
+    key(api, project, site) {
+        return JSON.stringify([api.replace(/\/$/, ''), project, site]);
+    }
+    read() {
+        if (!existsSync(this.file))
+            return {};
+        const raw = JSON.parse(readFileSync(this.file, 'utf8'));
+        if (!raw || typeof raw !== 'object' || Array.isArray(raw))
+            throw new UsageError('Could not read site vault choices.');
+        return raw;
+    }
+    get(api, project, site) {
+        return this.read()[this.key(api, project, site)];
+    }
+    save(api, project, site, selection) {
+        const all = this.read();
+        all[this.key(api, project, site)] = selection;
+        mkdirSync(join(this.file, '..'), { recursive: true, mode: 0o700 });
+        const temp = `${this.file}.${process.pid}.tmp`;
+        writeFileSync(temp, JSON.stringify(all), { mode: 0o600, flag: 'wx' });
+        renameSync(temp, this.file);
+        chmodSync(this.file, 0o600);
+    }
+}
+export async function approveCredential(ctx, request, selection, remember = false) {
+    if (request.state !== 'pending' || Date.parse(request.expires_at) <= Date.now())
+        throw new UsageError(`Credential request ${request.id} has expired or ended. ${VAULT_SECURITY_NOTE}`);
+    const credential = await vaultCredential(selection.vault, selection.item, request.site, { signal: ctx.signal });
+    for (const value of Object.values(credential))
+        if (typeof value === 'string' && value)
+            ctx.addSecret(value);
+    const required = request.fields.map((f) => (f === 'totp' ? 'totp_seed' : f));
+    if (required.some((f) => !credential[f]))
+        throw new UsageError(`The item does not contain every requested field. ${VAULT_SECURITY_NOTE}`);
+    const subset = Object.fromEntries(required.map((f) => [f, credential[f]]));
+    const ciphertext = sealCredential(request.public_key, request, subset);
+    const answered = await ctx.cloud().credentialRequests.fulfil(request.id, ciphertext);
+    if (answered.state !== 'fulfilled')
+        throw new UsageError(`Credential request is ${answered.state}. ${VAULT_SECURITY_NOTE}`);
+    if (remember)
+        await ctx.cloud().credentialRequests.remember(request.workspace_id, request.site, credential);
+    new SiteVaultStore(ctx.store.dir).save(ctx.apiUrl, request.project_id, request.site, selection);
+    ctx.io.stderr.write(`Approved ${request.site}. ${remember ? REMEMBERED_SECURITY_NOTE : VAULT_SECURITY_NOTE}\n`);
+}
+export async function configureCredentialFill(ctx, ws) {
+    try {
+        await ctx.cloud().credentialRequests.configure(ws, { signal: ctx.signal });
+        return true;
+    }
+    catch (e) {
+        if (e instanceof ShardfluxApiError &&
+            (e.status === 403 ||
+                e.status === 404 ||
+                (e.status === 503 && e.details?.reason === 'credential_requests_unavailable')))
+            return false;
+        // Fill is optional while older guest images are still in use.
+        // The explicit credentials enable command continues to report the failure.
+        if (e instanceof Error && e.message.startsWith('Credential '))
+            return false;
+        throw e;
+    }
+}
+export async function watchCredentialPrompts(ctx, ws, ask, signal) {
+    const seen = new Set();
+    const store = new SiteVaultStore(ctx.store.dir);
+    while (!signal.aborted) {
+        const page = await ctx.cloud().credentialRequests.list({
+            workspaceId: ws.id,
+            state: 'pending',
+            limit: 200,
+        });
+        for (const r of page.data) {
+            if (signal.aborted)
+                return;
+            if (seen.has(r.id))
+                continue;
+            seen.add(r.id);
+            try {
+                const saved = store.get(ctx.apiUrl, r.project_id, r.site);
+                if (saved?.always && r.fields.every((f) => saved.fields.includes(f))) {
+                    await approveCredential(ctx, r, saved);
+                    continue;
+                }
+                const choice = (await ask(`${r.site} requests ${r.fields.join(', ')}. Allow once / Always for this project / Deny [once/always/deny]. ${VAULT_SECURITY_NOTE}\n`)).toLowerCase();
+                if (choice === 'deny') {
+                    await ctx.cloud().credentialRequests.deny(r.id);
+                    ctx.io.stderr.write(`Denied ${r.site}. ${VAULT_SECURITY_NOTE}\n`);
+                    continue;
+                }
+                if (choice !== 'once' && choice !== 'always')
+                    throw new UsageError(`Choose once, always or deny. ${VAULT_SECURITY_NOTE}`);
+                const vault = vaultType(saved?.vault ?? (await ask(`Choose hsec, 1password, bitwarden or keychain. ${VAULT_SECURITY_NOTE}\n`)));
+                const item = saved?.item ?? (await ask(`Vault item name for ${r.site}. ${VAULT_SECURITY_NOTE}\n`));
+                const remember = (await ask(`Remember for unattended use? [yes/no]. ${REMEMBERED_SECURITY_NOTE}\n`)).toLowerCase() === 'yes';
+                await approveCredential(ctx, r, { vault, item, always: choice === 'always', fields: r.fields }, remember);
+            }
+            catch (e) {
+                if (signal.aborted)
+                    return;
+                ctx.io.stderr.write(`Credential approval could not finish. ${VAULT_SECURITY_NOTE}\n`);
+                if (e instanceof ShardfluxApiError && e.status === 401)
+                    throw e;
+            }
+        }
+        await new Promise((resolve) => {
+            const done = () => {
+                clearTimeout(timer);
+                signal.removeEventListener('abort', done);
+                resolve();
+            };
+            const timer = setTimeout(done, 5000);
+            signal.addEventListener('abort', done, { once: true });
+            if (signal.aborted)
+                done();
+        });
+    }
+}
+export const CREDENTIAL_HANDLERS = {
+    async 'secrets log'(ctx) {
+        const events = await ctx.cloud().credentialRequests.events({ limit: 200 });
+        ctx.io.stdout.write(ctx.json
+            ? JSON.stringify({ ...events, security_note: VAULT_SECURITY_NOTE }) + '\n'
+            : events.data
+                .map((e) => `${e.created_at} ${e.action} ${typeof e.details.site === 'string' ? e.details.site : ''}. ${VAULT_SECURITY_NOTE}\n`)
+                .join(''));
+        return 0;
+    },
+    async 'credentials list'(ctx) {
+        const page = await ctx.cloud().credentialRequests.list({ state: 'pending', limit: 200 });
+        ctx.io.stdout.write(ctx.json
+            ? JSON.stringify({ ...page, security_note: VAULT_SECURITY_NOTE }) + '\n'
+            : page.data.map((r) => `${r.id} ${r.site} ${r.fields.join(', ')}. ${VAULT_SECURITY_NOTE}\n`).join(''));
+        return 0;
+    },
+    async 'credentials enable'(ctx, _values, [ref]) {
+        const ws = await resolveWorkspace(ctx, ref);
+        await ctx.cloud().credentialRequests.configure(ws, { signal: ctx.signal });
+        ctx.io.stdout.write(ctx.json
+            ? JSON.stringify({
+                enabled: true,
+                workspace_id: ws.id,
+                security_note: VAULT_SECURITY_NOTE,
+            }) + '\n'
+            : `Credential fill enabled for ${ws.key}. ${VAULT_SECURITY_NOTE}\n`);
+        return 0;
+    },
+    async 'credentials approve'(ctx, values, [id]) {
+        const { request } = await ctx.cloud().credentialRequests.get(id);
+        const vault = vaultType(str(values.from));
+        const item = str(values.item);
+        if (!item)
+            throw new UsageError('--item names a vault login');
+        await approveCredential(ctx, request, { vault, item, always: values.always === true, fields: request.fields }, values.remember === true);
+        if (ctx.json)
+            ctx.io.stdout.write(JSON.stringify({
+                approved: true,
+                request_id: request.id,
+                security_note: values.remember === true ? REMEMBERED_SECURITY_NOTE : VAULT_SECURITY_NOTE,
+            }) + '\n');
+        return 0;
+    },
+    async 'credentials deny'(ctx, _values, [id]) {
+        const r = await ctx.cloud().credentialRequests.deny(id);
+        ctx.io.stdout.write(ctx.json
+            ? JSON.stringify({ ...r, security_note: VAULT_SECURITY_NOTE }) + '\n'
+            : `Credential request ${r.state}. ${VAULT_SECURITY_NOTE}\n`);
+        return 0;
+    },
+    async 'credentials forget'(ctx, _values, [ref, site]) {
+        const ws = await resolveWorkspace(ctx, ref);
+        await ctx.cloud().credentialRequests.forget(ws.id, site);
+        ctx.io.stdout.write(ctx.json
+            ? JSON.stringify({
+                forgotten: true,
+                site,
+                security_note: REMEMBERED_SECURITY_NOTE,
+            }) + '\n'
+            : `Removed remembered credential for ${site}. ${REMEMBERED_SECURITY_NOTE}\n`);
+        return 0;
+    },
+};

package/dist/filesystem-commands.d.ts

@@ -0,0 +1,2 @@
+import type { Handler } from './commands.js';
+export declare const FILESYSTEM_HANDLERS: Record<string, Handler>;

package/dist/filesystem-commands.js

@@ -0,0 +1,63 @@
+import { UsageError } from "./errors.js";
+import { projectIdentity, normalizeRemote } from "./project-identity.js";
+import { AGENT_HANDLERS } from "./agent-commands.js";
+import { syncAgentConfig } from "./agent-config-sync.js";
+function remote() {
+    const project = projectIdentity('./');
+    return { project, repoRemote: project.remote ?? normalizeRemote(`file://${project.folder}`) };
+}
+function output(ctx, state) {
+    ctx.io.stdout.write(ctx.json ? JSON.stringify(state) + '\n' : `${state.level}: ${state.state}; version ${state.version}\n` +
+        (state.pending ? `Saving version ${state.pending.version}. Run shard ${state.level} --json for progress.\n` : '') +
+        (state.failure ? `${state.failure.message}\n` : '') +
+        (state.template ? `${state.template.slug}@${state.template.version}\n` : 'No saved version yet.\n'));
+    return 0;
+}
+const rollbackTo = (value) => {
+    if (value === undefined)
+        return undefined;
+    const n = Number(value);
+    if (!Number.isSafeInteger(n) || n < 1)
+        throw new UsageError('--to must be a saved version number');
+    return n;
+};
+export const FILESYSTEM_HANDLERS = {
+    async machine(ctx) {
+        const cloud = ctx.cloud();
+        const state = await cloud.machine.get({ signal: ctx.signal });
+        if (ctx.json || !ctx.io.stdin.isTTY)
+            return output(ctx, state);
+        const key = `machine/${state.organization_id}/v${state.version}`;
+        const ws = await cloud.workspaces.open({ key, template: state.template ? `${state.template.slug}@${state.template.version}` : 'coding',
+            labels: { shard_layer: 'machine', shard_machine: state.organization_id, repo_path: '/home/user', app: 'claude', agent: 'machine' },
+            wait: { timeoutMs: ctx.wakeTimeoutMs, signal: ctx.signal } });
+        if (state.version === 0)
+            await syncAgentConfig(ctx, ws);
+        return AGENT_HANDLERS['agents open'](ctx, {}, [ws.key]);
+    },
+    async 'machine save'(ctx) {
+        const cloud = ctx.cloud();
+        const state = await cloud.machine.get({ signal: ctx.signal });
+        const ws = await cloud.workspaces.findByKey(`machine/${state.organization_id}/v${state.version}`, { signal: ctx.signal }) ??
+            (state.workspace_id ? await cloud.workspaces.get(state.workspace_id) : null);
+        if (!ws)
+            throw new UsageError('Open shard machine, change it, then run shard machine save');
+        return output(ctx, await cloud.machine.save({ workspaceId: ws.id }, { signal: ctx.signal }));
+    },
+    async 'machine rollback'(ctx, values) {
+        return output(ctx, await ctx.cloud().machine.rollback({ to: rollbackTo(values.to) }, { signal: ctx.signal }));
+    },
+    async template(ctx) {
+        return output(ctx, await ctx.cloud().templates.getProject(remote().repoRemote, { signal: ctx.signal }));
+    },
+    async 'template save'(ctx) {
+        const { project, repoRemote } = remote();
+        const ws = await ctx.cloud().workspaces.findByKey(`${project.slug}/main`, { signal: ctx.signal });
+        if (!ws)
+            throw new UsageError('Run shard ./ for this project before saving its template');
+        return output(ctx, await ctx.cloud().templates.saveProject({ repoRemote, workspaceId: ws.id }, { signal: ctx.signal }));
+    },
+    async 'template rollback'(ctx, values) {
+        return output(ctx, await ctx.cloud().templates.rollbackProject({ repoRemote: remote().repoRemote, to: rollbackTo(values.to) }, { signal: ctx.signal }));
+    },
+};

package/dist/filesystem-state.d.ts

@@ -0,0 +1,3 @@
+import type { AgentFilesystem } from '@shardflux/sdk';
+import type { Ctx } from './commands.js';
+export declare function savedMachine(ctx: Ctx): Promise<AgentFilesystem | undefined>;

package/dist/filesystem-state.js

@@ -0,0 +1,12 @@
+import { ShardfluxApiError } from '@shardflux/sdk';
+export async function savedMachine(ctx) {
+    try {
+        return await ctx.cloud().machine.get({ signal: ctx.signal });
+    }
+    catch (err) {
+        // Older APIs have no filesystem route; unmigrated APIs report its dependency.
+        if (err instanceof ShardfluxApiError && (err.status === 404 || err.details?.reason === 'filesystem_unavailable'))
+            return undefined;
+        throw err;
+    }
+}

package/dist/git-remote-bin.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/git-remote-bin.js

@@ -0,0 +1,37 @@
+#!/usr/bin/env node
+import { Shardflux } from '@shardflux/sdk';
+import { CredentialStore, configDir } from "./credentials.js";
+import { resolveApiUrl } from "./args.js";
+import { remoteHelper } from "./git-remote.js";
+import { redact } from "./errors.js";
+const controller = new AbortController();
+const abort = () => { controller.abort(); process.stdin.destroy(); };
+process.once('SIGINT', abort);
+process.once('SIGTERM', abort);
+let cell;
+let key = '';
+try {
+    const apiUrl = resolveApiUrl(undefined, process.env.SHARDFLUX_API_URL ?? process.env.SHARDFLUX_BASE_URL);
+    const store = new CredentialStore(configDir(process.env));
+    process.exitCode = await remoteHelper(process.argv[3] ?? process.argv[2] ?? '', process.stdin, process.stdout, process.stderr, async (remote) => {
+        key = process.env.SHARDFLUX_API_KEY?.trim() || store.profile(apiUrl).api_key?.token || '';
+        if (!key)
+            throw new Error('sign in and save a project key with shard setup');
+        const cloud = new Shardflux({ apiKey: key, baseUrl: apiUrl, versionCheck: false });
+        const ws = await cloud.workspaces.findByKey(remote.key, { includeDeleted: false, signal: controller.signal });
+        if (!ws)
+            throw new Error(`workspace ${remote.key} does not exist`);
+        cell = ws.cell({ agentLabel: 'git-remote-shard', transitionTimeoutMs: 120_000 });
+        return cell.exec;
+    }, controller.signal);
+}
+catch (error) {
+    process.stderr.write(`git-remote-shard: ${redact(error instanceof Error ? error.message : String(error), key)}\n`);
+    process.exitCode = controller.signal.aborted ? 130 : 1;
+}
+finally {
+    cell?.close();
+    process.stdin.destroy();
+    process.removeListener('SIGINT', abort);
+    process.removeListener('SIGTERM', abort);
+}

package/dist/git-remote-helper.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Git finds a remote helper as `git-remote-<transport>` on PATH. The package exposes only `shard` (a single bin keeps
+ * `npx @shardflux/cli` working), so the git commands shard runs get a private directory on PATH holding a
+ * `git-remote-shard` shim that runs this installation's helper with the same Node.
+ */
+export declare function gitRemoteHelperDir(env?: NodeJS.ProcessEnv): string;
+/** PATH for git commands shard runs: the helper directory first, then the caller's PATH. */
+export declare function gitPath(env?: NodeJS.ProcessEnv): string;

package/dist/git-remote-helper.js

@@ -0,0 +1,31 @@
+import { chmodSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { delimiter, extname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+/**
+ * Git finds a remote helper as `git-remote-<transport>` on PATH. The package exposes only `shard` (a single bin keeps
+ * `npx @shardflux/cli` working), so the git commands shard runs get a private directory on PATH holding a
+ * `git-remote-shard` shim that runs this installation's helper with the same Node.
+ */
+export function gitRemoteHelperDir(env = process.env) {
+    const dir = join(env.XDG_CACHE_HOME || join(homedir(), '.cache'), 'shardflux', 'git-remote');
+    const script = fileURLToPath(new URL(`./git-remote-bin${extname(fileURLToPath(import.meta.url))}`, import.meta.url));
+    const quote = (s) => `'${s.replaceAll("'", `'\\''`)}'`;
+    const shim = `#!/bin/sh\nexec ${quote(process.execPath)} ${quote(script)} "$@"\n`;
+    const target = join(dir, 'git-remote-shard');
+    let current = '';
+    try {
+        current = readFileSync(target, 'utf8');
+    }
+    catch { /* first use */ }
+    if (current !== shim) {
+        mkdirSync(dir, { recursive: true, mode: 0o700 });
+        writeFileSync(target, shim, { mode: 0o755 });
+        chmodSync(target, 0o755);
+    }
+    return dir;
+}
+/** PATH for git commands shard runs: the helper directory first, then the caller's PATH. */
+export function gitPath(env = process.env) {
+    return [gitRemoteHelperDir(env), env.PATH].filter(Boolean).join(delimiter);
+}

package/dist/git-remote.d.ts

@@ -0,0 +1,14 @@
+import type { CellClient } from '@shardflux/sdk';
+import type { Readable, Writable } from 'node:stream';
+export interface ShardRemote {
+    key: string;
+    path: string;
+}
+/** Keys have two segments (K9). Everything after the agent is an absolute guest path. */
+export declare function parseShardRemote(url: string): ShardRemote;
+export declare function shardRemote(key: string, path: string): string;
+export type GitExec = Pick<CellClient['exec'], 'start' | 'input' | 'output' | 'cancel'>;
+/** No text decoding of the pack stream; offsets are acknowledged bytes, including partial stdin writes. */
+export declare function bridgeGit(exec: GitExec, service: string, path: string, input: AsyncIterable<Uint8Array>, stdout: Writable, stderr: Writable, signal: AbortSignal): Promise<number>;
+/** Git's `connect` capability switches from newline commands to a full-duplex smart protocol. */
+export declare function remoteHelper(url: string, stdin: Readable, stdout: Writable, stderr: Writable, connect: (remote: ShardRemote) => Promise<GitExec>, signal: AbortSignal): Promise<number>;