@sgtbeatdown/pi-tasks 0.1.0 → 0.1.2

package/README.md

@@ -1,502 +1,131 @@
 # pi-tasks
 
-Structured task communication for Pi agents.
-
-`pi-tasks` lets one Pi session hand work to another agent, session, process, or
-worker and get durable structured results back. The core model is transport- and
-runner-neutral: local sessions, HTTP workers, queues, hosted control planes, and
-terminal multiplexers can all implement the same task lifecycle.
-
-## what this is
-
-A task lifecycle and communication layer:
-
-1. create a structured assignment
-2. persist task state in a store
-3. dispatch the assignment through a transport
-4. let the sender keep working
-5. record status/results in structured files/data, not terminal prose
-6. require the assignee to finish through the task protocol
-
-## what this is not
-
-This is **not** a subagent spawner. Use any process manager, terminal/session
-manager, HTTP worker pool, queue, cron job, or custom runner to create/host
-agents. `pi-tasks` only gives those agents a shared task protocol.
-
-## mental model
-
-```text
-parent pi session
-  agent_task_send
-    ↓
-  TaskStore      creates task + durable refs
-  TaskTransport  delivers assignment text to target
-    ↓
-target runner/session/worker
-  receives pi.task.assignment.v1
-  does work
-  completes task through agent_task_done or equivalent store/server completion API
-    ↓
-parent pi session
-  agent_task_status / agent_task_wait / agent_task_inbox
-```
-
-The `to` field is transport-specific:
-
-- session name
-- worker id
-- queue/topic name
-- tmux pane
-- process id
-- service-specific address
-
-## requirements for any runner
-
-For task communication to work, you need exactly these pieces:
-
-1. **running target** — an already-open Pi session, worker, process, or service.
-   `pi-tasks` does not open or close it.
-2. **transport** — code that delivers the assignment text to that target. This
-   can be `tmux paste-buffer`, HTTP POST, queue publish, file write, ssh, etc.
-3. **reachable task store** — parent and target must read/write the same task
-   state. With `createFilesystemTaskStore`, that means the same cwd and shared
-   `.pi/tasks` directory. For multi-host setups without shared disk, implement a
-   remote `TaskStore`.
-4. **completion capability** — Pi targets need this extension loaded so they have
-   `agent_task_done`. Non-Pi workers need an equivalent completion API/store
-   write.
-5. **preserved task id** — the target must complete the exact `taskId` from the
-   `pi.task.assignment.v1` assignment.
-
-If those are true, session lifecycle is irrelevant. Open agents with tmux,
-screen, ssh, a process manager, or manually; `pi-tasks` only handles the task
-protocol once the agents exist.
-
-## install
-
-Install locally into Pi:
-
-```bash
-pi install npm:@sgtbeatdown/pi-tasks
-```
-
-Temporary one-off run:
-
-```bash
-pi -e npm:@sgtbeatdown/pi-tasks
-```
+`pi-tasks` is a Pi extension client for Wolfpack task transports. The retained v1 adapter uses Wolfpack's machine-global `~/.wolfpack/tasks` store; v2 keeps endpoint-owned Pi task state locally and uses Wolfpack as a content-blind relay. Neither adapter writes assignments to terminals. Read Wolfpack's [harness-neutral task adapter contract](https://github.com/almogdepaz/wolfpack/blob/main/docs/task-adapter-contract.md) for canonical adapter behavior and its [task gateway guide](https://github.com/almogdepaz/wolfpack/blob/main/docs/task-gateway.md) for routes and operations.
 
-Every participating Pi session must load this extension. If a target Pi session
-does not have `agent_task_done`, the sender can still create/dispatch the task,
-but it will remain non-terminal until timeout or cancellation.
-
-## quick start: local/custom transport
-
-Most integrations reuse the filesystem store and provide only a transport:
-
-```ts
-import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
-import { registerAgentTaskTools } from "@sgtbeatdown/pi-tasks/src/extension";
-import { createFilesystemTaskStore } from "@sgtbeatdown/pi-tasks/src/stores/filesystem";
-import type { TaskTransport } from "@sgtbeatdown/pi-tasks/src/task-communication";
-
-function createCliTransport(pi: ExtensionAPI): TaskTransport {
-  return {
-    name: "local-cli",
-    getCurrentSessionName(env) {
-      return env.PI_TASK_SESSION ?? env.USER ?? "unknown-session";
-    },
-    async dispatchTask({ target, assignment, signal }) {
-      const result = await pi.exec("my-session-send", [target, assignment], { signal });
-      if (result.code === 0) return { ok: true };
-      return {
-        ok: false,
-        message: result.stderr || result.stdout || "my-session-send failed",
-        retryable: true,
-      };
-    },
-  };
-}
+## v2 endpoint-owned relay
 
-export default function extension(pi: ExtensionAPI): void {
-  registerAgentTaskTools(pi, {
-    store: createFilesystemTaskStore({ tasksDir: ".pi/tasks" }),
-    transport: createCliTransport(pi),
-  });
-}
-```
+The default extension uses the configured local Wolfpack relay v2 adapter, never the in-memory conformance relay. It registers an opaque endpoint with `POST /api/task-relay/v2/connect`, stores endpoint-owned task state at the deterministic per-session path `~/.pi/tasks/v2/sessions/<sha256(WOLFPACK_SESSION_NAME)>/tasks.sqlite`, and exchanges opaque relay envelopes through Wolfpack. The adapter needs a Wolfpack release exposing the stable [relay v2 control-api contract](https://github.com/almogdepaz/wolfpack/blob/main/docs/control-api-schema.md#pi-tasks-relay-v2-boundary); a v1-only gateway is incompatible and does not silently fall back.
 
-Then call `agent_task_send` from the parent session:
+Set `WOLFPACK_SESSION_NAME` for every Pi process. The adapter uses `WOLFPACK_PORT` when the local control port differs from `18790`; `WOLFPACK_SESSION_NAME` resolves the active Pi process to its relay endpoint. On startup, obtain a target's opaque `{ relay, id }` endpoint from its Wolfpack session-status projection after that target has registered, then send it through the endpoint-owned tool shape:
 
 ```json
 {
-  "to": "worker-a",
-  "task": "inspect the auth middleware and report risks",
-  "timeoutMs": 1800000
+  "to": { "relay": "wolfpack-pi-tasks-v2", "id": "target-opaque-endpoint-id" },
+  "task": "implement the narrow change and run focused tests"
 }
 ```
 
-The parent should keep working and later use `agent_task_status`,
-`agent_task_wait`, or `agent_task_inbox`. Do **not** infer completion from
-terminal output.
-
-## tmux recipe: already-open pi agents
-
-Use this when you manually open Pi agents in tmux panes and only need task
-communication between them.
-
-### 1. create a tmux transport extension
-
-Create `.pi/extensions/pi-tasks-tmux.ts` in the project:
-
-```ts
-import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
-import { registerAgentTaskTools } from "@sgtbeatdown/pi-tasks/src/extension";
-import { createFilesystemTaskStore } from "@sgtbeatdown/pi-tasks/src/stores/filesystem";
-import type { TaskTransport } from "@sgtbeatdown/pi-tasks/src/task-communication";
-
-function createTmuxTransport(pi: ExtensionAPI): TaskTransport {
-  return {
-    name: "tmux",
-    getCurrentSessionName(env) {
-      return env.PI_TASK_SESSION ?? env.TMUX_PANE ?? `pid-${process.pid}`;
-    },
-    async dispatchTask({ target, assignment, task, signal }) {
-      const bufferName = `pi-task-${task.id}`;
-      const setBuffer = await pi.exec("tmux", ["set-buffer", "-b", bufferName, assignment], { signal });
-      if (setBuffer.code !== 0) {
-        return {
-          ok: false,
-          message: setBuffer.stderr || setBuffer.stdout || "tmux set-buffer failed",
-          retryable: true,
-        };
-      }
-
-      const paste = await pi.exec("tmux", ["paste-buffer", "-d", "-b", bufferName, "-t", target], { signal });
-      if (paste.code !== 0) {
-        return {
-          ok: false,
-          message: paste.stderr || paste.stdout || "tmux paste-buffer failed",
-          retryable: true,
-        };
-      }
-
-      const enter = await pi.exec("tmux", ["send-keys", "-t", target, "Enter"], { signal });
-      if (enter.code !== 0) {
-        return {
-          ok: false,
-          message: enter.stderr || enter.stdout || "tmux send-keys failed",
-          retryable: true,
-        };
-      }
-
-      return { ok: true };
-    },
-  };
-}
-
-export default function extension(pi: ExtensionAPI): void {
-  registerAgentTaskTools(pi, {
-    // All tmux panes must run in the same project cwd so they share .pi/tasks.
-    store: createFilesystemTaskStore({ tasksDir: ".pi/tasks" }),
-    transport: createTmuxTransport(pi),
-  });
-}
-```
-
-This transport does not open panes. It only pastes assignment text into an
-already-running pane and presses Enter.
+Wolfpack's relay owns durable mailbox delivery and peer forwarding; Pi owns task lifecycle, logical event order, receipts, and its local SQLite state. Insertion receipts are idempotent by `{ taskId, eventId }`, so replay after Pi has structurally recorded an event cannot create an additional logical receipt. `createInMemoryTaskRelay` remains exported solely as a deterministic conformance fixture.
 
-### 2. open the agents yourself
+## v1 gateway adapter (retained)
 
-Start each Pi agent in the same repo/cwd and load the extension. Give each one a
-stable session name:
+The v1 gateway client is available only through the published `@sgtbeatdown/pi-tasks/v1-compat-extension` entry. This is an explicit opt-in: after resolving the installed package root, add `src/v1-compat-extension.ts` as an extension path in Pi settings instead of loading the package default. The package manifest loads only `src/extension.ts` (v2); v2 does not fall back to v1 when its relay is unavailable or incompatible. Its v1 behavior and operational requirements are documented below.
 
-```bash
-# pane 1
-PI_TASK_SESSION=parent pi -e ./.pi/extensions/pi-tasks-tmux.ts
-
-# pane 2
-PI_TASK_SESSION=worker-a pi -e ./.pi/extensions/pi-tasks-tmux.ts
-```
+## requirements and trust boundary
 
-If the extension is installed with `pi install`, you can omit `-e`; the important
-parts are same cwd, same `.pi/tasks`, and distinct `PI_TASK_SESSION` values.
+- a reachable local Wolfpack v1 task gateway on every participating machine;
+- this package loaded in every participating Pi process;
+- `WOLFPACK_SESSION_NAME` set by Wolfpack so the local gateway can resolve the caller to a stable broker ID; and
+- `WOLFPACK_PORT` when the local control port is not the default `18790`.
 
-### 3. find the target pane id
+The boundary is trusted local processes and trusted Tailnet machines. Pi only calls its own local gateway. The gateways perform direct fetch federation; Pi never fetches a peer directly. v1 adds no task capability authentication. Normal Wolfpack global JWT behavior is not bypassed, and JWT federation is unsupported: peer delivery fails clearly when credentials would be required.
 
-From inside tmux:
+## task address and send
 
-```bash
-tmux list-panes -a -F '#{pane_id} #{pane_current_path} #{pane_title}'
-```
-
-Pane ids look like `%12`. Use that pane id as `agent_task_send.to`.
-
-### 4. send a task
-
-From the parent Pi session, call:
+A target is always `{ machine, sessionId }`, where `sessionId` is the stable opaque broker ID returned by Wolfpack session control. Use `machine: "local"` for same-machine work. For a peer, use the receiver's canonical HTTPS Tailnet origin, for example `https://worker.example.ts.net`; do not supply a hostname label, path, query, fragment, credentials, unexpected port, or arbitrary HTTPS URL.
 
 ```json
 {
-  "to": "%12",
-  "task": "inspect the auth middleware and report risks",
-  "timeoutMs": 1800000
-}
-```
-
-Expected flow:
-
-1. parent creates `.pi/tasks/<taskId>/...`
-2. tmux transport pastes the assignment into pane `%12`
-3. worker receives `pi.task.assignment.v1`
-4. worker does the work
-5. worker calls `agent_task_done` with that `taskId`
-6. parent reads the result via `agent_task_status`, `agent_task_wait`, or
-   `agent_task_inbox`
-
-### tmux troubleshooting
-
-- If the target cannot complete the task, confirm it loaded the extension and has
-  `agent_task_done` available.
-- If status never changes, confirm parent and worker are in the same cwd and both
-  can see the same `.pi/tasks/<taskId>` directory.
-- If dispatch fails, run `tmux paste-buffer` manually against the same target id;
-  the pane id may be stale.
-- Do not use terminal output as the source of truth. The task result is the store
-  state, not visible prose in the pane.
-
-## using with non-pi workers
-
-A non-Pi worker can participate if it implements the same lifecycle:
-
-1. receive `pi.task.assignment.v1`
-2. do the assigned work
-3. write/report a terminal result with the same status and payload semantics
-4. never overwrite an already-terminal task
-
-Example HTTP transport from a Pi extension:
-
-```ts
-import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
-import { registerAgentTaskTools } from "@sgtbeatdown/pi-tasks/src/extension";
-import { createFilesystemTaskStore } from "@sgtbeatdown/pi-tasks/src/stores/filesystem";
-import type { TaskTransport } from "@sgtbeatdown/pi-tasks/src/task-communication";
-
-const httpTransport: TaskTransport = {
-  name: "http",
-  getCurrentSessionName(env) {
-    return env.PI_TASK_SESSION ?? "unknown-session";
-  },
-  async dispatchTask({ target, assignment, task, signal }) {
-    const response = await fetch(`https://tasks.example/sessions/${target}/assignments`, {
-      method: "POST",
-      headers: { "content-type": "application/json" },
-      body: JSON.stringify({ taskId: task.id, assignment }),
-      signal,
-    });
-
-    if (response.ok) return { ok: true };
-
-    return {
-      ok: false,
-      message: await response.text(),
-      retryable: response.status >= 500,
-    };
+  "to": { "machine": "local", "sessionId": "receiver-broker-id" },
+  "task": "implement the narrow change and run focused tests",
+  "context": {
+    "summary": "## constraints and preferences\n- keep scope narrow\n## key decisions\n- preserve the public contract",
+    "refs": [{ "path": "src/extension.ts", "purpose": "affected tool wiring" }]
   },
