@bermudi/pi-delegate 0.1.2 → 0.1.4

package/lifecycle.ts

@@ -27,6 +27,8 @@ import { resolveCwd, validateResumeFromPath } from "./utils.ts";
 import { getWholeTaskMaxRetries, getWholeTaskBaseDelayMs } from "./config.ts";
 import { addUsage, emptyUsage } from "./usage.ts";
 import { scheduleDeadline } from "./timer.ts";
+import { recordTask } from "./telemetry.ts";
+import { createScratchWorkspace, ScratchDeadlineError } from "./workspace.ts";
 
 /** Internal seam for lifecycle-level tests without replacing session ownership. */
 type RunAgentSession = typeof runAgentSession;
@@ -180,6 +182,11 @@ function updateProgressFromResult(p: TaskProgress, r: TaskResult): void {
   p.failureKind = r.failureKind;
 }
 
+const taskRetryCounts = new WeakMap<TaskResult, number>();
+/** The SQLite task id is part of the logical task, not the transient result
+ * object. Scratch wrapping clones results, so keep this alongside retry data. */
+const taskTelemetryIds = new WeakMap<TaskResult, string>();
+
 /** Apply a TaskResult to progress and notify the env (sync fires onUpdate).
  *  Used at every return point in runResolvedTask — mirrors the old fire() pattern
  *  that the duplicated sync/async bodies used after every early-return. */
@@ -187,8 +194,24 @@ function finishTask(
   env: TaskRunEnv,
   p: TaskProgress,
   r: TaskResult,
+  task: ResolvedTask,
+  retries = 0,
 ): TaskResult {
   updateProgressFromResult(p, r);
+  taskRetryCounts.set(r, retries);
+  if (env.telemetryCallId) {
+    const id = recordTask({
+      callId: env.telemetryCallId,
+      generation: env.telemetryGeneration,
+      async: env.async ?? false,
+      taskIndex: p.index,
+      task,
+      progress: p,
+      result: r,
+      retries,
+    });
+    if (id) taskTelemetryIds.set(r, id);
+  }
   env.onStatusChange?.();
   return r;
 }
@@ -479,15 +502,24 @@ async function acquireAgentSession(
   }
 
   // ── Fresh session (no resume) ────────────────────────────────────────────
