@pi-unipi/background-tasks 2.6.1

package/README.md

@@ -0,0 +1,87 @@
+# @pi-unipi/background-tasks
+
+Background tasks for UniPi — a full adoption of
+[pi-background-tasks](https://github.com/ismailsaleekh/pi-background-tasks) into the
+unipi conventions: durable background shell jobs, read-only delegated agents,
+attested Pi runs, fixed-purpose multi-model Fusion workflows, and package-owned
+Anthropic subscription attribution.
+
+## Master toggle
+
+One config key disables the entire module — no tools, no commands, no hooks, no UI:
+
+```json
+// ~/.unipi/config/background-tasks.json (global)
+// <workspace>/.unipi/config/background-tasks.json (override; workspace wins)
+{
+  "enabled": true
+}
+```
+
+Open `/unipi:bg-settings` for the interactive settings overlay (master toggle,
+defaults, output caps, delegate/fusion defaults).
+
+## Surfaces
+
+### Tools (reference names kept)
+
+| Tool | Purpose |
+| --- | --- |
+| `bg_run` | Start a named long-running shell command; terminal notification wakes a follow-up turn by default |
+| `bg_status` / `bg_logs` / `bg_kill` | Point-in-time inspection, bounded log reads, stop — never polling primitives |
+| `bg_delegate` + `bg_result` | One read-only child Pi agent seeded with a frozen projection of this conversation; hash-verified answer retrieval |
+| `bg_run_pi_attested` | Evidence-oriented direct Pi spawn with local hashes and route attestation |
+| `fusion_reason` | 3 candidates → blind evaluator → merger on the session projection |
+| `fusion_investigate` / `fusion_research` / `fusion_validate` | Fixed-purpose multi-model workflows on clean-task input (inspect tools / caller-URL research / advisory review) |
+
+### Commands (our namespace)
+
+`/unipi:bg`, `/unipi:bg-clear`, `/unipi:bg-tasks`, `/unipi:bg-update`,
+`/unipi:tasks`, `/unipi:jobs`, `/unipi:kill`, `/unipi:logs`,
+`/unipi:bg-settings`, `/unipi:fusion`, `/unipi:fusion-models`,
+`/unipi:claude-cache`.
+
+Shortcuts: `Shift↓` opens the task manager dock; `Ctrl+Alt+C` clears finished notices.
+
+## Storage layout (ours — never `.pi/`)
+
+- Runtime artifacts (task output/metadata): `$TMPDIR/unipi-bg-tasks/<session>-<pid>-<nonce>/`
+- Durable delegate artifacts: `<workspace>/.unipi/delegate/<session>-<pid>/<task-id>/`
+- Durable fusion artifacts: `<workspace>/.unipi/fusion/<session>-<pid>/<run-id>/`
+- Config: `~/.unipi/config/background-tasks.json` + workspace override
+- Fusion model config: five-slot selector persisted through `/unipi:fusion-models`
+
+## Environment
+
+`UNIPI_BG_*` prefix (replaces the reference `PI_BG_*`):
+`UNIPI_BG_TMP_DIR`, `UNIPI_BG_MAX_OUTPUT_BYTES`, `UNIPI_BG_SHELL`,
+`UNIPI_BG_SHELL_PATH`, `UNIPI_BG_DISABLE_PI_TELEMETRY`, `UNIPI_BG_DELEGATE_*`.
+
+## Completion delivery
+
+| `notifyOnCompletion` | `triggerOnCompletion` | Mode |
+| --- | --- | --- |
+| true (default) | true (bg_run default) | Durable terminal notification + automatic follow-up turn |
+| true | false (`/unipi:bg` default) | Notification only |
+| false | — | Manual monitoring |
+
+Treat `<background-task-notification>` as durable terminal truth — do not poll.
+
+## Attribution
+
+`extensions/anthropic-attribution.ts` loads first (provider-gated): Claude Code
+subscription OAuth attribution, exact-match system-prompt sanitization, and
+cache-retention policy for Anthropic routes. Duplicate installed copies resolve
+ownership through an EventBus claim; later copies go inert.
+
+## Differences from the reference
+
+- Commands live in the `/unipi:*` namespace; env prefix is `UNIPI_BG_*`.
+- Runtime artifacts under the OS temp root (per-registry nonce) and durable
+  delegate/fusion artifacts under workspace `.unipi/` — never `.pi/`.
+- The reference's `update-check` footer surface is dropped (unipi's updater
+  module owns updates).
+- `agent_settled` / `before_provider_headers` hooks register defensively on our
+  pi SDK with an `agent_end` settlement fallback.
+
+ISC-licensed reference: Copyright Ismail <ismailsalikhodjaev@gmail.com>.

