@kdonev/termscape 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 kdonev
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,288 @@
+# Termscape
+
+Run a crew of AI coding agents on one infinite canvas, and let them talk to
+each other.
+
+Each terminal window on the canvas runs an agent CLI wired to an MCP server the
+hub exposes. Agents can look each other up, send each other messages, spawn
+helpers into their workspace, and check on each other's terminals. A message
+from one agent is delivered by typing it into the other's terminal, immediately.
+
+Local-first: the hub runs on your machine, binds loopback only, and the UI is a
+browser tab. Other machines run the same hub as a daemon and appear on the same
+canvas.
+
+## Getting started
+
+```bash
+npx @kdonev/termscape
+```
+
+That starts the hub and opens the canvas in your browser — pass `--no-open`
+if you would rather it did not; the URL is printed either way. Nothing is
+installed system-wide: state lives in `~/.termscape`, and deleting that
+directory is the uninstall.
+
+Slide out the **machines** panel: every machine, the workspaces on it, and
+the agents in each. Point a workspace at a folder there, and start an agent
+in it.
+
+- **Scroll** to pan, **Ctrl/⌘ + scroll** to zoom, **Ctrl/⌘ + 1** to fit,
+  **Ctrl/⌘ + 2** to zoom to one terminal
+- A **quick flick** of the zoom — a fast pinch, or a fast spin of the wheel —
+  navigates instead of zooming: in over a terminal maximizes it, out steps
+  back to the workspace around it and then to everything. Zooming at any
+  ordinary pace is left alone
+- Below 60% zoom terminals become preview cards — zoom in to interact
+- Clicking an agent in the panel brings the canvas to it
+
+## Requirements
+
+- Node 22 or newer
+- An agent CLI on your `PATH` — [Claude Code](https://claude.com/claude-code)
+  is the profile that ships configured
+- macOS, Windows, or Linux
+
+Everything native is prebuilt on all three platforms, so no compiler is
+needed.
+
+## How it fits together
+
+```
+Browser (canvas, xterm.js)
+   │  WebSocket: JSON control + binary PTY frames
+Hub (Node)
+   │  node-pty ── agent CLI processes
+   │  MCP over HTTP ── the tools agents call
+   │  SQLite ── workspaces, layout, sessions, screens
+   │  hub↔hub WebSocket, either direction
+Remote hub (same binary, --headless)
+```
+
+Agents never talk to each other directly. They call `send_message` on their own
+hub; the hub does the delivery, locally or by forwarding to a peer. That is why
+an agent addresses a peer on another machine exactly as it addresses one in the
+next window.
+
+## Adding another machine
+
+Start the hub so the other machine can see it, then let that machine come to
+you:
+
+```bash
+npx @kdonev/termscape --listen lan
+```
+
+(From a clone that is `npm run dev -- --listen lan`, or
+`npm run dev -w @termscape/hub -- --listen lan` if you are calling the
+workspace directly — npm needs the `--` to hand flags to the hub rather than
+reading them itself.)
+
+The hub prints an `enroll:` URL alongside the usual one. Open it **on the
+machine you want to add** and run the command it shows:
+
+```bash
+curl -fsSL http://studio:7777/join.sh | sh    # macOS, Linux
+irm http://studio:7777/join.ps1 | iex         # Windows
+```
+
+Both halves of that URL are chosen to be typeable, because the join page is the
+one address you have to carry to another machine and enter by hand:
+
+- **The host** is this machine's own name when that name actually resolves to
+  the address the hub bound — checked, not assumed. Windows resolves bare names
+  over LLMNR/NetBIOS and macOS/Linux over mDNS, and neither is guaranteed, so
+  the hub prints the numeric URL underneath as a fallback and the machines
+  panel offers it too. The canvas itself is reachable by name as well, token and all,
+  which is how you open it on a second screen or a phone.
+- **The port** is the first free one from `7777, 4242, 7333, 3333, ...`.
+  `--port <n>` overrides it; `--port 0` takes whatever the OS hands out.
+
+That installs the hub into `~/.termscape` there and connects it back. The machine
+appears in the **machines** panel with a node of its own, and a workspace added
+under that node runs its agents over there — same addresses, same
+`send_message`, same canvas.
+
+The installer works out what is missing before it changes anything:
+
+- **Node 22.** If the machine has none, or an older one, it fetches a private
+  copy into `~/.termscape/node` — checksum-verified against nodejs.org's own
+  `SHASUMS256.txt`, since it is a binary about to be executed. Private rather
+  than system-wide, so it needs no administrator rights, no package manager,
+  and no fresh shell to pick up a PATH change; uninstalling is deleting the
+  directory. A copy already there is reused.
+- **Native modules.** It prefers prebuilt binaries for `node-pty` and
+  `better-sqlite3`, falls back to compiling, and if neither works tells you
+  exactly which toolchain to install.
+
+If the machine does not appear, the installer says why rather than reporting
+success: a spent or expired key, a version gap, or a hub that exited. It waits
+for the canvas to actually accept the machine, not merely for the hub to start
+listening. `~/.termscape/hub.log` on that machine has the detail.
+
+Re-running the join command on a machine that already joined is the supported
+way to update or repair it: it stops the hub running there, replaces the
+install, and rejoins with the token it already holds — or, if you had removed
+that host from the canvas, with the fresh key the command carries. Removing a
+machine from the panel stops its hub too, so it is not left running a daemon
+that belongs to nobody — and takes the workspaces and agents on it with it,
+which the panel says before it does it.
+
+A re-join is quick after the first one: it keeps the dependency tree already
+installed there unless the dependencies, the Node version, or the platform
+have actually changed, and checks that tree really loads before trusting it.
+
+Two things worth knowing:
+
+- `--listen` is opt-in and off by default. With it, your hub is reachable on
+  that network, and anyone who can load the join page can attach a machine to
+  your canvas. Every other route still requires the token.
+- Each download carries a single-use key that expires in 15 minutes. Once a
+  machine has joined it keeps a durable token in `~/.termscape/host-token` and
+  rejoins by itself after a reboot or a dropped link — its agents keep running
+  in the meantime.
+
+**If you can't stand at the other machine**, the panel's *deploy over ssh* tab
+does the reverse: it connects with your SSH agent or a key, installs the hub
+over SFTP, starts it bound to that machine's loopback, and reaches it through a
+tunnel. Same protocol, opposite direction.
+
+## Tools agents get
+
+| Tool | What it does |
+|---|---|
+| `whoami` | your address, workspace and working directory |
+| `list_agents` | everyone on the canvas, across every host, and whether they are busy |
+| `send_message` | type a message into another agent's terminal, right now |
+| `spawn_agent` | start a helper in your workspace, with an optional first task |
+| `read_screen` | look at another agent's terminal without interrupting it |
+| `set_status` | label your own window so the human can see what you are doing |
+| `stop_agent` | stop an agent you spawned |
+
+Every agent is also given a brief explaining its address, its peers, and that
+text arriving as `[from <address>] ...` is a colleague rather than the human.
+
+## Agent profiles
+
+An agent CLI is configuration, not code. Built-ins are `claude` and `shell`
+(a plain terminal, no agent wiring). Override or add profiles in
+`~/.termscape/agents.toml`:
+
+```toml
+[my-agent]
+command = "my-cli"
+args = ["--mcp-config", "{{mcp_config_path}}"]
+status = "heuristic"          # or "hooks", for exact turn boundaries
+ready_hint = "[$#>%] ?$"      # prompt regex, for the idle indicator
+inject = "bracketed"          # bracketed paste, or "raw"
+```
+
+## State and restart
+
+SQLite at `~/.termscape/state.db` holds everything needed to redraw the canvas
+and relaunch every agent. It deliberately does not hold conversation history —
+Claude Code already keeps that, and we store the pointer to it.
+
+Kill the hub and start it again: the canvas comes back with its window
+positions, its zoom, and each terminal's last screen, with the sessions marked
+stopped. **Resume** relaunches an agent with `--resume`, continuing its prior
+conversation.
+
+Two consequences worth knowing:
+
+- Only the **last screen** of each terminal survives a restart. Scrollback above
+  it is not persisted. (While the hub is running, full scrollback is held in
+  memory and replayed when you zoom back into a window.)
+- Resume relaunches in the **same working directory**, because that is how
+  Claude Code finds a conversation. Move the folder and resume starts fresh.
+
+## Remote machines
+
+Add a machine in the panel. The hub is copied over SSH, installed, and started as a
+detached daemon bound to the remote machine's loopback interface, reached only
+through an SSH tunnel. Because it is a daemon and not an `ssh` subprocess,
+remote agents keep running when the connection drops, and reattach with their
+state when it comes back.
+
+The remote host needs Node 22+ and a toolchain able to build `node-pty` and
+`better-sqlite3`.
+
+## Security
+
+Agents can type into each other's terminals and spawn more agents. That is the
+feature, and it is the risk surface: an agent that reads a hostile repository
+could be talked into sending an attacker's text to a peer.
+
+- The hub binds `127.0.0.1` only, never a network interface. Remote hubs too.
+- Every agent gets its own bearer token. The sender of a message is taken from
+  that token, never from the arguments, so attribution cannot be forged.
+- Messages are length-capped, rate-limited per sender, and always arrive with a
+  visible `[from <address>]` prefix.
+- Every delivery attempt is recorded with its outcome and shown in the message
+  log. Nothing is delivered invisibly.
+- `spawn_agent` is capped per workspace, so a confused agent cannot recurse the
+  machine to death.
+- An agent may only stop agents it spawned.
+- `--dangerously-skip-permissions` is never a default.
+
+## Development
+
+From a clone, rather than the published package:
+
+```bash
+git clone https://github.com/kdonev/termscape.git
+cd termscape
+npm install
+npm run build
+npm run dev           # hub with the built UI
+```
+
+If `npm install` or `npm ci` tries to compile `better-sqlite3` and fails for
+want of a C++ toolchain, install this way instead:
+
+```bash
+npm ci --ignore-scripts && npm rebuild node-pty
+```
+
+Any install that reads `package-lock.json` misses better-sqlite3's
+`gypfile: false` and runs `node-gyp` on a module that already ships working
+prebuilds. Skipping install scripts avoids that; the rebuild puts back the one
+native build that is real, which is a no-op except on Linux. This is what CI
+does. It does not affect anyone installing the published package.
+
+```bash
+npm test              # unit + integration, no LLM required
+npm run typecheck
+npm run dev:web       # vite dev server, expects a hub on :7777
+```
+
+The integration tests spawn real PTYs and drive the real MCP endpoint, so
+`npm test` genuinely exercises message delivery and cross-host routing.
+
+### Known quirks
+
+- On Windows, node-pty prints `AttachConsole failed` to stderr when killing a
+  PTY from a process with no console attached (notably under the test runner).
+  It is noise from a helper process and does not affect behaviour.
+
+### Releasing
+
+The repo is a workspace of three private packages; what gets published is a
+single package assembled by `packages/hub/scripts/pack-npm.mjs` — the hub,
+the built UI it serves, and `@termscape/protocol` bundled inside it.
+
+```bash
+npm run pack:npm      # build everything, then stage and pack the tarball
+```
+
+Tagging `v<version>` runs `.github/workflows/release.yml`, which refuses a
+tag that disagrees with `packages/hub/package.json`, installs the packed
+tarball on macOS, Windows and Linux and checks each one starts and serves the
+canvas, and only then publishes to npm with provenance. Bump the version in
+`packages/hub/package.json` **and** `HUB_VERSION` in `packages/hub/src/hub.ts`
+together — peer compatibility is gated on the constant, and a test fails if
+the two drift.
+
+## License
+
+MIT — see [LICENSE](LICENSE).

package/dist/agents/env.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Environment sanitizing for spawned agents.
+ *
+ * Agents inherit the hub's environment so they can find their tools and
+ * credentials. But when the hub itself is launched from inside an agent CLI —
+ * which is not exotic; it is how you would develop this app — that parent's
+ * private session state is in the environment too, and inheriting it is
+ * actively harmful:
+ *
+ *   CLAUDE_CODE_CHILD_SESSION   marks the child as a sub-session, which turns
+ *                               transcript saving OFF. Since --resume reads
+ *                               that transcript, inheriting this silently
+ *                               breaks the resume feature entirely.
+ *   CLAUDE_CODE_MESSAGING_SOCKET / _TOKEN
+ *                               the parent session's private IPC channel. A
+ *                               spawned agent must not be handed it.
+ *   CLAUDE_CODE_SESSION_ID / _HOST_SESSION_ID / CLAUDE_PID
+ *                               identify the parent run; a child adopting them
+ *                               confuses session bookkeeping on both sides.
+ *
+ * So anything that identifies the *parent agent process* is stripped, while
+ * ordinary user configuration (PATH, HOME, ANTHROPIC_API_KEY, proxy settings)
+ * is passed through untouched.
+ */
+export declare function shouldStrip(name: string): boolean;
+/**
+ * Base environment for a spawned agent: the hub's environment minus the
+ * parent-session variables, plus the profile's own overrides.
+ *
+ * Profile overrides win, so a profile can deliberately re-add something that
+ * would otherwise be stripped.
+ */
+export declare function buildAgentEnv(base: NodeJS.ProcessEnv, overrides?: Record<string, string>): Record<string, string>;
+/** Names that were removed, for logging and for the tests to assert on. */
+export declare function strippedNames(base: NodeJS.ProcessEnv): string[];
+//# sourceMappingURL=env.d.ts.map

package/dist/agents/env.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"env.d.ts","sourceRoot":"","sources":["../../src/agents/env.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAYH,wBAAgB,WAAW,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAIjD;AAED;;;;;;GAMG;AACH,wBAAgB,aAAa,CAC3B,IAAI,EAAE,MAAM,CAAC,UAAU,EACvB,SAAS,GAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAM,GACrC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAQxB;AAED,2EAA2E;AAC3E,wBAAgB,aAAa,CAAC,IAAI,EAAE,MAAM,CAAC,UAAU,GAAG,MAAM,EAAE,CAE/D"}

package/dist/agents/env.js

@@ -0,0 +1,61 @@
+/**
+ * Environment sanitizing for spawned agents.
+ *
+ * Agents inherit the hub's environment so they can find their tools and
+ * credentials. But when the hub itself is launched from inside an agent CLI —
+ * which is not exotic; it is how you would develop this app — that parent's
+ * private session state is in the environment too, and inheriting it is
+ * actively harmful:
+ *
+ *   CLAUDE_CODE_CHILD_SESSION   marks the child as a sub-session, which turns
+ *                               transcript saving OFF. Since --resume reads
+ *                               that transcript, inheriting this silently
+ *                               breaks the resume feature entirely.
+ *   CLAUDE_CODE_MESSAGING_SOCKET / _TOKEN
+ *                               the parent session's private IPC channel. A
+ *                               spawned agent must not be handed it.
+ *   CLAUDE_CODE_SESSION_ID / _HOST_SESSION_ID / CLAUDE_PID
+ *                               identify the parent run; a child adopting them
+ *                               confuses session bookkeeping on both sides.
+ *
+ * So anything that identifies the *parent agent process* is stripped, while
+ * ordinary user configuration (PATH, HOME, ANTHROPIC_API_KEY, proxy settings)
+ * is passed through untouched.
+ */
+/** Exact names that must never reach a spawned agent. */
+const STRIP_EXACT = new Set(['CLAUDECODE', 'CLAUDE_PID', 'CLAUDE_EFFORT']);
+/** Prefixes whose whole family is parent-session state. */
+const STRIP_PREFIXES = [
+    'CLAUDE_CODE_',
+    'CLAUDE_AGENT_SDK_',
+    'CLAUDE_PREVIEW_',
+];
+export function shouldStrip(name) {
+    const upper = name.toUpperCase();
+    if (STRIP_EXACT.has(upper))
+        return true;
+    return STRIP_PREFIXES.some((p) => upper.startsWith(p));
+}
+/**
+ * Base environment for a spawned agent: the hub's environment minus the
+ * parent-session variables, plus the profile's own overrides.
+ *
+ * Profile overrides win, so a profile can deliberately re-add something that
+ * would otherwise be stripped.
+ */
+export function buildAgentEnv(base, overrides = {}) {
+    const out = {};
+    for (const [k, v] of Object.entries(base)) {
+        if (v === undefined)
+            continue;
+        if (shouldStrip(k))
+            continue;
+        out[k] = v;
+    }
+    return { ...out, ...overrides };
+}
+/** Names that were removed, for logging and for the tests to assert on. */
+export function strippedNames(base) {
+    return Object.keys(base).filter(shouldStrip).sort();
+}
+//# sourceMappingURL=env.js.map

package/dist/agents/env.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"env.js","sourceRoot":"","sources":["../../src/agents/env.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAEH,yDAAyD;AACzD,MAAM,WAAW,GAAG,IAAI,GAAG,CAAC,CAAC,YAAY,EAAE,YAAY,EAAE,eAAe,CAAC,CAAC,CAAC;AAE3E,2DAA2D;AAC3D,MAAM,cAAc,GAAG;IACrB,cAAc;IACd,mBAAmB;IACnB,iBAAiB;CAClB,CAAC;AAEF,MAAM,UAAU,WAAW,CAAC,IAAY;IACtC,MAAM,KAAK,GAAG,IAAI,CAAC,WAAW,EAAE,CAAC;IACjC,IAAI,WAAW,CAAC,GAAG,CAAC,KAAK,CAAC;QAAE,OAAO,IAAI,CAAC;IACxC,OAAO,cAAc,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,KAAK,CAAC,UAAU,CAAC,CAAC,CAAC,CAAC,CAAC;AACzD,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,aAAa,CAC3B,IAAuB,EACvB,YAAoC,EAAE;IAEtC,MAAM,GAAG,GAA2B,EAAE,CAAC;IACvC,KAAK,MAAM,CAAC,CAAC,EAAE,CAAC,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,IAAI,CAAC,EAAE,CAAC;QAC1C,IAAI,CAAC,KAAK,SAAS;YAAE,SAAS;QAC9B,IAAI,WAAW,CAAC,CAAC,CAAC;YAAE,SAAS;QAC7B,GAAG,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC;IACb,CAAC;IACD,OAAO,EAAE,GAAG,GAAG,EAAE,GAAG,SAAS,EAAE,CAAC;AAClC,CAAC;AAED,2EAA2E;AAC3E,MAAM,UAAU,aAAa,CAAC,IAAuB;IACnD,OAAO,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,MAAM,CAAC,WAAW,CAAC,CAAC,IAAI,EAAE,CAAC;AACtD,CAAC"}

package/dist/agents/profiles.d.ts

@@ -0,0 +1,45 @@
+import type { InjectMode } from '../protocol/index.js';
+/**
+ * An agent profile describes how to launch one kind of CLI and how to talk to
+ * it. Adding a new agent CLI should be a config change, not a code change.
+ */
+export interface AgentProfile {
+    id: string;
+    description: string;
+    command: string;
+    args: string[];
+    env: Record<string, string>;
+    /** false = plain terminal: no MCP wiring, no brief, no agent identity. */
+    mcp: boolean;
+    /** How busy/idle is determined. */
+    status: 'hooks' | 'heuristic';
+    /** Regex matched against the last non-empty line when status = heuristic. */
+    readyHint?: string;
+    inject: InjectMode;
+    /**
+     * Argument template used to bring a session back with its prior
+     * conversation. `{{uuid}}` is replaced with agent_session_uuid. When absent,
+     * the profile is not resumable and restarts clean.
+     */
+    resumeArgs?: string[];
+}
+/**
+ * Built-in profiles. All Claude Code flags here are verified against the CLI:
+ * --mcp-config, --strict-mcp-config, --session-id, --settings,
+ * --append-system-prompt-file, --resume.
+ */
+export declare const BUILTIN_PROFILES: Record<string, AgentProfile>;
+export declare class ProfileRegistry {
+    private profiles;
+    constructor(profiles?: Record<string, AgentProfile>);
+    /** Built-ins, overlaid with ~/.termscape/agents.toml if present. */
+    static load(): ProfileRegistry;
+    get(id: string): AgentProfile | null;
+    require(id: string): AgentProfile;
+    list(): AgentProfile[];
+    isResumable(id: string): boolean;
+}
+/** Replace `{{key}}` placeholders. Unknown placeholders are left untouched. */
+export declare function template(input: string, vars: Record<string, string>): string;
+export declare function templateAll(args: string[], vars: Record<string, string>): string[];
+//# sourceMappingURL=profiles.d.ts.map

package/dist/agents/profiles.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"profiles.d.ts","sourceRoot":"","sources":["../../src/agents/profiles.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,qBAAqB,CAAC;AAGtD;;;GAGG;AACH,MAAM,WAAW,YAAY;IAC3B,EAAE,EAAE,MAAM,CAAC;IACX,WAAW,EAAE,MAAM,CAAC;IACpB,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,EAAE,MAAM,EAAE,CAAC;IACf,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC5B,0EAA0E;IAC1E,GAAG,EAAE,OAAO,CAAC;IACb,mCAAmC;IACnC,MAAM,EAAE,OAAO,GAAG,WAAW,CAAC;IAC9B,6EAA6E;IAC7E,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,MAAM,EAAE,UAAU,CAAC;IACnB;;;;OAIG;IACH,UAAU,CAAC,EAAE,MAAM,EAAE,CAAC;CACvB;AAOD;;;;GAIG;AACH,eAAO,MAAM,gBAAgB,EAAE,MAAM,CAAC,MAAM,EAAE,YAAY,CA8CzD,CAAC;AAEF,qBAAa,eAAe;IAC1B,OAAO,CAAC,QAAQ,CAA+B;gBAEnC,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,YAAY,CAAC;IAInD,oEAAoE;IACpE,MAAM,CAAC,IAAI,IAAI,eAAe;IA8B9B,GAAG,CAAC,EAAE,EAAE,MAAM,GAAG,YAAY,GAAG,IAAI;IAIpC,OAAO,CAAC,EAAE,EAAE,MAAM,GAAG,YAAY;IAMjC,IAAI,IAAI,YAAY,EAAE;IAItB,WAAW,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO;CAIjC;AAED,+EAA+E;AAC/E,wBAAgB,QAAQ,CAAC,KAAK,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,MAAM,CAI5E;AAED,wBAAgB,WAAW,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,MAAM,EAAE,CAElF"}

package/dist/agents/profiles.js

@@ -0,0 +1,123 @@
+import { readFileSync, existsSync } from 'node:fs';
+import { platform } from 'node:process';
+import { parse as parseToml } from 'smol-toml';
+import { paths } from '../paths.js';
+function defaultShell() {
+    if (platform === 'win32')
+        return process.env.COMSPEC ?? 'powershell.exe';
+    return process.env.SHELL ?? '/bin/bash';
+}
+/**
+ * Built-in profiles. All Claude Code flags here are verified against the CLI:
+ * --mcp-config, --strict-mcp-config, --session-id, --settings,
+ * --append-system-prompt-file, --resume.
+ */
+export const BUILTIN_PROFILES = {
+    claude: {
+        id: 'claude',
+        description: 'Claude Code, wired to the hub MCP endpoint',
+        command: 'claude',
+        args: [
+            '--mcp-config',
+            '{{mcp_config_path}}',
+            '--strict-mcp-config',
+            '--session-id',
+            '{{session_uuid}}',
+            '--settings',
+            '{{settings_path}}',
+            '--append-system-prompt-file',
+            '{{brief_path}}',
+        ],
+        env: {},
+        mcp: true,
+        status: 'hooks',
+        inject: 'bracketed',
+        // Resume swaps --session-id for --resume; everything else is re-templated
+        // identically, and crucially the session is relaunched in the same cwd,
+        // because Claude Code keys its conversation store by working directory.
+        resumeArgs: [
+            '--mcp-config',
+            '{{mcp_config_path}}',
+            '--strict-mcp-config',
+            '--resume',
+            '{{session_uuid}}',
+            '--settings',
+            '{{settings_path}}',
+            '--append-system-prompt-file',
+            '{{brief_path}}',
+        ],
+    },
+    shell: {
+        id: 'shell',
+        description: 'Plain terminal, no agent wiring',
+        command: defaultShell(),
+        args: [],
+        env: {},
+        mcp: false,
+        status: 'heuristic',
+        readyHint: '[$#>%] ?$',
+        inject: 'raw',
+    },
+};
+export class ProfileRegistry {
+    profiles;
+    constructor(profiles) {
+        this.profiles = profiles ?? { ...BUILTIN_PROFILES };
+    }
+    /** Built-ins, overlaid with ~/.termscape/agents.toml if present. */
+    static load() {
+        const merged = { ...BUILTIN_PROFILES };
+        const file = paths.profiles();
+        if (existsSync(file)) {
+            try {
+                const raw = parseToml(readFileSync(file, 'utf8'));
+                for (const [id, v] of Object.entries(raw)) {
+                    if (typeof v !== 'object' || v === null)
+                        continue;
+                    const base = merged[id];
+                    merged[id] = {
+                        id,
+                        description: v.description ?? base?.description ?? id,
+                        command: v.command ?? base?.command ?? id,
+                        args: v.args ?? base?.args ?? [],
+                        env: v.env ?? base?.env ?? {},
+                        mcp: v.mcp ?? base?.mcp ?? true,
+                        status: v.status ?? base?.status ?? 'heuristic',
+                        readyHint: v.ready_hint ?? v.readyHint ?? base?.readyHint,
+                        inject: v.inject ?? base?.inject ?? 'bracketed',
+                        resumeArgs: v.resume_args ?? v.resumeArgs ?? base?.resumeArgs,
+                    };
+                }
+            }
+            catch (err) {
+                // A broken config must not take the hub down; fall back to built-ins.
+                console.error(`[profiles] ignoring ${file}: ${err.message}`);
+            }
+        }
+        return new ProfileRegistry(merged);
+    }
+    get(id) {
+        return this.profiles[id] ?? null;
+    }
+    require(id) {
+        const p = this.get(id);
+        if (!p)
+            throw new Error(`unknown agent profile "${id}"`);
+        return p;
+    }
+    list() {
+        return Object.values(this.profiles);
+    }
+    isResumable(id) {
+        const p = this.get(id);
+        return !!p?.resumeArgs;
+    }
+}
+/** Replace `{{key}}` placeholders. Unknown placeholders are left untouched. */
+export function template(input, vars) {
+    return input.replace(/\{\{(\w+)\}\}/g, (whole, key) => key in vars ? vars[key] : whole);
+}
+export function templateAll(args, vars) {
+    return args.map((a) => template(a, vars));
+}
+//# sourceMappingURL=profiles.js.map

package/dist/agents/profiles.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"profiles.js","sourceRoot":"","sources":["../../src/agents/profiles.ts"],"names":[],"mappings":"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"}