-  const fresh = createSubagentSessionManager(
-    env.parentSessionManager,
-    task.cwd,
-  );
-  if (!fresh) {
-    return { error: failTask(task, "Internal: could not create session file") };
+  if (task.workspace === "scratch") {
+    // A discarded filesystem must not advertise a resumable conversation: a
+    // later resume would run against the source cwd and silently lose scratch
+    // isolation. Keep scratch transcripts in memory only.
+    sessionManager = SessionManager.inMemory(task.cwd);
+  } else {
+    const fresh = createSubagentSessionManager(
+      env.parentSessionManager,
+      task.cwd,
+    );
+    if (!fresh) {
+      return {
+        error: failTask(task, "Internal: could not create session file"),
+      };
+    }
+    sessionManager = fresh.manager;
+    sessionFile = fresh.file;
   }
-  sessionManager = fresh.manager;
-  sessionFile = fresh.file;
 
   const session = await buildDelegateSession(
     task,
@@ -549,11 +581,171 @@ async function runResolvedTaskUnlocked(
   task: ResolvedTask,
   p: TaskProgress,
   taskIndex: number,
+): Promise<TaskResult> {
+  if (task.workspace !== "scratch") {
+    return runResolvedTaskCore(env, task, p, taskIndex);
+  }
+  if (task.sessionId || task.resumeFrom || task.sessionAction) {
+    return finishTask(
+      env,
+      p,
+      failTask(
+        task,
+        "workspace 'scratch' is one-shot and cannot be combined with sessionId, resumeFrom, or sessionAction.",
+      ),
+      task,
+    );
+  }
+
+  const startedAt = Date.now();
+  const deadlineAt =
+    task.deadlineMs && task.deadlineMs > 0
+      ? startedAt + task.deadlineMs
+      : undefined;
+  let workspace: Awaited<ReturnType<typeof createScratchWorkspace>>;
+  try {
+    workspace = await createScratchWorkspace(task.cwd, env.signal, deadlineAt);
+  } catch (error) {
+    const setupError = error instanceof Error ? error.message : String(error);
+    const deadlineExceeded =
+      !env.signal?.aborted && error instanceof ScratchDeadlineError;
+    return finishTask(
+      env,
+      p,
+      {
+        ...failTask(
+          task,
+          env.signal?.aborted
+            ? "Aborted"
+            : deadlineExceeded
+              ? formatDeadlineExceededError(task.deadlineMs ?? 0)
+              : setupError,
+        ),
+        failureKind: deadlineExceeded ? "deadline_exceeded" : undefined,
+        durationMs: Date.now() - startedAt,
+      },
+      task,
+    );
+  }
+
+  const executionTask: ResolvedTask = {
+    ...task,
+    cwd: workspace.cwd,
+  };
+  let result: TaskResult | undefined;
+  let cleanupError: string | undefined;
+  let needsCorrection = false;
+  let telemetryTaskId: string | undefined;
+  let retries = 0;
+  try {
+    const preMappingResult = await runResolvedTaskCore(
+      env,
+      executionTask,
+      p,
+      taskIndex,
+      {
+        taskStartedAt: startedAt,
+        deadlineAt,
+      },
+    );
+    result = preMappingResult;
+    // Capture metadata before scratch wrapping creates a new result object.
+    // Both values belong to the logical task and must survive that clone.
+    telemetryTaskId = taskTelemetryIds.get(result);
+    retries = taskRetryCounts.get(result) ?? 0;
+    result = {
+      ...result,
+      workspace: "scratch",
+      sessionFile: undefined,
+      touchedFiles: await Promise.all(
+        result.touchedFiles.map((file) => workspace.resolveReportedPath(file)),
+      ),
+      // Writes inside scratch are discarded and cannot conflict. Explicit
+      // writes outside scratch (for example an absolute host path) persist and
+      // must remain attributable for overlap warnings. Resolve those paths
+      // physically so aliases to the same host file compare equally.
+      attributedFiles: (
+        await Promise.all(
+          (result.attributedFiles ?? []).map((file) =>
+            workspace.resolveAttributedPath(file),
+          ),
+        )
+      ).filter((file): file is string => file !== undefined),
+    };
+  } catch (error) {
+    result = {
+      ...failTask(task, error instanceof Error ? error.message : String(error)),
+      ...(result
+        ? {
+            tokens: result.tokens,
+            usage: result.usage,
+          }
+        : {}),
+      workspace: "scratch",
+      durationMs: Date.now() - startedAt,
+    };
+    // runResolvedTaskCore may already have recorded/notified a successful
+    // result before path mapping failed. Correct those observable outcomes.
+    needsCorrection = true;
+  } finally {
+    try {
+      await workspace.cleanup();
+    } catch (error) {
+      cleanupError = `Scratch workspace cleanup failed: ${error instanceof Error ? error.message : String(error)}`;
+      console.error("[delegate] scratch workspace cleanup failed", error);
+    }
+  }
+
+  if (!result) {
+    result = {
+      ...failTask(task, "Scratch task failed before producing a result."),
+      workspace: "scratch",
+      durationMs: Date.now() - startedAt,
+    };
+  }
+  if (cleanupError || needsCorrection) {
+    result = {
+      ...result,
+      error: cleanupError
+        ? result.error
+          ? `${result.error}\n${cleanupError}`
+          : cleanupError
+        : result.error,
+      durationMs: Math.max(result.durationMs, Date.now() - startedAt),
+    };
+    updateProgressFromResult(p, result);
+    if (env.telemetryCallId) {
+      // runResolvedTaskCore already recorded the pre-cleanup result. Telemetry
+      // rows are upserts, so replace it with the actual returned outcome while
+      // preserving the retry count captured by finishTask.
+      recordTask({
+        id: telemetryTaskId,
+        callId: env.telemetryCallId,
+        generation: env.telemetryGeneration,
+        async: env.async ?? false,
+        taskIndex: p.index,
+        task,
+        progress: p,
+        result,
+        retries,
+      });
+    }
+    env.onStatusChange?.();
+  }
+  return result;
+}
+
+async function runResolvedTaskCore(
+  env: TaskRunEnv,
+  task: ResolvedTask,
+  p: TaskProgress,
+  taskIndex: number,
+  timing?: { taskStartedAt: number; deadlineAt: number | undefined },
 ): Promise<TaskResult> {
   try {
     // ── Aborted before we started? ───────────────────────────────────
     if (env.signal?.aborted) {
-      return finishTask(env, p, failTask(task, "Aborted"));
+      return finishTask(env, p, failTask(task, "Aborted"), task);
     }
 
     // ── Session busy guard (defense-in-depth) ────────────────────────
@@ -563,7 +755,7 @@ async function runResolvedTaskUnlocked(
       const busyTicketId = isSessionBusy(task.sessionId);
       if (busyTicketId && busyTicketId !== env.ticketId) {
         const msg = `Session '${task.sessionId}' is already in use by ticket ${busyTicketId}. Each session can only handle one task at a time.`;
-        return finishTask(env, p, failTask(task, msg));
+        return finishTask(env, p, failTask(task, msg), task);
       }
     }
 
@@ -577,6 +769,7 @@ async function runResolvedTaskUnlocked(
           env,
           p,
           failTask(task, "sessionAction='close' requires sessionId."),
+          task,
         );
       }
       // The per-session lock for action-based operations is already held by the
@@ -593,6 +786,7 @@ async function runResolvedTaskUnlocked(
             : `Session '${task.sessionId}' not found.`,
           Date.now() - env.delegateStartedAt,
         ),
+        task,
       );
     }
 
@@ -605,17 +799,19 @@ async function runResolvedTaskUnlocked(
           `Active sessions:\n${pool.listPooledAgents().join("\n")}`,
           Date.now() - env.delegateStartedAt,
         ),
+        task,
       );
     }
 
     let hasBashExecution = false;
     let cumulativeTokens = 0;
     let cumulativeToolUses = 0;
