@shardflux/cli 0.28.1 → 0.28.2

package/CHANGELOG.md

@@ -2,6 +2,19 @@
 
 ## Unreleased
 
+- The Shardflux app 0.9.3 (0.28.2+): `shard` installs and updates `@shardflux/desktop-darwin-arm64` / `-x64` and
+  `@shardflux/desktop-linux-x64` / `-arm64` 0.9.3 (files open beside your work, pictures and videos picture in picture,
+  ⌘2 shows the agents your orchestrator starts, needs-you questions read whole).
+
+- Agent credentials (0.28.2+, SDK 0.30.2): environment credential questions can be answered with `shard needs-you answer acred_ID --credential --ask` (or stdin / `--from-file`), with scope chosen before the write. Scope flags preserve organization and thread identity; workspace-only permission flags are rejected for agent credentials.
+
+- Agent credential scopes (0.28.2+): `shard secrets create NAME --scope agents --org ORG --ask` adds a credential for all your agents; use `--scope project --project PROJECT` or `--scope conversation --conversation CONVERSATION` for a local override. Import, list, get, update, rotate, versions, access-log and delete accept the same scope. Values use the secure page, stdin, or `--from-file` and never command arguments.
+- Conversation origin (0.28.2+, SDK 0.30.2): conversation starts stay compatible with older APIs: send launching-conversation provenance only after `/v1/meta` advertises `capabilities.conversation_origin: true`; no create fallback retry.
+
+- Question explanations (0.28.2+, SDK 0.30.2): needs-you output prints each question and its optional `option_details` in full, including what each choice does and what follows it.
+
+- Launch attribution (0.28.2+, SDK 0.30.2): preserve the requesting orchestrator thread when `project_link` starts work in a laptop folder. API and guest title sources strip pasted-content/image transport markers, so `shard agents list` shows the request text. Tasks delete their workers and spawned descendants along with their computers.
+
 - The Shardflux app 0.9.2 (0.28.1+): `shard` installs and updates `@shardflux/desktop-darwin-arm64` / `-x64` and
   `@shardflux/desktop-linux-x64` / `-arm64` 0.9.2 (Stop in ⌘1, organization choice at the first sign-in, Sign in after
   signing out).

package/README.md