-};
-
-export default function extension(pi: ExtensionAPI): void {
-  registerAgentTaskTools(pi, {
-    store: createFilesystemTaskStore({ tasksDir: ".pi/tasks" }),
-    transport: httpTransport,
-  });
+  "metadata": { "phaseId": "phase-1", "issueId": "task-3", "verificationTier": "focused" },
+  "onCompletePrompt": "review the receiver diff before reporting completion",
+  "timeoutMs": 1800000
 }
 ```
 
-For non-Pi workers, expose a completion endpoint or let workers use your store
-implementation directly. The worker should report a terminal result equivalent
-to:
+### minimal valid send envelope
 
 ```json
 {
-  "taskId": "task_...",
-  "status": "completed",
-  "summary": "finished the assigned work",
-  "result": {}
+  "to": {
+    "machine": "local",
+    "sessionId": "receiver-broker-id"
+  },
+  "task": "implement the narrow change and run focused tests"
 }
 ```
 
-## file inbox / polling workers
-
-A pushed message is not required. A transport can durably drop assignments into a
-file inbox or queue and return success once the assignment is written.
-
-One simple design:
-
-- store tasks in `.pi/tasks`
-- transport writes assignment text to `.pi/task-inbox/<target>/<taskId>.txt`
-- worker watches its inbox directory
-- worker reads the assignment, does the work, then completes through a store API
-  or by invoking a Pi session that has `agent_task_done`
-
-Completion is separate from dispatch. Dispatch means “assignment delivered,” not
-“work finished.”
-
-## when to implement a custom store
-
-Do **not** implement a custom store just because you have a new dispatch
-mechanism. Implement `TaskStore` only when task state itself must be somewhere
-else:
-
-- central HTTP service
-- Redis/Postgres/SQLite shared by multiple machines
-- multi-host queue system
-- hosted control plane
-
-If only delivery changes, keep the filesystem store.
+`INVALID_REQUEST.error.path` is an optional RFC 6901 JSON Pointer to the rejected send field, for example `/preflight/requiredProject`; use it rather than parsing error prose. A pre-persistence validation rejection creates no task, so correct the field and retry. If creation status is uncertain, idempotency remains necessary.
 
-## included wolfpack transport
+Remote addressing changes only `to.machine`:
 
-This package includes a Wolfpack transport for convenience. It is only a delivery
-adapter:
-
-```bash
-wolfpack session send <target-session> <assignment>
+```json
+{ "to": { "machine": "https://worker.example.ts.net", "sessionId": "receiver-broker-id" }, "task": "review the cited diff" }
 ```
 
