@giladbarnea/pi-simple-team 1.0.31 → 1.0.32

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/README.md CHANGED
@@ -62,16 +62,14 @@ Main agent:
62
62
  <br>
63
63
 
64
64
  <details>
65
- <summary><strong>See real tool outputs</strong></summary>
65
+ <summary><strong>pi-simple-team screenshots</strong></summary>
66
66
 
67
67
  <br>
68
68
 
69
- <p align="center">
70
- <a href="screenshots/1.png"><img src="screenshots/1.png" width="48%" alt="Pi tool outputs for spawning a team, sending instructions, and checking status"></a>
71
- <a href="screenshots/2.png"><img src="screenshots/2.png" width="48%" alt="Pi tool outputs for team status and the timestamped event log"></a>
72
- </p>
73
69
  <p align="center">
74
70
  <a href="screenshots/team-status-multiple.png"><img src="screenshots/team-status-multiple.png" width="48%" alt="Status outputs for several parallel teams"></a>
71
+ </p>
72
+ <p align="center">
75
73
  <a href="screenshots/team-log-multiple.png"><img src="screenshots/team-log-multiple.png" width="48%" alt="Event log outputs for two parallel teams"></a>
76
74
  </p>
77
75
 
@@ -104,8 +102,6 @@ This is both efficient and effective:
104
102
  - ✔ Context window stays lean.
105
103
  - ✔ Unlocks arbitrary workflows.
106
104
 
107
- *{ironic screenshot of Codex filling up the entire visible chat with countless* `Waiting agents to finish...`*}*
108
-
109
105
  ### ⚡ Messages arrive _fast_.
110
106
 
111
107
  - Sub-second, when the recipient is idle.
@@ -115,9 +111,9 @@ This is both efficient and effective:
115
111
 
116
112
  Teammates publish a one-liner:
117
113
 
118
- > <span style="color:grey">implementer </span> Done, 89 tests green, awaiting review.
114
+ > <span style="color:grey">implementer  </span> Done, 89 tests green, awaiting review.
119
115
 
120
- > <span style="color:grey">reviewer </span> Reading implementation, will finalize review in a few minutes.
116
+ > <span style="color:grey">reviewer      </span> Reading implementation, will finalize review in a few minutes.
121
117
 
122
118
  Your main agent calls `teamstatus` and understands exactly what is going on. Main does not ask teammates for updates or clutter their context.
123
119
 
@@ -127,7 +123,7 @@ Teammates know how much free context they have left.
127
123
 
128
124
  Main agent knows its own and everyone else's too.
129
125
 
130
- They will hand off work on their own when it's time to say goodbye.
126
+ They will hand off work autonomously when it's time to say goodbye.
131
127
 
132
128
  You can stop babysitting everyone's context window.
133
129
 
@@ -154,27 +150,29 @@ Your main uses `teamlog` when it needs to understand the chain of events in high
154
150
 
155
151
  A teammate is a normal Pi session with a team attachment.
156
152
 
157
- This means every teammate can be resurrected, moved around teams and reused everywhere, anytime.
153
+ This means teammates survive shutdown, whole team or member by member.
158
154
 
159
- A teammate from one session can be added to a team in a later session.
155
+ Have a teammate do work, exit Pi entirely, come back tomorrow in a brand-new session: main wakes that same teammate into the new conversation, everything it learned intact.
160
156
 
161
157
  You can even `/resume` a teammate session directly if you ever want a cozy one-on-one.
162
158
 
163
159
  The full lifecycle and persistence rules live in [ARCHITECTURE.md](ARCHITECTURE.md).
164
160
 
165
- ## When one room is not enough
161
+ ## 🪾 Teams all the way down (optionally)
162
+
163
+ Tell main you want to give a teammate the ability to manage its own team(s).
166
164
 
167
- `pi-simple-team` supports teammates spawning and managing their own teams, one level down.
165
+ This is a powerful technique to create a new layer of context breathing room.
168
166
 
