Three One Four

https://github.com/weshipwork/threeonefour
Admin
Three One Four is a pnpm monorepo for Pi extensions providing Herdr integration, read-only...
Tokens:89,228
Snippets:554
Trust Score:4.3
License:MIT
Update:1 month ago
Show doc for...
Tokens:
Raw
### Run mise setup

Source: https://github.com/weshipwork/threeonefour/blob/main/README.md

Installs the pinned Node.js, pnpm, and hook tools, then enables the tracked hk hooks for the checkout.

```sh
mise run setup
```

--------------------------------

### MirrorRuntime setup in createPiHerdExtension

Source: https://github.com/weshipwork/threeonefour/blob/main/_autodocs/api-reference/pi-herd.md

Code executed on session_start to create a Unix socket path, instantiate the MirrorServer and HerdrMirrorPaneLauncher, and start the MirrorRuntime. Requires HERDR_ENV and HERDR_PANE_ID to be present.

```typescript
const socketPath = join(tmpdir(), `pi-herd-${process.pid}-${Date.now()}.sock`);
const server = new MirrorServer({ socketPath });
const launcher = new HerdrMirrorPaneLauncher({ pi, currentPaneId });
runtime = new MirrorRuntime({ source, server, launcher, socketPath });
await runtime.start();
```

--------------------------------

### Install from a local checkout

Source: https://github.com/weshipwork/threeonefour/blob/main/packages/pi-subagents/README.md

Installs from a local checkout, including commands to install the package and run the source file.

```sh
pi install ./packages/pi-subagents
pi -e ./packages/pi-subagents/src/index.ts
```

--------------------------------

### Install into project settings with pi install -l

Source: https://github.com/weshipwork/threeonefour/blob/main/packages/pi-herdr/README.md

Installs into project settings (.pi/settings.json) so trusted project sessions auto-install it on startup.

```sh
pi install -l npm:@weshipwork/pi-herdr
```

--------------------------------

### start

Source: https://github.com/weshipwork/threeonefour/blob/main/_autodocs/api-reference/pi-herd.md

Starts the MirrorServer. Creates the parent directory, removes any stale socket, and listens. Rejects with the listen error if binding fails.

```APIDOC
## start

### Description
Starts the MirrorServer. Creates the parent directory, removes any stale socket, and listens. Rejects with the listen error if binding fails.

### Method
start

### Signature
`async start(): Promise<void>`

### Parameters
None

### Returns
`Promise<void>` - Resolves when the server is listening.

### Errors
Rejects with the listen error if binding fails.
```

--------------------------------

### Install both packages in the Delegator Pi session

Source: https://github.com/weshipwork/threeonefour/blob/main/packages/pi-subagents/README.mirror.md

Install @weshipwork/pi-subagents and @weshipwork/pi-herd in the Delegator Pi session using the pi install command.

```sh
pi install npm:@weshipwork/pi-subagents
pi install npm:@weshipwork/pi-herd
```

--------------------------------

### Install from local checkout

Source: https://github.com/weshipwork/threeonefour/blob/main/README.md

Installs from a local checkout of the monorepo.

```sh
pi install ./packages/pi-herdr
pi install ./packages/pi-subagents
pi install ./packages/pi-herd
```

--------------------------------

### Install globally with pi install

Source: https://github.com/weshipwork/threeonefour/blob/main/packages/pi-herdr/README.md

Installs the extension globally for user settings (~/.pi/agent/settings.json).

```sh
pi install npm:@weshipwork/pi-herdr
```

--------------------------------

### Install both packages for project-local settings

Source: https://github.com/weshipwork/threeonefour/blob/main/packages/pi-subagents/README.mirror.md

Install @weshipwork/pi-subagents and @weshipwork/pi-herd locally for the project using the -l flag.

```sh
pi install -l npm:@weshipwork/pi-subagents
pi install -l npm:@weshipwork/pi-herd
```

--------------------------------

### Clone and install dependencies

Source: https://github.com/weshipwork/threeonefour/blob/main/README.md

Clones the repository and installs dependencies with pnpm.

```sh
git clone https://github.com/WeShipWork/threeonefour.git
cd threeonefour
pnpm install
```

--------------------------------

### Install into project settings

