@skydiveai/pi-extensions 0.1.0-beta.1602 → 0.1.0-beta.1603

package/dist/index.mjs

@@ -2264,6 +2264,58 @@ async function postBackgroundTaskDone({ messageId, content }) {
 	} });
 	if (!res.ok) throw new Error(`bg-task-done POST failed: ${res.status}`);
 }
+async function putBackgroundTaskJournalSpec({ messageId, spec }) {
+	const client = sandboxClient();
+	if (!client) return;
+	try {
+		const res = await client["bg-task-journal"].$put({ json: {
+			messageId,
+			spec
+		} });
+		if (!res.ok) log$10.warn({
+			status: res.status,
+			taskId: spec.id,
+			event: "bg_journal_put_failed"
+		}, "bg-task journal PUT failed");
+	} catch (err) {
+		log$10.warn({
+			err,
+			taskId: spec.id,
+			event: "bg_journal_put_failed"
+		}, "bg-task journal PUT threw");
+	}
+}
+async function deleteBackgroundTaskJournalSpec({ messageId, taskId }) {
+	const client = sandboxClient();
+	if (!client) return;
+	try {
+		await client["bg-task-journal"].$delete({ json: {
+			messageId,
+			taskId
+		} });
+	} catch (err) {
+		log$10.debug({
+			err,
+			taskId,
+			event: "bg_journal_delete_failed"
+		}, "bg-task journal DELETE failed");
+	}
+}
+async function listBackgroundTaskJournalSpecs({ messageId }) {
+	const client = sandboxClient();
+	if (!client) return [];
+	try {
+		const res = await client["bg-task-journal"].$get({ query: { messageId } });
+		if (!res.ok) return [];
+		return (await res.json()).specs ?? [];
+	} catch (err) {
+		log$10.debug({
+			err,
+			event: "bg_journal_list_failed"
+		}, "bg-task journal GET failed");
+		return [];
+	}
+}
 function postBackgroundTasksSnapshot({ messageId, tasks }) {
 	const client = sandboxClient();
 	if (!client || !messageId) return;
@@ -3860,16 +3912,32 @@ const toolCallSummaryExtension = (pi) => {
 * spills to disk (/home/user/.anyone/bg-tasks/<id>.log) to avoid buffering a chatty job
 * in memory; exit code and run state live on the in-memory task.
 *
-* **No cross-restart survival (v1, deliberate).** Task state lives only in
-* the running harness process. A harness restart (crash → supervisord
-* respawn, or `platform harness reload` after the agent edits its own
-* harness) drops the map and pi's exec children are reaped with it. We don't
-* resurrect from disk because the common next-run case cold-provisions a
-* *different* sandbox anyway (warm reuse is the minority in prod), so on-disk
-* state would rarely be the box the next run lands on. The idle-completion wake
-* does cross the sandbox → platform boundary (a fresh run via `bg-task-done`),
-* but a task whose harness dies before it finishes is gone — it is not
-* resurrected, and this stays distinct from the scheduled-run (cron) system.
+* **Cross-restart survival is OPT-IN, via `bg_run({ resumable: true })`.**
+* A non-resumable task's state lives only in the running harness process: a
+* harness restart (crash → supervisord respawn, `platform harness reload`, or
+* a sandbox recycle on idle timeout / redeploy / template rebuild) drops the
+* map and pi's exec children are reaped with it, and the task is gone — the
+* right behavior for a one-shot side-effecting command, which must never
+* silently re-run.
+*
+* A RESUMABLE task additionally checkpoints its *spec* (command, cwd, labels,
+* origin messageId — not its live output/exit state) to a durable, api-side
+* journal keyed by conversation (`/sandbox/bg-task-journal`, redis). On the
+* NEXT run's `session_start` — which usually lands on a *different*,
+* cold-provisioned sandbox, which is exactly why the journal is api-side and
+* not on the sandbox disk — the harness lists the journal and relaunches any
+* spec it isn't already running, keeping the original id and prepending a
+* `<resumed-after-restart>` banner so the agent knows it re-ran from scratch,
+* not continued. The spec is dropped from the journal when the task
+* finishes/kills. Because relaunch RE-EXECUTES the command, resumable is only
+* for idempotent, long-lived work (pollers, watchers, retry loops); the tool
+* description enforces this and the default is false.
+*
+* The idle-completion wake (a task finishing while the agent is idle) crosses
+* the sandbox → platform boundary via a fresh run (`bg-task-done`) for both
+* resumable and non-resumable tasks; the journal is a separate, additive layer
+* that only handles a task whose harness dies BEFORE it finishes. This stays
+* distinct from the scheduled-run (cron) system.
 */
 const log = logger.child({ module: "background-tasks-ext" });
 const ops = createLocalBashOperations();
@@ -4148,9 +4216,9 @@ This is a background-task completion, not a message from the user. If it needs n
 			}
 			await publishSnapshotNow();
 		}