package/extensions/anthropic-attribution.ts

@@ -0,0 +1 @@
+export { default } from '../src/anthropic-attribution.js';

package/extensions/delegate-child.ts

@@ -0,0 +1 @@
+export { default } from '../src/delegate-child-extension.js';

package/extensions/fusion-child.ts

@@ -0,0 +1 @@
+export { default } from '../src/fusion-child-extension.js';

package/package.json

@@ -0,0 +1,40 @@
+{
+  "name": "@pi-unipi/background-tasks",
+  "version": "2.6.1",
+  "description": "Background tasks for UniPi \u2014 durable shell jobs, delegated agents, attested Pi runs, and fixed-purpose Fusion workflows",
+  "type": "module",
+  "main": "src/index.ts",
+  "types": "src/index.ts",
+  "scripts": {
+    "test": "npx tsx --test src/__tests__/*.test.ts"
+  },
+  "dependencies": {
+    "@earendil-works/pi-ai": "^0.80.0",
+    "@pi-unipi/core": "2.6.1",
+    "turndown": "^7.2.4"
+  },
+  "devDependencies": {
+    "@types/turndown": "^5.0.6",
+    "typescript": "^5.8.3"
+  },
+  "peerDependencies": {
+    "@earendil-works/pi-coding-agent": "^0.80.0",
+    "@earendil-works/pi-tui": "^0.80.0",
+    "typebox": "^1.1.38"
+  },
+  "files": [
+    "src/**/*.ts",
+    "src/**/*.json",
+    "extensions/*.ts",
+    "README.md"
+  ],
+  "pi": {
+    "extensions": [
+      "./extensions/anthropic-attribution.ts",
+      "./src/index.ts"
+    ],
+    "skills": [],
+    "prompts": [],
+    "themes": []
+  }
+}

package/src/__tests__/anthropic-attribution.test.ts