@@ -34,6 +34,12 @@ an explicit selection keeps the default credentials and target status. An approv
 
 Filesystem recovery timing (0.28.0+): cold resume output identifies `guest_filesystem` in JSON and the restart notice. See the [workspace lifecycle](https://docs.shardflux.dev/concepts/lifecycle) for retained files and process restart semantics.
 
+## Agent credentials (0.28.2+)
+
+Answer a credential question with `shard needs-you answer acred_ID --credential --ask --scope project`. The value goes to the write-only answer field and the asking agent receives an availability message.
+
+`shard secrets create NAME --scope agents --org ORG --ask` adds a credential for all your agents; use `--scope project --project PROJECT` or `--scope conversation --conversation CONVERSATION` for a local override. Import, list, get, update, rotate, versions, access-log and delete accept the same scope. Values use the secure page, stdin, or `--from-file` and never command arguments.
+
 ## Support and bug reports
 
 [Report a bug](https://github.com/shardfluxdev/community/issues/new?template=bug_report.yml) or
@@ -1635,6 +1641,8 @@ hour), and `--json` prints the API's answer. Pass an id to `shard agents new --m
 
 ## Conversations
 
+When an orchestrator starts work through a device project link (0.28.2+), the new conversation carries its requesting thread through to the API. `shard agents list --json` retains the orchestrator conversation and known input IDs.
+
 From 0.14.0, `shard conversations list|get|send|wait|land|move` manages project conversations. `shard c` is the short form. Conversations retain their branch and transcript as their VM binding changes.
 
 Watch an agent work: `shard conversations watch <id>` shows the conversation's terminal live, read-only. It starts
@@ -1907,7 +1915,7 @@ shard board --follow                               # each change as it happens,
 changes the words (`--text`, and the task's master hears it), the title (`--title`), the bucket (`--now`, `--next`,
 `--later`) and the order (`--first`, `--after`), keeps an agent's suggestion as your own (`--keep`) or clears the task
 (`--clear`; `--no-clear` brings it back). `shard task steer <id> <words...>` sends steering words to the task's master,
-`shard task rm <id>` deletes the task, and `shard task clear-done` clears every finished one. `shard task show <id>`
+`shard task rm <id>` deletes the task, every nested follow-up, and their owned conversation trees and computers; masters shared by other tasks stay. `shard task clear-done` clears every finished one. `shard task show <id>`
 prints the task, its plan and each report: milestone, outcome and evidence (`tests 12/12 (pnpm test)`).
 `shard task land <id>` lands a finished task: its result (the branch `shard/<task id>`, where its master merged its
 workers' branches) goes into the project's default branch and into your folder on this computer the way finished
@@ -2086,3 +2094,9 @@ shard volumes detach --machine datasets
 Defaults mount in new and running conversations. Removal waits for current work to finish and preserves manual attachments. Add `--json` to read propagation results.
 
 Bare `shard` in a coding-agent shell or without a TTY returns its setup guide using locally saved sign-in and API-key state.
+
+### Question explanations (0.28.2+)
+
+Needs-you output prints each question and its optional `option_details` in full, including what each choice does and what follows it. The first suggested answer is the agent’s recommendation. Secret values go through the project’s secure setup, never a question or its ordinary answer.
+
+Conversation creation (0.28.2+) includes the optional launching conversation only when `/v1/meta` advertises `capabilities.conversation_origin: true`. Older APIs receive the existing create body; no rejected create is replayed with different fields.

package/dist/args.d.ts

@@ -1,4 +1,4 @@
-export declare const CLI_VERSION = "0.28.1";
+export declare const CLI_VERSION = "0.28.2";
 export interface OptionSpec {
     type: 'string' | 'boolean';
     short?: string;

package/dist/args.js

@@ -15,7 +15,7 @@ import { BOARD_COMMANDS } from "./board-args.js";
 import { ORCHESTRATOR_COMMANDS } from "./orchestrator-args.js";
 import { UsageError } from "./errors.js";
 import { DEFAULT_CHOICE, MODEL_CHOICES } from "./agent-models.js";
-export const CLI_VERSION = '0.28.1';
+export const CLI_VERSION = '0.28.2';
 export const GLOBAL_OPTIONS = {
     'api-url': { type: 'string', value: '<url>', description: 'API base URL (default $SHARDFLUX_API_URL, else https://api.shardflux.dev).' },
     json: { type: 'boolean', description: 'Print machine-readable JSON on stdout (errors as JSON on stderr).' },
@@ -127,6 +127,9 @@ const LIFETIME_FILTER = {
 };
 const SECRET_REF = { name: 'id|name', required: true };
 const SECRET_SCOPE = {
+    scope: { type: 'string', value: '<agents|project|conversation>', description: 'Agent credential scope: all your agents, this project, or one thread. Omit for workspace-bound secrets.' },
+    project: { type: 'string', value: '<project-id>', description: 'Project for a local agent credential (default: the key’s project).' },
+    conversation: { type: 'string', value: '<conversation-id>', description: 'Thread for --scope conversation.' },
     org: { type: 'string', value: '<organization-id>', description: 'Organization-wide secrets of this organization (owners/admins; project API keys get 403). Default: the API key’s project.' },
 };
 const SECRET_VALUE = {
@@ -993,6 +996,7 @@ const KEY_COMMANDS = [
         summary: 'Import named items from your vault as encrypted project secrets',
         positionals: [{ name: 'name', required: true, variadic: true }],
         options: {
+            ...SECRET_SCOPE,
             from: { type: 'string', value: '<hsec|1password|bitwarden|keychain>', description: 'Vault to read; values go straight into the encrypted secrets request.' },
             as: { type: 'string', value: '<secret-name>', description: 'Secret name for a single imported item.' },
             keychain: { type: 'string', value: '<path>', description: 'Read from this Keychain (keychain source only).' },

package/dist/board-args.js

@@ -123,6 +123,12 @@ export const BOARD_COMMANDS = [
         summary: 'Answer something that waits on you (0.25.0+)',
         positionals: [{ name: 'id', required: true }, { name: 'decision' }],
         options: {
+            credential: { type: 'boolean', description: 'Provide an environment credential through the secure value input; never through --text.' },
+            scope: { type: 'string', value: '<agents|project|conversation>', description: 'Credential storage scope (default: what the request suggests).' },
+            org: { type: 'string', value: '<organization-id>', description: 'The organization for a signed-in credential answer.' },
+            ask: { type: 'boolean', description: 'Open the secure page for the credential value.' },
+            'from-file': { type: 'string', value: '<file>', description: 'Read the credential value from this file; never from an argument.' },
+            timeout: { type: 'string', value: '<duration>', description: 'How long the secure page waits (default 10m).' },
             everywhere: { type: 'boolean', description: 'With always: the rule covers every project.' },
             text: { type: 'string', value: '<answer>', description: 'Your answer to an agent’s question.' },
             pick: { type: 'string', multiple: true, value: '<option|question=option>', description: 'The option you pick for an agent’s question in a permission request (repeatable for a multi-select question; "<question>=<option>" when it asks several).' },
@@ -136,6 +142,7 @@ export const BOARD_COMMANDS = [
             '  ask_…     --text <answer>: the task’s master gets it',
             '  oq_…      --text <answer>: the orchestrator thread that asked gets it (0.27.0+)',
             '  cred_…    deny (the value goes through the credential request, sealed for its computer)',
+            '  acred_…   --credential --ask: provide an environment value securely, or deny to decline it',
             '  land_…    land (as shard task land: the result into your folder and the default branch), keep (the',
             '            branch stays) or discard',
             '  prune_…   --keep <task-id> for each task to keep, keep for all of them, or discard to clear them',

package/dist/board-commands.d.ts

@@ -44,7 +44,7 @@ export declare function feedJson(u: BoardUpdate): Record<string, unknown>;
 /** `shard task show`: the task, its plan and conversations, then every report oldest first with its evidence. Every
  *  title, step and outcome prints whole (0.27.0+), however long the agent wrote it; the terminal wraps it. */
 export declare function taskDetailText(d: TaskDetail): string;
-/** An item's kind from its id (perm_, cq_, ask_, oq_, cred_, land_, prune_, dev_); undefined for another id. */
+/** An item's kind from its id (perm_, cq_, ask_, oq_, cred_, acred_, land_, prune_, dev_); undefined for another id. */
 export declare function itemKind(id: string): NeedsYouItem['kind'] | undefined;
 export interface AnswerInput {
     word?: string | undefined;

package/dist/board-commands.js

@@ -1,4 +1,5 @@
-import { out, principal, str, strs } from "./commands.js";
+import { findOrg, resolveOrg } from "./account-scope.js";
+import { out, principal, str, strs, readSecretValue, askSecretValue } from "./commands.js";
 import { detailLine, pickAnswers } from "./conversation-commands.js";
 import { NotFoundError, UsageError } from "./errors.js";
 import { time } from "./format.js";
@@ -36,8 +37,8 @@ export function taskLine(t) {
  * request your orchestrator made to your computer while it was offline reads "Waiting for your computer: list ~/code".
  */
 export function needsLine(n) {
-    const detail = n.permission ? detailLine(n.permission.detail) : n.options?.length ? n.options.join(' / ') : n.land ? n.land.branch : n.device ? 'cancel drops it' : '';
-    return `${n.id}\t${oneLine(n.ask, 100)}${detail ? `\t${detail}` : ''}`;
+    const detail = n.credential?.kind === 'environment' ? [n.credential.name, n.credential.suggested_scope].filter(Boolean).join(' · ') : n.permission ? detailLine(n.permission.detail) : n.options?.length ? n.options.map(o => n.option_details?.[o] ? `${o}: ${n.option_details[o]}` : o).join(' / ') : n.land ? n.land.branch : n.device ? 'cancel drops it' : '';
+    return `${n.id}\t${oneLine(n.ask, n.kind === 'question' || n.credential?.kind === 'environment' ? Infinity : 100)}${detail ? `\t${detail}` : ''}`;
 }
 /** A sealed report as --follow prints it: id, milestone, title, then its evidence labels. */
 export function reportLine(r) {
@@ -140,7 +141,7 @@ export function taskDetailText(d) {
             if (r.outcome.trim())
                 lines.push(`  ${whole(r.outcome)}`);
             if (r.options?.length)
-                lines.push(`  Options: ${r.options.join(' / ')}`);
+                lines.push(`  Options: ${r.options.map(o => r.option_details?.[o] ? `${o}: ${r.option_details[o]}` : o).join(' / ')}`);
             if (r.evidence.length)
                 lines.push(`  Evidence: ${r.evidence.map(evidenceText).join('; ')}`);
             if (r.media.length)
@@ -166,8 +167,8 @@ function orderOf(values) {
     return first ? null : after;
 }
 // ---- needs you -------------------------------------------------------------------------------
-const KINDS = { perm: 'permission', cq: 'question', ask: 'question', oq: 'question', cred: 'credential', land: 'land', prune: 'prune', dev: 'device' };
-/** An item's kind from its id (perm_, cq_, ask_, oq_, cred_, land_, prune_, dev_); undefined for another id. */
+const KINDS = { perm: 'permission', cq: 'question', ask: 'question', oq: 'question', cred: 'credential', acred: 'credential', land: 'land', prune: 'prune', dev: 'device' };
+/** An item's kind from its id (perm_, cq_, ask_, oq_, cred_, acred_, land_, prune_, dev_); undefined for another id. */
 export function itemKind(id) {
     return KINDS[id.slice(0, Math.max(0, id.indexOf('_')))];
 }
@@ -364,6 +365,45 @@ export const BOARD_HANDLERS = {
         return 0;
     },
     async 'needs-you answer'(ctx, values, [id, word]) {
+        if (values.credential === true) {
+            if (!id?.startsWith('acred_') || word !== undefined || values.text !== undefined || values.pick !== undefined || values.keep !== undefined || values.everywhere === true) {
+                throw new UsageError('Use --credential for an environment request, without a decision or chat answer.');
+            }
+            const hasKey = Boolean(ctx.io.env.SHARDFLUX_API_KEY?.trim()) || ctx.store.profile(ctx.apiUrl).api_key !== undefined;
+            const scope = str(values.scope);
+            if (scope !== undefined && !['agents', 'project', 'conversation'].includes(scope))
+                throw new UsageError('--scope must be agents, project or conversation');
+            const signed = scope === 'agents' || !hasKey;
+            let cloud = signed ? ctx.account() : ctx.cloud();
+            let organizationId = str(values.org);
+            if (signed) {
+                const org = organizationId ? await findOrg(ctx.account(), organizationId) : await resolveOrg(ctx, ctx.account(), {});
+                organizationId = org.id;
+            }
+            // Inspect the request before reading a file, stdin or opening the secure page.
+            const item = (await cloud.needsYou.list({ ...(organizationId ? { organizationId } : {}), signal: ctx.signal })).find(n => n.id === id);
+            if (!item || item.kind !== 'credential' || item.credential?.kind !== 'environment' || !item.credential.name)
+                throw new NotFoundError('Nothing waits for that environment credential.');
+            const target = scope ?? item.credential.suggested_scope ?? 'project';
+            if (target === 'agents' && !signed) {
+                organizationId ??= (await principal(ctx)).organization_id;
+                cloud = ctx.account();
+                await findOrg(ctx.account(), organizationId);
+            }
+            const save = (value) => {
+                ctx.addSecret(value);
+                return cloud.needsYou.answer(id, { credential: { value, scope: target } }, { ...(organizationId ? { organizationId } : {}), signal: ctx.signal });
+            };
+            const value = await readSecretValue(ctx, values, item.credential.name);
+            const r = value !== null ? await save(value) : await askSecretValue(ctx, values, {
+                title: `Provide ${item.credential.name}`, purpose: item.credential.purpose ?? item.ask, name: item.credential.name,
+            }, save);
+            out(ctx, `Credential ${item.credential.name} is available (${target}).\n`, r);
+            return 0;
+        }
+        if (values.scope !== undefined || values.ask === true || values['from-file'] !== undefined || values.org !== undefined || values.timeout !== undefined) {
+            throw new UsageError('Use --credential for a secure environment credential answer.');
+        }
         const input = { word, text: str(values.text), picks: strs(values.pick), keep: strs(values.keep), everywhere: values.everywhere === true };
         const cloud = boardClient(ctx);
         // Land merges here (shard task land) and records itself after; the board only takes keep and discard.

package/dist/commands.d.ts

@@ -152,4 +152,16 @@ export declare function withConversations(rows: import('@shardflux/sdk').Agent[]
     question?: string | null;
 }[] | null): ThreadRow[];
 export declare const KEY_HANDLERS: Record<string, Handler>;
+/**
+ * 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).
+ */
+export declare function readSecretValue(ctx: Ctx, values: Values, name: string): Promise<string | null>;
+/** The secret's value from the page shard opens, handed straight to `save` (create or rotate); the page shows its outcome. */
+export declare function askSecretValue<T>(ctx: Ctx, values: Values, page: {
+    title: string;
+    purpose: string;
+    name: string;
+}, save: (value: string) => Promise<T>): Promise<T>;
 export {};

package/dist/commands.js

@@ -2345,17 +2345,20 @@ export const KEY_HANDLERS = {
         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 agent = values.scope !== undefined ? await agentSecretContext(ctx, values) : null;
+        const project = agent ? null : (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 }));
+            imported.push(agent ? await agent.cloud.secrets.createAgent(agent.target, { name: targets[i], value }) : 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 (values.scope !== undefined)
+            return agentSecretCommand(ctx, values, 'create', 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}"`);
         const scope = scopeFlag(values);
@@ -2377,6 +2380,8 @@ export const KEY_HANDLERS = {
         return 0;
     },
     async 'secrets list'(ctx, values) {
+        if (values.scope !== undefined)
+            return agentSecretCommand(ctx, values, 'list', undefined);
         const cloud = ctx.cloud();
         const org = scopeFlag(values);
         const project = org === null ? (await principal(ctx)).project_id : null;
@@ -2404,11 +2409,15 @@ export const KEY_HANDLERS = {
         return 0;
     },
     async 'secrets get'(ctx, values, [ref]) {
+        if (values.scope !== undefined)
+            return agentSecretCommand(ctx, values, 'get', ref);
         const s = await resolveSecret(ctx, values, ref);
         out(ctx, secretDetail(s), s);
         return 0;
     },
     async 'secrets update'(ctx, values, [ref]) {
+        if (values.scope !== undefined)
+            return agentSecretCommand(ctx, values, 'update', ref);
         const s = await resolveSecret(ctx, values, ref);
         const params = { ...permissionParams(values, s.scope, 'update') };
         const description = str(values.description);
@@ -2421,6 +2430,8 @@ export const KEY_HANDLERS = {
         return 0;
     },
     async 'secrets rotate'(ctx, values, [ref]) {
+        if (values.scope !== undefined)
+            return agentSecretCommand(ctx, values, 'rotate', ref);
         const value = await readSecretValue(ctx, values, ref);
         const s = await resolveSecret(ctx, values, ref);
         const rotate = (secret) => ctx.cloud().secrets.rotate(s.id, secret);
@@ -2433,6 +2444,8 @@ export const KEY_HANDLERS = {
         return 0;
     },
     async 'secrets versions'(ctx, values, [ref]) {
+        if (values.scope !== undefined)
+            return agentSecretCommand(ctx, values, 'versions', ref);
         const s = await resolveSecret(ctx, values, ref);
         const limitText = str(values.limit);
         const page = await ctx.cloud().secrets.versions(s.id, limitText ? { limit: parsePositiveInt(limitText, 'limit', 200) } : {});
@@ -2440,6 +2453,8 @@ export const KEY_HANDLERS = {
         return 0;
     },
     async 'secrets delete'(ctx, values, [ref]) {
+        if (values.scope !== undefined)
+            return agentSecretCommand(ctx, values, 'delete', ref);
         if (values.yes !== true)
             throw new UsageError('refusing to delete without --yes (the values are erased and the name is removed from every workspace binding)');
         const s = await resolveSecret(ctx, values, ref);
@@ -2448,6 +2463,8 @@ export const KEY_HANDLERS = {
         return 0;
     },
     async 'secrets access-log'(ctx, values, [ref]) {
+        if (values.scope !== undefined)
+            return agentSecretCommand(ctx, values, 'access-log', ref);
         const outcome = str(values.outcome);
         if (outcome !== undefined && !['granted', 'denied', 'failed'].includes(outcome))
             throw new UsageError('--outcome must be granted, denied or failed');
@@ -2549,6 +2566,106 @@ function updateLine(u, d) {
     }
 }
 /** `--org <id>`: organization scope; null: the API key's project. */
+async function agentSecretContext(ctx, values) {
+    const scope = str(values.scope);
+    if (!['agents', 'project', 'conversation'].includes(scope ?? ''))
+        throw new UsageError('--scope must be agents, project or conversation');
+    const restrictions = ['tool', 'allow-workspace', 'any-workspace', 'allow-project', 'all-projects', 'clear-projects'];
+    if (restrictions.some(k => Array.isArray(values[k]) ? values[k].length > 0 : values[k] !== undefined && values[k] !== false))
+        throw new UsageError('Workspace tool permissions apply to workspace-bound secrets. Agent credentials use their agents, project or conversation scope.');
+    if (scope === 'agents' && (values.project !== undefined || values.conversation !== undefined))
+        throw new UsageError('--scope agents takes --org; use a local scope for --project or --conversation.');
+    if (scope === 'project' && values.conversation !== undefined)
+        throw new UsageError('Use --scope conversation with --conversation.');
+    const hasKey = Boolean(ctx.io.env.SHARDFLUX_API_KEY?.trim()) || ctx.store.profile(ctx.apiUrl).api_key !== undefined;
+    const cloud = scope === 'agents' || !hasKey ? ctx.account() : ctx.cloud();
+    if (scope === 'agents') {
+        const account = ctx.account(), org = str(values.org);
+        const organization = org ? await findOrg(account, org) : await resolveOrg(ctx, account, {});
+        return { cloud, target: { scope, organizationId: organization.id } };
+    }
+    const localOrg = str(values.org);
+    if (localOrg !== undefined && !UUID.test(localOrg))
+        throw new UsageError('--org must be an organization id for a local credential.');
+    const organization = localOrg ? { organizationId: localOrg } : {};
+    if (scope === 'conversation') {
+        const conversationId = str(values.conversation);
+        if (!conversationId)
+            throw new UsageError('--conversation is required with --scope conversation');
+        return { cloud, target: { scope, conversationId, ...organization, ...(str(values.project) ? { projectId: str(values.project) } : {}) } };
+    }
+    const projectId = str(values.project) ?? (hasKey ? (await principal(ctx)).project_id : undefined);
+    if (!projectId)
+        throw new UsageError('--project is required with a signed-in session and --scope project');
+    return { cloud, target: { scope: 'project', projectId, ...organization } };
+}
+async function agentSecretCommand(ctx, values, action, ref) {
+    const { cloud, target } = await agentSecretContext(ctx, values);
+    if (action === 'list' && (values.limit !== undefined || values.cursor !== undefined || values['include-deleted'] === true))
+        throw new UsageError('Agent credential lists return all active names. Pagination and deleted-history flags apply to workspace-bound secrets.');
+    const describe = (r) => `${r.name} (${r.id}) · ${r.scope} · version ${r.current_version}\n`;
+    if (action === 'list') {
+        const data = await cloud.secrets.listAgents(target);
+        out(ctx, data.map(describe).join('') || 'No credentials.\n', { data });
+        return 0;
+    }
+    if (action === 'create') {
+        if (!SECRET_NAME.test(ref ?? ''))
+            throw new UsageError('Use an environment variable name for the credential.');
+        const value = await readSecretValue(ctx, values, ref), save = (value) => { ctx.addSecret(value); return cloud.secrets.createAgent(target, { name: ref, value, ...(str(values.description) !== undefined ? { description: str(values.description) } : {}) }); };
+        const r = value !== null ? await save(value) : await askSecretValue(ctx, values, { title: `Add ${ref}`, purpose: `Saved encrypted for your agents as ${ref}.`, name: ref }, save);
+        out(ctx, describe(r), r);
+        return 0;
+    }
+    const r = UUID.test(ref ?? '') ? await cloud.secrets.getAgent(ref) : (await cloud.secrets.listAgents(target)).find(r => r.name === ref);
+    if (!r)
+        throw new NotFoundError(`No credential named ${ref} in this scope.`);
+    // An id is still checked against the explicitly named target rather than silently operating in another scope.
+    if (r.scope !== target.scope || target.organizationId && r.organization_id !== target.organizationId || target.projectId && r.project_id !== target.projectId || target.conversationId && r.conversation_id !== target.conversationId)
+        throw new NotFoundError('That credential belongs to another scope.');
+    if (action === 'get') {
+        out(ctx, describe(r), r);
+        return 0;
+    }
+    if (action === 'update') {
+        const description = str(values.description);
+        if (description === undefined)
+            throw new UsageError('Pass --description to update an agent credential.');
+        const changed = await cloud.secrets.updateAgent(r.id, description);
+        out(ctx, describe(changed), changed);
+        return 0;
+    }
+    if (action === 'rotate') {
+        const value = await readSecretValue(ctx, values, r.name), save = (value) => { ctx.addSecret(value); return cloud.secrets.rotateAgent(r.id, value); };
+        const changed = value !== null ? await save(value) : await askSecretValue(ctx, values, { title: `New value for ${r.name}`, purpose: `Replaces the encrypted credential ${r.name}.`, name: r.name }, save);
+        out(ctx, describe(changed), changed);
+        return 0;
+    }
+    if (action === 'delete') {
+        if (values.yes !== true)
+            throw new UsageError('Pass --yes to erase this credential.');
+        await cloud.secrets.deleteAgent(r.id);
+        out(ctx, `Deleted ${r.name}.\n`, { deleted: true, id: r.id, name: r.name, scope: r.scope });
+        return 0;
+    }
+    if (action === 'versions') {
+        const limit = str(values.limit);
+        const page = await cloud.secrets.versions(r.id, limit ? { limit: parsePositiveInt(limit, 'limit', 200) } : {});
+        out(ctx, secretVersionTable(page.data), { data: page.data, next_cursor: page.nextCursor });
+        return 0;
+    }
+    if (action === 'access-log') {
+        const outcome = str(values.outcome), workspace = str(values.workspace), limit = str(values.limit);
+        if (outcome !== undefined && !['granted', 'denied', 'failed'].includes(outcome))
+            throw new UsageError('--outcome must be granted, denied or failed');
+        if (workspace !== undefined && !UUID.test(workspace))
+            throw new UsageError('--workspace must be a workspace id');
+        const page = await cloud.secrets.accessEvents(r.id, { ...(outcome ? { outcome: outcome } : {}), ...(workspace ? { workspaceId: workspace } : {}), ...(limit ? { limit: parsePositiveInt(limit, 'limit', 200) } : {}) });
+        out(ctx, JSON.stringify(page.data) + '\n', { data: page.data, next_cursor: page.nextCursor });
+        return 0;
+    }
+    throw new UsageError('Unknown credential action.');
+}
 function scopeFlag(values) {
     const org = str(values.org);
     if (org === undefined)
@@ -2599,7 +2716,7 @@ function permissionParams(values, scope, mode) {
  * 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, name) {
+export async function readSecretValue(ctx, values, name) {
     const file = str(values['from-file']);
     if (values.ask === true) {
         if (file !== undefined)
@@ -2643,7 +2760,7 @@ function secretText(value) {
     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) {
+export async function askSecretValue(ctx, values, page, save) {
     const asked = await askInBrowser(ctx, {
         kind: 'secret',
         title: page.title,

package/dist/conversations.d.ts

@@ -59,6 +59,8 @@ export interface Conversation {
     started_by?: {
         user_id: string;
     } | null;
+    orchestrator_conversation_id?: string | null;
+    orchestrator_input_id?: string | null;
 }
 export interface LocalConversation {
     api_url: string;

package/dist/conversations.js

@@ -250,7 +250,7 @@ export async function createConversationRecord(ctx, folder, harness, route, name
     capture.catch(() => undefined);
     // The title marker this computer chose (`shard settings --title-prefix`, 0.20.1+); none sent means the platform's.
     const titlePrefix = storedTitlePrefix(ctx.store.dir);
-    const response = await conversationClient(ctx).conversations.create({ repoRemote: project.remote ?? `file://${project.folder}`, harness, route, mode: 'new',
+    const response = await conversationClient(ctx).conversations.create({ fromConversationId: ctx.io.env.SF_CONVERSATION_ID, repoRemote: project.remote ?? `file://${project.folder}`, harness, route, mode: 'new',
         base: { commit, ...(branch ? { branch } : {}) }, ...(name ? { name } : {}), ...choice, projectId: ctx.store.profile(ctx.apiUrl).project_id,
         ...(titlePrefix !== undefined ? { titlePrefix } : {}),
         ...(movedIn ? { harnessSessionId: movedIn.session_id, ...(movedIn.title ? { title: movedIn.title.slice(0, 200) } : {}) } : {}) }, { idempotencyKey, signal: ctx.signal });

package/dist/device-bridge.js

@@ -585,7 +585,7 @@ export class DeviceExecutor {
             if (r.kind === 'dir_list')
                 result = { state: 'done', dir: await listDeviceDir(target, r.dir ?? {}, ctx.signal) };
             else if (r.kind === 'project_link')
-                result = { state: 'done', project: await linkLocalProject(ctx, target, { ...(r.link?.brief ? { brief: r.link.brief } : {}), harness: r.link?.harness ?? current.harness, projectId: current.project_id, seed: true }, undefined, this.#seedHub) };
+                result = { state: 'done', project: await linkLocalProject(ctx, target, { ...(r.link?.brief ? { brief: r.link.brief } : {}), harness: r.link?.harness ?? current.harness, projectId: current.project_id, seed: true, fromConversationId: r.conversation_id }, undefined, this.#seedHub) };
             else {
                 const f = r.files;
                 if (!f.remote_path.startsWith('/') || /[\0\r\n]/.test(f.remote_path))

package/dist/device-folders.d.ts

@@ -36,7 +36,7 @@ export interface LinkedProject {
     commit?: string;
     branch?: string;
 }
-type Starter = (ctx: Ctx, folder: string, harness: 'claude' | 'codex', brief: string) => Promise<{
+type Starter = (ctx: Ctx, folder: string, harness: 'claude' | 'codex', brief: string, fromConversationId?: string) => Promise<{
     id: string;
     project_id: string;
 }>;
@@ -65,6 +65,7 @@ export declare function linkLocalProject(ctx: Ctx, path: string, options?: {
     harness?: 'claude' | 'codex';
     projectId?: string;
     seed?: boolean;
+    fromConversationId?: string;
 }, start?: Starter, seedHub?: (ctx: Ctx, folder: string, projectId: string) => Promise<HubSeed>): Promise<LinkedProject>;
 /** `shard projects link <path>` (0.25.0+): what the desktop app's "Add a folder…" runs, the same as a device's project_link. */
 export declare const PROJECT_LINK_HANDLERS: Record<string, Handler>;

package/dist/device-folders.js

@@ -139,14 +139,14 @@ export async function listDeviceDir(root, options = {}, signal) {
  * working tree (uncommitted files too, .gitignore respected) seeds it while its VM boots, and the brief is its first
  * prompt. The brief goes in on standard input, never in a command line another user can read.
  */
-export const startFromFolder = (ctx, folder, harness, brief) => {
+export const startFromFolder = (ctx, folder, harness, brief, fromConversationId) => {
     const node = ctx.runtime?.node ?? process.execPath, script = ctx.runtime?.script ?? process.argv[1];
     if (!script)
         return Promise.reject(new Error('The Shardflux CLI could not find itself to start the conversation.'));
     return new Promise((resolveStart, reject) => {
         const child = spawn(node, [script, 'agents', 'new', '--app', harness, '--path', folder, '--prompt-file', '-', '--json'], {
             cwd: folder, stdio: ['pipe', 'pipe', 'pipe'],
-            env: { ...process.env, ...ctx.io.env, SHARDFLUX_CONFIG_DIR: ctx.store.dir, SHARDFLUX_API_URL: ctx.apiUrl, CI: '1' },
+            env: { ...process.env, ...ctx.io.env, SHARDFLUX_CONFIG_DIR: ctx.store.dir, SHARDFLUX_API_URL: ctx.apiUrl, CI: '1', ...(fromConversationId ? { SF_CONVERSATION_ID: fromConversationId } : {}) },
         });
         const out = [], err = [];
         let outBytes = 0;
@@ -209,7 +209,7 @@ export async function linkLocalProject(ctx, path, options = {}, start = startFro
     const profile = ctx.store.profile(ctx.apiUrl);
     let projectId = profile.project_id ?? profile.api_key?.project_id ?? options.projectId, conversationId;
     if (options.brief) {
-        const started = await start(ctx, folder, options.harness ?? 'claude', options.brief);
+        const started = await start(ctx, folder, options.harness ?? 'claude', options.brief, options.fromConversationId);
         conversationId = started.id;
         projectId = started.project_id || projectId;
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@shardflux/cli",
-  "version": "0.28.1",
+  "version": "0.28.2",
   "type": "module",
   "description": "shard: the Shardflux command line. Create an account, sign in, set up keys and billing, then open, run commands in, move files to, suspend, resume and fork serverless agent workspaces.",
   "license": "Apache-2.0",
@@ -53,7 +53,7 @@
     "snappyjs": "0.7.0",
     "ws": "8.22.0",
     "yaml": "2.9.1",
-    "@shardflux/sdk": "^0.30.1"
+    "@shardflux/sdk": "^0.30.2"
   },
   "devDependencies": {
     "@eslint/js": "10.0.1",
@@ -65,10 +65,10 @@
     "typescript-eslint": "8.70.1"
   },
   "optionalDependencies": {
-    "@shardflux/desktop-darwin-arm64": "0.9.2",
-    "@shardflux/desktop-darwin-x64": "0.9.2",
-    "@shardflux/desktop-linux-arm64": "0.9.2",
-    "@shardflux/desktop-linux-x64": "0.9.2"
+    "@shardflux/desktop-darwin-arm64": "0.9.3",
+    "@shardflux/desktop-darwin-x64": "0.9.3",
+    "@shardflux/desktop-linux-arm64": "0.9.3",
+    "@shardflux/desktop-linux-x64": "0.9.3"
   },
   "scripts": {
     "build": "node scripts/build.mjs",