-		async function launchTask({ command, description, cwd }) {
+		async function launchTask({ command, description, cwd, resumable = false, resumedFromJournal = false, id: providedId, startedAt: providedStartedAt }) {
 			taskCounter += 1;
-			const id = `bg-${process.pid.toString(36)}-${taskCounter}`;
+			const id = providedId ?? `bg-${process.pid.toString(36)}-${taskCounter}`;
 			try {
 				await mkdir(tasksDir(), { recursive: true });
 			} catch (err) {
@@ -4166,7 +4234,7 @@ This is a background-task completion, not a message from the user. If it needs n
 					taskId: id
 				}, "bg task log write failed");
 			});
-			const startedAt = Date.now();
+			const startedAt = providedStartedAt ?? Date.now();
 			const meta = {
 				id,
 				command: stripPlatformExportsForDisplay(command),
@@ -4182,9 +4250,23 @@ This is a background-task completion, not a message from the user. If it needs n
 				controller: new AbortController(),
 				running: true,
 				exitCode: null,
-				error: null
+				error: null,
+				resumable,
+				cwd,
+				resumedFromJournal
 			};
 			tasks.set(id, meta);
+			if (resumable && messageId) putBackgroundTaskJournalSpec({
+				messageId,
+				spec: {
+					id,
+					command,
+					cwd,
+					description,
+					startedAt,
+					messageId
+				}
+			});
 			ops.exec(command, cwd, {
 				onData: (chunk) => {
 					meta.logBytes += chunk.length;
@@ -4210,6 +4292,10 @@ This is a background-task completion, not a message from the user. If it needs n
 					taskId: id,
 					exitCode: meta.exitCode
 				}, "bg task finished");
+				if (meta.resumable && meta.messageId) deleteBackgroundTaskJournalSpec({
+					messageId: meta.messageId,
+					taskId: id
+				});
 				schedulePublishSnapshot();
 				await notifyCompletion(meta);
 			});
@@ -4224,9 +4310,44 @@ This is a background-task completion, not a message from the user. If it needs n
 		function knownTaskIds() {
 			return [...tasks.values()].filter((t) => sameScope(t, scopeKey())).map((t) => t.id).join(", ") || "(none)";
 		}