@@ -0,0 +1,195 @@
+import assert from 'node:assert/strict';
+import { describe, it } from 'node:test';
+import spawnAnthropicAttribution, {
+  ANTHROPIC_ATTRIBUTION_CLAIM_CHANNEL,
+  rewriteAnthropicRequestPayload,
+  type PiExtensionHost,
+  type PiContextLike,
+} from '../anthropic-attribution.js';
+import { isJsonObject } from '../types.js';
+import { buildAttestedPiArgv } from '../attested-pi-run.js';
+
+const BAD_SYSTEM_LINES = [
+  '- When asked about: extensions (docs/extensions.md, examples/extensions/), themes (docs/themes.md), skills (docs/skills.md), prompt templates (docs/prompt-templates.md), TUI components (docs/tui.md), keybindings (docs/keybindings.md), SDK integrations (docs/sdk.md), custom providers (docs/custom-provider.md), adding models (docs/models.md), pi packages (docs/packages.md)',
+  '- When asked about: extensions (docs/extensions.md, examples/extensions/), themes (docs/themes.md), skills (docs/skills.md), prompt templates (docs/prompt-templates.md), TUI components (docs/tui.md), keybindings (docs/keybindings.md), SDK integrations (docs/sdk.md), custom providers (docs/custom-provider.md), adding models (docs/models.md), pi packages (docs/packages.md), environment variables (docs/environment-variables.md)',
+  '- When working on pi topics, read the docs and examples, and follow .md cross-references before implementing',
+] as const;
+
+function context(provider = 'anthropic'): PiContextLike {
+  return {
+    model: {
+      provider,
+      id: provider === 'anthropic' ? 'claude-sonnet-4-5' : 'gpt-5.5',
+      maxTokens: 64_000,
+      reasoning: true,
+    },
+    sessionManager: {
+      getSessionId: () => '11111111-2222-4333-8444-555555555555',
+      getBranch: () => [],
+    },
+  };
+}
+
+class SynchronousTestBus {
+  private readonly handlers = new Map<string, Array<(data: unknown) => void>>();
+
+  emit(channel: string, data: unknown): void {
+    for (const handler of this.handlers.get(channel) ?? []) handler(data);
+  }
+
+  on(channel: string, handler: (data: unknown) => void): () => void {
+    const handlers = this.handlers.get(channel) ?? [];
+    handlers.push(handler);
+    this.handlers.set(channel, handlers);
+    return () => {
+      this.handlers.set(
+        channel,
+        (this.handlers.get(channel) ?? []).filter((candidate) => candidate !== handler),
+      );
+    };
+  }
+
+  listenerCount(channel: string): number {
+    return this.handlers.get(channel)?.length ?? 0;
+  }
+}
+
+function recordingHost(bus: SynchronousTestBus): {
+  host: PiExtensionHost;
+  registrations: { commands: number; handlers: number; providers: number; entries: number };
+} {
+  const registrations = { commands: 0, handlers: 0, providers: 0, entries: 0 };
+  const on: PiExtensionHost['on'] = () => {
+    registrations.handlers += 1;
+  };
+  return {
+    host: {
+      events: bus,
+      on,
+      registerCommand: () => {
+        registrations.commands += 1;
+      },
+      registerProvider: () => {
+        registrations.providers += 1;
+      },
+      appendEntry: () => {
+        registrations.entries += 1;
+      },
+    },
+    registrations,
+  };
+}
+
+void describe('global Anthropic attribution extension', () => {
+  void it('matches all SPS exact-line variants while preserving unrelated blocks and cache controls', () => {
+    const original = {
+      model: 'claude-sonnet-4-5',
+      max_tokens: 64_000,
+      system: [
+        {
+          type: 'text',
+          text: ['keep before', ...BAD_SYSTEM_LINES, 'keep after'].join('\n'),
+          cache_control: { type: 'ephemeral', ttl: '1h' },
+          custom_field: 'preserved',
+        },
+        { type: 'custom', payload: 'unchanged' },
+      ],
+      messages: [{ role: 'user', content: 'hello' }],
+    };
+
+    const rewritten = rewriteAnthropicRequestPayload({
+      payload: original,
+      ctx: context(),
+      account: {
+        deviceId: 'd'.repeat(64),
+        accountUuid: 'aaaaaaaa-bbbb-4ccc-8ddd-eeeeeeeeeeee',
+      },
+    });
+    assert.ok(isJsonObject(rewritten));
+    const system: unknown = rewritten['system'];
+    assert.ok(Array.isArray(system));
+    const retained = system.find(
+      (block) => isJsonObject(block) && block['custom_field'] === 'preserved',
+    );
+    assert.ok(isJsonObject(retained));
+    assert.equal(retained['text'], 'keep before\nkeep after');
+    assert.deepEqual(retained['cache_control'], { type: 'ephemeral', ttl: '1h' });
+    assert.equal(retained['custom_field'], 'preserved');
+    assert.deepEqual(system.at(-1), { type: 'custom', payload: 'unchanged' });
+    assert.deepEqual(original.system[0]?.cache_control, { type: 'ephemeral', ttl: '1h' });
+    for (const rejected of BAD_SYSTEM_LINES) {
+      assert.equal(JSON.stringify(rewritten).includes(rejected), false);
+    }
+  });
+
+  void it('leaves non-Anthropic payloads untouched', () => {
+    const payload = { model: 'gpt-5.5', metadata: { untouched: true } };
+    assert.equal(
+      rewriteAnthropicRequestPayload({
+        payload,
+        ctx: context('openai-codex'),
+        account: { deviceId: 'd', accountUuid: 'a' },
+      }),
+      undefined,
+    );
+    assert.deepEqual(payload, { model: 'gpt-5.5', metadata: { untouched: true } });
+  });
+
+  void it('adds package attribution to attested Anthropic argv only', () => {
+    const base = {
+      name: 'Attested child',
+      model: 'model',
+      prompt: 'write report.md',
+      reportPath: 'report.md',
+    };
+    assert.deepEqual(
+      buildAttestedPiArgv(
+        { ...base, provider: 'anthropic' },
+        '/pkg/extensions/anthropic-attribution.ts',
+      ),
+      [
+        'pi',
+        '--mode',
+        'json',
+        '--provider',
+        'anthropic',
+        '--model',
+        'model',
+        '--extension',
+        '/pkg/extensions/anthropic-attribution.ts',
+        'write report.md',
+      ],
+    );
+    assert.deepEqual(buildAttestedPiArgv({ ...base, provider: 'openai-codex' }), [
+      'pi',
+      '--mode',
+      'json',
+      '--provider',
+      'openai-codex',
+      '--model',
+      'model',
+      'write report.md',
+    ]);
+    assert.throws(
+      () => buildAttestedPiArgv({ ...base, provider: 'anthropic' }),
+      /require the package attribution extension/,
+    );
+  });
+
+  void it('allows exactly one independently loaded copy to own global registration', () => {
+    const bus = new SynchronousTestBus();
+    const first = recordingHost(bus);
+    const second = recordingHost(bus);
+
+    spawnAnthropicAttribution(first.host);
+    spawnAnthropicAttribution(second.host);
+
+    assert.equal(first.registrations.commands, 1);
+    assert.equal(first.registrations.handlers, 4);
+    assert.equal(first.registrations.providers, 1);
+    assert.equal(second.registrations.commands, 0);
+    assert.equal(second.registrations.handlers, 0);
+    assert.equal(second.registrations.providers, 0);
+    assert.equal(bus.listenerCount(ANTHROPIC_ATTRIBUTION_CLAIM_CHANNEL), 1);
+  });
+});

