@blockrun/franklin 3.9.6 → 3.10.1

package/dist/tasks/store.js

@@ -0,0 +1,124 @@
+/**
+ * Task persistence: meta.json (single record) + events.jsonl (append-only log).
+ *
+ * Concurrency contract: applyEvent does a read-modify-write on meta.json. It
+ * is safe to call from a single writer per task — by convention, that writer
+ * is the _task-runner subprocess. CLI commands that need to influence a
+ * running task (e.g. `franklin task cancel`) MUST signal the runner pid
+ * (SIGTERM) rather than calling applyEvent directly, otherwise the two
+ * writers race and one update is silently lost. Lost-task reconciliation
+ * is an exception — it runs only when the runner is provably dead, so
+ * there is no second writer to race with.
+ *
+ * Atomicity: writeTaskMeta uses tmp + rename; readers see either old or new
+ * meta, never partial. appendTaskEvent relies on POSIX O_APPEND + PIPE_BUF
+ * atomicity (~4096 bytes); summaries should stay short. readTaskEvents is
+ * tolerant of a torn last line.
+ */
+import fs from 'node:fs';
+import { ensureTaskDir, taskMetaPath, taskEventsPath, getTasksDir, } from './paths.js';
+export function writeTaskMeta(record) {
+    ensureTaskDir(record.runId);
+    const target = taskMetaPath(record.runId);
+    const tmp = `${target}.tmp`;
+    fs.writeFileSync(tmp, JSON.stringify(record, null, 2));
+    try {
+        fs.renameSync(tmp, target);
+    }
+    catch (err) {
+        try {
+            fs.unlinkSync(tmp);
+        }
+        catch { /* may not exist */ }
+        throw err;
+    }
+}
+export function readTaskMeta(runId) {
+    let raw;
+    try {
+        raw = fs.readFileSync(taskMetaPath(runId), 'utf-8');
+    }
+    catch (err) {
+        if (err.code === 'ENOENT')
+            return null;
+        // Surface unexpected I/O errors instead of pretending the task doesn't exist.
+        throw err;
+    }
+    try {
+        return JSON.parse(raw);
+    }
+    catch (err) {
+        process.stderr.write(`[franklin] meta.json corrupt for ${runId}: ${err.message}\n`);
+        return null;
+    }
+}
+export function appendTaskEvent(runId, event) {
+    ensureTaskDir(runId);
+    fs.appendFileSync(taskEventsPath(runId), JSON.stringify(event) + '\n');
+}
+export function readTaskEvents(runId) {
+    let raw;
+    try {
+        raw = fs.readFileSync(taskEventsPath(runId), 'utf-8');
+    }
+    catch (err) {
+        if (err.code === 'ENOENT')
+            return [];
+        throw err;
+    }
+    // Per-line tolerance: a torn last line (concurrent appendFileSync over PIPE_BUF)
+    // would otherwise discard the whole log. Mirror storage.ts:loadSessionHistory.
+    const out = [];
+    for (const line of raw.split('\n')) {
+        if (!line.trim())
+            continue;
+        try {
+            out.push(JSON.parse(line));
+        }
+        catch { /* skip torn / corrupt line */ }
+    }
+    return out;
+}
+export function applyEvent(runId, event) {
+    const cur = readTaskMeta(runId);
+    if (!cur)
+        throw new Error(`applyEvent: no task ${runId}`);
+    const next = { ...cur };
+    next.lastEventAt = event.at;
+    if (event.summary !== undefined)
+        next.progressSummary = event.summary;
+    if (event.kind === 'running' && next.status === 'queued') {
+        next.status = 'running';
+        next.startedAt = event.at;
+    }
+    else if (event.kind !== 'progress' && event.kind !== 'running') {
+        // event.kind is now narrowed to terminal statuses
+        next.status = event.kind;
+        next.endedAt = event.at;
+        if (event.summary !== undefined)
+            next.terminalSummary = event.summary;
+    }
+    appendTaskEvent(runId, event);
+    writeTaskMeta(next);
+    return next;
+}
+export function listTasks() {
+    let entries;
+    try {
+        entries = fs.readdirSync(getTasksDir(), { withFileTypes: true });
+    }
+    catch {
+        return [];
+    }
+    const out = [];
+    for (const ent of entries) {
+        // Skip junk like .DS_Store — only real per-task subdirectories are valid.
+        if (!ent.isDirectory())
+            continue;
+        const meta = readTaskMeta(ent.name);
+        if (meta)
+            out.push(meta);
+    }
+    out.sort((a, b) => b.createdAt - a.createdAt);
+    return out;
+}