-It does not own storage. The default exported extension uses the generic
-filesystem store at `.pi/tasks/` plus the included Wolfpack transport.
+Context is optional, curated Markdown plus deliberately selected ref metadata. The extension renders refs but never reads or copies their contents. Relative refs resolve in the receiver project; absolute refs are same-machine only and must remain inside the authoritative parent or receiver project root. Missing refs are warnings, not copied content or transcript transfer.
 
-If you are using Wolfpack, install this extension in every participating Pi
-session and target a session name/id with `agent_task_send`.
+Initial limits are 16 KiB UTF-8 each for task instructions and context summary, 48 KiB for the assignment envelope, and 64 KiB for an HTTP request body. The initial size limits require representative payload benchmarking before adjustment.
 
-If you are not using Wolfpack, register the tools with your own `{ store,
-transport }` composition.
+`agent_task_send` waits for durable gateway acceptance, not adapter insertion or task execution; delivery remains pending until `task.delivered`. A remote initial send has one initial attempt: the receiver persists a provisional receipt, then receives sender confirmation before Pi can see the assignment. Later peer confirmation, messages, terminal updates, cancellation, delivery notices, and parent acknowledgment have four total attempts: the initial attempt plus retries around 1, 2, and 4 seconds with jitter. Exhaustion is a visible local delivery failure, not a background queue or offline dispatch promise.
 