package/dist/agents/resolve.d.ts

@@ -0,0 +1,16 @@
+/** Absolute path to `command`, or null when it is not on PATH. */
+export declare function which(command: string): string | null;
+export interface ResolvedCommand {
+    argv: string[];
+    /** The executable that was found, before any shell wrapping. */
+    resolved: string;
+}
+/**
+ * Turn a profile's (command, args) into an argv node-pty can actually spawn.
+ *
+ * Windows batch shims (.cmd/.bat) are not executable images, so CreateProcess
+ * refuses them. Many CLIs installed via npm are exactly that, so those get
+ * wrapped in `cmd.exe /c`.
+ */
+export declare function resolveCommand(command: string, args: string[]): ResolvedCommand;
+//# sourceMappingURL=resolve.d.ts.map

package/dist/agents/resolve.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"resolve.d.ts","sourceRoot":"","sources":["../../src/agents/resolve.ts"],"names":[],"mappings":"AA4BA,kEAAkE;AAClE,wBAAgB,KAAK,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAuBpD;AAED,MAAM,WAAW,eAAe;IAC9B,IAAI,EAAE,MAAM,EAAE,CAAC;IACf,gEAAgE;IAChE,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED;;;;;;GAMG;AACH,wBAAgB,cAAc,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,GAAG,eAAe,CAgB/E"}