package/dist/tasks/types.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Task subsystem types. Mirrors openclaw/openclaw src/tasks/task-registry.types.ts
+ * with channel/delivery fields stripped — Franklin is CLI-first single-user.
+ */
+export type TaskStatus = 'queued' | 'running' | 'succeeded' | 'failed' | 'timed_out' | 'cancelled' | 'lost';
+export type TaskRuntime = 'detached-bash';
+export type TaskTerminalOutcome = 'succeeded' | 'blocked';
+export type TaskEventKind = Exclude<TaskStatus, 'queued'> | 'progress';
+export interface TaskEventRecord {
+    at: number;
+    kind: TaskEventKind;
+    summary?: string;
+}
+export interface TaskRecord {
+    runId: string;
+    runtime: TaskRuntime;
+    label: string;
+    command: string;
+    workingDir: string;
+    pid?: number;
+    status: TaskStatus;
+    createdAt: number;
+    startedAt?: number;
+    endedAt?: number;
+    lastEventAt?: number;
+    exitCode?: number;
+    error?: string;
+    progressSummary?: string;
+    terminalSummary?: string;
+    terminalOutcome?: TaskTerminalOutcome;
+}
+export declare function isTerminalTaskStatus(s: TaskStatus): boolean;

package/dist/tasks/types.js

@@ -0,0 +1,14 @@
+/**
+ * Task subsystem types. Mirrors openclaw/openclaw src/tasks/task-registry.types.ts
+ * with channel/delivery fields stripped — Franklin is CLI-first single-user.
+ */
+const TERMINAL = new Set([
+    'succeeded',
+    'failed',
+    'timed_out',
+    'cancelled',
+    'lost',
+]);
+export function isTerminalTaskStatus(s) {
+    return TERMINAL.has(s);
+}

package/dist/tools/detach.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Detach capability — start a detached background Bash command.
+ *
+ * Returns immediately with a runId. The command continues even if Franklin
+ * exits or the user closes their terminal. Manage running tasks with
+ * `franklin task list / tail / wait / cancel`.
+ */
+import type { CapabilityHandler } from '../agent/types.js';
+export declare const detachCapability: CapabilityHandler;

package/dist/tools/detach.js

@@ -0,0 +1,53 @@
+/**
+ * Detach capability — start a detached background Bash command.
+ *
+ * Returns immediately with a runId. The command continues even if Franklin
+ * exits or the user closes their terminal. Manage running tasks with
+ * `franklin task list / tail / wait / cancel`.
+ */
+import { startDetachedTask } from '../tasks/spawn.js';
+async function execute(input, ctx) {
+    const { label, command } = input;
+    if (typeof label !== 'string' || label.length === 0) {
+        return { output: 'Error: label is required (non-empty string)', isError: true };
+    }
+    if (typeof command !== 'string' || command.length === 0) {
+        return { output: 'Error: command is required (non-empty string)', isError: true };
+    }
+    const runId = startDetachedTask({ label, command, workingDir: ctx.workingDir });
+    return {
+        output: `Detached task started.\n` +
+            `runId: ${runId}\n` +
+            `label: ${label}\n` +
+            `command: ${command}\n\n` +
+            `Inspect with:\n` +
+            `  franklin task tail ${runId} --follow\n` +
+            `  franklin task wait ${runId}\n` +
+            `  franklin task cancel ${runId}\n`,
+    };
+}
+export const detachCapability = {
+    spec: {
+        name: 'Detach',
+        description: "Run a Bash command as a detached background job. Returns immediately " +
+            "with a runId. The command continues even if Franklin exits or the user " +
+            "closes their terminal. Use this for any iteration over more than ~20 " +
+            "items, large data fetches, paginated API loops, or anything you'd " +
+            "otherwise loop on turn-by-turn (which would burn turns and trip " +
+            "timeouts). The agent's job is to design and orchestrate, not to be " +
+            "the for-loop. Pair with a script that writes a checkpoint file so " +
+            "progress survives restarts. Tail logs with `franklin task tail " +
+            "<runId> --follow` and check completion with `franklin task wait " +
+            "<runId>`.",
+        input_schema: {
+            type: 'object',
+            properties: {
+                label: { type: 'string', description: 'Short human-readable label, e.g. "scrape stargazers"' },
+                command: { type: 'string', description: 'Bash command to run. Will be executed via `bash -lc`.' },
+            },
+            required: ['label', 'command'],
+        },
+    },
+    execute,
+    concurrent: true,
+};