-## tools
+Normal delegation is fire-and-forget. Use `agent_task_wait` only when the user explicitly asks to block.
+
+## tools, messages, and acknowledgment
 
 | tool | purpose |
 | --- | --- |
-| `agent_task_send` | create a task and dispatch it through the configured transport |
-| `agent_task_status` | read compact structured status for one task |
-| `agent_task_wait` | wait in tool code for a terminal result when the user wants it now |
-| `agent_task_inbox` | list terminal tasks for the current parent session |
-| `agent_task_cancel` | cancel a non-terminal task |
-| `agent_task_done` | assignee-side structured completion; terminates the target response |
+| `agent_task_send` | create a durable gateway assignment |
+| `agent_task_status` | read task state, history, result, and warnings |
+| `agent_task_wait` | explicitly poll a task until terminal or timeout |
+| `agent_task_inbox` | read task events without acknowledgment |
+| `agent_task_ack` | acknowledge one independently verified terminal task |
+| `agent_task_message` | send a durable `question`, `answer`, or `information` event |
+| `agent_task_cancel` | request cancellation |
+| `agent_task_done` | receiver-only terminal completion; terminates the tool turn |
 
-### completion contract
+Use `agent_task_message` for clarification instead of terminal prose. Only one question can be unresolved per task; answers link to that question. Information is durable and does not change task state. An accepted receiver question terminates that receiver turn; a parent question does not.
 