Source: https://github.com/weshipwork/threeonefour/blob/main/packages/pi-subagents/README.md

Installs the package locally for project settings with the -l flag.

```sh
pi install -l npm:@weshipwork/pi-subagents
```

--------------------------------

### AgentManager usage example

Source: https://github.com/weshipwork/threeonefour/blob/main/_autodocs/api-reference/agent-manager.md

Shows how to instantiate AgentManager with a callback and max concurrency, spawn an agent with options, check its status, abort it if running, wait for all agents to finish, and dispose the manager. The spawn call returns an ID and the agent starts as 'queued' or 'running'.

```typescript
import { AgentManager } from "@weshipwork/pi-subagents/src/agent-manager.js"; // path import from a checkout

const manager = new AgentManager(
  (record) => console.log(`[demo] ${record.description} → ${record.status}`),
  4, // max concurrent
);

const id = manager.spawn(pi, ctx, "Explore", "Map the API routes", {
  description: "Map API routes",
  run_in_background: true,
  maxTurns: 10,
});
console.log("spawned", id); // "queued" or "running"

// later
if (manager.getRecord(id)?.status === "running") manager.abort(id);
await manager.waitForAll();
manager.dispose();
```

--------------------------------

### Install globally for user settings

Source: https://github.com/weshipwork/threeonefour/blob/main/packages/pi-subagents/README.md

Installs the package globally for user settings.

```sh
pi install npm:@weshipwork/pi-subagents
```

--------------------------------

### Persistence and Worktree Usage Example

Source: https://github.com/weshipwork/threeonefour/blob/main/_autodocs/api-reference/persistence.md

Demonstrates initializing an output file, streaming session data, and managing a git worktree for agent tasks.

```ts
import { createOutputFilePath, writeInitialEntry, streamToOutputFile } from "@weshipwork/pi-subagents/src/output-file.js";
import { createWorktree, cleanupWorktree } from "@weshipwork/pi-subagents/src/worktree.js";

const out = createOutputFilePath(cwd, agentId, sessionId);
writeInitialEntry(out, agentId, "Do the thing", cwd);
const cleanupStream = streamToOutputFile(session, out, agentId, cwd);

const wt = createWorktree(cwd, agentId);           // undefined outside a git repo
if (wt) {
  console.log("agent works at", wt.workPath, "branch", wt.branch);
  const result = cleanupWorktree(cwd, wt, "my task");
  // result.hasChanges → branch "pi-agent-<id>" holds the committed work
}
cleanupStream();
```

--------------------------------

### Mirror protocol example transcripts

Source: https://github.com/weshipwork/threeonefour/blob/main/_autodocs/endpoints.md

Example transcripts showing the subscribe payload, immediate snapshot, and live events exchanged over the Mirror socket.

```text
# subscribe payload written by the viewer
{"agentId":"a1b2c3d4e5f6789"}

# immediate snapshot (if one exists)
{"type":"snapshot","agent":{"id":"a1b2c3d4e5f6789","type":"Explore","description":"find auth","status":"running","assistantText":"Looking for auth files…","updatedAt":1750000000000},"sequence":0}

# live events
{"type":"status","agentId":"a1b2c3d4e5f6789","status":"running","sequence":1}
{"type":"assistant_text_delta","agentId":"a1b2c3d4e5f6789","delta":"Found 5 files","sequence":2}
{"type":"status","agentId":"a1b2c3d4e5f6789","status":"completed","sequence":3}
```

--------------------------------

### Usage example with subagent prompts and model resolution

Source: https://github.com/weshipwork/threeonefour/blob/main/_autodocs/api-reference/prompting.md

Shows how to call `buildAgentPrompt`, `buildParentContext`, `resolveModel`, and the enabled-model helpers together. The example passes a config, cwd, Git context, and parent prompt, then resolves a model by name (logging a warning if not found) and checks whether a specific model is in scope.

