runwork 0.12.0 → 0.13.2

package/dist/commands/doctor.js

@@ -2,6 +2,88 @@ import { Command } from 'commander';
 import { shouldOutputJson, jsonOut } from '../utils/output.js';
 import { bold, dim, green, yellow, cyan } from '../ui/colors.js';
 import { runAllChecks } from '../health/runner.js';
+import { detectCurrentAgent } from '../agents/runtime-detection.js';
+/**
+ * Env vars worth surfacing in --verbose for AI agents debugging their own
+ * environment. Filtered to known-safe runtime signals; never includes
+ * credentials, tokens, or anything matching common secret patterns.
+ */
+const VERBOSE_ENV_ALLOWLIST = [
+    // Claude Code
+    'CLAUDECODE',
+    'CLAUDE_CODE_ENTRYPOINT',
+    'CLAUDE_CODE_SESSION_ID',
+    'CLAUDE_CODE_EXECPATH',
+    'CLAUDE_EFFORT',
+    // Codex
+    'CODEX_CI',
+    'CODEX_THREAD_ID',
+    'CODEX_SANDBOX',
+    'CODEX_SANDBOX_NETWORK_DISABLED',
+    // Generic shell context
+    'PWD',
+    'SHELL',
+    'TERM',
+    'LANG',
+    // CI markers
+    'CI',
+    'GITHUB_ACTIONS',
+];
+function collectVerboseInfo() {
+    const env = {};
+    for (const key of VERBOSE_ENV_ALLOWLIST) {
+        if (process.env[key] !== undefined) {
+            env[key] = process.env[key];
+        }
+    }
+    const detected = detectCurrentAgent();
+    return {
+        hostAgent: detected ?? null,
+        env,
+        runtime: {
+            platform: process.platform,
+            arch: process.arch,
+            nodeVersion: process.version,
+            cwd: process.cwd(),
+            pid: process.pid,
+        },
+    };
+}
+function printVerboseBlock(info) {
+    console.log('');
+    console.log(bold('Verbose runtime info'));
+    console.log('');
+    const detected = info.hostAgent;
+    if (detected) {
+        console.log(`  ${green('[detected]')} Host agent: ${detected.slug}`);
+        if (detected.sessionId)
+            console.log(`             sessionId:       ${detected.sessionId}`);
+        if (detected.sessionFilePath)
+            console.log(`             sessionFilePath: ${detected.sessionFilePath}`);
+        console.log(`             source:          ${detected.source}`);
+    }
+    else {
+        console.log(`  ${dim('[none]')} No host agent detected (not running inside a known AI agent)`);
+    }
+    console.log('');
+    console.log(bold('Env vars (allowlisted)'));
+    const envEntries = Object.entries(info.env);
+    if (envEntries.length === 0) {
+        console.log(`  ${dim('(none set)')}`);
+    }
+    else {
+        for (const [k, v] of envEntries) {
+            console.log(`  ${k.padEnd(38)} ${v}`);
+        }
+    }
+    console.log('');
+    console.log(bold('Runtime'));
+    const r = info.runtime;
+    for (const [k, v] of Object.entries(r)) {
+        console.log(`  ${k.padEnd(38)} ${v}`);
+    }
+    console.log('');
+}
 const STATUS_LABELS = {
     pass: green('[pass]'),
     warn: yellow('[warn]'),
@@ -67,14 +149,19 @@ function printHumanReport(report) {
 }
 export const doctorCommand = new Command('doctor')
     .description('Check system health: auth, network, project config, agent setup')
-    .action(async (_opts, command) => {
+    .option('-v, --verbose', 'Include host-agent detection results, runtime info, and allowlisted env vars (useful for AI agents debugging their own environment)')
+    .action(async (opts, command) => {
     const asJson = shouldOutputJson(command.optsWithGlobals().json);
     const report = await runAllChecks();
+    const verboseInfo = opts.verbose ? collectVerboseInfo() : null;
     if (asJson) {
-        jsonOut(report);
+        jsonOut(verboseInfo ? { ...report, verbose: verboseInfo } : report);
     }
     else {
         printHumanReport(report);
+        if (verboseInfo) {
+            printVerboseBlock(verboseInfo);
+        }
     }
     if (report.checks.some(c => c.status === 'fail')) {
         process.exit(1);

package/dist/commands/inbox.d.ts

@@ -0,0 +1,11 @@
+import { Command } from 'commander';
+/**
+ * `runwork inbox` - list shared conversations visible to the current user.
+ *
+ * Scopes:
+ *   --filter received   shares others sent to me
+ *   --filter sent       shares I sent to others
+ *   --filter saved      my personal checkpoints (save-convo)
+ *   --filter all        all of the above (default)
+ */
+export declare const inboxCommand: Command;

package/dist/commands/inbox.js

@@ -0,0 +1,60 @@
+import { Command } from 'commander';
+import { requireAuth } from '../auth/store.js';
+import { ApiClient } from '../api/client.js';
+import { resolveWorkspace } from '../workspace/resolve.js';
+import { shouldOutputJson, jsonOut } from '../utils/output.js';
+/**
+ * `runwork inbox` - list shared conversations visible to the current user.
+ *
+ * Scopes:
+ *   --filter received   shares others sent to me
+ *   --filter sent       shares I sent to others
+ *   --filter saved      my personal checkpoints (save-convo)
+ *   --filter all        all of the above (default)
+ */
+export const inboxCommand = new Command('inbox')
+    .description('List shared conversations visible to you')
+    .option('--filter <scope>', 'Filter: all | received | sent | saved', 'all')
+    .option('--limit <n>', 'Max rows to return', '50')
+    .option('--workspace <id>', 'Workspace ID')
+    .action(async (opts, command) => {
+    const useJson = shouldOutputJson(command.optsWithGlobals().json);
+    const scope = opts.filter === 'received' || opts.filter === 'sent' || opts.filter === 'saved'
+        ? opts.filter
+        : 'all';
+    const limit = opts.limit ? parseInt(opts.limit, 10) : 50;
+    const credentials = requireAuth();
+    const client = new ApiClient(credentials);
+    const { workspaceId } = await resolveWorkspace(client, { workspace: opts.workspace });
+    try {
+        const { shares, total } = await client.listSharedConversations(workspaceId, { scope, limit });
+        if (useJson) {
+            jsonOut({ shares, total });
+            return;
+        }
+        if (shares.length === 0) {
+            console.log(`No shared conversations (scope: ${scope}).`);
+            return;
+        }
+        console.log(`\nShared conversations (${scope}, ${total}):\n`);
+        console.log(`  ${'ID'.padEnd(20)} ${'Title'.padEnd(40)} ${'Agent'.padEnd(14)} Status`);
+        console.log('  ' + '-'.repeat(96));
+        for (const raw of shares) {
+            const share = raw;
+            const id = share.id.slice(0, 18);
+            const title = (share.title || '').slice(0, 38);
+            const agent = (share.sourceAgent || 'unknown').slice(0, 12);
+            const status = share.deletedAt
+                ? 'deleted'
+                : share.isPersonal
+                    ? 'saved'
+                    : ((share.recipients ?? []).every(r => r.status === 'resumed') ? 'resumed' : 'pending');
+            console.log(`  ${id.padEnd(20)} ${title.padEnd(40)} ${agent.padEnd(14)} ${status}`);
+        }
+        console.log('');
+    }
+    catch (err) {
+        console.error(`Failed to list inbox: ${err instanceof Error ? err.message : err}`);
+        process.exit(1);
+    }
+});

package/dist/commands/resume.d.ts

@@ -0,0 +1,2 @@
+import { Command } from 'commander';
+export declare const resumeCommand: Command;

package/dist/commands/resume.js

@@ -0,0 +1,289 @@
+import { Command } from 'commander';
+import { writeFileSync, mkdirSync, realpathSync } from 'fs';
+import { homedir } from 'os';
+import { join } from 'path';
+import { spawn } from 'child_process';
+import { requireAuth } from '../auth/store.js';
+import { ApiClient } from '../api/client.js';
+import { resolveWorkspace } from '../workspace/resolve.js';
+import { shouldOutputJson, jsonOut } from '../utils/output.js';
+import { getAgent } from '../agents/registry-data.js';
+import { detectCurrentAgent } from '../agents/runtime-detection.js';
+import { whichBinary } from '../utils/which.js';
+/**
+ * Mirror of Claude Code's cwd encoding rule: replace every non-alphanumeric
+ * character with '-'. The canonical (realpath-resolved) cwd is encoded so
+ * /tmp/foo on macOS encodes the same as /private/tmp/foo (which is how
+ * Claude Code itself resolves the cwd).
+ */
+function encodeClaudeCodeCwd(cwd) {
+    let canonical;
+    try {
+        canonical = realpathSync(cwd);
+    }
+    catch {
+        canonical = cwd;
+    }
+    return canonical.replace(/[^a-zA-Z0-9]/g, '-');
+}
+/**
+ * Extract the original Claude Code session UUID from the first event of a
+ * JSONL bundle. Claude Code's `--resume <uuid>` expects this UUID; the
+ * filename on disk must match `<uuid>.jsonl`.
+ */
+function extractClaudeCodeUuid(jsonlContent) {
+    const firstLine = jsonlContent.split('\n').find(l => l.trim().length > 0);
+    if (!firstLine)
+        return null;
+    try {
+        const event = JSON.parse(firstLine);
+        return event.sessionId ?? null;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Extract the original Codex thread UUID from the first event of a rollout
+ * file. `codex resume <UUID>` accepts this id; the file's filename embeds it.
+ */
+function extractCodexUuid(rolloutContent) {
+    const firstLine = rolloutContent.split('\n').find(l => l.trim().length > 0);
+    if (!firstLine)
+        return null;
+    try {
+        const event = JSON.parse(firstLine);
+        return event.payload?.id ?? null;
+    }
+    catch {
+        return null;
+    }
+}
+function placeClaudeJsonl(uuid, content, recipientCwd) {
+    const encoded = encodeClaudeCodeCwd(recipientCwd);
+    const projectDir = join(homedir(), '.claude', 'projects', encoded);
+    mkdirSync(projectDir, { recursive: true });
+    const placedAt = join(projectDir, `${uuid}.jsonl`);
+    writeFileSync(placedAt, content);
+    return { placedAt, runFromCwd: recipientCwd };
+}
+function placeCodexRollout(uuid, content) {
+    const now = new Date();
+    const yyyy = String(now.getUTCFullYear());
+    const mm = String(now.getUTCMonth() + 1).padStart(2, '0');
+    const dd = String(now.getUTCDate()).padStart(2, '0');
+    const dir = join(homedir(), '.codex', 'sessions', yyyy, mm, dd);
+    mkdirSync(dir, { recursive: true });
+    // Filename pattern Codex itself uses: rollout-YYYY-MM-DDThh-mm-ss-<uuid>.jsonl
+    const ts = now.toISOString().replace(/\.\d+Z$/, '').replace(/:/g, '-');
+    const placedAt = join(dir, `rollout-${ts}-${uuid}.jsonl`);
+    writeFileSync(placedAt, content);
+    return { placedAt };
+}
+/**
+ * Pick the target agent based on flag overrides, the share's sourceAgent,
+ * and what's installed locally.
+ */
+function pickTargetAgent(opts, sourceAgent) {
+    if (opts.agent) {
+        return getAgent(opts.agent) ?? null;
+    }
+    // Prefer the same agent the sender used, if installed
+    const source = getAgent(sourceAgent);
+    if (source && isAgentInstalled(source)) {
+        return source;
+    }
+    // Fall back to the sender's agent registry entry even if not detectably installed
+    // (the user may have it; better to print accurate instructions than abort)
+    return source ?? null;
+}
+function isAgentInstalled(agent) {
+    // Lightweight check: just look for the launch binary on PATH.
+    // More comprehensive detection lives in agents/detection.ts but requires
+    // async resolution; this synchronous check is good enough for resume.
+    if (agent.launch?.cli) {
+        return !!whichBinary(agent.launch.cli);
+    }
+    return false;
+}
+export const resumeCommand = new Command('resume')
+    .description('Resume a shared conversation locally in your agent of choice')
+    .argument('<share-id>', 'The share ID (sc_*) returned by share-convo or save-convo')
+    .option('--agent <slug>', 'Override target agent (e.g. claude-code, codex)')
+    .option('--into <path>', 'Override target cwd (defaults to current $PWD)')
+    .option('--dry-run', 'Print the resume command instead of executing it')
+    .option('--pick', 'Show interactive picker (requires TTY) - not yet implemented')
+    .option('--workspace <id>', 'Workspace ID')
+    .action(async (shareId, opts, command) => {
+    const useJson = shouldOutputJson(command.optsWithGlobals().json);
+    const credentials = requireAuth();
+    const client = new ApiClient(credentials);
+    const { workspaceId } = await resolveWorkspace(client, { workspace: opts.workspace });
+    let share;
+    try {
+        const { share: raw } = await client.getSharedConversation(workspaceId, shareId);
+        share = raw;
+    }
+    catch (err) {
+        console.error(`Failed to fetch share ${shareId}: ${err instanceof Error ? err.message : err}`);
+        process.exit(1);
+    }
+    // If --agent not provided, detect what the user is currently in - that's
+    // often the best default ("share to me, resume in same agent")
+    if (!opts.agent) {
+        const detected = detectCurrentAgent();
+        if (detected) {
+            opts.agent = detected.slug;
+        }
+    }
+    const target = pickTargetAgent(opts, share.sourceAgent);
+    if (!target) {
+        console.error(`No target agent could be determined. Pass --agent <slug> or install the source agent (${share.sourceAgent}).`);
+        process.exit(1);
+    }
+    const cap = target.resumeCapability;
+    // Tier 3 fallback: no native resume - print a paste-prompt
+    if (!cap || cap.mode === 'unsupported' || !cap.nativeBundleFormat) {
+        const promptText = buildPastePrompt(shareId, share.title);
+        if (useJson) {
+            jsonOut({ mode: 'paste-prompt', shareId, prompt: promptText });
+            return;
+        }
+        console.log(`\n${target.name} does not support native resume. Paste this prompt into your agent:\n`);
+        console.log('---');
+        console.log(promptText);
+        console.log('---\n');
+        return;
+    }
+    // Need a matching native bundle on the share
+    const hasNative = (share.bundles ?? []).some(b => b.format === cap.nativeBundleFormat);
+    if (!hasNative) {
+        console.error(`This share has no ${cap.nativeBundleFormat} bundle (sourceAgent was ${share.sourceAgent}). ` +
+            `Falling back to paste-prompt.`);
+        const promptText = buildPastePrompt(shareId, share.title);
+        console.log('\n---');
+        console.log(promptText);
+        console.log('---\n');
+        return;
+    }
+    // Download the native bundle content
+    const bundle = await client.downloadSharedConversationBundle(workspaceId, shareId, cap.nativeBundleFormat);
+    // Extract the ORIGINAL session UUID from the bundle content - that's
+    // what the native resume command expects, not our share ID.
+    let nativeUuid;
+    if (cap.nativeBundleFormat === 'claude-jsonl') {
+        nativeUuid = extractClaudeCodeUuid(bundle.content);
+    }
+    else if (cap.nativeBundleFormat === 'codex-rollout') {
+        nativeUuid = extractCodexUuid(bundle.content);
+    }
+    else {
+        console.error(`No UUID extraction strategy for native bundle format ${cap.nativeBundleFormat}`);
+        process.exit(1);
+    }
+    if (!nativeUuid) {
+        console.error(`Could not extract native session UUID from ${cap.nativeBundleFormat} bundle. ` +
+            `The bundle may be malformed.`);
+        process.exit(1);
+    }
+    // Place the file per-agent using the original UUID
+    let placement;
+    const recipientCwd = opts.into ?? process.cwd();
+    if (cap.nativeBundleFormat === 'claude-jsonl') {
+        placement = placeClaudeJsonl(nativeUuid, bundle.content, recipientCwd);
+    }
+    else if (cap.nativeBundleFormat === 'codex-rollout') {
+        placement = placeCodexRollout(nativeUuid, bundle.content);
+    }
+    else {
+        console.error(`No placement strategy for native bundle format ${cap.nativeBundleFormat}`);
+        process.exit(1);
+    }
+    // Tell the server we resumed it (best-effort)
+    client.markSharedConversationResumed(workspaceId, shareId).catch(() => {
+        // Non-fatal; the user is already up and resuming
+    });
+    if (cap.mode === 'file-drop-only') {
+        const result = {
+            mode: 'file-drop-only',
+            agent: target.slug,
+            placedAt: placement.placedAt,
+            hint: cap.manualOpenHint ?? `Open ${target.name} to find this session in your history.`,
+        };
+        if (useJson) {
+            jsonOut(result);
+            return;
+        }
+        console.log(`\nBundle placed at: ${placement.placedAt}`);
+        console.log(`${result.hint}\n`);
+        return;
+    }
+    if (cap.mode === 'cli-resume') {
+        // Substitute {uuid} in the resume command template with the original
+        // session UUID we extracted from the bundle content.
+        const cmd = (cap.cliResumeCommand ?? '').replace(/\{uuid\}/g, nativeUuid);
+        // If we're running inside the SAME agent we'd resume into (very common
+        // when an LLM in claude-code invokes `runwork resume` to pick up a
+        // saved claude-code conversation), exec'ing `claude --resume <uuid>`
+        // from inside that session is broken: the child claude process can't
+        // attach to the parent's TTY and the resume hits agent-specific edge
+        // cases ("No deferred tool marker found in the resumed session..."
+        // for Claude Code). Detect this and degrade to print-the-command mode
+        // so the user can copy/paste into a fresh terminal -- AND tell the
+        // caller agent that the in-session continuation path is via the
+        // `get_shared_conversation` MCP tool, which inlines the transcript.
+        const detected = detectCurrentAgent();
+        const insideSameAgent = detected && detected.slug === target.slug;
+        const shouldPrintOnly = opts.dryRun || insideSameAgent;
+        if (shouldPrintOnly) {
+            const fullCmd = placement.runFromCwd
+                ? `cd "${placement.runFromCwd}" && ${cmd}`
+                : cmd;
+            const result = {
+                mode: 'cli-resume',
+                agent: target.slug,
+                placedAt: placement.placedAt,
+                command: fullCmd,
+                insideSameAgent: !!insideSameAgent,
+            };
+            if (useJson) {
+                jsonOut(result);
+                return;
+            }
+            console.log(`\nBundle placed at: ${placement.placedAt}`);
+            if (insideSameAgent) {
+                console.log(`\nYou are already inside ${target.name}, so I can't auto-launch a new session in this terminal.`);
+                console.log(`To resume natively, exit this session and run in a fresh terminal:`);
+                console.log(`  ${fullCmd}`);
+                console.log(`\nOr ask the assistant to continue the conversation in THIS session by ` +
+                    `fetching the transcript via the Runwork MCP \`get_shared_conversation\` tool ` +
+                    `(share ID: ${shareId}).`);
+            }
+            else {
+                console.log(`Run: ${fullCmd}\n`);
+            }
+            return;
+        }
+        // Exec the resume command (fresh-shell case)
+        const parts = cmd.split(' ');
+        const child = spawn(parts[0], parts.slice(1), {
+            cwd: placement.runFromCwd ?? recipientCwd,
+            stdio: 'inherit',
+        });
+        child.on('exit', (code) => {
+            process.exit(code ?? 0);
+        });
+        return;
+    }
+    console.error(`Unexpected resumeCapability.mode: ${cap.mode}`);
+    process.exit(1);
+});
+function buildPastePrompt(shareId, title) {
+    return `Continue the conversation that a teammate shared with me. The share ID is ${shareId} (title: "${title}").
+
+PREFERRED: if the \`runwork\` CLI is installed locally, run:
+  runwork resume ${shareId}
+That auto-detects your active agent and resumes natively if possible.
+
+FALLBACK: use the Runwork MCP tool \`get_shared_conversation\` with this share ID to fetch the full transcript, then continue from where the conversation left off.`;
+}

package/dist/commands/save-convo.d.ts

@@ -0,0 +1,8 @@
+import { Command } from 'commander';
+/**
+ * `runwork save-convo` - personal checkpoint of the current AI conversation.
+ *
+ * Thin alias over `share-convo` with isPersonal=true. The recipient is always
+ * the sender; no notifications are sent. Same capture mechanics otherwise.
+ */
+export declare const saveConvoCommand: Command;

package/dist/commands/save-convo.js

@@ -0,0 +1,20 @@
+import { Command } from 'commander';
+import { runShareConvo } from './share-convo.js';
+/**
+ * `runwork save-convo` - personal checkpoint of the current AI conversation.
+ *
+ * Thin alias over `share-convo` with isPersonal=true. The recipient is always
+ * the sender; no notifications are sent. Same capture mechanics otherwise.
+ */
+export const saveConvoCommand = new Command('save-convo')
+    .description('Save the current AI conversation as a personal checkpoint')
+    .option('--transcript-file <path>', 'Path to the LLM-emitted markdown transcript (required)')
+    .option('--native-file <path>', 'Path to the native session file (optional; auto-detected from env vars)')
+    .option('--source-agent <slug>', 'Override host-agent detection')
+    .option('--title <string>', 'Short title for the conversation (required)')
+    .option('--note <string>', 'Optional note to your future self')
+    .option('--ttl-days <n>', 'Days until expiration (1-30, default 7)')
+    .option('--metadata-json <json>', 'Inline JSON object with workMode, openQuestions, etc.')
+    .option('--metadata-file <path>', 'Path to a JSON file with metadata fields')
+    .option('--workspace <id>', 'Workspace ID')
+    .action((opts, command) => runShareConvo({ ...opts, personal: true }, command, true));

package/dist/commands/share-convo.d.ts

@@ -0,0 +1,24 @@
+import { Command } from 'commander';
+/**
+ * `runwork share-convo` - share the current AI conversation with a teammate.
+ *
+ * Typically invoked by the `share-conversation` skill from inside an AI agent.
+ * The skill is responsible for emitting the markdown transcript and metadata;
+ * this command does the upload, host-agent detection, and native-bundle pickup.
+ */
+interface ShareConvoOptions {
+    to?: string[];
+    transcriptFile?: string;
+    nativeFile?: string;
+    sourceAgent?: string;
+    title?: string;
+    note?: string;
+    personal?: boolean;
+    ttlDays?: string;
+    metadataJson?: string;
+    metadataFile?: string;
+    workspace?: string;
+}
+export declare function runShareConvo(opts: ShareConvoOptions, command: Command, isPersonalAlias?: boolean): Promise<void>;
+export declare const shareConvoCommand: Command;
+export {};