@trim21/personal-pi-extensions 0.0.208 → 0.0.210
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/package.json +1 -1
- package/src/bwrap/index.ts +87 -25
- package/src/lib/cli-args.ts +116 -0
- package/src/lib/cli.ts +340 -0
- package/src/talk/core.ts +72 -70
- package/src/talk/format.ts +14 -15
- package/src/talk/group.ts +11 -14
- package/src/talk/index.ts +156 -84
- package/src/talk/mailbox.ts +27 -6
- package/src/talk/policy.ts +1 -1
- package/src/talk/registry.ts +50 -27
- package/src/talk/skills/multi-agent-dev/SKILL.md +27 -26
- package/src/talk/storage.ts +1 -1
|
@@ -1,21 +1,21 @@
|
|
|
1
1
|
---
|
|
2
2
|
name: multi-agent-dev
|
|
3
|
-
description: Coordinate multi-agent development across pi
|
|
3
|
+
description: Coordinate multi-agent development across pi agents using the talk extension. Explains how agents discover and address each other, when to use talk-send vs talk-ask, and how to split work, exchange information, and review between agents. Use whenever you need to collaborate with other agents on the same machine.
|
|
4
4
|
---
|
|
5
5
|
|
|
6
6
|
# Multi-Agent Development with Talk
|
|
7
7
|
|
|
8
8
|
## Concept
|
|
9
9
|
|
|
10
|
-
Multi-agent development runs several independent pi
|
|
10
|
+
Multi-agent development runs several independent pi agents in parallel and coordinates them over **talk**. Every agent is a complete workspace — its own cwd, conversation history, and context. Talk lets agents discover each other, exchange messages, ask questions, and sync progress.
|
|
11
11
|
|
|
12
|
-
The core rule: **a peer only knows what you tell it.** Messages must be self-contained — background, goal, and constraints — because the receiving
|
|
12
|
+
The core rule: **a peer only knows what you tell it.** Messages must be self-contained — background, goal, and constraints — because the receiving agent has none of your context.
|
|
13
13
|
|
|
14
|
-
##
|
|
14
|
+
## Agent model
|
|
15
15
|
|
|
16
16
|
### Discovery and addressing
|
|
17
17
|
|
|
18
|
-
- `talk-list-
|
|
18
|
+
- `talk-list-agents` returns agents as JSON — **your own agent is included and marked `self: true`** (also where you learn your own id):
|
|
19
19
|
|
|
20
20
|
```json
|
|
21
21
|
[
|
|
@@ -29,55 +29,56 @@ The core rule: **a peer only knows what you tell it.** Messages must be self-con
|
|
|
29
29
|
]
|
|
30
30
|
```
|
|
31
31
|
|
|
32
|
-
- Addressing is **by
|
|
33
|
-
- An unknown or invisible target is refused with `Unknown
|
|
32
|
+
- Addressing is **by agent id only**: `talk-send` / `talk-ask` take the full `id` (pi agent uuid). Names, paths, and prefixes are not accepted.
|
|
33
|
+
- An unknown or invisible target is refused with `Unknown agent id` — always list before sending.
|
|
34
34
|
|
|
35
35
|
### Status
|
|
36
36
|
|
|
37
37
|
- `idle` / `working` (agent actively running) / `waiting-talk-message` (blocked in `talk-ask` waiting for a reply)
|
|
38
38
|
- `offline` (process exited or marked dead)
|
|
39
|
-
- `talk-list-
|
|
39
|
+
- `talk-list-agents` lists every visible agent — live or offline — with its current status.
|
|
40
40
|
|
|
41
41
|
### Visibility
|
|
42
42
|
|
|
43
|
-
- Visibility is fully group-driven:
|
|
43
|
+
- Visibility is fully group-driven: an agent in a group sees only its co-members; an agent in no group sees only itself. Ungrouped agents are invisible to everyone.
|
|
44
44
|
- Groups are managed by the user from the TUI (`/talk-group-*` commands) — you cannot create, join, or leave a group yourself.
|
|
45
|
-
-
|
|
45
|
+
- When the user joins a group they can tag their agent with a display name via `/talk-group-join <group> --name <alias>` (e.g. `frontend`, `backend`). That alias is what peers see as `name` in `talk-list-agents` — prefer it over the raw agent id when describing who is who.
|
|
46
|
+
- If an agent you need to collaborate with is missing from `talk-list-agents`, ask the user to pair the agents into the same group.
|
|
46
47
|
|
|
47
48
|
## Tools
|
|
48
49
|
|
|
49
|
-
| Tool
|
|
50
|
-
|
|
|
51
|
-
| `talk-list-
|
|
52
|
-
| `talk-send`
|
|
53
|
-
| `talk-ask`
|
|
54
|
-
| `talk-reply`
|
|
50
|
+
| Tool | Purpose |
|
|
51
|
+
| ------------------ | -------------------------------------------------------------------------------------------------------------------- |
|
|
52
|
+
| `talk-list-agents` | List visible agents (`id` / `status` / `work_dir` / `name`); only group co-members (or only yourself when ungrouped) |
|
|
53
|
+
| `talk-send` | Send a plain message to a single agent id (async — the main collaboration primitive) |
|
|
54
|
+
| `talk-ask` | Ask a question and block for the reply (default 30 min timeout) |
|
|
55
|
+
| `talk-reply` | Reply to a received ask; `replyTo` is the ask id shown in the delivered message |
|
|
55
56
|
|
|
56
|
-
Pairing into groups is a user action (`/talk-group-*` in the TUI); you only observe its effect through `talk-list-
|
|
57
|
+
Pairing into groups is a user action (`/talk-group-*` in the TUI); you only observe its effect through `talk-list-agents`.
|
|
57
58
|
|
|
58
59
|
## Collaboration workflows
|
|
59
60
|
|
|
60
|
-
### Split work between
|
|
61
|
+
### Split work between agents
|
|
61
62
|
|
|
62
|
-
1. `talk-list-
|
|
63
|
+
1. `talk-list-agents` first: see which co-members exist, their `work_dir`, and status. If only yourself shows up, the peer agents are not in your group yet — ask the user to pair them.
|
|
63
64
|
2. Assign work by module/files with `talk-send` — state the scope, boundaries, and expected output.
|
|
64
|
-
3. Each
|
|
65
|
+
3. Each agent completes its slice, then sends the result or a review request.
|
|
65
66
|
4. Sync progress periodically to avoid overlapping edits.
|
|
66
67
|
|
|
67
68
|
### Synchronous question/answer (need the answer to continue)
|
|
68
69
|
|
|
69
70
|
- Use `talk-ask` when the next step depends on the peer's information and the peer is reachable.
|
|
70
71
|
- On receiving an ask, reply with `talk-reply` using the `replyTo` id from the delivered message.
|
|
71
|
-
- If two
|
|
72
|
+
- If two agents ask each other simultaneously: the later asker yields — answer the peer's ask first, then re-ask.
|
|
72
73
|
|
|
73
74
|
### Async notifications
|
|
74
75
|
|
|
75
76
|
- Use `talk-send` for heads-ups that do not block: send and keep working.
|
|
76
77
|
- Messages deliver on the next natural turn by default (`queue`); `steer` interrupts the peer immediately — behavior depends on the `talk.deliver` setting.
|
|
77
78
|
|
|
78
|
-
### Cross-
|
|
79
|
+
### Cross-agent review
|
|
79
80
|
|
|
80
|
-
- Ask another
|
|
81
|
+
- Ask another agent to review your changes: `talk-send` the file paths plus a diff summary, request a review, and let it reply.
|
|
81
82
|
- Send paths and summaries, not whole file contents — the peer can `read` them itself.
|
|
82
83
|
|
|
83
84
|
## Message style
|
|
@@ -91,6 +92,6 @@ Pairing into groups is a user action (`/talk-group-*` in the TUI); you only obse
|
|
|
91
92
|
## Pitfalls
|
|
92
93
|
|
|
93
94
|
- **Avoid message loops**: if the peer sent you something or is asking you, answer it before sending new ones. Two agents pinging each other deadlock.
|
|
94
|
-
- **Address from known ids**: only run `talk-list-
|
|
95
|
-
- **Respect status**: asking an offline
|
|
96
|
-
- **Visibility boundary**: you can only collaborate with
|
|
95
|
+
- **Address from known ids**: only run `talk-list-agents` to discover agents or verify an id. If you already hold a valid id (e.g. from an incoming message or a previous listing), send directly — an unknown or invisible id is refused with `Unknown agent id`.
|
|
96
|
+
- **Respect status**: asking an offline agent blocks until the 30 min timeout. Prefer `talk-send` there — the message queues on disk and the peer receives it when it resumes.
|
|
97
|
+
- **Visibility boundary**: you can only collaborate with agents that share your group; ungrouped agents and other groups' members are unreachable by design. Ask the user to pair agents before collaborating.
|
package/src/talk/storage.ts
CHANGED
|
@@ -45,7 +45,7 @@ export interface TalkStorage {
|
|
|
45
45
|
* SQLite backend (Node's built-in `node:sqlite`, no npm dependency).
|
|
46
46
|
*
|
|
47
47
|
* A single database file holds everything; WAL mode plus a busy timeout lets
|
|
48
|
-
* multiple pi
|
|
48
|
+
* multiple pi agents read and write it concurrently. SQL parameter binding
|
|
49
49
|
* removes the need for path/symlink hardening entirely.
|
|
50
50
|
*
|
|
51
51
|
* The backend is synchronous; each method wraps its result in a resolved
|