+		let journalChecked = false;
+		async function rehydrateJournaledTasks() {
+			if (!messageId || journalChecked) return;
+			journalChecked = true;
+			const specs = await listBackgroundTaskJournalSpecs({ messageId });
+			if (specs.length === 0) return;
+			for (const spec of specs) {
+				const live = tasks.get(spec.id);
+				if (live && sameScope(live, scopeKey())) continue;
+				log.info({
+					taskId: spec.id,
+					conversationId
+				}, "relaunching journaled resumable bg task after restart");
+				const meta = await launchTask({
+					command: spec.command,
+					description: spec.description,
+					cwd: spec.cwd,
+					resumable: true,
+					resumedFromJournal: true,
+					id: spec.id,
+					startedAt: spec.startedAt
+				});
+				try {
+					const stream = createWriteStream(logPath(meta.id), { flags: "a" });
+					stream.write(`<resumed-after-restart>requeued and relaunched on a new sandbox after the previous one was drained; this is a fresh execution of the command from the start, not a continuation</resumed-after-restart>\n`);
+					stream.end();
+				} catch (err) {
+					log.debug({
+						err,
+						taskId: meta.id
+					}, "resume banner write failed");
+				}
+			}
+		}
 		pi.on("session_start", async () => {
-			if (tasks.size === 0) return;
+			if (tasks.size === 0 && (!messageId || journalChecked)) return;
 			await ensureConversationId();
+			await rehydrateJournaledTasks();
 			for (const [id, meta] of tasks) if (sameScope(meta, scopeKey()) && !meta.running && meta.notified) {
 				tasks.delete(id);
 				await unlink(logPath(id)).catch(() => {});
@@ -4285,24 +4406,27 @@ This is a background-task completion, not a message from the user. If it needs n
 		const bgRun = {
 			name: "bg_run",
 			label: "Run in background",
-			description: "Run a bash command in the background. Returns immediately with a task id; output streams to a log file. You are sent a message when it finishes — keep working or end your turn meanwhile. Use for anything over a couple of minutes (builds, batch jobs, retry loops, downloads). Inspect with bg_status / bg_logs, stop with bg_kill.",
-			promptSnippet: "bg_run — run a long command without blocking; you are notified on completion",
+			description: "Run a bash command in the background. Returns immediately with a task id; output streams to a log file. You are sent a message when it finishes — keep working or end your turn meanwhile. Use for anything over a couple of minutes (builds, batch jobs, retry loops, downloads). Inspect with bg_status / bg_logs, stop with bg_kill. Pass resumable:true ONLY for an idempotent, long-lived command (a poller/watcher/retry loop) that should be requeued and relaunched on your next run if the sandbox goes away before it finishes (a sandbox is drained and replaced with a fresh one, not restarted in place) — the requeue re-runs the command from scratch, so never mark a one-shot side-effecting job (a migration, an apply, a send) resumable.",
+			promptSnippet: "bg_run — run a long command without blocking; you are notified on completion (resumable:true requeues the task onto a fresh sandbox if the current one is drained, idempotent commands only)",
 			parameters: Type.Object({
 				command: Type.String({ description: "Bash command to execute" }),
-				description: Type.Optional(Type.String({ description: "Clear, concise description of what this command does in active voice (2-6 words)." }))
+				description: Type.Optional(Type.String({ description: "Clear, concise description of what this command does in active voice (2-6 words)." })),
+				resumable: Type.Optional(Type.Boolean({ description: "When true, this task is requeued and relaunched on your next run if the sandbox it is running on goes away before it finishes (a sandbox is drained and replaced with a fresh one, rather than restarted in place, so an in-flight task would otherwise be lost). Use ONLY for idempotent, long-lived commands (pollers, watchers, retry loops) — the requeue re-runs the command from scratch on the new sandbox, so never set this on a one-shot side-effecting command." }))
 			}),
 			async execute(_toolCallId, params, _signal, _onUpdate, ctx) {
 				await ensureConversationId();
-				const { command, description = null } = params;
+				const { command, description = null, resumable = false } = params;
 				const meta = await launchTask({
 					command,
 					description,
-					cwd: ctx.cwd
+					cwd: ctx.cwd,
+					resumable
 				});
+				const resumeNote = resumable && meta.messageId ? "\nResumable: if this sandbox is drained before the task finishes, it will be requeued and relaunched from the start on your next run." : resumable ? "\nNote: resumable was requested but this session has no durable conversation, so it will NOT be requeued if the sandbox is drained." : "";
 				return {
 					content: [{
 						type: "text",
-						text: `Started background task ${taskLabel(meta)}.\nlog: ${logPath(meta.id)}\nYou will get a message when it finishes. Check on it with bg_status {"taskId":"${meta.id}"}.`
+						text: `Started background task ${taskLabel(meta)}.\nlog: ${logPath(meta.id)}\nYou will get a message when it finishes. Check on it with bg_status {"taskId":"${meta.id}"}.${resumeNote}`
 					}],
 					details: {}
 				};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@skydiveai/pi-extensions",
-  "version": "0.1.0-beta.1602",
+  "version": "0.1.0-beta.1603",
   "homepage": "https://skydive.com",
   "license": "MIT",
   "author": "Create, Inc.",