pi-better-background-tasks 0.2.16 → 0.2.18

package/src/sandbox.ts

@@ -29,7 +29,15 @@ import { dirname } from "node:path";
 
 import { commandExecution } from "./process.js";
 import { baseDir } from "./registry.js";
-import { maybeBuildSandboxCommand, type SandboxSeams } from "./shared-sandbox-core.js";
+import { compileWritePolicy, maybeBuildSandboxCommand, type SandboxSeams } from "./shared-sandbox-core.js";
+
+type SandboxPermissions = {
+  projectFiles: "off" | "read" | "read-write";
+  outsideProject: "off" | "read" | "read-write";
+  storedCredentials: "off" | "read" | "read-write";
+  commands: boolean;
+  network: boolean;
+};
 import type { CommandSpec } from "./types.js";
 
 /**
@@ -70,6 +78,7 @@ export interface ForegroundSandboxPolicy {
   readonly denyWrite: readonly string[];
   /** Human-readable evidence for why `state` is what it is. */
   readonly reason: string;
+  readonly permissions?: Readonly<SandboxPermissions & { enabled: boolean }>;
 }
 
 /** The minimum `pi.events` surface this module uses. */
@@ -98,6 +107,7 @@ export type ForegroundSandboxPlan =
       readonly confined: true;
       readonly writableRoot: string;
       readonly denyWrite: readonly string[];
+      readonly permissions?: SandboxPermissions;
     };
 
 const UNCONFINED: ForegroundSandboxPlan = { confined: false };
