@blockrun/franklin 3.9.6 → 3.10.1

package/dist/agent/context.js

@@ -174,7 +174,7 @@ function getToolPatternsSection() {
 - **Research**: WebSearch for discovery → WebFetch for specific URLs from search results. Don't WebFetch URLs you invented.
 - **Complex tasks**: Use Agent to spawn sub-agents for 2+ independent research or implementation tasks. Don't do sequentially what can be done in parallel.
 - **Multiple independent lookups**: Call all tools in a single response. NEVER make sequential calls when parallel calls would work.
-- **Long-running iteration (>20 items)**: Do NOT loop in the agent (one tool call per item burns turns and trips timeouts on the 21st item). Instead: Write a script (Node/Bash/Python), have it iterate with a checkpoint file (\`./.franklin/<task>.checkpoint.json\` storing cursor + processedCount), then Bash it once. The agent re-engages only on errors or completion. Pattern fits paginated APIs, batch enrichment, large CSV emit, anything where the loop body is deterministic. The agent's job is to design and orchestrate, not to be the for-loop.
+- **Long-running iteration (>20 items)**: Use the **Detach** tool, not turn-by-turn loops. Write a script that iterates and persists a checkpoint file (e.g. \`./.franklin/<task>.checkpoint.json\` with cursor + processedCount), then start it via Detach — \`{ label: "scrape stargazers", command: "node fetch.mjs" }\`. Detach returns a runId immediately and the work continues even if Franklin exits. Inspect with \`franklin task tail <runId> --follow\` / \`task wait <runId>\` / \`task cancel <runId>\`. The agent's job is to design and orchestrate, not to be the for-loop. Pattern fits paginated APIs, batch enrichment, large CSV emit, anything where the loop body is deterministic.
 
 # Grounding Before Answering
 Your training data is frozen in the past. Live-world questions MUST be answered from tool results, not memory.

package/dist/commands/task.d.ts

@@ -0,0 +1,11 @@
+/**
+ * `franklin task` CLI surface — human-facing operations on detached background
+ * tasks. Mirrors the on-disk shape under `~/.franklin/tasks/<runId>/` that the
+ * runner / store layers maintain. Subcommands grow incrementally over T10–T13:
+ *   - list    : recent tasks, newest first
+ *   - tail    : print log + status; --follow polls until terminal
+ *   - cancel  : SIGTERM the runner pid
+ *   - wait    : block until terminal, exit 0/1/2 by outcome
+ */
+import { Command } from 'commander';
+export declare function buildTaskCommand(): Command;

package/dist/commands/task.js

@@ -0,0 +1,134 @@
+/**
+ * `franklin task` CLI surface — human-facing operations on detached background
+ * tasks. Mirrors the on-disk shape under `~/.franklin/tasks/<runId>/` that the
+ * runner / store layers maintain. Subcommands grow incrementally over T10–T13:
+ *   - list    : recent tasks, newest first
+ *   - tail    : print log + status; --follow polls until terminal
+ *   - cancel  : SIGTERM the runner pid
+ *   - wait    : block until terminal, exit 0/1/2 by outcome
+ */
+import fs from 'node:fs';
+import { Command } from 'commander';
+import { listTasks, readTaskMeta } from '../tasks/store.js';
+import { reconcileLostTasks } from '../tasks/lost-detection.js';
+import { taskLogPath } from '../tasks/paths.js';
+import { isTerminalTaskStatus } from '../tasks/types.js';
+function fmtAge(ms) {
+    const s = Math.floor(ms / 1000);
+    if (s < 60)
+        return `${s}s`;
+    const m = Math.floor(s / 60);
+    if (m < 60)
+        return `${m}m`;
+    return `${Math.floor(m / 60)}h${m % 60}m`;
+}
+export function buildTaskCommand() {
+    const cmd = new Command('task').description('Manage long-running detached tasks');
+    cmd
+        .command('list')
+        .description('List recent tasks (newest first)')
+        .action(() => {
+        reconcileLostTasks();
+        const tasks = listTasks();
+        if (tasks.length === 0) {
+            console.log('No tasks. Start one via the Task agent tool.');
+            return;
+        }
+        const now = Date.now();
+        for (const t of tasks) {
+            const age = fmtAge(now - (t.lastEventAt ?? t.createdAt));
+            console.log(`${t.runId}  ${t.status.padEnd(10)}  ${age.padStart(5)}  ${t.label}`);
+        }
+    });
+    cmd
+        .command('tail <runId>')
+        .description('Print log + current status for a task')
+        .option('-f, --follow', 'Poll until task reaches terminal state')
+        .action(async (runId, opts) => {
+        const meta0 = readTaskMeta(runId);
+        if (!meta0) {
+            console.error(`No task: ${runId}`);
+            process.exit(1);
+        }
+        let printed = 0;
+        const printNew = () => {
+            try {
+                const buf = fs.readFileSync(taskLogPath(runId));
+                if (buf.length > printed) {
+                    process.stdout.write(buf.subarray(printed));
+                    printed = buf.length;
+                }
+            }
+            catch {
+                /* log not yet written */
+            }
+        };
+        printNew();
+        if (opts.follow) {
+            while (true) {
+                await new Promise((r) => setTimeout(r, 1000));
+                printNew();
+                const meta = readTaskMeta(runId);
+                if (meta && isTerminalTaskStatus(meta.status))
+                    break;
+            }
+        }
+        const meta = readTaskMeta(runId);
+        if (meta) {
+            console.log(`\n--- ${meta.status} ---`);
+            if (meta.terminalSummary)
+                console.log(meta.terminalSummary);
+        }
+    });
+    cmd
+        .command('wait <runId>')
+        .description('Block until task reaches terminal state, then exit')
+        .option('--timeout <ms>', 'Max wait, default 30 minutes', '1800000')
+        .action(async (runId, opts) => {
+        const cap = parseInt(opts.timeout, 10);
+        const t0 = Date.now();
+        while (true) {
+            const meta = readTaskMeta(runId);
+            if (!meta) {
+                console.error(`No task: ${runId}`);
+                process.exit(1);
+            }
+            if (isTerminalTaskStatus(meta.status)) {
+                console.log(`${meta.status}: ${meta.terminalSummary ?? ''}`);
+                process.exit(meta.status === 'succeeded' ? 0 : 1);
+            }
+            if (Date.now() - t0 > cap) {
+                console.error(`Timed out after ${cap}ms; task still ${meta.status}.`);
+                process.exit(2);
+            }
+            await new Promise((r) => setTimeout(r, 1000));
+        }
+    });
+    cmd
+        .command('cancel <runId>')
+        .description('Cancel a running task (SIGTERM to runner)')
+        .action((runId) => {
+        const meta = readTaskMeta(runId);
+        if (!meta) {
+            console.error(`No task: ${runId}`);
+            process.exit(1);
+        }
+        if (isTerminalTaskStatus(meta.status)) {
+            console.log(`Task already ${meta.status}.`);
+            return;
+        }
+        if (typeof meta.pid !== 'number') {
+            console.error('Task has no recorded pid (likely still queued).');
+            process.exit(1);
+        }
+        try {
+            process.kill(meta.pid, 'SIGTERM');
+            console.log(`SIGTERM sent to ${meta.pid}.`);
+        }
+        catch (err) {
+            console.error(`Could not signal pid ${meta.pid}: ${err.message}`);
+            process.exit(1);
+        }
+    });
+    return cmd;
+}

package/dist/index.js

@@ -23,6 +23,7 @@ import { daemonCommand } from './commands/daemon.js';
 import { initCommand } from './commands/init.js';
 import { uninitCommand } from './commands/uninit.js';
 import { proxyCommand } from './commands/proxy.js';
+import { buildTaskCommand } from './commands/task.js';
 import { VERSION as version } from './config.js';
 const program = new Command();
 program
@@ -215,6 +216,21 @@ program
     const { listAvailablePlugins } = await import('./commands/plugin.js');
     listAvailablePlugins();
 });
+// `franklin task <subcmd>` — human-facing CLI for detached background tasks.
+// Defined in src/commands/task.ts; subcommands: list, tail, cancel, wait.
+program.addCommand(buildTaskCommand());
+// Hidden internal subcommand — invoked by startDetachedTask via spawn(detached).
+// The underscore prefix signals "not for humans"; we still register it via
+// commander so exit codes and arg parsing stay consistent with the rest of
+// the CLI.
+program
+    .command('_task-runner <runId>')
+    .description('(internal) execute a detached task by runId')
+    .action(async (runId) => {
+    const { runDetachedTask } = await import('./tasks/runner.js');
+    const code = await runDetachedTask(runId);
+    process.exit(code);
+});
 // Default action: if no subcommand given, run 'start'
 const args = process.argv.slice(2);
 const firstArg = args[0];