169
- This is opt-in: when spawning a team, ask main to turn this on for one (or more) teammates.
167
+ That teammate will spawn, steer and observe its own team(s) without costing tokens to its siblings or parent.
170
168
 
171
- That teammate stays in your team and becomes main for the teams it creates, with the same tools your main agent has. The boundary is strict: it manages only teams its own session created — never its parent team, sibling teams, or their teammates.
169
+ The tradeoff, like any higher-order delegation, is reduced control: you are moved one level further away from the action.
172
170
 
173
- A room can open another room. It does not get the keys to the whole building.
171
+ This is opt-in: teammates by default can't create teams.
174
172
 
175
173
  ---
176
174
 
177
- ## Graphs engineer themselves
175
+ ## 🧬 Graphs engineer themselves
178
176
 
179
177
  **Because** it does nothing special, `pi-simple-team` can construct any team graph you need:
180
178
 
package/index.ts CHANGED
@@ -989,6 +989,9 @@ export default function (pi: ExtensionAPI) {
989
989
  ? "List active and dormant teams created by this overseeing teammate."
990
990
  : "List active and dormant teams for the current project.",
991
991
  promptSnippet: "List teams for the current project",
992
+ renderShell: "self",
993
+ renderCall: (_args, theme, context) => renderTeamToolCall("team_list", {}, theme, context, sessionTeammateRoster),
994
+ renderResult: (result, options, theme, context) => renderTeamToolResult("team_list", result, options, theme, context, undefined, sessionTeammateRoster),
992
995
  parameters: Type.Object({}),
993
996
  async execute(_toolCallId, _params, _signal, _onUpdate, context) {
994
997
  const projectDirectory = context.sessionManager?.getCwd?.() ?? context.cwd;
@@ -1033,6 +1036,9 @@ export default function (pi: ExtensionAPI) {
1033
1036
  ? "Resume all or selected stopped members of a dormant team created by this overseeing teammate."
1034
1037
  : "Resume all stopped teammates in a dormant current-project team, or only selected stopped teammates.",
1035
1038
  promptSnippet: "Resume all or selected stopped teammates",
1039
+ renderShell: "self",
1040
+ renderCall: (args, theme, context) => renderTeamToolCall("team_resume", args, theme, context, sessionTeammateRoster),
1041
+ renderResult: (result, options, theme, context) => renderTeamToolResult("team_resume", result, options, theme, context, undefined, sessionTeammateRoster),
1036
1042
  parameters: Type.Object({
1037
1043
  team: Type.String({ description: "Persistent team ID" }),
1038
1044
  teammates: Type.Optional(Type.Array(Type.String({ minLength: 1 }), { minItems: 1, description: "Stopped teammate names. Omit to resume all stopped teammates." })),
@@ -1123,7 +1129,9 @@ export default function (pi: ExtensionAPI) {
1123
1129
  accepted: true,
1124
1130
  id: team.id,
1125
1131
  team: team.name,
1132
+ teammates: [...team.members.keys()],
1126
1133
  resumed: starts.map(({ teammate }) => teammate.name),
1134
+ restartedEmpty: starts.filter(({ sessionFile }) => sessionFile === undefined).map(({ teammate }) => teammate.name),
1127
1135
  sessions: Object.fromEntries(
1128
1136
  starts.map(({ teammate }) => [teammate.name, { sessionId: teammate.sessionId, sessionFile: teammate.sessionFile }]),
1129
1137
  ),
@@ -1138,6 +1146,9 @@ export default function (pi: ExtensionAPI) {
1138
1146
  label: "Team Add",
1139
1147
  description: "Add one or more new RPC teammates to a running team owned by this main session.",
1140
1148
  promptSnippet: "Add new teammates to a running team",
1149
+ renderShell: "self",
1150
+ renderCall: (args, theme, context) => renderTeamToolCall("team_add", args, theme, context, sessionTeammateRoster),
1151
+ renderResult: (result, options, theme, context) => renderTeamToolResult("team_add", result, options, theme, context, undefined, sessionTeammateRoster),
1141
1152
  parameters: Type.Object({
1142
1153
  team: Type.String({ description: "Persistent team ID" }),
1143
1154
  teammates: Type.Array(teammateSchema(""), { minItems: 1, description: "New teammates to add" }),
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@giladbarnea/pi-simple-team",
3
- "version": "1.0.31",
3
+ "version": "1.0.32",
4
4
  "description": "A flat, live team of Pi agents.",
5
5
  "keywords": [
6
6
  "pi-package",
package/render.ts CHANGED
@@ -4,7 +4,7 @@ import { padVisible, stableRenderWidth, visibleLength } from "./render-support/a
4
4
  import { glyphs } from "./render-support/glyphs.ts";
5
5
  import { stackPrefix, toolLabel, treeConnector, treeGlyph, treeStem } from "./render-support/theme.ts";
6
6
  import { commandExit, plural, renderPendingCall, textContent } from "./render-support/text.ts";
7
- import { timeOfDay, type TeamLogEntry } from "./teamlog.ts";
7
+ import { monthDay, nowText, timeOfDay, type TeamLogEntry } from "./teamlog.ts";
8
8
 
9
9
  export interface ThemeLike {
10
10
  bold(text: string): string;
@@ -12,7 +12,7 @@ export interface ThemeLike {
12
12
  }
13
13
 
14
14
  interface ToolRenderContextLike {
15
- args?: Record<string, unknown>;
15
+ args?: object;
16
16
  cwd?: string;
17
17
  executionStarted?: boolean;
18
18
  invalidate?: () => void;
@@ -21,7 +21,7 @@ interface ToolRenderContextLike {
21
21
  toolCallId?: string;
22
22
  }
23
23
 
24
- export type TeamToolName = "team_spawn" | "teamsend" | "teamstatus" | "teamlog" | "team_shutdown";
24
+ export type TeamToolName = "team_spawn" | "team_list" | "team_resume" | "team_add" | "teamsend" | "teamstatus" | "teamlog" | "team_shutdown";
25
25
 
26
26
  export interface TeamStatusView {
27
27
  word: string;
@@ -153,8 +153,11 @@ const STATUS_WORD_TOKENS: Record<string, string> = {
153
153
  running: "success",
154
154
  working: "success",
155
155
  blocked: "warning",
156
+ restarted: "warning",
157
+ resumed: "success",
156
158
  waiting: "warning",
157
159
  available: "muted",
160
+ dormant: "muted",
158
161
  idle: "muted",
159
162
  spawned: "muted",
160
163
  done: "dim",
@@ -209,14 +212,90 @@ interface TeammateSpecView {
209
212
  thinking?: string;
210
213
  }
211
214
 
212
- export function teamSpawnLines(theme: ThemeLike, team: string, teammates: TeammateSpecView[], roster: string[] = []): string[] {
213
- const header = headerLine(theme, "Team Spawn", theme.fg("accent", team), [theme.fg("muted", plural(teammates.length, "teammate"))]);
215
+ function teammateSpecRows(theme: ThemeLike, teammates: TeammateSpecView[], roster: string[]): string[] {
214
216
  const nameWidth = Math.max(...teammates.map((teammate) => teammate.name.length));
215
- const rows = teammates.map((teammate, index) => {
217
+ return teammates.map((teammate, index) => {
216
218
  const branch = index === teammates.length - 1 ? "└" : "├";
217
219
  const spec = statLine(theme, [theme.fg("muted", teammate.model), theme.fg("dim", teammate.thinking ?? "")]);
218
220
  return `${treeConnector(theme, branch)}${theme.fg(actorHueToken(teammate.name, roster), padVisible(teammate.name, nameWidth))} ${spec}`;
219
221
  });
222
+ }
223
+
224
+ export function teamSpawnLines(theme: ThemeLike, team: string, teammates: TeammateSpecView[], roster: string[] = []): string[] {
225
+ const header = headerLine(theme, "Team Spawn", theme.fg("accent", team), [theme.fg("muted", plural(teammates.length, "teammate"))]);
226
+ return [header, ...teammateSpecRows(theme, teammates, roster)];
227
+ }
228
+
229
+ export function teamAddLines(theme: ThemeLike, team: string, teammates: TeammateSpecView[], memberCount: number, roster: string[] = []): string[] {
230
+ const header = headerLine(theme, "Team Add", theme.fg("accent", team), [
231
+ theme.fg("muted", `${teammates.length} added`),
232
+ theme.fg("muted", plural(memberCount, "member")),
233
+ ]);
234
+ return [header, ...teammateSpecRows(theme, teammates, roster)];
235
+ }
236
+
237
+ export interface ResumedMemberView {
238
+ name: string;
239
+ restored: boolean;
240
+ }
241
+
242
+ export function teamResumeLines(theme: ThemeLike, team: string, resumed: ResumedMemberView[], teammateCount: number, roster: string[] = []): string[] {
243
+ const countText = resumed.length === teammateCount ? `${resumed.length} resumed` : `${resumed.length} of ${teammateCount} resumed`;
244
+ const header = headerLine(theme, "Team Resume", theme.fg("accent", team), [theme.fg("muted", countText)]);
245
+ if (resumed.length === 0) return [header, `${treeConnector(theme, "└")}${theme.fg("muted", "no stopped teammates")}`];
246
+ const nameWidth = Math.max(...resumed.map((member) => member.name.length));
247
+ const wordWidth = Math.max(...resumed.map((member) => (member.restored ? "resumed" : "restarted").length));
248
+ const rows = resumed.map((member, index) => {
249
+ const branch = index === resumed.length - 1 ? "└" : "├";
250
+ const word = member.restored ? "resumed" : "restarted";
251
+ const note = member.restored ? "history restored" : "empty session";
252
+ return `${treeConnector(theme, branch)}${theme.fg(actorHueToken(member.name, roster), padVisible(member.name, nameWidth))} ${theme.fg(statusWordToken(word), padVisible(word, wordWidth))} ${theme.fg("muted", note)}`;
253
+ });
254
+ return [header, ...rows];
255
+ }
256
+
257
+ export interface TeamListMemberView {
258
+ name: string;
259
+ live: boolean;
260
+ canOverseeOwnTeams: boolean;
261
+ }
262
+
263
+ export interface TeamListTeamView {
264
+ name: string;
265
+ state: string;
266
+ leaseState: string;
267
+ members: TeamListMemberView[];
268
+ updatedAt: string;
269
+ expiresAt?: string;
270
+ }
271
+
272
+ function teamListMemberName(theme: ThemeLike, teamView: TeamListTeamView, member: TeamListMemberView, roster: string[]): string {
273
+ let name = theme.fg(actorHueToken(member.name, roster), member.name);
274
+ if (teamView.state === "active" && !member.live) name = `${DIM_SGR_OPEN}${name}${DIM_SGR_CLOSE}`;
275
+ if (member.canOverseeOwnTeams) name += theme.fg("dim", glyphs().diamond);
276
+ return name;
277
+ }
278
+
279
+ function teamListTimestamp(teamView: TeamListTeamView): string {
280
+ if (teamView.state === "dormant" && teamView.expiresAt) return `expires ${monthDay(Date.parse(teamView.expiresAt))}`;
281
+ return `updated ${nowText(new Date(teamView.updatedAt))}`;
282
+ }
283
+
284
+ export function teamListLines(theme: ThemeLike, teamViews: TeamListTeamView[], roster: string[] = []): TeamLine[] {
285
+ const activeCount = teamViews.filter((teamView) => teamView.state === "active").length;
286
+ const stats = [theme.fg("muted", plural(teamViews.length, "team"))];
287
+ if (activeCount > 0) stats.push(theme.fg("success", `${activeCount} active`));
288
+ const header = headerLine(theme, "Team List", "", stats);
289
+ if (teamViews.length === 0) return [header, `${treeConnector(theme, "└")}${theme.fg("muted", "no teams")}`];
290
+ const nameWidth = Math.max(...teamViews.map((teamView) => teamView.name.length));
291
+ const stateWidth = Math.max(...teamViews.map((teamView) => teamView.state.length));
292
+ const rows: TeamLine[] = teamViews.map((teamView, index) => {
293
+ const branch = index === teamViews.length - 1 ? "└" : "├";
294
+ const rosterText = teamView.members.map((member) => teamListMemberName(theme, teamView, member, roster)).join(theme.fg("muted", glyphs().dot));
295
+ const staleLease = teamView.leaseState === "stale" ? `${dimDot(theme)}${theme.fg("error", "stale lease")}` : "";
296
+ const left = `${treeConnector(theme, branch)}${theme.fg("accent", padVisible(teamView.name, nameWidth))} ${theme.fg(statusWordToken(teamView.state), padVisible(teamView.state, stateWidth))} ${rosterText}${staleLease}`;
297
+ return { left, right: theme.fg("dim", teamListTimestamp(teamView)) };
298
+ });
220
299
  return [header, ...rows];
221
300
  }
222
301
 
@@ -646,6 +725,18 @@ function callBodyFor(tool: TeamToolName, theme: ThemeLike, args: Record<string,
646
725
  const teammates = (args.teammates ?? []) as unknown[];
647
726
  return callBody(theme, "Team Spawn", accentTeam(theme, args.team), [theme.fg("muted", plural(teammates.length, "teammate"))]);
648
727
  }
728
+ if (tool === "team_list") {
729
+ return callBody(theme, "Team List", "");
730
+ }
731
+ if (tool === "team_resume") {
732
+ const requested = args.teammates as string[] | undefined;
733
+ const scope = requested?.length ? plural(requested.length, "teammate") : "all stopped";
734
+ return callBody(theme, "Team Resume", accentTeam(theme, args.team), [theme.fg("muted", scope)]);
735
+ }
736
+ if (tool === "team_add") {
737
+ const teammates = (args.teammates ?? []) as unknown[];
738
+ return callBody(theme, "Team Add", accentTeam(theme, args.team), [theme.fg("muted", plural(teammates.length, "teammate"))]);
739
+ }
649
740
  if (tool === "teamsend") {
650
741
  const message = String(args.message ?? "");
651
742
  return callBody(theme, "Team Send", sendTarget(theme, (args.to ?? []) as string[], roster), sendStats(theme, message, Boolean(args.interrupt)));
@@ -672,6 +763,26 @@ function resultLinesFor(tool: TeamToolName, theme: ThemeLike, args: Record<strin
672
763
  if (tool === "team_spawn") {
673
764
  return teamSpawnLines(theme, String(details.team), (args.teammates ?? []) as TeammateSpecView[], roster);
674
765
  }
766
+ if (tool === "team_list") {
767
+ const teamViews = ((details.teams ?? []) as Array<Record<string, unknown>>).map((entry) => ({
768
+ name: String(entry.name),
769
+ state: String(entry.state),
770
+ leaseState: String(entry.leaseState ?? ""),
771
+ members: (entry.members ?? []) as TeamListMemberView[],
772
+ updatedAt: String(entry.updatedAt),
773
+ expiresAt: entry.expiresAt as string | undefined,
774
+ }));
775
+ return teamListLines(theme, teamViews, roster);
776
+ }
777
+ if (tool === "team_resume") {
778
+ const restartedEmpty = new Set((details.restartedEmpty ?? []) as string[]);
779
+ const resumed = ((details.resumed ?? []) as string[]).map((name) => ({ name, restored: !restartedEmpty.has(name) }));
780
+ return teamResumeLines(theme, String(details.team), resumed, ((details.teammates ?? []) as string[]).length, roster);
781
+ }
782
+ if (tool === "team_add") {
783
+ const memberCount = Object.keys((details.status ?? {}) as Record<string, unknown>).length;
784
+ return teamAddLines(theme, String(details.team), (args.teammates ?? []) as TeammateSpecView[], memberCount, roster);
785
+ }
675
786
  if (tool === "teamsend") {
676
787
  return teamSendLines(theme, {
677
788
  to: (details.to ?? []) as string[],
@@ -712,7 +823,7 @@ export function renderTeamToolResult(
712
823
  markdownTheme?: MarkdownTheme,
713
824
  roster: string[] = [],
714
825
  ): TeamSendView | TeamLines {
715
- const args = context?.args ?? {};
826
+ const args = (context?.args ?? {}) as Record<string, unknown>;
716
827
  if (context?.isError || result?.isError) {
717
828
  return new TeamLines(errorLines(theme, callBodyFor(tool, theme, args, roster), textContent(result)), options.expanded ? "wrap" : "clip");
718
829
  }
@@ -1,6 +1,6 @@
1
1
  ---
2
2
  name: ai-to-ai
3
- description: Best practices for getting a step-function leap in performance from other AI agents when instructing or communicating with them. Markdown docs are AI agents’ bread-and-butter, not only humans’. Load `ai-to-ai` before spawning a sub-agent, creating a team, talking to a teammate agent, or writing documentation. Trigger words include “dispatch an agent”, “spawn a team”, and “talk with another AI”.
3
+ description: Best practices for getting a step-function leap in performance from other AI agents when instructing or communicating with them. Markdown docs are AI agents’ bread-and-butter, not only humans’. Load `ai-to-ai` before spawning a sub-agent, creating a team, talking to a teammate agent, or writing documentation. Trigger words include “dispatch an agent”, “spawn a team”, and “talk with <another ai>”.
4
4
  ---
5
5
 
6
6
  ## Why delegate at all? Rationale
@@ -7,6 +7,6 @@ goes_well_with: tech-lead
7
7
 
8
8
  # Head of Product
9
9
 
10
- Cares about user value, time to delivery, and working outcomes. For Gilad's business, working deliverables create income. For his clients, useful deliverables create value and trust, and lead to more work.
10
+ Cares about user value, time to delivery, and working outcomes. For Gilad’s business, working deliverables create income. For his clients, useful deliverables create value and trust, and lead to more work.
11
11
  Head of product deeply understands that homing in on the minimal deliverable that works well but does not go an inch beyond that desired minimal scope is crucial for the business to work.
12
12
  The inverse of successful scope home-in is the following scope-creep failure mode to prevent: as the team loops, it convinces itself, when deciding on the next iteration’s goal and scope, that they must add this and that new requirement to the scope because of something they had discovered in the last loop iteration. Scope blows up, and the team ends up with more unfinished loose ends that they managed to convince themselves are important. A team that ends up like this does more damage than good. Head of product understands this. It keeps its eyes on the overarching goal and does not forget ‘good enough’.
@@ -1,7 +1,6 @@
1
1
  ---
2
2
  name: tech-lead
3
3
  description: Owns deep technical expertise while retaining architecture and tradeoff decisions.
4
- type: role
5
4
  goes_well_with: head-of-product
6
5
  ---
7
6
 
package/teamlog.ts CHANGED
@@ -74,6 +74,10 @@ export function timeOfDay(epochMilliseconds: number): string {
74
74
  return timeFormatter.format(new Date(epochMilliseconds));
75
75
  }
76
76
 
77
+ export function monthDay(epochMilliseconds: number): string {
78
+ return dateFormatter.format(new Date(epochMilliseconds));
79
+ }
80
+
77
81
  function safeStringify(value: unknown): string {
78
82
  try {
79
83
  return JSON.stringify(value) ?? String(value);