@@ -111,7 +121,7 @@ const VALID_STATES = new Set<string>(["inactive", "enabled", "disabled", "unavai
  * sessions inside one process (and separate tests) cannot read each other's
  * policy.
  */
-const mirrors = new WeakMap<PolicyEventBus, { policy: ForegroundSandboxPolicy | undefined }>();
+const mirrors = new WeakMap<PolicyEventBus, { policy: ForegroundSandboxPolicy | undefined; error?: Error }>();
 
 function eventBusOf(pi: unknown): PolicyEventBus | undefined {
   const events = (pi as { events?: unknown } | undefined)?.events;
@@ -134,14 +144,34 @@ function readPolicy(data: unknown): ForegroundSandboxPolicy | undefined {
   const denyWrite = Array.isArray(value.denyWrite)
     ? value.denyWrite.filter((entry): entry is string => typeof entry === "string")
     : [];
+  const permissions = value.permissions === undefined ? undefined : readPermissions(value.permissions);
+  if (value.permissions !== undefined && !permissions) {
+    throw new Error("Invalid Main sandbox permission profile; update permissions in the sandbox UI.");
+  }
   return {
     state: value.state as ForegroundSandboxState,
     writableRoot,
     denyWrite: Object.freeze([...denyWrite]),
     reason: typeof value.reason === "string" ? value.reason : "No reason was published.",
+    ...(permissions ? { permissions } : {}),
   };
 }
 
+function readPermissions(value: unknown): ForegroundSandboxPolicy["permissions"] | undefined {
+  if (!value || typeof value !== "object") return undefined;
+  const p = value as Record<string, unknown>;
+  const access = (v: unknown) => v === "off" || v === "read" || v === "read-write";
+  if (typeof p.enabled !== "boolean" || typeof p.commands !== "boolean" ||
+      typeof p.network !== "boolean" || !access(p.projectFiles) ||
+      !access(p.outsideProject) || !access(p.storedCredentials)) return undefined;
+  return Object.freeze({
+    enabled: p.enabled, commands: p.commands, network: p.network,
+    projectFiles: p.projectFiles as SandboxPermissions["projectFiles"],
+    outsideProject: p.outsideProject as SandboxPermissions["outsideProject"],
+    storedCredentials: p.storedCredentials as SandboxPermissions["storedCredentials"],
+  });
+}
+
 /**
  * Start mirroring foreground policy on this session's event bus.
  *
@@ -154,11 +184,15 @@ export function observeForegroundSandboxPolicy(pi: unknown): void {
   const events = eventBusOf(pi);
   if (!events || mirrors.has(events)) return;
 
-  const mirror: { policy: ForegroundSandboxPolicy | undefined } = { policy: undefined };
+  const mirror: { policy: ForegroundSandboxPolicy | undefined; error?: Error } = { policy: undefined };
   mirrors.set(events, mirror);
   events.on(FOREGROUND_SANDBOX_POLICY_CHANNEL, (data) => {
-    const policy = readPolicy(data);
-    if (policy) mirror.policy = policy;
+    try {
+      const policy = readPolicy(data);
+      if (policy) { mirror.policy = policy; mirror.error = undefined; }
+    } catch (error) {
+      mirror.error = error as Error;
+    }
   });
   events.emit(FOREGROUND_SANDBOX_POLICY_REQUEST_CHANNEL, undefined);
 }
@@ -177,7 +211,9 @@ export function currentForegroundSandboxPolicy(pi: unknown): ForegroundSandboxPo
   const events = eventBusOf(pi);
   if (!events) return undefined;
   events.emit(FOREGROUND_SANDBOX_POLICY_REQUEST_CHANNEL, undefined);
-  return mirrors.get(events)?.policy;
+  const mirror = mirrors.get(events);
+  if (mirror?.error) throw mirror.error;
+  return mirror?.policy;
 }
 
 /**
@@ -187,8 +223,16 @@ export function currentForegroundSandboxPolicy(pi: unknown): ForegroundSandboxPo
  * Throws for every state that is neither confinable nor intentionally
  * unconfined, which keeps a blocked launch from leaving task state behind.
  */
-export function resolveForegroundSandboxPlan(pi: unknown): ForegroundSandboxPlan {
-  return planFor(currentForegroundSandboxPolicy(pi));
+export function resolveForegroundSandboxPlan(pi: unknown, remote = false): ForegroundSandboxPlan {
+  const policy = currentForegroundSandboxPolicy(pi);
+  if (remote && !policy?.permissions) return UNCONFINED; // Preserve legacy SSH behavior.
+  const plan = planFor(policy);
+  if (remote && plan.confined) {
+    throw new ForegroundSandboxBlockedError(policy!, !plan.permissions?.network
+      ? "Main profile disables network. SSH launches are blocked."
+      : "Structured SSH cannot apply local file and credential permissions yet. Use SSH through confined bash, or change Main permissions in /sandbox.");
+  }
+  return plan;
 }
 
 /** The plan for one already-read policy. Exposed for tests and reuse. */
@@ -196,11 +240,22 @@ export function planFor(policy: ForegroundSandboxPolicy | undefined): Foreground
   // No sandbox extension is publishing: this package is installed on its own and
   // keeps its historical unsandboxed behaviour.
   if (!policy) return UNCONFINED;
+  if (policy.permissions?.enabled && !policy.permissions.commands) {
+    throw new ForegroundSandboxBlockedError(policy, "Main profile disables commands. Change permissions in the sandbox UI before launching background tasks.");
+  }
   if (policy.state === "inactive" || policy.state === "disabled") return UNCONFINED;
   if (policy.state !== "enabled" || !policy.writableRoot) {
     throw new ForegroundSandboxBlockedError(policy);
   }
-  return { confined: true, writableRoot: policy.writableRoot, denyWrite: policy.denyWrite };
+  const permissions = policy.permissions?.enabled ? {
+    projectFiles: policy.permissions.projectFiles,
+    outsideProject: policy.permissions.outsideProject,
+    storedCredentials: policy.permissions.storedCredentials,
+    commands: policy.permissions.commands,
+    network: policy.permissions.network,
+  } : undefined;
+  return { confined: true, writableRoot: policy.writableRoot, denyWrite: policy.denyWrite,
+    ...(permissions ? { permissions } : {}) };
 }
 
 /**
@@ -245,16 +300,21 @@ export function confineCommandSpec(
   const controlPlane = baseDir();
   mkdirSync(controlPlane, { recursive: true });
   const denyWrite = [...plan.denyWrite, controlPlane];
+  const policy = {
+    writableRoot: plan.writableRoot,
+    denyWrite,
+    home: homedir(),
+    ...(plan.permissions ? { permissions: plan.permissions } : {}),
+  };
   let command;
   try {
+    if (plan.permissions && !("permissions" in compileWritePolicy(policy))) {
+      throw new Error("permission-aware sandbox core is unavailable; update the sandbox packages before launching");
+    }
     command = maybeBuildSandboxCommand(
       {
         profilePath,
-        policy: {
-          writableRoot: plan.writableRoot,
-          denyWrite,
-          home: homedir(),
-        },
+        policy,
         execPath,
         execArgs,
       },

package/src/shared-callback-batcher.ts

@@ -105,6 +105,7 @@ export function createCallbackBatcher(
   const pending = new Map<string, PendingEvent>();
   const inFlight = new Set<string>();
   const urgentInFlight = new Set<string>();
+  const handedOff = new Map<string, number>();
   let sequence = 0;
   let timer: ReturnType<typeof setTimeout> | undefined;
   let flushPromise: Promise<boolean> | undefined;
@@ -140,9 +141,25 @@ export function createCallbackBatcher(
     for (const [key] of snapshot) inFlight.add(key);
 
     const deliverable: Array<[string, PendingEvent]> = [];
+    let deferred = false;
     for (const item of snapshot) {
       const [key, pendingEvent] = item;
+      const priorHandoff = handedOff.get(key);
+      if (priorHandoff !== undefined) {
+        if (!invokeDelivered(pendingEvent.event, priorHandoff)) {
+          deferred = true;
+          pending.set(key, pendingEvent);
+        }
+        inFlight.delete(key);
+        continue;
+      }
       const disposition = eventDisposition(pendingEvent.event);
+      if (disposition.kind === "deferred") {
+        deferred = true;
+        pending.set(key, pendingEvent);
+        inFlight.delete(key);
+        continue;
+      }
       if (disposition.kind === "delivered") {
         inFlight.delete(key);
         continue;
@@ -156,8 +173,8 @@ export function createCallbackBatcher(
     }
 
     if (deliverable.length === 0) {
-      if (pending.size > 0) schedule(windowMs);
-      return true;
+      if (pending.size > 0) schedule(deferred ? retryMs : windowMs);
+      return !deferred;
     }
 
     try {
@@ -183,11 +200,15 @@ export function createCallbackBatcher(
 
     const deliveredAt = Date.now();
     for (const [key, item] of deliverable) {
-      invokeDelivered(item.event, deliveredAt);
+      handedOff.set(key, deliveredAt);
+      if (!invokeDelivered(item.event, deliveredAt)) {
+        deferred = true;
+        pending.set(key, item);
+      }
       inFlight.delete(key);
     }
-    if (pending.size > 0) schedule(windowMs);
-    return true;
+    if (pending.size > 0) schedule(deferred ? retryMs : windowMs);
+    return !deferred;
   };
 
   const flush = (): Promise<boolean> => {
@@ -201,7 +222,15 @@ export function createCallbackBatcher(
   const deliverUrgent = (event: UrgentCallbackEvent): boolean | Promise<boolean> => {
     const key = eventKey(event);
     if (urgentInFlight.has(key)) return false;
+    const priorHandoff = handedOff.get(key);
+    if (priorHandoff !== undefined) return invokeDelivered(event, priorHandoff);
+    const acknowledge = (): boolean => {
+      const at = Date.now();
+      handedOff.set(key, at);
+      return invokeDelivered(event, at);
+    };
     const disposition = eventDisposition(event);
+    if (disposition.kind === "deferred") return false;
     if (disposition.kind === "delivered") return true;
     if (disposition.kind === "suppressed") {
       invokeSuppressed(event, disposition.reason, Date.now());
@@ -216,16 +245,13 @@ export function createCallbackBatcher(
       );
       if (isPromiseLike(handoff)) {
         return Promise.resolve(handoff).then(
-          () => {
-            invokeDelivered(event, Date.now());
-            return true;
-          },
+          () => acknowledge(),
           () => false,
         ).finally(() => urgentInFlight.delete(key));
       }
-      invokeDelivered(event, Date.now());
+      const acknowledged = acknowledge();
       urgentInFlight.delete(key);
-      return true;
+      return acknowledged;
     } catch {
       urgentInFlight.delete(key);
       return false;
@@ -278,25 +304,25 @@ function eventKey(event: Pick<CallbackBatchEvent, "source" | "id" | "status">):
 
 function eventDisposition(
   event: Pick<CallbackBatchEvent, "isDelivered" | "getSuppressionReason">,
-): { kind: "deliver" } | { kind: "delivered" } | { kind: "suppressed"; reason: string } {
+):   | { kind: "deliver" } | { kind: "delivered" } | { kind: "deferred" } | { kind: "suppressed"; reason: string } {
   try {
     if (event.isDelivered?.()) return { kind: "delivered" };
   } catch {
-    return { kind: "suppressed", reason: "durable delivery state could not be verified" };
+    return { kind: "deferred" };
   }
   try {
     const reason = event.getSuppressionReason?.();
     return reason ? { kind: "suppressed", reason } : { kind: "deliver" };
   } catch {
-    return { kind: "suppressed", reason: "callback ownership could not be verified" };
+    return { kind: "deferred" };
   }
 }
 
 function invokeDelivered(
   event: Pick<CallbackBatchEvent, "onDelivered">,
   at: number,
-): void {
-  try { event.onDelivered?.(at); } catch { /* handoff already succeeded */ }
+): boolean {
+  try { event.onDelivered?.(at); return true; } catch { return false; }
 }
 
 function invokeSuppressed(

package/src/shared-failure-observations.ts

@@ -0,0 +1,205 @@
+// Generated from packages/failure-observations/index.ts. Do not edit directly.
+import { appendFileSync, closeSync, existsSync, openSync, readFileSync, mkdirSync } from "node:fs";
+import { dirname } from "node:path";
+import { createHash } from "node:crypto";
+
+export interface FailureEvent {
+  /** Stable source event identity: replay must reuse this id. */
+  id: string;
+  operation: string;
+  kind: "failure" | "recovered" | "incomplete" | "delivered";
+  /** Event time when known; never fabricate it from log mtime. */
+  at?: number;
+  summary?: string;
+  category?: string;
+  evidence?: string;
+  expected?: boolean;
+  /** Recovery/delivery must name the incidents it resolves/delivers. */
+  incidents?: string[];
+}
+export interface FailureObservation {
+  id: string;
+  operation: string;
+  status: "unresolved" | "expected" | "resolved";
+  category: string;
+  summary: string;
+  evidence?: string;
+  firstObservedAt: number;
+  lastObservedAt: number;
+  /** Journal order breaks timestamp ties without inventing an event time. */
+  lastSequence?: number;
+  at?: number;
+  count: number;
+  resolvedAt?: number;
+}
+export interface FailureState {
+  version: 1;
+  seen: string[];
+  observations: Record<string, FailureObservation>;
+  delivered: Record<string, number>;
+  resolved?: Record<string, number>;
+}
+export function emptyFailureState(): FailureState {
+  return { version: 1, seen: [], observations: {}, delivered: {} };
+}
+export function failureIdentity(...parts: unknown[]): string {
+  return createHash("sha256").update(JSON.stringify(parts)).digest("hex").slice(0, 32);
+}
+function text(value: string | undefined, fallback: string): string {
+  return (value || fallback).replace(/[\x00-\x1f\x7f]/g, " ").slice(0, 400);
+}
+/** Pure transition. Lifecycle is deliberately not an input or an output. */
+export function reduceFailure(state: FailureState, event: FailureEvent, observedAt: number): FailureState {
+  if (state.seen.includes(event.id)) return state;
+  const next: FailureState = { ...state, seen: [...state.seen, event.id],
+    observations: { ...state.observations }, delivered: { ...state.delivered } };
+  if (event.kind === "delivered") {
+    for (const id of event.incidents ?? []) next.delivered = { ...next.delivered, [id]: observedAt };
+    return next;
+  }
+  const key = failureIdentity(event.operation);
+  const previous = state.observations[key];
+  if (event.kind === "recovered") {
+    if (previous && event.incidents?.includes(previous.id)) {
+      next.observations[key] = { ...previous, status: "resolved", resolvedAt: event.at ?? observedAt };
+      next.resolved = { ...state.resolved, [previous.id]: event.at ?? observedAt };
+    }
+    return next;
+  }
+  const active = previous && previous.status !== "resolved" &&
+    !(previous.status === "expected" && !event.expected);
+  next.observations[key] = {
+    id: active ? previous.id : event.id, operation: event.operation,
+    status: active ? previous.status : event.expected ? "expected" : "unresolved",
+    category: event.kind === "incomplete" ? "observation-incomplete" : event.category ?? "operation",
+    summary: text(event.summary, "Operation failed"), evidence: event.evidence,
+    firstObservedAt: active ? previous.firstObservedAt : observedAt,
+    lastObservedAt: observedAt, lastSequence: next.seen.length, at: event.at,
+    count: active ? previous.count + 1 : 1,
+  };
+  return next;
+}
+export function activeFailures(state: FailureState): FailureObservation[] {
+  const priority = (x: FailureObservation) => x.status === "expected" ? 2 : x.category === "observation-incomplete" ? 0 : 1;
+  return Object.values(state.observations).filter((x) => x.status !== "resolved")
+    .sort((a, b) => priority(a) - priority(b) || (b.lastSequence ?? 0) - (a.lastSequence ?? 0) || b.lastObservedAt - a.lastObservedAt);
+}
+/** Shared priority text, placed BEFORE assistant progress on every consumer surface. */
+export function formatFailureSummary(state: FailureState): string {
+  const failures = activeFailures(state);
+  if (!failures.length) return "";
+  const rows = failures.slice(0, 5).map((x) => {
+    const label = x.status === "expected" ? "Expected failure" :
+      x.category === "observation-incomplete" ? "Observation incomplete" : "Unresolved failure";
+    const time = x.at === undefined ? `observed ${new Date(x.firstObservedAt).toISOString()}` : new Date(x.at).toISOString();
+    return `${label} · ${time} · ${x.summary}${x.count > 1 ? ` (${x.count} occurrences)` : ""}${x.evidence ? ` · evidence: ${text(x.evidence, "")}` : ""}`;
+  });
+  if (failures.length > 5) rows.push(`${failures.length - 5} additional active failure observations retained in the failure journal.`);
+  return rows.join("\n");
+}
+export function pendingFailureAttention(state: FailureState, now: number, options: { terminal?: boolean; graceMs?: number } = {}): { key: string; incidents: string[]; summary: string } | undefined {
+  const due = activeFailures(state).filter((x) => x.status === "unresolved" && !Object.hasOwn(state.delivered, x.id) &&
+    (options.terminal || x.category === "observation-incomplete" || now - x.firstObservedAt >= (options.graceMs ?? 60_000)));
+  if (!due.length) return undefined;
+  const incidents = due.map((x) => x.id).sort();
+  return { key: failureIdentity(incidents), incidents,
+    summary: due.map((x) => x.summary).join("; ").slice(0, 800) };
+}
+function storageProblem(state: FailureState, summary: string): FailureState {
+  return reduceFailure(state, { id: failureIdentity("storage", summary), operation: "failure-observation-storage",
+    kind: "incomplete", summary }, Date.now());
+}
+/** Append-only journal: individual bounded writes avoid lost read/modify/write snapshots. */
+interface PendingRecord { event: FailureEvent; observedAt: number }
+const pendingWrites = new Map<string, PendingRecord[]>();
+const knownJournals = new Map<string, number>();
+function appendRecord(path: string, record: PendingRecord): void {
+  mkdirSync(dirname(path), { recursive: true });
+  // A durable existence marker distinguishes a lost journal from a run that has
+  // never observed a failure, including after a process restart.
+  try { closeSync(openSync(`${path}.observed`, "wx", 0o600)); }
+  catch (error) { if ((error as NodeJS.ErrnoException).code !== "EEXIST") throw error; }
+  appendFileSync(path, "\n" + JSON.stringify(record) + "\n", { mode: 0o600 });
+}
+/** Retry unpersisted evidence and receipts on every observation/read. Pending
+ * receipts count as handed off in this process, preventing notification storms. */
+export function readFailureState(path: string): FailureState {
+  const pending = pendingWrites.get(path);
+  while (pending?.length) {
+    try { appendRecord(path, pending[0]!); pending.shift(); }
+    catch { break; }
+  }
+  if (!pending?.length) pendingWrites.delete(path);
+  let state = readStoredState(path);
+  const remaining = pendingWrites.get(path);
+  for (const record of remaining ?? []) state = reduceFailure(state, record.event, record.observedAt);
+  return remaining?.length ? storageProblem(state, "Failure evidence could not be persisted") : state;
+}
+function readStoredState(path: string): FailureState {
+  let source: string;
+  try { source = readFileSync(path, "utf8"); }
+  catch (error) {
+    if ((error as NodeJS.ErrnoException).code === "ENOENT" && !knownJournals.has(path) && !existsSync(`${path}.observed`)) return emptyFailureState();
+    return storageProblem(emptyFailureState(), "Failure journal could not be read");
+  }
+  const bytes = Buffer.byteLength(source);
+  const truncated = bytes < (knownJournals.get(path) ?? 0);
+  if (bytes || knownJournals.has(path)) knownJournals.set(path, bytes);
+  let state = truncated ? storageProblem(emptyFailureState(), "Failure journal was truncated; observations may be incomplete") : emptyFailureState();
+  for (const line of source.split("\n")) {
+    if (!line) continue;
+    try {
+      const row = JSON.parse(line);
+      const e = row.event;
+      if (!e || typeof e.id !== "string" || !e.id || typeof e.operation !== "string" || !e.operation ||
+          (e.expected !== undefined && typeof e.expected !== "boolean") ||
+          !["failure", "incomplete", "recovered", "delivered"].includes(e.kind) ||
+          !Number.isFinite(row.observedAt) || Math.abs(row.observedAt) > 8.64e15 ||
+          (e.at !== undefined && (!Number.isFinite(e.at) || Math.abs(e.at) > 8.64e15)) ||
+          (e.incidents !== undefined && (!Array.isArray(e.incidents) || !e.incidents.every((id: unknown) => typeof id === "string"))) ||
+          [e.summary, e.category, e.evidence].some((v) => v !== undefined && typeof v !== "string")) throw new Error("invalid record");
+      state = reduceFailure(state, e, row.observedAt);
+    } catch { state = storageProblem(state, "Failure journal contains unreadable records; observations may be incomplete"); }
+  }
+  if (truncated) {
+    const summary = "Failure journal was truncated; observations may be incomplete";
+    const record: PendingRecord = { event: { id: failureIdentity("storage", summary), operation: "failure-observation-storage", kind: "incomplete", summary }, observedAt: Date.now() };
+    try { appendRecord(path, record); }
+    catch { pendingWrites.set(path, [...(pendingWrites.get(path) ?? []), record]); }
+  }
+  return state;
+}
+export function observeFailures(path: string, events: readonly FailureEvent[], now = Date.now()): FailureState {
+  let state = readFailureState(path);
+  for (const raw of events) {
+    if (state.seen.includes(raw.id)) continue;
+    if (raw.kind === "recovered") {
+      const prior = state.observations[failureIdentity(raw.operation)];
+      if (!prior || prior.status === "resolved" || !raw.incidents?.includes(prior.id)) continue;
+    }
+    const event = { ...raw, ...(raw.summary ? { summary: text(raw.summary, "") } : {}),
+      ...(raw.evidence ? { evidence: text(raw.evidence, "") } : {}) };
+    try {
+      if (pendingWrites.has(path)) throw new Error("Earlier evidence is awaiting persistence");
+      appendRecord(path, { event, observedAt: now });
+      state = reduceFailure(state, event, now);
+    } catch {
+      const pending = pendingWrites.get(path) ?? [];
+      pending.push({ event, observedAt: now });
+      pendingWrites.set(path, pending);
+      state = storageProblem(reduceFailure(state, event, now), "Failure evidence could not be persisted");
+    }
+  }
+  return state;
+}
+export function failureAttentionHandled(state: FailureState, incidents: readonly string[]): boolean {
+  return incidents.every((id) => {
+    if (Object.hasOwn(state.delivered, id) || Object.hasOwn(state.resolved ?? {}, id)) return true;
+    const observation = Object.values(state.observations).find((item) => item.id === id);
+    if (!observation) throw new Error("Failure incident evidence is unavailable; defer notification delivery");
+    return observation.status !== "unresolved";
+  });
+}
+export function markFailureAttentionDelivered(path: string, pending: { key: string; incidents: string[] }, at = Date.now()): FailureState {
+  return observeFailures(path, [{ id: `delivered:${pending.key}`, operation: "attention-delivery", kind: "delivered", incidents: pending.incidents }], at);
+}