-Assigned Pi agents must call `agent_task_done` as their final action:
+Report source modifications in `result.changedFiles`. Artifacts are receiver-project-relative regular files for a parent to inspect, not a changed-file list:
 
 ```json
-{
-  "taskId": "task_...",
-  "status": "completed",
-  "summary": "inspected auth middleware; no bypass found",
-  "result": {
-    "filesReviewed": ["src/auth.ts"]
-  }
-}
+{ "result": { "changedFiles": ["src/extension.ts"] }, "artifacts": [{ "path": "verification/task-2.md" }] }
 ```
 
-Non-Pi workers should complete through an equivalent store/server API with the
-same terminal status and payload semantics.
-
-Valid terminal statuses:
+See the canonical Wolfpack artifact contract for provenance, containment, and warning behavior.
 
-- `completed`
-- `failed`
-- `cancelled`
-- `timed_out`
-- `rejected`
+The sender gateway owns canonical event order, timeout, and terminal state. The first accepted terminal event wins. Sender timeout triggers best-effort remote cancellation; late terminals remain diagnostics. After independently verifying one terminal result, call `agent_task_ack({ taskId })`. Remote acknowledgment is two-phase: the receiver durably confirms pending acknowledgment before the sender records final parent acknowledgment. If that delivery fails, the task remains visible and a later explicit acknowledgment repairs it with the same event ID.
 
