@shardflux/cli 0.20.0 → 0.22.0

package/dist/codex-cloud.js

@@ -2,7 +2,7 @@ import { spawn } from 'node:child_process';
 import { CodedError, UsageError } from "./errors.js";
 import { json } from "./format.js";
 import { syncAgentCredentials } from "./agent-credentials.js";
-import { createConversation, getConversation, recordedChoice, resumeConversation } from "./conversations.js";
+import { createConversation, conversationWorkspace, getConversation, localConversations, recordedChoice, resumeConversation, seedConversation } from "./conversations.js";
 import { CHOICE_PENDING, choiceReport, hasChoice, modelChoice } from "./agent-models.js";
 import { AgentStateStore } from "./agent-state.js";
 import { ensureProjectGit } from "./project-git.js";
@@ -128,24 +128,68 @@ export async function launchCodexCloud(ctx, values, path, images = []) {
     await ensureProjectGit(ctx, project.folder);
     await gitRunner(project.folder, { ...process.env, ...ctx.io.env }, ctx.signal)(['rev-parse', 'HEAD']);
     await ensureCodexCloud(ctx);
-    const created = await createConversation(ctx, path, 'codex', 'codex-cloud', typeof values.name === 'string' ? values.name : undefined, choice);
-    const c = created.conversation;
-    // --computer: the conversation VM's desktop is on before Codex starts, so the thread gets the computer tools.
-    if (values.computer === true)
-        await created.workspace.setComputerUse(true);
-    // The thread's tools run in this VM, so its first message can name the images by their VM paths.
-    await uploadInitialImages(created.workspace.cell(), images, ctx.signal);
-    // Idempotency follows the durable conversation, including a lost response.
-    await ctx.cloud().codex.admit(c.id, { idempotencyKey: `codex-${c.id}`, signal: ctx.signal });
-    const task = await ctx.cloud().codex.waitTask(c.id, { timeoutMs: ctx.wakeTimeoutMs, signal: ctx.signal });
-    new AgentStateStore(ctx.store.dir).save(project.remote ?? project.folder, 'codex');
-    const submitted = typeof values.initialPrompt === 'string';
-    if (submitted)
-        await submitCloudInitialPrompt(ctx, c, values.initialPrompt, created.workspace.key);
-    await output(ctx, c, task, submitted, choice);
-    return 0;
+    const patch = (id, update) => new AgentStateStore(ctx.store.dir).update(doc => {
+        const records = doc.conversations;
+        const r = records[id];
+        if (r?.cloud_start)
+            r.cloud_start = { ...r.cloud_start, ...update };
+    });
+    let release;
+    try {
+        const created = await createConversation(ctx, path, 'codex', 'codex-cloud', typeof values.name === 'string' ? values.name : undefined, choice, undefined, undefined, undefined, {
+            accepted(c) {
+                new AgentStateStore(ctx.store.dir).update(doc => {
+                    const records = doc.conversations;
+                    records[c.id].cloud_start = { ...(typeof values.initialPrompt === 'string' ? { prompt: values.initialPrompt } : {}), computer: values.computer === true, attachments_pending: images.length > 0, state: 'accepted', heartbeat_at: Date.now() };
+                });
+                release = carryStart(ctx, c.id);
+            },
+            async beforeSeed(ws, c) {
+                if (values.computer === true)
+                    await ws.setComputerUse(true);
+                await uploadInitialImages(ws.cell(), images, ctx.signal);
+                patch(c.id, { attachments_pending: false });
+            },
+        });
+        const c = created.conversation;
+        // --computer: the conversation VM's desktop is on before Codex starts, so the thread gets the computer tools.
+        // The thread's tools run in this VM, so its first message can name the images by their VM paths.
+        // Idempotency follows the durable conversation, including a lost response.
+        await ctx.cloud().codex.admit(c.id, { idempotencyKey: `codex-${c.id}`, signal: ctx.signal });
+        const task = await ctx.cloud().codex.waitTask(c.id, { timeoutMs: ctx.wakeTimeoutMs, signal: ctx.signal });
+        new AgentStateStore(ctx.store.dir).save(project.remote ?? project.folder, 'codex');
+        const submitted = typeof values.initialPrompt === 'string';
+        if (submitted)
+            await submitCloudInitialPrompt(ctx, c, values.initialPrompt, created.workspace.key);
+        patch(c.id, { state: 'active', submitted, prompt: undefined });
+        await output(ctx, c, task, submitted, choice);
+        return 0;
+    }
+    finally {
+        release?.();
+    }
+}
+/**
+ * While this process carries an accepted start it says so every 10 s (0.22.0+): the device helper resumes only a start
+ * nobody carries, never one a foreground command is still running.
+ */
+function carryStart(ctx, id) {
+    const beat = () => new AgentStateStore(ctx.store.dir).update(doc => { const r = doc.conversations[id]; if (r?.cloud_start)
+        r.cloud_start.heartbeat_at = Date.now(); });
+    beat();
+    const timer = setInterval(beat, 10_000);
+    timer.unref?.();
+    return () => clearInterval(timer);
 }