```typescript
import { buildAgentPrompt } from "@weshipwork/pi-subagents/src/prompts.js";
import { buildParentContext } from "@weshipwork/pi-subagents/src/context.js";
import { resolveModel } from "@weshipwork/pi-subagents/src/model-resolver.js";
import { isModelInScope, readEnabledModels, resolveEnabledModels } from "@weshipwork/pi-subagents/src/enabled-models.js";

const prompt = buildAgentPrompt(cfg, cwd, { isGitRepo: true, branch: "main", platform: "linux" }, parentPrompt, {
  memoryBlock: "…",
  skillBlocks: [{ name: "api-conventions", content: "…" }],
});

const inherited = buildParentContext(ctx); // "" when the branch is empty

const resolved = resolveModel("haiku", ctx.modelRegistry);
if (typeof resolved === "string") console.warn(resolved); // "Model not found: ..."
else console.log(resolved.id);

const allowed = resolveEnabledModels(readEnabledModels(cwd), ctx.modelRegistry, cwd);
if (allowed && !isModelInScope({ provider: "anthropic", id: "claude-opus-4-6" }, allowed)) {
  console.warn("out of scope");
}
```

--------------------------------

### Install pi-subagents, pi-herd, and pi-herdr globally

Source: https://github.com/weshipwork/threeonefour/blob/main/packages/pi-herd/README.md

Installs the required packages globally for user settings (~/.pi/agent/settings.json).

```sh
pi install npm:@weshipwork/pi-subagents
pi install npm:@weshipwork/pi-herd
pi install npm:@weshipwork/pi-herdr
```

--------------------------------

### Install pi-subagents, pi-herd, and pi-herdr into project settings

Source: https://github.com/weshipwork/threeonefour/blob/main/packages/pi-herd/README.md

Installs the packages into project settings (.pi/settings.json) so trusted project sessions auto-install them on startup.

```sh
pi install -l npm:@weshipwork/pi-subagents
pi install -l npm:@weshipwork/pi-herd
pi install -l npm:@weshipwork/pi-herdr
```

--------------------------------

### AgentManager Usage Example

Source: https://github.com/weshipwork/threeonefour/blob/main/_autodocs/api-reference/agent-manager.md

Example of creating an AgentManager, spawning a subagent, checking its status, aborting it, waiting for all agents to complete, and disposing the manager.

```APIDOC
## AgentManager Usage Example

### Description
Demonstrates how to instantiate an AgentManager, spawn a subagent, monitor its status, abort it if running, wait for all agents to finish, and dispose of the manager.

### Constructor
`new AgentManager(onStatusChange, maxConcurrent)`

- **onStatusChange** (function) - Callback invoked with `(record)` whenever an agent's status changes.
- **maxConcurrent** (number) - Maximum number of concurrently running agents.

### Methods

#### `spawn(pi, ctx, type, description, options)`
- **pi** (object) - The PI instance.
- **ctx** (object) - The context object.
- **type** (string) - The subagent type (e.g., "Explore").
- **description** (string) - A description of the task.
- **options** (object) - Optional settings:
  - **description** (string) - Description of the agent.
  - **run_in_background** (boolean) - Whether to run in background.
  - **maxTurns** (number) - Maximum number of turns.
- Returns: **id** (string) - The agent record ID.

#### `getRecord(id)`
- **id** (string) - The agent record ID.
- Returns: **AgentRecord | undefined** - The agent record or undefined if not found.

#### `abort(id)`
- **id** (string) - The agent record ID.
- Aborts the running agent.

#### `waitForAll()`
- Returns: **Promise<void>** - Resolves when all agents have completed.

#### `dispose()`
- Cleans up resources.

### Example Code
```ts
import { AgentManager } from "@weshipwork/pi-subagents/src/agent-manager.js"; // path import from a checkout

const manager = new AgentManager(
  (record) => console.log(`[demo] ${record.description} → ${record.status}`),
  4, // max concurrent
);

const id = manager.spawn(pi, ctx, "Explore", "Map the API routes", {
  description: "Map API routes",
  run_in_background: true,
  maxTurns: 10,
});
console.log("spawned", id); // "queued" or "running"

// later
if (manager.getRecord(id)?.status === "running") manager.abort(id);
await manager.waitForAll();
manager.dispose();
```
```

--------------------------------

### Default and example scoping configurations

Source: https://github.com/weshipwork/threeonefour/blob/main/packages/pi-subagents/README.md

Shows defaults for both options and several configurations for narrowing or expanding tools and extensions. Note that `tools: "*"` is an alias for `all`, `tools: none` is an alias for `""`, and `extensions: [mcp]` loads only the mcp extension. Array and string forms are equivalent.