-Terminal completion is first-writer-wins.
+## structured delivery and replay
 
-## task protocol
+The extension polls the local gateway every five seconds. With no pending message, it submits each visible event as a structured custom message using Pi's safe `deliverAs: "followUp"` mode: idle Pi starts immediately, while an active turn finishes before the queued event starts the next turn. It never steers or interrupts active work. Delivery remains pending until `task.delivered`. The `{ taskId, eventId }` details let task context participate in the session without parsing prose.
 
-Assignments are delivered as human-readable text plus a structured envelope with:
+On start or resume it rebuilds incorporated IDs from the full durable session entry set, not only active prompt context. A session gets only missing events; a new Pi session in the same Wolfpack PTY gets complete active history. The receiver records gateway delivery only after the structured insertion exists. A restart after insertion and before acknowledgment therefore acknowledges the existing entry without duplicate injection. Unknown model-visible events fail closed without advancing the cursor. Gateway delivery is at-least-once; this does not claim exactly-once model execution.
 
-- `type: "pi.task.assignment.v1"`
-- `taskId`
-- `fromSession`
-- `instructions`
-- protocol requirements telling the assignee to use `agent_task_done`
+## parent workflow
 
-Task state includes:
+1. create or select a Wolfpack Pi session with the canonical session-control workflow and retain its stable broker ID. Spawn a disposable worker without an initial model prompt so it reaches idle before assignment; put worker instructions in `agent_task_send.task`.
+2. before remote dispatch, complete Wolfpack's [Live-peer readiness checklist](https://github.com/almogdepaz/wolfpack/blob/main/docs/task-gateway.md#live-peer-readiness-checklist) and retain operator-recorded package/reload evidence; only then check the target's local requirements and send compact instructions with curated context and selected refs when they save receiver investigation.
+3. keep working; use `agent_task_status` or `agent_task_inbox` for structured follow-up, and `agent_task_message` for questions, answers, and decisions.
+4. verify cited files, diffs, tests, and paths-only artifact metadata independently before reporting success.
+5. acknowledge the accepted terminal result, then clean up only sessions this parent spawned. Keep a reusable implementer alive while review or correction remains possible; never make workers close their own sessions.
 
-- `pending`
-- `dispatched`
-- `running`
-- terminal status
-- assignment/result refs
-- event history
-- optional result payload/artifacts/error
+Isolated coverage is the deterministic acceptance gate, but a specific live peer still requires current readiness at the time of use. If the checklist cannot pass, stop before task creation and report fixture-only verification. Do not use direct peer URLs from Pi.
 
-Filesystem layout:
+See `skills/wolfpack-pi-task-delegation/SKILL.md` for the operational workflow and `skills/task-context-summary/SKILL.md` for recovery/reuse summaries.
 
-```text
-<tasksDir>/<taskId>/
-├── task.json
-├── assignment.json
-├── events.jsonl
-└── result.json
-```
+## deferred follow-up
 
-Generic filesystem storage defaults to `.pi/tasks/` when used directly.
+These are documented operational debt, not production TODOs: exact Pi runtime registration and heartbeat/capability leases; durable offline initial dispatch; JWT/authenticated peer federation; artifact byte transfer and retention; representative payload benchmarking; automated recovery summaries; and summary caching only after measured repeated-generation waste. v1 has no queue, scheduler, artifact transfer, or transcript transfer.
 
-## architecture
+## legacy historical metrics
 
