@pi-unipi/background-tasks 2.6.2 → 2.6.4

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@pi-unipi/background-tasks",
-  "version": "2.6.2",
-  "description": "Background tasks for UniPi \u2014 durable shell jobs, delegated agents, attested Pi runs, and fixed-purpose Fusion workflows",
+  "version": "2.6.4",
+  "description": "Background tasks for UniPi — durable shell jobs, delegated agents, attested Pi runs, and fixed-purpose Fusion workflows",
   "type": "module",
   "main": "src/index.ts",
   "types": "src/index.ts",
@@ -25,6 +25,7 @@
   "files": [
     "src/**/*.ts",
     "src/**/*.json",
+    "!src/__tests__/**",
     "extensions/*.ts",
     "README.md"
   ],

package/src/tools.ts

@@ -330,7 +330,9 @@ export function registerToolsAndCommands(options: RegisterSurfaceOptions): void
       "Use bg_run instead of bash for commands expected to run for a long time, such as test suites, dev servers, watchers, or builds.",
       "Set isAgent:true only when the background task launches an LLM/agent process; false for scripts, tests, dev servers, sleeps.",
       "Always set name to a concise 2-6 word human-readable label; do not use the raw command as the name.",
-      "After a default bg_run launch, continue only independent useful work; otherwise end the turn and wait for <background-task-notification>.",
+      "bg_run returns immediately. With notifyOnCompletion:true and triggerOnCompletion:true (both defaults), completed, failed, or killed terminal state is delivered as <background-task-notification> and automatically starts a follow-up agent turn.",
+      "After a default bg_run launch, continue only independent useful work that does not merely wait for the task; otherwise briefly acknowledge it if useful, then end the current turn. Do not call sleep, bg_status, or bg_logs merely to wait; the terminal notification will wake you.",
+      "A running result is not an instruction to poll again.",
       "Treat <background-task-notification> as durable terminal truth. Do not call bg_status to reconfirm it.",
       "Do not set notifyOnCompletion:false or triggerOnCompletion:false unless intentionally opting out.",
     ],

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

@@ -1,195 +0,0 @@
-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

@@ -1,137 +0,0 @@
-/**
- * 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);
-  });
-});