```yaml
# Default (both omitted): all extensions load, all 7 built-ins surface

tools: read, grep, find           # narrow to listed built-ins; extensions still load
tools: "*"                        # all 7 built-ins (alias: `all`)
tools: none                       # zero built-ins (alias: `""`)
tools: "*, ext:mcp/search"        # built-ins plus one extension tool

extensions: false                 # no extensions load
extensions: [mcp]                 # only mcp loads
extensions: ["*", "/abs/foo.ts"]  # all defaults plus one path-loaded extension

exclude_extensions: pi-notify     # everything except pi-notify (with extensions: true)

# Specialist: load one extension, expose only one of its tools, keep built-ins
extensions: [mcp]
tools: "*, ext:mcp/search"

isolated: true                    # hermetic: built-ins only, no extensions/skills/context
```

--------------------------------

### Usage example: ConversationViewer with createViewerKeys

Source: https://github.com/weshipwork/threeonefour/blob/main/_autodocs/api-reference/ui.md

Shows how to create viewer keys and open a ConversationViewer overlay. The createViewerKeys call is optional; the overlay is centered with 90% width and a max height based on VIEWPORT_HEIGHT_PCT.

```ts
import { ConversationViewer, VIEWPORT_HEIGHT_PCT } from "@weshipwork/pi-subagents/src/ui/conversation-viewer.js";
import { createViewerKeys } from "@weshipwork/pi-subagents/src/ui/viewer-keys.js";

const keys = createViewerKeys(keybindings); // optional
await ctx.ui.custom<undefined>(
  (tui, theme, kb, done) => new ConversationViewer(tui, session, record, activity, theme, done, onStop, kb),
  { overlay: true, overlayOptions: { anchor: "center", width: "90%", maxHeight: `${VIEWPORT_HEIGHT_PCT}%` } },
);
```

--------------------------------

### Usage example for runAgent, steerAgent, getAgentConversation

Source: https://github.com/weshipwork/threeonefour/blob/main/_autodocs/api-reference/agent-runner.md

Shows how to run an agent with runAgent, then conditionally steer it with steerAgent and retrieve the conversation with getAgentConversation. The example imports from '@weshipwork/pi-subagents/src/agent-runner.js' and uses options like pi, agentId, maxTurns, cwd, and callbacks onToolActivity and onTextDelta.

```TypeScript
import { runAgent, steerAgent, getAgentConversation } from "@weshipwork/pi-subagents/src/agent-runner.js";

const { responseText, session, aborted, steered } = await runAgent(ctx, "Explore", "Find the API routes", {
  pi,
  agentId: "a1b2c3d4",
  maxTurns: 20,
  cwd: "/workspace/myapp",
  onToolActivity: (a) => console.log(a.type, a.toolName),
  onTextDelta: (delta) => process.stdout.write(delta),
});

if (!aborted && !steered) {
  await steerAgent(session, "Now check the auth code too");
  const conversation = getAgentConversation(session);
  console.log(conversation);
}
```

--------------------------------

### Spawn a sub-agent

Source: https://github.com/weshipwork/threeonefour/blob/main/packages/pi-subagents/README.md

Example of using the Agent tool to spawn a sub-agent.

```text
Agent({
  subagent_type: "Explore",
  prompt: "Find all files that handle authentication",
  description: "Find auth files",
  run_in_background: true,
})
```

--------------------------------

### Pin exact npm version with pi install

Source: https://github.com/weshipwork/threeonefour/blob/main/packages/pi-herdr/README.md

Pins an exact npm version for installation.

```sh
pi install npm:@weshipwork/pi-herdr@0.1.0
```

--------------------------------

### Use local checkout with pi install and pi -e

Source: https://github.com/weshipwork/threeonefour/blob/main/packages/pi-herdr/README.md

Uses a local checkout of the package for installation and execution.

```sh
pi install ./packages/pi-herdr
```

```sh
pi -e ./packages/pi-herdr/extensions/herdr.ts
```

--------------------------------

### Usage example for createMirrorEventHub

Source: https://github.com/weshipwork/threeonefour/blob/main/_autodocs/api-reference/mirror.md