-`pi-tasks` separates storage from delivery:
-
-```ts
-interface TaskStore {
-  createOrReuseDispatchedTask(...): Promise<...>;
-  readTask(...): Promise<...>;
-  readTaskResult(...): Promise<...>;
-  expireTaskIfOverdue(...): Promise<...>;
-  waitForTask(...): Promise<...>;
-  listInbox(...): Promise<...>;
-  ackTask(...): Promise<...>;
-  cancelTask(...): Promise<...>;
-  completeTask(...): Promise<...>;
-}
-
-interface TaskTransport {
-  getCurrentSessionName(env): string;
-  dispatchTask(input): Promise<DispatchTaskResult>;
-}
-```
-
-Registration composes both:
-
-```ts
-registerAgentTaskTools(pi, {
-  store: createFilesystemTaskStore({ tasksDir: ".pi/tasks" }),
-  transport: myTransport,
-});
-```
-
-## exported building blocks
-
-- `src/extension.ts`
-  - `registerAgentTaskTools`
-  - `createDefaultTaskCommunicationLayer`
-- `src/task-communication.ts`
-  - `TaskStore`
-  - `TaskTransport`
-  - `TaskCommunicationLayer`
-- `src/stores/filesystem.ts`
-  - `createFilesystemTaskStore`
-- `src/transports/wolfpack.ts`
-  - `createWolfpackTaskTransport`
-- `src/protocol.ts`
-  - `buildAssignment`
-  - `compactTaskResult`
-- `src/store.ts`
-  - low-level filesystem store functions, if you need finer control than
-    `createFilesystemTaskStore`
+`task-metrics` and the task board remain read-only analyzers for already-existing historical `.pi/tasks` directories. They are not part of the runtime task protocol and must not create, mutate, or deliver v1 gateway tasks. Replacing or retiring that historical reporting surface requires a product decision about gateway-wide query/metrics ownership.
 
 ## development
 
@@ -505,10 +134,3 @@ bun install
 bun test
 bun run typecheck
 ```
-
-## current limitations
-
-- no built-in HTTP/Redis transport yet
-- no runtime transport selector yet; compose a store/transport in an extension
-- default extension uses the generic filesystem store plus the included Wolfpack transport
-- package is source-first; install with `pi install npm:@sgtbeatdown/pi-tasks`

package/package.json

@@ -1,11 +1,15 @@
 {
   "name": "@sgtbeatdown/pi-tasks",
-  "version": "0.1.0",
-  "description": "Structured task communication for Pi agents with pluggable stores and transports.",
-  "module": "src/extension.ts",
+  "version": "0.1.2",
+  "description": "Durable Pi agent delegation through the Wolfpack task gateway.",
+  "module": "src/index.ts",
+  "exports": {
+    ".": "./src/index.ts",
+    "./v1-compat-extension": "./src/v1-compat-extension.ts"
+  },
   "repository": {
     "type": "git",
-    "url": "https://github.com/almogdepaz/pi-tasks.git"
+    "url": "git+https://github.com/almogdepaz/pi-tasks.git"
   },
   "keywords": [
     "pi-package",
@@ -46,6 +50,7 @@
   },
   "scripts": {
     "test": "bun test",
+    "task-metrics": "bun src/metrics-cli.ts",
     "typecheck": "tsc --noEmit"
   },
   "type": "module"

package/skills/task-context-summary/SKILL.md

@@ -0,0 +1,34 @@
+---
+name: task-context-summary
+description: Recover or reuse a bounded Wolfpack task context summary when the parent needs to reconstruct handoff context without copying a transcript.
+---
+
+# task context summary
+
+parent authors normal summaries. use this skill only for recovery or reuse when the parent lacks enough already-loaded context.
+
+## evidence order
+
+1. inspect relevant docs/code first.
+2. use an existing session summary next, if one exists.
+3. inspect only the selective recent transcript needed to resolve remaining gaps.
+
+do not copy a full transcript, infer unseen file contents, or automatically cache generated summaries. when evidence disagrees, state the disagreement explicitly instead of silently choosing a version.
+
+## output
+
+return concise Markdown, under 16KiB UTF-8, using any useful subset:
+
+```md
+## constraints and preferences
+## progress
+### done
+### in progress
+### blocked
+## key decisions
+## critical context
+## failed approaches
+## open questions
+```
+
+include selected refs separately in the task request. mention a ref's path, selector, and purpose only; do not read or duplicate ref contents merely to populate the summary.