-    const taskStartedAt = Date.now();
+    const taskStartedAt = timing?.taskStartedAt ?? Date.now();
     const deadlineAt =
-      task.deadlineMs && task.deadlineMs > 0
+      timing?.deadlineAt ??
+      (task.deadlineMs && task.deadlineMs > 0
         ? taskStartedAt + task.deadlineMs
-        : undefined;
+        : undefined);
     let accumulatedUsage = emptyUsage();
 
     const onAttemptProgress = (u: AgentProgressUpdate): void => {
@@ -821,16 +1017,22 @@ async function runResolvedTaskUnlocked(
         task,
         err instanceof Error ? err.message : String(err),
       );
-      return finishTask(env, p, {
-        ...failure,
-        durationMs: Math.max(failure.durationMs, Date.now() - taskStartedAt),
-        tokens: accumulatedUsage.totalTokens,
-        usage: accumulatedUsage,
-      });
+      return finishTask(
+        env,
+        p,
+        {
+          ...failure,
+          durationMs: Math.max(failure.durationMs, Date.now() - taskStartedAt),
+          tokens: accumulatedUsage.totalTokens,
+          usage: accumulatedUsage,
+        },
+        task,
+      );
     }
 
     const maxRetries = resolvedWholeTaskMaxRetries();
     const baseDelayMs = resolvedWholeTaskBaseDelayMs();
+    let retriesExecuted = 0;
     for (
       let retry = 0;
       retry < maxRetries && canRetryWholeTask(task, result, hasBashExecution);
@@ -864,6 +1066,7 @@ async function runResolvedTaskUnlocked(
       p.error = undefined;
       p.failureKind = undefined;
       env.onStatusChange?.();
+      retriesExecuted++;
       try {
         result = await runAttempt();
       } catch (err) {
@@ -881,12 +1084,18 @@ async function runResolvedTaskUnlocked(
       }
     }
 
-    return finishTask(env, p, {
-      ...result,
-      durationMs: Math.max(result.durationMs, Date.now() - taskStartedAt),
-      tokens: Math.max(cumulativeTokens, accumulatedUsage.totalTokens),
-      usage: accumulatedUsage,
-    });
+    return finishTask(
+      env,
+      p,
+      {
+        ...result,
+        durationMs: Math.max(result.durationMs, Date.now() - taskStartedAt),
+        tokens: Math.max(cumulativeTokens, accumulatedUsage.totalTokens),
+        usage: accumulatedUsage,
+      },
+      task,
+      retriesExecuted,
+    );
   } catch (err) {
     // Any acquired session is released by runAttempt's finally before an
     // exception reaches this boundary. This outer catch handles unexpected
@@ -896,6 +1105,7 @@ async function runResolvedTaskUnlocked(
       env,
       p,
       failTask(task, err instanceof Error ? err.message : String(err)),
+      task,
     );
   }
 }