+/** A start whose carrying process said so in the last 45 s. */
+export const startCarried = (start) => Date.now() - (start.heartbeat_at ?? 0) < 45_000;
 export async function openCodexConversation(ctx, c) {
+    const local = localConversations(ctx)[c.id];
+    if (local?.cloud_start && local.cloud_start.state !== 'active' && !c.ended_at) {
+        const task = await resumeCloudStartup(ctx, c);
+        await output(ctx, c, task, local.cloud_start.prompt !== undefined, recordedChoice(c));
+        return 0;
+    }
     if (c.state === 'done' || c.state === 'archived' || c.ended_at) {
         c = await resumeConversation(ctx, c);
         await ctx.cloud().codex.admit(c.id, { idempotencyKey: `codex-resume-${c.id}-${c.workspace_id}`, signal: ctx.signal });
@@ -162,6 +206,33 @@ export async function openCodexConversation(ctx, c) {
     await output(ctx, c, task);
     return 0;
 }
+/** Continues the same accepted identity, never creates a replacement VM/chat. */
+export async function resumeCloudStartup(ctx, c) {
+    const local = localConversations(ctx)[c.id], start = local?.cloud_start;
+    if (!start)
+        throw new UsageError('This conversation has no local accepted startup.');
+    if (start.attachments_pending)
+        throw new CodedError('initial_images_pending', 'This accepted conversation still needs its initial images. Resume from the launcher with the retained images.', undefined, { conversation_id: c.id, workspace_key: c.key });
+    const release = carryStart(ctx, c.id);
+    try {
+        const ws = await conversationWorkspace(ctx, c);
+        // The same seed the start began: its own captured revision (never a newer checkout), or the copy seed.
+        await seedConversation(ctx, c, ws, local.folder);
+        await ctx.cloud().codex.admit(c.id, { idempotencyKey: `codex-${c.id}`, signal: ctx.signal });
+        const task = await ctx.cloud().codex.waitTask(c.id, { timeoutMs: ctx.wakeTimeoutMs, signal: ctx.signal });
+        if (start.prompt !== undefined && !start.submitted)
+            await submitCloudInitialPrompt(ctx, c, start.prompt, ws.key);
+        new AgentStateStore(ctx.store.dir).update(doc => {
+            const records = doc.conversations;
+            if (records[c.id]?.cloud_start)
+                records[c.id].cloud_start = { ...start, state: 'active', submitted: start.prompt !== undefined || start.submitted, prompt: undefined, error: undefined };
+        });
+        return task;
+    }
+    finally {
+        release();
+    }
+}
 export const CODEX_CLOUD_HANDLERS = {
     'agents codex status': async (ctx) => { ctx.io.stdout.write(json(await ctx.cloud().codex.connector())); return 0; },
     'agents codex enable': async (ctx) => { ctx.io.stdout.write(json(await ensureCodexCloud(ctx))); return 0; },

package/dist/command-center-actions.js

@@ -69,7 +69,11 @@ export const CENTER_HANDLERS = {
         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]);
+        // The agent's own terminal session: attached here, started detached with --json, or (without a terminal here) a
+        // tab of the person's terminal app, as agents open does (0.20.1+).
+        const next = { ...values };
+        delete next.in;
+        return agentAction(ctx, 'open', next, [ref]);
     },
     async 'agents fork'(ctx, values, [ref, name]) {
         if (!ref || !name || !/^[a-z0-9][a-z0-9._-]{0,63}$/.test(name))

package/dist/commands.js

@@ -1,4 +1,5 @@
 import { agentReachability } from "./agent-reachability.js";
+import { findOrg, resolveOrg, sessionScopeWarnings, writeWarnings } from "./account-scope.js";
 import { vaultType, vaultValue, SECRET_SECURITY_NOTE } from "./vault.js";
 /**
  * Command implementations of the project-key commands (workspaces, files, operations, secrets, templates, usage).
@@ -18,10 +19,12 @@ import { CLI_VERSION, SECRET_NAME, UUID, parseDuration, parseEnvPairs, parsePosi
 import { ExecSessionRunningError, ExecutionFailedError, ExecutionPendingError, InterruptedError, NotFoundError, UsageError } from "./errors.js";
 import { updateCheckDisabled } from "./update-check.js";
 import { withLiveAgents } from "./agent-live.js";
+import { codingAgentShell } from "./agent-setup.js";
+import { askInBrowser, askTimeout } from "./secret-ask.js";
 import { initTemplateYaml, recipeYaml } from "./template-yaml.js";
 import { BuildTimer, buildTimingJson, buildTimingText, progressLine } from "./timing.js";
 import { timingJson } from "./timing.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";
+import { table, bindingsText, buildTable, buildText, changesTable, diffSummaryText, diffTable, draftText, draftStateTable, executionJson, executionSummary, fileInfoText, fileTable, languageTable, json, kv, memoryGrowText, burstText, modeText, operationDetail, suspendProgressText, 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;
@@ -43,6 +46,8 @@ const cellOf = (ctx, ws) => ws.cell({
 });
 export const strs = (v) => (Array.isArray(v) ? v : typeof v === 'string' ? [v] : []);
 const MAX_SECRET_VALUE_BYTES = 65_536;
+/** `files write --ask`: a secret file typed or pasted into the page (~/.npmrc, a key, a service-account JSON). */
+const MAX_ASKED_FILE_BYTES = 1024 * 1024;
 /** `files patch --content-file`: a patch request is at most 7 MiB; larger files go through `files write`. */
 const MAX_PATCH_CONTENT = 7 * 1024 * 1024;
 const STOPPED_AT = { max_matches: '--max matches', budget: 'its 10 s budget', max_bytes: '4 MiB of results' };
@@ -476,6 +481,45 @@ function feedbackSender(ctx) {
     const sessionConfigured = Boolean(ctx.io.env.SHARDFLUX_SESSION_TOKEN?.trim()) || ctx.store.profile(ctx.apiUrl).session !== undefined;
     return keyConfigured || !sessionConfigured ? ctx.cloud() : ctx.account();
 }
+/**
+ * An organization-level read (`shard usage`; 0.20.2+). The API key reads its own organization. Another organization
+ * (--org) answers 404 to a project key, so that read is made with the signed-in session, which sees every organization
+ * the person is in; without a session the error says which organization the key belongs to and how to switch. No key
+ * but a session: the session, for --org or the default organization.
+ */
+async function readOrg(ctx, orgFlag, read) {
+    const signedIn = ctx.sessionSource() !== null;
+    const hasKey = Boolean(ctx.io.env.SHARDFLUX_API_KEY?.trim()) || ctx.store.profile(ctx.apiUrl).api_key !== undefined;
+    const bySession = async () => {
+        const account = ctx.account();
+        return read(account, (orgFlag !== undefined ? await findOrg(account, orgFlag) : await resolveOrg(ctx, account, {})).id);
+    };
+    if (!hasKey && signedIn)
+        return bySession();
+    if (orgFlag === undefined)
+        return read(ctx.cloud(), (await principal(ctx)).organization_id);
+    if (!UUID.test(orgFlag)) {
+        if (signedIn)
+            return bySession();
+        throw new UsageError('--org must be an organization id (UUID)', 'or sign in (shard auth login) to name it by slug');
+    }
+    try {
+        return await read(ctx.cloud(), orgFlag);
+    }
+    catch (err) {
+        if (!(err instanceof ShardfluxApiError && err.status === 404))
+            throw err;
+        const p = await principal(ctx);
+        // Retry only a cross-org read. A real 404 in the key's own org must keep its error and credential boundary.
+        if (p.organization_id === orgFlag)
+            throw err;
+        if (signedIn)
+            return bySession();
+        const envKey = ctx.apiKey().source === 'env';
+        const key = envKey ? `The API key in SHARDFLUX_API_KEY (${p.api_key.key_id})` : `The saved API key ${p.api_key.key_id}`;
+        throw new UsageError(`${key} belongs to organization ${p.organization_id}, so it cannot read organization ${orgFlag}.`, `sign in to read any of your organizations: shard auth login   (or switch the key: shard setup --org ${orgFlag} --new-key)${envKey ? '; after saving the new key, unset SHARDFLUX_API_KEY so shard uses it' : ''}`);
+    }
+}
 /** Contract bounds of the feedback context fields shard sends (characters). */
 const FEEDBACK_CONTEXT_MAX = { workspace: 200, 'request-id': 200, 'error-code': 100, command: 2000 };
 /**
@@ -879,7 +923,10 @@ export const KEY_HANDLERS = {
     },
     async whoami(ctx) {
         const p = await principal(ctx);
-        out(ctx, principalText(p), p);
+        // Signed in too (0.20.2+): distinguish departed defaults/keys from an accessible key in another default org.
+        const warnings = await sessionScopeWarnings(ctx, { keyId: p.api_key.key_id, source: ctx.apiKey().source, organizationId: p.organization_id, projectId: p.project_id });
+        writeWarnings(ctx, warnings);
+        out(ctx, principalText(p), warnings.length ? { ...p, warnings } : p);
         return 0;
     },
     async version(ctx, values) {
@@ -893,7 +940,16 @@ export const KEY_HANDLERS = {
         const category = oneOf(values, 'category', FEEDBACK_CATEGORIES);
         const context = feedbackContext(ctx, values);
         const message = await feedbackMessage(ctx, values, words);
-        const r = await feedbackSender(ctx).sendFeedback({ message, ...(category ? { category } : {}), context });
+        if (values.yes !== true) {
+            const { requestId, errorCode, ...fields } = context;
+            const preview = { message, category: category ?? 'other', context: { ...fields, ...(requestId ? { request_id: requestId } : {}), ...(errorCode ? { error_code: errorCode } : {}) } };
+            out(ctx, `Feedback preview for the Shardflux team (not sent):\n${json(preview)}Show the exact message and context to the user. Send the same content with --yes only after explicit authorization.\n`, {
+                sent: false, authorization_required: true, preview,
+                note: 'Not sent. Show the exact message and context to the user; use --yes only after explicit authorization.',
+            });
+            return 0;
+        }
+        const r = await feedbackSender(ctx).sendFeedback({ message, category: category ?? 'other', context });
         const human = r.duplicate
             ? `Already received: the same message was sent in the last 24 hours (feedback ${r.id}); not emailed again.\n`
             : `Sent to the Shardflux team (feedback ${r.id}). Thank you.\n`;
@@ -917,20 +973,18 @@ export const KEY_HANDLERS = {
             out(ctx, usageSeriesText(series), series);
             return 0;
         }
-        const org = str(values.org) ?? (await principal(ctx)).organization_id;
-        if (!UUID.test(org))
-            throw new UsageError(`--org must be an organization id (UUID)`);
+        const org = str(values.org);
         if (values.estimate === true) {
-            const estimate = await ctx.cloud().usage.estimate(org);
+            const estimate = await readOrg(ctx, org, (client, id) => client.usage.estimate(id));
             out(ctx, usageEstimateText(estimate), estimate);
             return 0;
         }
         if (values.series === true) {
-            const series = await ctx.cloud().usage.series(org, range);
+            const series = await readOrg(ctx, org, (client, id) => client.usage.series(id, range));
             out(ctx, usageSeriesText(series), series);
             return 0;
         }
-        const summary = await ctx.cloud().request('GET', `/v1/organizations/${encodeURIComponent(org)}/usage/summary`);
+        const summary = await readOrg(ctx, org, (client, id) => client.request('GET', `/v1/organizations/${encodeURIComponent(id)}/usage/summary`));
         out(ctx, usageText(summary), summary);
         return 0;
     },
@@ -1334,11 +1388,38 @@ export const KEY_HANDLERS = {
     },
     async 'files write'(ctx, values, [ref, path]) {
         const ifRev = ifRevision(values);
-        const data = await readInput(ctx, str(values.from) ?? '-', 1024 * 1024 * 1024, 'input');
+        // --ask (0.20.1+): a secret file's contents come from the person, on a page shard opens; the agent never sees them.
+        const ask = values.ask === true;
+        if (ask && str(values.from) !== undefined)
+            throw new UsageError('use --ask or --from, not both');
+        const data = ask ? null : await readInput(ctx, str(values.from) ?? '-', 1024 * 1024 * 1024, 'input');
         const ws = await resolveWorkspace(ctx, ref);
         fileFirstOnly(ws, ifRev !== undefined ? ['--if-revision'] : []);
         const cell = cellOf(ctx, ws);
-        const r = await cell.files.write(path, data, { append: values.append === true, createParents: values.parents !== false, ...(ifRev !== undefined ? { ifTreeRevision: ifRev } : {}) });
+        // A new file written from the page is the owner's only (0600); an existing file keeps its mode.
+        const write = (bytes) => cell.files.write(path, bytes, { append: values.append === true, createParents: values.parents !== false, ...(ask ? { mode: '0600' } : {}), ...(ifRev !== undefined ? { ifTreeRevision: ifRev } : {}) });
+        const r = data !== null ? await write(data) : (await askInBrowser(ctx, {
+            kind: 'file',
+            title: `Write ${path}`,
+            purpose: `Saved to ${path} in ${ws.key}. Your coding agent never sees it.`,
+            label: 'File contents',
+            submit: 'Save',
+            done: 'Saved',
+            failed: 'Not saved',
+            doing: `to type the contents of ${path}`,
+            maxBytes: MAX_ASKED_FILE_BYTES,
+            timeoutMs: askTimeout(values),
+            use: async (text) => {
+                // Text files end with a newline; the browser's text area drops a pasted one.
+                const bytes = Buffer.from(text.endsWith('\n') ? text : `${text}\n`, 'utf8');
+                try {
+                    return await write(bytes);
+                }
+                finally {
+                    bytes.fill(0);
+                }
+            },
+        })).result;
         // File-first: the tree revision the write published (or the current one when nothing changed), to chain --if-revision.
         const tree = treeRevisionAfter(ws, cell);
         out(ctx, `wrote ${r.bytes_written} bytes to ${r.path}${r.sha256 ? ` (sha256 ${r.sha256})` : ''}${tree !== null ? `, tree revision ${tree}` : ''}\n`, tree !== null ? { ...r, tree_revision: tree } : r);
@@ -2272,12 +2353,18 @@ export const KEY_HANDLERS = {
         const scope = scopeFlag(values);
         const perms = permissionParams(values, scope === null ? 'project' : 'organization', 'create');
         const description = str(values.description);
-        const value = await readSecretValue(ctx, values);
+        const value = await readSecretValue(ctx, values, name);
         const cloud = ctx.cloud();
-        const base = { name: name, value, ...(description !== undefined ? { description } : {}) };
-        const s = scope === null
-            ? await cloud.secrets.create((await principal(ctx)).project_id, { ...base, ...perms })
-            : await cloud.secrets.createOrganization(scope, { ...base, ...perms });
+        const project = scope === null ? (await principal(ctx)).project_id : null;
+        const create = (secret) => {
+            const base = { name: name, value: secret, ...(description !== undefined ? { description } : {}) };
+            return project !== null ? cloud.secrets.create(project, { ...base, ...perms }) : cloud.secrets.createOrganization(scope, { ...base, ...perms });
+        };
+        const s = value !== null ? await create(value) : await askSecretValue(ctx, values, {
+            title: `Add ${name}`,
+            purpose: `Saved to your ${project !== null ? 'project' : 'organization'}’s secrets as ${name}. Your coding agent never sees it.`,
+            name: name,
+        }, create);
         out(ctx, `Created ${s.scope} secret ${s.name} (${s.id}), version ${s.current_version}. The value is stored encrypted and is never shown.\n${secretDetail(s)}`, s);
         return 0;
     },
@@ -2326,9 +2413,14 @@ export const KEY_HANDLERS = {
         return 0;
     },
     async 'secrets rotate'(ctx, values, [ref]) {
-        const value = await readSecretValue(ctx, values);
+        const value = await readSecretValue(ctx, values, ref);
         const s = await resolveSecret(ctx, values, ref);
-        const r = await ctx.cloud().secrets.rotate(s.id, value);
+        const rotate = (secret) => ctx.cloud().secrets.rotate(s.id, secret);
+        const r = value !== null ? await rotate(value) : await askSecretValue(ctx, values, {
+            title: `New value for ${s.name}`,
+            purpose: `Replaces ${s.name} in your ${s.scope === 'project' ? 'project' : 'organization'}’s secrets; older values are erased. Your coding agent never sees it.`,
+            name: s.name,
+        }, rotate);
         out(ctx, `Rotated ${r.secret.name} to version ${r.version.version}; older values were erased. Processes that already read the old value keep it.\n`, r);
         return 0;
     },
@@ -2382,6 +2474,27 @@ export const KEY_HANDLERS = {
         out(ctx, operationDetail(op), op);
         return 0;
     },
+    async 'operations progress'(ctx, _values, [id]) {
+        if (!UUID.test(id))
+            throw new UsageError('<operation-id> must be a UUID');
+        const progress = await ctx.cloud().workspaces.suspendProgress(id, { signal: ctx.signal });
+        out(ctx, suspendProgressText(progress), { progress });
+        return 0;
+    },
+    async 'operations cancel'(ctx, values, [id]) {
+        if (!UUID.test(id))
+            throw new UsageError('<operation-id> must be a UUID');
+        if (values.wait === true) {
+            const operation = await waited(ctx, `Suspension cancellation for ${id} continues server side.`, () => ctx.cloud().workspaces.cancelSuspend(id, { signal: ctx.signal, timeoutMs: waitTimeout(values) }));
+            const progress = await ctx.cloud().workspaces.suspendProgress(id, { signal: ctx.signal });
+            out(ctx, suspendProgressText(progress), { operation, progress });
+        }
+        else {
+            const result = await ctx.cloud().workspaces.requestCancelSuspend(id, { signal: ctx.signal });
+            out(ctx, suspendProgressText(result.progress), result);
+        }
+        return 0;
+    },
     async 'operations wait'(ctx, values, [id]) {
         if (!UUID.test(id))
             throw new UsageError(`<operation-id> must be a UUID (got "${id}")`);
@@ -2474,12 +2587,26 @@ function permissionParams(values, scope, mode) {
     return out;
 }
 /**
- * The secret value from --from-file or standard input (never from arguments): UTF-8 text, one trailing
- * newline removed, 1..65536 bytes. Never echoed.
+ * The secret value (never from arguments): --from-file, piped standard input, or a no-echo prompt on a terminal. Null
+ * when the person types it on the page shard opens instead (0.20.1+): --ask, or a coding agent's shell with nothing
+ * piped (a terminal there is not the person's).
  */
-async function readSecretValue(ctx, values) {
+async function readSecretValue(ctx, values, name) {
     const file = str(values['from-file']);
+    if (values.ask === true) {
+        if (file !== undefined)
+            throw new UsageError('use --ask or --from-file, not both');
+        return null;
+    }
+    const agentShell = codingAgentShell(ctx.io.env);
+    if (file === undefined && ctx.io.stdin.isTTY) {
+        if (agentShell)
+            return null;
+        return secretText(await ctx.input.secret(`${name} (typing is hidden): `, 'the secret value', 'pipe the value in, or use --ask'));
+    }
     const bytes = await readInput(ctx, file ?? '-', MAX_SECRET_VALUE_BYTES + 2, file === undefined ? 'secret value (standard input)' : '--from-file');
+    if (file === undefined && bytes.length === 0 && agentShell)
+        return null;
     let text;
     try {
         text = new TextDecoder('utf-8', { fatal: true }).decode(bytes);
@@ -2490,18 +2617,40 @@ async function readSecretValue(ctx, values) {
     finally {
         bytes.fill(0);
     }
+    return secretText(text);
+}
+/** A secret value as stored: one trailing newline removed, 1..65536 UTF-8 bytes, no NUL. */
+function secretText(value) {
+    let text = value;
     if (text.endsWith('\r\n'))
         text = text.slice(0, -2);
     else if (text.endsWith('\n'))
         text = text.slice(0, -1);
     if (text.length === 0)
-        throw new UsageError('the secret value is empty: pipe it on standard input or pass --from-file <file>');
+        throw new UsageError('the secret value is empty: pipe it on standard input, pass --from-file <file> or use --ask');
     if (Buffer.byteLength(text, 'utf8') > MAX_SECRET_VALUE_BYTES)
         throw new UsageError(`the secret value exceeds ${MAX_SECRET_VALUE_BYTES} bytes`);
     if (text.includes('\u0000'))
         throw new UsageError('the secret value must not contain NUL characters');
     return text;
 }
+/** The secret's value from the page shard opens, handed straight to `save` (create or rotate); the page shows its outcome. */
+async function askSecretValue(ctx, values, page, save) {
+    const asked = await askInBrowser(ctx, {
+        kind: 'secret',
+        title: page.title,
+        purpose: page.purpose,
+        label: 'Value',
+        submit: 'Save',
+        done: 'Saved',
+        failed: 'Not saved',
+        doing: `to type ${page.name}`,
+        maxBytes: MAX_SECRET_VALUE_BYTES + 2,
+        timeoutMs: askTimeout(values),
+        use: (value) => save(secretText(value)),
+    });
+    return asked.result;
+}
 /** `<id|name>`: a UUID is tried as an id first; otherwise the live secret of that name in the scope (project, or --org). */
 async function resolveSecret(ctx, values, ref) {
     const cloud = ctx.cloud();

package/dist/conversation-commands.d.ts

@@ -5,4 +5,9 @@ export declare function questionLine(c: {
     state: string;
     question?: string | null;
 }, max?: number): string | undefined;
+/** A conversation's title as people read it: "New conversation" while it is still named by its generated id, before a
+ * prompt names it; a name someone chose stays (0.21.1+). The menu bar's AgentNaming.isRawIdentifier rule. */
+export declare function displayTitle(c: {
+    title: string;
+}): string;
 export declare const CONVERSATION_HANDLERS: Record<string, Handler>;

package/dist/conversation-commands.js

@@ -11,17 +11,20 @@ export function questionLine(c, max = 100) {
     const text = c.state === 'needs_you' ? c.question?.replace(/\s+/g, ' ').trim() : undefined;
     return !text ? undefined : text.length > max ? `${text.slice(0, max - 1).trimEnd()}…` : text;
 }
+/** A conversation's title as people read it: "New conversation" while it is still named by its generated id, before a
+ * prompt names it; a name someone chose stays (0.21.1+). The menu bar's AgentNaming.isRawIdentifier rule. */
+export function displayTitle(c) { return !c.title || /^(conv[-_])?[a-z0-9]{26}$/.test(c.title) ? 'New conversation' : c.title; }
 export const CONVERSATION_HANDLERS = {
-    async 'conversations resume'(ctx, _values, [id]) { const r = await conversationClient(ctx).conversations.resume(id, { signal: ctx.signal }); out(ctx, `${r.conversation.title}: resumed.\n`, r); return 0; },
+    async 'conversations resume'(ctx, _values, [id]) { const r = await conversationClient(ctx).conversations.resume(id, { signal: ctx.signal }); out(ctx, `${displayTitle(r.conversation)}: resumed.\n`, r); return 0; },
     async 'conversations reader'(ctx, _values, [id]) { const r = await conversationClient(ctx).conversations.spaceReader(id, { signal: ctx.signal }); out(ctx, `${r.workspace.workspace_key}\n`, r); return 0; },
     async 'conversations list'(ctx, values) {
         const state = str(values.state);
         const page = await conversationClient(ctx).conversations.list({ projectId: str(values.project), state, parentId: str(values.parent), cursor: str(values.cursor), limit: values.limit ? Number(values.limit) : undefined });
         // A conversation that needs you adds a fifth column: why (0.18.0+).
-        out(ctx, page.data.map(c => { const q = questionLine(c); return `${c.id}\t${c.title}\t${c.state}\t${c.branch}${q ? `\t${q}` : ''}`; }).join('\n') + '\n', page);
+        out(ctx, page.data.map(c => { const q = questionLine(c); return `${c.id}\t${displayTitle(c)}\t${c.state}\t${c.branch}${q ? `\t${q}` : ''}`; }).join('\n') + '\n', page);
         return 0;
     },
-    async 'conversations get'(ctx, _values, [id]) { const c = await conversationClient(ctx).conversations.get(id); const q = questionLine(c, 200); out(ctx, `${c.title}\n${c.state}\n${c.branch}\n${q ? `${q}\n` : ''}`, c); return 0; },
+    async 'conversations get'(ctx, _values, [id]) { const c = await conversationClient(ctx).conversations.get(id); const q = questionLine(c, 200); out(ctx, `${displayTitle(c)}\n${c.state}\n${c.branch}\n${q ? `${q}\n` : ''}`, c); return 0; },
     // A finished conversation whose VM was removed restores into a fresh one, then takes the message (APIs that do; 0.18.1+).
     async 'conversations send'(ctx, _values, [id, text]) {
         const r = await conversationClient(ctx).conversations.send(id, text, { signal: ctx.signal });
@@ -34,14 +37,14 @@ export const CONVERSATION_HANDLERS = {
             throw new UsageError('--timeout must be 0..900 seconds.');
         const until = str(values.until)?.split(',');
         const r = await conversationClient(ctx).conversations.wait(id, { until, timeoutSeconds: seconds, signal: ctx.signal });
-        out(ctx, 'timeout' in r ? 'Still working.\n' : `${r.conversation.title}: ${r.event.kind}\n${r.event.question ?? r.event.result?.summary ?? ''}\n`, r);
+        out(ctx, 'timeout' in r ? 'Still working.\n' : `${displayTitle(r.conversation)}: ${r.event.kind}\n${r.event.question ?? r.event.result?.summary ?? ''}\n`, r);
         return 0;
     },
     async 'conversations land'(ctx, values, [id, action]) {
         if (!['merge', 'pr', 'keep', 'discard'].includes(action))
             throw new UsageError('Choose merge, pr, keep or discard.');
         const r = await conversationClient(ctx).conversations.land(id, action, { into: str(values.into), signal: ctx.signal });
-        out(ctx, `${r.title}: ${r.landed.how}\n`, r);
+        out(ctx, `${displayTitle(r)}: ${r.landed.how}\n`, r);
         return 0;
     },
     async 'files pull'(ctx, _values, [conversation, path]) {

package/dist/conversation-terminal.d.ts

@@ -2,8 +2,13 @@ import type { Workspace } from '@shardflux/sdk';
 import type { Ctx, Handler } from './commands.js';
 import type { Values } from './args.js';
 import type { Conversation } from './conversations.js';
-/** Every terminal entry point uses the durable conversation's native harness, worktree and session. */
-export declare function conversationTerminal(ctx: Ctx, ws: Workspace, c: Conversation, project: string, values: Values, afterStart?: () => Promise<void> | undefined): Promise<number>;
+import type { ConversationSetup } from './project-template-setup.js';
+/**
+ * Every terminal entry point uses the durable conversation's native harness, worktree and session. A new conversation
+ * in a repository without a project template for its dependencies sets its worktree up once its agent has started
+ * (`setup`, 0.21.1+).
+ */
+export declare function conversationTerminal(ctx: Ctx, ws: Workspace, c: Conversation, project: string, values: Values, afterStart?: () => Promise<void> | undefined, setup?: ConversationSetup): Promise<number>;
 /**
  * A conversation and its VM, for an app to open (Claude Desktop, claude.ai, T3 Code, the menu bar). A conversation
  * whose VM was removed after it finished restores first (0.18.1+): a fresh VM from its saved branch and transcript, the
@@ -17,7 +22,10 @@ export declare function reopenConversation(ctx: Ctx, c: Conversation, values: Va
 /**
  * `shard ./` (and `agents new --in auto`): new conversations open where `agents targets` says (open_in, 0.17.0+): T3
  * Code mode, Claude Desktop or claude.ai for Claude (the conversation's Remote Control session), else this terminal.
+ * From a shell nobody types into (a coding agent's, or none) a terminal conversation opens in a new tab of the
+ * person's terminal app (0.20.1+, agents targets --terminal).
  */
 export declare const launchProjectCommand: Handler;
+export declare function forwardedFlags(values: Values): string[];
 /** Select a durable conversation, then use the harness's native terminal for all interaction. */
 export declare const launchConversationProject: Handler;