Shows how to create a mirror event hub, subscribe to events, publish a status event, and unsubscribe. The listener logs agent snapshot details when an `AGENT_SNAPSHOT` event is received.

```typescript
import { createMirrorEventHub, agentRecordToMirrorSnapshot, PI_SUBAGENTS_MIRROR_EVENT_TYPE } from "@weshipwork/pi-subagents/src/mirror.js";

const hub = createMirrorEventHub(() => manager.listAgents());

const unsubscribe = hub.subscribeToMirrorEvents((event) => {
  if (event.type === PI_SUBAGENTS_MIRROR_EVENT_TYPE.AGENT_SNAPSHOT) {
    console.log(event.agent.id, event.agent.status, event.agent.assistantText.length, "chars");
  }
});

hub.publish({ type: PI_SUBAGENTS_MIRROR_EVENT_TYPE.STATUS, agentId: "abc", status: "running" });
unsubscribe();
```

--------------------------------

### Usage example for spawning an agent via RPC

Source: https://github.com/weshipwork/threeonefour/blob/main/_autodocs/api-reference/rpc.md

Shows how to emit a spawn RPC request and listen for the reply. Uses crypto.randomUUID() for requestId and subscribes to the reply channel before emitting.

```typescript
import { crypto } from "node:crypto";
import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";

export default function (pi: ExtensionAPI) {
  const requestId = crypto.randomUUID();
  const unsubscribe = pi.events.on(`subagents:rpc:spawn:reply:${requestId}`, (raw: unknown) => {
    unsubscribe();
    const reply = raw as { success: boolean; data?: { id: string }; error?: string };
    if (!reply.success) {
      console.error(`spawn failed: ${reply.error}`);
      return;
    }
    console.log(`spawned agent ${reply.data?.id}`);
  });

  pi.events.emit("subagents:rpc:spawn", {
    requestId,
    type: "general-purpose",
    prompt: "Do something useful",
    options: {
      description: "My task",
      run_in_background: true,
      model: "anthropic/claude-haiku-4-5-20251001", // string model accepted
      cwd: "/workspace/myapp",
    },
  });
}
```

--------------------------------

### Global subagents.json defaults example

Source: https://github.com/weshipwork/threeonefour/blob/main/_autodocs/configuration.md

Example global defaults for the pi-subagents settings file. Missing file falls back to defaults; malformed JSON logs '[pi-subagents] Ignoring malformed settings at <path>: <reason>' on stderr and uses defaults; out-of-range values are dropped per-field.

```json
{ "maxConcurrent": 16, "graceTurns": 10 }
```

--------------------------------

### Use a local checkout of pi-subagents and pi-herd

Source: https://github.com/weshipwork/threeonefour/blob/main/packages/pi-herd/README.md

Installs from local package paths and runs with local source files.

```sh
pi install ./packages/pi-subagents
pi install ./packages/pi-herd
pi -e ./packages/pi-subagents/src/index.ts -e ./packages/pi-herd/extensions/herd.ts
```

--------------------------------

### Run root-level package commands

Source: https://github.com/weshipwork/threeonefour/blob/main/AGENTS.md

Run from the repo root. Installs dependencies and runs all package checks, typechecks, and tests where present.

```sh
pnpm install
pnpm check       # all package checks where present
pnpm typecheck   # all package typechecks where present
pnpm test        # all package tests where present
```

--------------------------------

### Set Global Defaults for Max Concurrency and Grace Turns

Source: https://github.com/weshipwork/threeonefour/blob/main/packages/pi-subagents/README.md

Bash commands to create ~/.pi/agent/subagents.json with maxConcurrent 16 and graceTurns 10, setting global defaults that every project starts with. Use the menu to override per project.

```bash
mkdir -p ~/.pi/agent
cat > ~/.pi/agent/subagents.json <<'EOF'
{
  "maxConcurrent": 16,
  "graceTurns": 10
}
EOF
```

--------------------------------

### Tool denylist frontmatter YAML: disallowed_tools

Source: https://github.com/weshipwork/threeonefour/blob/main/packages/pi-subagents/README.md

Frontmatter YAML block that blocks specific tools from an agent, even if provided by extensions. This example disallows 'write' and 'edit' tools.

```yaml
---
tools: read, bash, grep, write
disallowed_tools: write, edit
---
```
Tokens:
Raw