package/manual.ts

@@ -185,8 +185,9 @@ export function getSubagentManualMarkdown(
     "```",
     "",
     '- `delegate({ ticketAction: "poll" })` \u2014 list all tickets',
-    '- `delegate({ ticketAction: "poll", ticket: "abc123" })` \u2014 check one ticket',
-    '- `delegate({ ticketAction: "wait", ticket: "abc123", timeoutMs: 600000 })` \u2014 block until finished or timeout',
+    '- `delegate({ ticketAction: "poll", ticket: "abc123" })` \u2014 take one progress snapshot',
+    '- `delegate({ ticketAction: "wait", ticket: "abc123" })` \u2014 block until finished; omit `timeoutMs` when the result is needed this turn',
+    '- `delegate({ ticketAction: "wait", ticket: "abc123", timeoutMs: 600000 })` \u2014 bounded wait; timeout includes the latest snapshot, so do not poll afterward',
     '- `delegate({ ticketAction: "cancel", ticket: "abc123" })` \u2014 preview activity and partial effects before cancelling',
     '- `delegate({ ticketAction: "cancel", ticket: "abc123", force: true })` \u2014 abort after review',
     "",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bermudi/pi-delegate",
-  "version": "0.1.2",
+  "version": "0.1.4",
   "description": "Delegate tool for the Pi coding agent.",
   "keywords": [
     "pi-package"

package/schema.ts

@@ -103,6 +103,13 @@ export const delegateTaskSchema = Type.Object({
         "Wall-clock budget (ms) from run start after queueing. Cooperative abort; side effects remain. Omit disables.",
     }),
   ),
+  workspace: Type.Optional(
+    StringEnum(["shared", "scratch"], {
+      description:
+        "scratch=disposable CoW project copy; relative edits are discarded. Not security isolation. Default=shared.",
+      default: "shared",
+    }),
+  ),
 });
 
 // Single source of truth for registration and generated help. The exported
@@ -139,14 +146,14 @@ export const delegateArgumentsSchema = Type.Object({
     Type.Number({
       minimum: 0,
       description:
-        "Bounds wait (ms); omit to block until settled. Timeout never cancels the ticket.",
+        "Bounds wait (ms); omit to block until settled. Timeout returns a snapshot; do not poll afterward.",
     }),
   ),
   tasks: Type.Optional(
     Type.Array(delegateTaskSchema, {
       minItems: 0,
       description:
-        "Tasks share the real filesystem and run concurrently; separate dependent/shared-file work. []=full manual.",
+        "Tasks run concurrently; shared workspaces share files. scratch uses a disposable CoW copy. []=full manual.",
     }),
   ),
 });
@@ -167,6 +174,7 @@ const TASK_FIELD_NAMES = [
   "sessionAction",
   "resumeFrom",
   "deadlineMs",
+  "workspace",
 ] as const;
 
 /** Every field a task entry may carry. Anything else is a model mistake —
@@ -317,6 +325,12 @@ export function validateDelegateOperation(
     if (typeof rawTask.deadlineMs === "number" && !(rawTask.deadlineMs > 0)) {
       return `task ${index + 1}: deadlineMs must be a positive number of milliseconds.`;
     }
+    if (
+      task.workspace === "scratch" &&
+      (task.sessionId || task.resumeFrom || sessionAction !== undefined)
+    ) {
+      return `task ${index + 1}: workspace 'scratch' is one-shot and cannot be combined with sessionId, resumeFrom, or sessionAction.`;
+    }
     if (sessionAction === "close") {
       if (!task.sessionId) {
         return `task ${index + 1}: sessionAction 'close' requires sessionId.`;

package/task-resolution.ts

@@ -208,6 +208,11 @@ export function resolveTasks(
     );
     let tools: string[] = [];
     const warnings: string[] = [];
+    if (t.workspace === "scratch") {
+      warnings.push(
+        "Scratch workspace: relative file changes run in a disposable CoW copy and are discarded.",
+      );
+    }
 
     // Prompt is required for fresh tasks. ResumeFrom provides context already.
     if (
@@ -418,6 +423,7 @@ export function resolveTasks(
       ...t,
       id: t.id,
       cwd,
+      workspace: t.workspace ?? "shared",
       systemPrompt,
       model: model!,
       tools,