package/dist/tools/index.d.ts

@@ -11,6 +11,7 @@ import { grepCapability } from './grep.js';
 import { webFetchCapability } from './webfetch.js';
 import { webSearchCapability } from './websearch.js';
 import { taskCapability } from './task.js';
+import { detachCapability } from './detach.js';
 /**
  * Reset module-level tool state that would otherwise leak between sessions
  * when the same process runs `interactiveSession()` more than once (library
@@ -19,5 +20,5 @@ import { taskCapability } from './task.js';
 export declare function resetToolSessionState(): void;
 /** All capabilities available to the Franklin agent (excluding sub-agent, which needs config). */
 export declare const allCapabilities: CapabilityHandler[];
-export { readCapability, writeCapability, editCapability, bashCapability, globCapability, grepCapability, webFetchCapability, webSearchCapability, taskCapability, };
+export { readCapability, writeCapability, editCapability, bashCapability, globCapability, grepCapability, webFetchCapability, webSearchCapability, taskCapability, detachCapability, };
 export { createSubAgentCapability } from './subagent.js';

package/dist/tools/index.js

@@ -12,6 +12,7 @@ import { grepCapability } from './grep.js';
 import { webFetchCapability, clearSessionState as clearWebFetchSessionState } from './webfetch.js';
 import { webSearchCapability } from './websearch.js';
 import { taskCapability } from './task.js';
+import { detachCapability } from './detach.js';
 import { createImageGenCapability } from './imagegen.js';
 import { createVideoGenCapability } from './videogen.js';
 import { createMusicGenCapability } from './musicgen.js';
@@ -125,6 +126,7 @@ export const allCapabilities = [
     webFetchCapability,
     webSearchCapability,
     taskCapability,
+    detachCapability,
     defaultImageGenCapability,
     defaultVideoGenCapability,
     defaultMusicGenCapability,
@@ -143,5 +145,5 @@ export const allCapabilities = [
     webhookPostCapability,
     walletCapability,
 ];
-export { readCapability, writeCapability, editCapability, bashCapability, globCapability, grepCapability, webFetchCapability, webSearchCapability, taskCapability, };
+export { readCapability, writeCapability, editCapability, bashCapability, globCapability, grepCapability, webFetchCapability, webSearchCapability, taskCapability, detachCapability, };
 export { createSubAgentCapability } from './subagent.js';

package/dist/tools/tool-categories.js

@@ -23,6 +23,10 @@ export const CORE_TOOL_NAMES = new Set([
     'Edit',
     // Shell execution — needed for running tests, builds, scripts.
     'Bash',
+    // Detached background execution — bash-adjacent: spawns a long-running
+    // command that survives Franklin exiting. Belongs in core so the agent
+    // can offload >20-item iteration without first activating a meta-tool.
+    'Detach',
     // Search — code exploration is table stakes.
     'Grep',
     'Glob',

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@blockrun/franklin",
-  "version": "3.9.6",
+  "version": "3.10.1",
   "description": "Franklin — The AI agent with a wallet. Spends USDC autonomously to get real work done. Pay per action, no subscriptions.",
   "type": "module",
   "exports": {