package/src/__tests__/config.test.ts

@@ -0,0 +1,137 @@
+/**
+ * Config layering + validation tests for @pi-unipi/background-tasks.
+ * Adapted from reference config/operations specs to OUR paths and layering.
+ */
+
+import test from "node:test";
+import assert from "node:assert/strict";
+import { mkdtempSync, mkdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { homedir, tmpdir } from "node:os";
+import { join } from "node:path";
+import {
+  DEFAULT_CONFIG,
+  loadBackgroundTasksConfig,
+  validateBackgroundTasksConfig,
+} from "../config.js";
+
+/** Run loadBackgroundTasksConfig with HOME pointed at a temp dir. */
+function withTempHome<T>(fn: (home: string, cwd: string) => T): T {
+  const home = mkdtempSync(join(tmpdir(), "unipi-bg-cfg-home-"));
+  const cwd = mkdtempSync(join(tmpdir(), "unipi-bg-cfg-ws-"));
+  const realHome = process.env.HOME;
+  const realUserProfile = process.env.USERPROFILE;
+  process.env.HOME = home;
+  process.env.USERPROFILE = home;
+  try {
+    return fn(home, cwd);
+  } finally {
+    if (realHome === undefined) delete process.env.HOME;
+    else process.env.HOME = realHome;
+    if (realUserProfile === undefined) delete process.env.USERPROFILE;
+    else process.env.USERPROFILE = realUserProfile;
+    rmSync(home, { recursive: true, force: true });
+    rmSync(cwd, { recursive: true, force: true });
+  }
+}
+
+test("defaults: enabled true, notify+wake on, 20MiB cap", () => {
+  assert.equal(DEFAULT_CONFIG.enabled, true);
+  assert.equal(DEFAULT_CONFIG.notifyOnCompletion, true);
+  assert.equal(DEFAULT_CONFIG.triggerOnCompletion, true);
+  assert.equal(DEFAULT_CONFIG.maxOutputBytes, 20 * 1024 * 1024);
+  assert.equal(DEFAULT_CONFIG.delegate.extensionMode, "isolated");
+});
+
+test("first run creates the global config file", () => {
+  withTempHome((home) => {
+    const { config } = loadBackgroundTasksConfig("");
+    assert.equal(config.enabled, true);
+    const written = JSON.parse(readFileSync(join(home, ".unipi", "config", "background-tasks.json"), "utf-8"));
+    assert.equal(written.enabled, true);
+  });
+});
+
+test("workspace config wins over global", () => {
+  withTempHome((home, cwd) => {
+    const globalPath = join(home, ".unipi", "config", "background-tasks.json");
+    mkdirSync(join(globalPath, ".."), { recursive: true });
+    writeFileSync(globalPath, JSON.stringify({ maxFinishedTasks: 10 }));
+    const wsPath = join(cwd, ".unipi", "config", "background-tasks.json");
+    mkdirSync(join(wsPath, ".."), { recursive: true });
+    writeFileSync(wsPath, JSON.stringify({ maxFinishedTasks: 7, triggerOnCompletion: false }));
+
+    const { config } = loadBackgroundTasksConfig(cwd);
+    assert.equal(config.maxFinishedTasks, 7);
+    assert.equal(config.triggerOnCompletion, false);
+    assert.equal(config.enabled, true); // untouched default
+  });
+});
+
+test("corrupt layers are skipped with warnings, not crashes", () => {
+  withTempHome((home, cwd) => {
+    const globalPath = join(home, ".unipi", "config", "background-tasks.json");
+    mkdirSync(join(globalPath, ".."), { recursive: true });
+    writeFileSync(globalPath, "{not json");
+    const wsPath = join(cwd, ".unipi", "config", "background-tasks.json");
+    mkdirSync(join(wsPath, ".."), { recursive: true });
+    writeFileSync(wsPath, "[1,2,3]");
+
+    const { config, warnings } = loadBackgroundTasksConfig(cwd);
+    assert.equal(config.enabled, true);
+    assert.equal(config.maxFinishedTasks, DEFAULT_CONFIG.maxFinishedTasks);
+    assert.ok(warnings.length >= 1);
+  });
+});
+
+test("validation rejects bad values with visible messages", () => {
+  const problems = validateBackgroundTasksConfig({
+    enabled: "yes",
+    maxOutputBytes: 10,
+    delegate: { extensionMode: "wild" },
+    fusion: { candidates: ["a"] },
+  });
+  assert.ok(problems.some((p) => p.includes("enabled")));
+  assert.ok(problems.some((p) => p.includes("maxOutputBytes")));
+  assert.ok(problems.some((p) => p.includes("extensionMode")));
+  assert.ok(problems.some((p) => p.includes("candidates")));
+});
+
+test("validation accepts a full valid config", () => {
+  const problems = validateBackgroundTasksConfig({
+    enabled: false,
+    notifyOnCompletion: false,
+    triggerOnCompletion: false,
+    defaultTimeoutSeconds: 600,
+    maxFinishedTasks: 5,
+    maxOutputBytes: 1024 * 1024,
+    delegate: { extensionMode: "ambient", autoDeliver: "always", maxTurns: 10, maxToolCalls: 20, timeoutSeconds: 60 },
+    fusion: { candidates: ["m1", "m2", "m3"], evaluator: "e", merger: "g" },
+  });
+  assert.deepEqual(problems, []);
+});
+
+test("invalid values sanitize to defaults instead of crashing the loader", () => {
+  withTempHome((home) => {
+    const globalPath = join(home, ".unipi", "config", "background-tasks.json");
+    mkdirSync(join(globalPath, ".."), { recursive: true });
+    writeFileSync(
+      globalPath,
+      JSON.stringify({ enabled: "nope", maxFinishedTasks: -1, delegate: { extensionMode: "wild" } }),
+    );
+    const { config, warnings } = loadBackgroundTasksConfig("");
+    assert.equal(config.enabled, true);
+    assert.equal(config.maxFinishedTasks, DEFAULT_CONFIG.maxFinishedTasks);
+    assert.equal(config.delegate.extensionMode, "isolated");
+    assert.ok(warnings.length >= 1);
+  });
+});
+
+test("master toggle off is preserved through load", () => {
+  withTempHome((home) => {
+    const globalPath = join(home, ".unipi", "config", "background-tasks.json");
+    mkdirSync(join(globalPath, ".."), { recursive: true });
+    writeFileSync(globalPath, JSON.stringify({ enabled: false }));
+    const { config } = loadBackgroundTasksConfig("");
+    assert.equal(config.enabled, false);
+  });
+});