pi-lanes

Background work never blocks the session you type in.

pi runs one turn at a time. Everything an extension triggers (a Teams message in listen mode, a mail hook, a scheduled prompt) is queued into the session you are working in, and waits for whatever runs there. A twenty-minute task for one colleague means twenty minutes of silence for everyone else.

pi-lanes takes those prompts off your session and runs each in a lane: a pi --mode rpc process with a session of its own.

you ──typing──▶ front session (pi in the terminal)
                   │
extension prompt ──┼──▶ lane "teams:Anna"  pi --mode rpc, own session ──▶ subagents …
                   ├──▶ lane "teams:Bob"   pi --mode rpc, own session
                   └──▶ one-off lane        pi --mode rpc, ends when done

Installation

pi install npm:@patimweb/pi-lanes

No configuration needed. Settings go in ~/.pi/agent/pi-lanes.json.

What goes where

Within a lane, order is kept: a prompt for a lane that is busy is steered into the running turn and read after the current step. Different lanes run in parallel, up to maxConcurrent; more wait in line.

Lanes do not chain

Only the interactive terminal session routes. Every lane is started with PI_LANE in its environment, and every process a lane starts (a subagent, a tool, another pi) inherits it. A prompt an extension sends inside a lane stays in that lane. So the depth is fixed: front session, lane, and what the lane itself starts.

For extension authors: hints

Emit a hint on pi's event bus right before sending the prompt:

const prompt = buildPrompt(message);
pi.events.emit("pi-lanes:route", {
  text: prompt,                       // exactly what goes to sendUserMessage
  lane: `mychat:${conversationId}`,   // same key, same lane and session
  label: "Anna Schmidt",
  env: { MY_EXTENSION_CONVERSATION: conversationId },
  command: normalisedMessageText,     // for stop and reset words
  request: shortFormForTheJournal,
  from: "Anna Schmidt",
  trusted: false,                     // may this lane read lanes_journal?
});
pi.sendUserMessage(prompt, { deliverAs: "followUp" });

Nothing listens when pi-lanes is not installed, and the prompt takes the usual way into the session: the hint needs no dependency on this package.

env is how an extension tells the process in the lane what it is for. pi-teams sets PI_TEAMS_WORKER_CHAT, and in a process with that variable it refuses to write to any other chat and never starts its own watcher.

Control words

When a hint carries a command that is exactly one of these words:

Settings

~/.pi/agent/pi-lanes.json, every key optional:

Isolation

Separate sessions keep a lane from knowing what other lanes talked about. Isolation keeps it from looking: a lane asked "what did Bob want?" can say that Bob was around, but not what about.

Always on, without configuration:

• <agent dir>/pi-lanes is closed to every lane and every process it starts: sessions, journal, nothing of it can be read through a tool.
• lanes_journal shows who and when in a lane: which lane, for whom, at what time, how long. What was asked and answered only in the front session and in lanes started as trusted.

Configurable in isolation:

"isolation": {
  "lane":     { "allowedTools": ["subagent", "teams_send_chat_message", "teams_read_chat", "lanes_journal"] },
  "children": { "blockedTools": ["teams_*", "subagent"] },
  "ownLane":  { "teams_read_chat": { "param": "chat", "env": "PI_TEAMS_WORKER_CHAT" } },
  "protectedPaths": ["~/.pi"],
  "workspace": "/workspace/lanes"
}

A lane and its children are told apart by PI_LANE_CHILD: the lane puts its pid there when it loads, and everything it starts inherits it. A hint's env cannot set any PI_LANE* variable.

How far it goes. Tool lists and ownLane are exact. Paths are checked in two ways: path arguments are resolved (symlinks included), and every other string argument, a bash command above all, is searched for the protected paths in their usual spellings (absolute, ~/, $HOME/). A command that assembles a path at run time gets past that search. It is a guard rail against a model that was talked into looking, not a sandbox. Where that matters, run lanes as an OS user of their own.

Commands and tools

Files, all below ~/.pi/agent/pi-lanes/:

With isolation.workspace set, lanes work in <workspace>/<hash>; the hash is the same as for the sessions.

Things to know

• Nobody sits in front of a lane. Dialogs (confirm, select, …) are cancelled. An extension that asks before acting has to be configured to act on its own, or it will refuse in a lane.
• Lanes are RPC processes, so ctx.hasUI is true in them. An extension that starts background loops on hasUI (a scheduler, a poller) would start them in every lane. Check ctx.mode === "tui" instead, or pass an environment variable through env that switches the loop off.
• Context is per lane. Nothing from one lane reaches another by itself. Shared memory extensions still work across lanes, since they read the same files: close their tools with lane.allowedTools (and children.blockedTools) when lanes belong to different people.

License

MIT