sessionpipe 0.12.0 → 0.13.1

package/README.md

@@ -34,6 +34,18 @@ machines by their id, so the pairing holds and its two cards become one.
 | 2 | + your prompts and the assistant's text, redacted |
 | 3 | + tool input and output |
 
+A tool call is two events (`tool.started`, `tool.ended`), and a workflow that runs a few
+hundred subagents fires thousands a minute. So a receiver is sent a subagent's finished
+tool calls (`tool.ended`) at most one per session per minute, plus the one that answers a
+subagent's permission prompt, the main thread's tool events as they happen, and at most
+one request a second from this machine with everything that piled up in it. `--tools` on
+`sink add` picks the first: `all` sends every tool event (the default), `main` is what a
+receiver that meters requests asks for in its well-known file and is used where it does,
+`beat` thins the main thread's tool events the same way. The local outbox keeps every event whichever you
+pick; turns, prompts, attention and subagents are never thinned. `replay --tools all`
+sends every tool event once, for a receiver rebuilt from the outbox, and `replay` says
+how many it thinned.
+
 No telemetry. Secrets never leave (`secrets@1` runs above tier 0, always). Your
 server or none. Pre-release: the reference receiver is still being built; see the
 [roadmap](https://github.com/spacesheep-dev/sessionpipe/blob/main/ROADMAP.md).
@@ -72,17 +84,36 @@ is missing or doesn't match, the session doesn't start.
 
 One daemon per computer holds one long-poll per receiver and delivers each message the
 cheapest way the session allows: to `sessionpipe wait` parked in the session's
-background (in place, ~60 ms, no network), at the session's next Stop if it is
-mid-turn, through the Agent SDK for a session it started (if the SDK is installed), or
-as a headless `claude -p --resume` (a `--fork-session` copy when a live process holds
-it). A session stays reachable in place with zero idle turns by running, as a
-background command with the longest timeout it can (Claude Code: raise
-`BASH_MAX_TIMEOUT_MS`, else a background command is stopped after 2 hours at most):
+background (in place, ~60 ms, no network), at the session's next Stop if it is mid-turn,
+through its channel if it has one (below), into the live session's own inbox if it is
+idle (every Claude Code session on macOS and Linux has one, the Claude app's included;
+the session reads such a message as a teammate's request, so it won't change its
+settings or CLAUDE.md for it), through the Agent SDK for a session it started (if the
+SDK is installed), or as a headless `claude -p --resume` (a `--fork-session` copy when a
+live process holds it and nothing else reaches it). A session stays reachable in place
+with zero idle turns by running, as a background command with the longest timeout it can
+(Claude Code: raise `BASH_MAX_TIMEOUT_MS`, else a background command is stopped after 2
+hours at most):
 
 ```sh
 sessionpipe wait            # Claude Code: the session id comes from CLAUDE_CODE_SESSION_ID
 ```
 
+Or let Claude Code keep the waiter for you, the way its Telegram plugin reaches a
+session: `sessionpipe channel` is a Claude Code channel (an MCP server that pushes
+messages in). It parks for its session the whole time the session runs, and each message
+sent while the session is idle arrives in the session's own thread, in the terminal and
+in the Claude app, as a message from `sessionpipe`, in the session's own permission
+mode, and the session reads it as your own words. Channels are a research preview: a
+channel that isn't on Anthropic's allowlist loads only with
+`--dangerously-load-development-channels`, which asks once at startup, and a session the
+Claude app starts through `claude remote-control` can't be given one yet.
+
+```sh
+claude mcp add --scope user sessionpipe -- sessionpipe channel
+claude --dangerously-load-development-channels server:sessionpipe
+```
+
 The waiter and next-Stop modes work in any Claude Code session that runs your hooks,
 the Claude desktop app's included, and need nothing else. The Agent SDK, resume and fork
 modes run the `claude` command, which has its own login (`claude auth login`); the
@@ -178,6 +209,29 @@ a signed `pool` command; turning it on or off, removing or reordering accounts,
 finishing a sign-in need a fresh confirm with your passkey or device key, never a day
 grant alone. `sessionpipe uninstall` runs `pool off` first.
 
+### Agents that ask agents
+
+A session can hand a task to another agent on this machine and get the answer back:
+`sessionpipe ask codex "review the diff on this branch"` runs Codex headlessly, waits,
+and prints its reply on stdout (the child's id and progress on stderr), so Claude Code
+can use Codex for a review, Codex can ask Gemini, and any harness with a shell can use
+any other. The request never leaves the machine: it goes over the daemon's local socket
+(the one `wait` uses), the daemon runs the agent in an allowed folder at `safe` (or
+`read`; never wider than the machine's mode), caps it as it caps a start, and stops a
+chain at two deep. Both
+sessions' events say what happened (`delegation.started` / `delegation.ended` on the
+asker, `delegated_by` on the answerer). A receiver can do the same from outside with
+`reply_to` on a `start` or a `prompt`: the answer comes back into that session as a
+message. `sessionpipe ask on` turns it on, with or without a receiver; `sessionpipe ask
+setup` tells Claude Code and Codex the command exists, in their own instruction files,
+since hooks never inject anything.
+
+```sh
+sessionpipe ask on                                        # once; the daemon runs as a service
+sessionpipe ask codex "review the diff on this branch"    # from inside any session; the answer is stdout
+sessionpipe ask status                                    # on or off, the daemon, the agents it can ask
+```
+
 ## Updates
 
 The control daemon keeps its own copy current. About a minute after it starts, and then
@@ -263,7 +317,7 @@ names and meanings as `doctor --json`:
 |---|---|
 | `version`, `machine`, `state`, `config` | Strings; state and config are absolute paths. |
 | `harnesses` | Object keyed by harness name; each value is an array of `{file, state, note?}` hook checks. `file` uses `~` for home, as doctor does. Includes detected **or configured** harnesses. |
-| `sinks` | Array of `{name, url, tier, max_tier, pii, control, paused, pending_sessions}`. `tier` is the configured tier; the effective tier is `min(tier, max_tier ?? 3)`. `max_tier` and `paused` are `null` when unset. No token or secret is included. |
+| `sinks` | Array of `{name, url, tier, max_tier, pii, tools, control, paused, pending_sessions}`. `tier` is the configured tier; the effective tier is `min(tier, max_tier ?? 3)`. `max_tier` and `paused` are `null` when unset. `tools` is which tool events the sink is sent (`all`, `main`, `beat`), its default resolved. No token or secret is included. |
 | `timing` | `{n, p50, p95}` from the last 100 local hook timings, in milliseconds; `null` when unavailable. |
 | `update` | Doctor's update summary: `{auto, off, last_check, latest, last_error, pending, updated, failed}`. `auto` is boolean; absent details are `null`. |
 | `jobs` | Number of entries waiting in the local jobs directory; zero when absent. |

package/dist/ask.d.ts

@@ -0,0 +1,40 @@
+export declare const ASK_HELP = "  sessionpipe ask <agent|harness:id> \"<task>\" [--cwd DIR] [--permission read|safe] [--model M] [--json] [--quiet]\n                                                   (hand a task to another agent here; its answer comes back on stdout;\n                                                    `--text -` reads the task from stdin, words after `--` are the task)\n  sessionpipe ask on | off | status                (whether sessions on this machine may ask each other; `on` is the\n                                                    person's to run at the terminal, never a session's)\n  sessionpipe ask setup [--remove]                 (tell Claude Code and Codex the command exists)";
+/** What the asker writes where. `out` is one line on stdout: the answer, or a status
+ *  line of on/off/status/setup. `err` is stderr, raw: progress and what went wrong. */
+export interface AskIo {
+    out: (s?: string) => void;
+    err: (s: string) => void;
+    /** Stdin, whole, for `--text -`. */
+    stdin?: () => string;
+}
+export interface AskOptions {
+    env?: NodeJS.ProcessEnv;
+    /** Where the CLI's dist lives: the service points at its cli.js. */
+    distDir?: string;
+    /** The agents this machine can run headlessly (tests stand in for the PATH walk). */
+    harnesses?: (env: NodeJS.ProcessEnv) => string[];
+}
+/** Run `sessionpipe ask …`; `argv` starts with "ask". Returns the exit code: 0 with the
+ *  answer on stdout, 1 when the daemon refused or the run failed, 2 for a usage error. */
+export declare function askMain(argv: string[], io: AskIo, o?: AskOptions): Promise<number>;
+export declare const ASK_OPEN = "<!-- sessionpipe ask -->";
+export declare const ASK_CLOSE = "<!-- /sessionpipe ask -->";
+/** The section a model reads, between the markers; `agents` is what this machine can run. */
+export declare function askSection(agents: string[]): string;
+/** The files `ask setup` writes: every Claude Code config dir's CLAUDE.md, and Codex's
+ *  AGENTS.md. A file is written when it exists or its harness dir does; a harness that
+ *  isn't here is left alone. */
+export declare function setupFiles(env?: NodeJS.ProcessEnv): string[];
+/** `text` with the section in: replaced in place when one is there, else after what is
+ *  there with one newline between (reversible byte for byte by withoutAskSection). */
+export declare function withAskSection(text: string | null, section: string): string;
+/** `text` without the section and the newline that joined it on: what the file held
+ *  before setup wrote it. Unchanged when there is no section. */
+export declare function withoutAskSection(text: string): string;
+export type SetupDid = "added" | "updated" | "unchanged" | "removed" | "absent" | "skipped";
+/** Write (or take out) the section in every file setupFiles names. */
+export declare function setupAsk(env: NodeJS.ProcessEnv, agents: string[], remove: boolean): {
+    file: string;
+    did: SetupDid;
+}[];
+//# sourceMappingURL=ask.d.ts.map

package/dist/ask.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ask.d.ts","sourceRoot":"","sources":["../src/ask.ts"],"names":[],"mappings":"AAqBA,eAAO,MAAM,QAAQ,8qBAK8E,CAAC;AAEpG;uFACuF;AACvF,MAAM,WAAW,KAAK;IACpB,GAAG,EAAE,CAAC,CAAC,CAAC,EAAE,MAAM,KAAK,IAAI,CAAC;IAC1B,GAAG,EAAE,CAAC,CAAC,EAAE,MAAM,KAAK,IAAI,CAAC;IACzB,oCAAoC;IACpC,KAAK,CAAC,EAAE,MAAM,MAAM,CAAC;CACtB;AAED,MAAM,WAAW,UAAU;IACzB,GAAG,CAAC,EAAE,MAAM,CAAC,UAAU,CAAC;IACxB,oEAAoE;IACpE,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,qFAAqF;IACrF,SAAS,CAAC,EAAE,CAAC,GAAG,EAAE,MAAM,CAAC,UAAU,KAAK,MAAM,EAAE,CAAC;CAClD;AAUD;0FAC0F;AAC1F,wBAAsB,OAAO,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,EAAE,EAAE,KAAK,EAAE,CAAC,GAAE,UAAe,GAAG,OAAO,CAAC,MAAM,CAAC,CAmC5F;AAmPD,eAAO,MAAM,QAAQ,6BAA6B,CAAC;AACnD,eAAO,MAAM,SAAS,8BAA8B,CAAC;AAErD,6FAA6F;AAC7F,wBAAgB,UAAU,CAAC,MAAM,EAAE,MAAM,EAAE,GAAG,MAAM,CAenD;AAED;;gCAEgC;AAChC,wBAAgB,UAAU,CAAC,GAAG,GAAE,MAAM,CAAC,UAAwB,GAAG,MAAM,EAAE,CAMzE;AAQD;sFACsF;AACtF,wBAAgB,cAAc,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,EAAE,OAAO,EAAE,MAAM,GAAG,MAAM,CAK3E;AAED;iEACiE;AACjE,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAOtD;AAED,MAAM,MAAM,QAAQ,GAAG,OAAO,GAAG,SAAS,GAAG,WAAW,GAAG,SAAS,GAAG,QAAQ,GAAG,SAAS,CAAC;AAE5F,sEAAsE;AACtE,wBAAgB,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC,UAAU,EAAE,MAAM,EAAE,MAAM,EAAE,EAAE,MAAM,EAAE,OAAO,GAAG;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,GAAG,EAAE,QAAQ,CAAA;CAAE,EAAE,CA8BrH"}

package/dist/cli.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":";AAwEA,MAAM,WAAW,EAAE;IACjB,0BAA0B;IAC1B,GAAG,EAAE,CAAC,CAAC,CAAC,EAAE,MAAM,KAAK,IAAI,CAAC;IAC1B,kDAAkD;IAClD,GAAG,EAAE,CAAC,CAAC,EAAE,MAAM,KAAK,IAAI,CAAC;IACzB,IAAI,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;CAC9B;AAED,8FAA8F;AAC9F,wBAAsB,IAAI,CACxB,IAAI,EAAE,MAAM,EAAE,EACd,EAAE,GAAE,EAA2F,GAC9F,OAAO,CAAC,IAAI,CAAC,CAUf;AAED,sFAAsF;AACtF,wBAAgB,YAAY,CAAC,KAAK,EAAE,MAAM,GAAG,SAAS,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,CAM5E"}
+{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":";AAsFA,MAAM,WAAW,EAAE;IACjB,0BAA0B;IAC1B,GAAG,EAAE,CAAC,CAAC,CAAC,EAAE,MAAM,KAAK,IAAI,CAAC;IAC1B,kDAAkD;IAClD,GAAG,EAAE,CAAC,CAAC,EAAE,MAAM,KAAK,IAAI,CAAC;IACzB,IAAI,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;CAC9B;AAED,8FAA8F;AAC9F,wBAAsB,IAAI,CACxB,IAAI,EAAE,MAAM,EAAE,EACd,EAAE,GAAE,EAA2F,GAC9F,OAAO,CAAC,IAAI,CAAC,CAUf;AAED,sFAAsF;AACtF,wBAAgB,YAAY,CAAC,KAAK,EAAE,MAAM,GAAG,SAAS,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,CAM5E"}