ac-teams 0.0.7 → 0.0.9

package/src/store.ts

@@ -4,7 +4,7 @@ import { randomUUID } from "node:crypto";
 import { stateRoot } from "./config.ts";
 import { validatePolicy } from "./egress.ts";
 import { stripVTControlCharacters } from "node:util";
-import { isDescendant, isLive, memberNamePattern, memberNameMaxLength, taskLabelMaxLength, taskLabelPattern } from "./types.ts";
+import { isDescendant, isLive, isMain, memberNamePattern, memberNameMaxLength, taskLabelMaxLength, taskLabelPattern } from "./types.ts";
 import type { TeamState, TaskArgs, MessageArgs, Task, TaskView, Message, Worktree } from "./types.ts";
 
 // UI envelopes add task context after the public 16,000-character input limit.
@@ -54,7 +54,18 @@ function taskView(state: TeamState, task: Task): TaskView {
 }
 
 function migrate(state: unknown): boolean {
-  if (!object(state) || (state.version !== 1 && state.version !== 2)) return false;
+  if (!object(state) || ![1, 2, 3].includes(state.version as number)) return false;
+  if (state.version !== 3) migrateTasks(state);
+  // Schema 4: roles replace the special root ID; the creator's record becomes a main session.
+  const root = state.root ?? "root";
+  requireValue(object(state.members) && typeof root === "string" && Object.hasOwn(state.members, root), "Invalid legacy root member");
+  for (const [key, member] of Object.entries(state.members)) if (object(member)) member.role = key === root ? "main" : "member";
+  delete state.root;
+  state.key = randomUUID();
+  state.version = 4;
+  return true;
+}
+function migrateTasks(state: Record<string, unknown>): void {
   requireValue(object(state.tasks), "Invalid legacy state tasks");
   let number = 0;
   for (const task of Object.values(state.tasks)) {
@@ -69,14 +80,12 @@ function migrate(state: unknown): boolean {
     task.number = ++number;
     task.label = stripVTControlCharacters(task.title).replace(/[\x00-\x1f\x7f-\x9f]/g, " ").trim().split(/\s+/).slice(0, 3).join(" ").slice(0, taskLabelMaxLength).trim() || "Task";
   }
-  state.version = 3;
-  return true;
 }
 
 function validate(state: unknown): asserts state is TeamState {
   requireValue(object(state), "Invalid state snapshot");
   id(state.id);
-  requireValue(state.version === 3 && text(state.root) && integer(state.limit, 1) && integer(state.depth) && object(state.members) && object(state.tasks) && Array.isArray(state.messages), "Invalid state snapshot schema");
+  requireValue(state.version === 4 && text(state.key) && integer(state.limit, 1) && integer(state.depth) && object(state.members) && object(state.tasks) && Array.isArray(state.messages), "Invalid state snapshot schema");
   const members = state.members;
   const names = new Set<string>(["main", "root", ...Object.keys(members)]);
   for (const [key, member] of Object.entries(members)) {
@@ -91,6 +100,10 @@ function validate(state: unknown): asserts state is TeamState {
       const usage = member.contextUsage;
       requireValue(object(usage) && integer(usage.contextWindow, 1) && (usage.tokens === null || integer(usage.tokens)) && (usage.percent === null || typeof usage.percent === "number" && Number.isFinite(usage.percent) && usage.percent >= 0), "Invalid member context usage");
     }
+    requireValue(member.role === undefined || member.role === "main" || member.role === "member", "Invalid member role");
+    requireValue(member.role !== "main" || member.parent === undefined, "A main session has no parent");
+    requireValue(member.handover === undefined || ["busy", "idle", "input"].includes(String(member.handover)), "Invalid member handover state");
+    requireValue(member.promotion === undefined || (object(member.promotion) && ["stopped", "moved", "role", "entry"].includes(String(member.promotion.step)) && text(member.promotion.sessionFile)), "Invalid member promotion");
     requireValue(member.terminal === undefined || typeof member.terminal === "boolean", "Invalid member terminal flag");
     requireValue(member.needsInput === undefined || typeof member.needsInput === "boolean", "Invalid member input flag");
     requireValue(member.pid === undefined || integer(member.pid, 1), "Invalid member PID");
@@ -105,7 +118,6 @@ function validate(state: unknown): asserts state is TeamState {
       parent = (members[parent] as Record<string, unknown>).parent;
     }
   }
-  requireValue(Object.hasOwn(members, state.root), "Invalid root member");
   const tasks = state.tasks;
   const edges: Record<string, string[]> = {};
   const taskNumbers = new Set<number>();
@@ -156,13 +168,24 @@ function privateFile(path: string, flags: number): number {
   } catch (error) { closeSync(fd); throw error; }
 }
 
+export const teamsHome = () => join(stateRoot(), "teams");
+/** Reads a team snapshot without taking ownership, for sessions that connect to its coordinator as clients. */
+export function readState(dir: string): TeamState {
+  const fd = privateFile(join(dir, "state.json"), constants.O_RDONLY);
+  try {
+    const stored: unknown = JSON.parse(readFileSync(fd, "utf8"));
+    migrate(stored); validate(stored);
+    return stored;
+  } finally { closeSync(fd); }
+}
+
 export class Store {
   readonly dir: string;
   state: TeamState;
   private lock?: number;
   private closed = false;
 
-  constructor(initial: TeamState, home = join(stateRoot(), "teams")) {
+  constructor(initial: TeamState, home = teamsHome()) {
     validate(initial);
     this.dir = join(resolve(home), initial.id);
     this.state = structuredClone(initial);
@@ -299,12 +322,12 @@ export class Store {
       } else if (args.action === "release") {
         requireValue(task.owner, "Task has no owner to release");
         const interrupted = ["interrupted", "stopped"].includes(state.members[task.owner].status);
-        requireValue(task.owner === actor || (interrupted && (actor === state.root || isDescendant(state, task.owner, actor))), "Only the owner can release this task; ancestors may release interrupted descendants");
+        requireValue(task.owner === actor || (interrupted && (isMain(state.members[actor]) || isDescendant(state, task.owner, actor))), "Only the owner can release this task; ancestors may release interrupted descendants");
         if (task.status === "in_progress") task.status = "todo";
         delete task.owner;
       } else if (args.action === "reopen") {
         requireValue(task.status === "done", "Only done tasks can be reopened");
-        requireValue(!task.owner || task.owner === actor || actor === state.root, "Only the owner or root can reopen an owned task");
+        requireValue(!task.owner || task.owner === actor || isMain(state.members[actor]), "Only the owner or a main session can reopen an owned task");
         const dependents = Object.values(state.tasks).filter(other => other.dependencies.includes(task.id) && other.status !== "todo");
         requireValue(dependents.length === 0, `Cannot reopen task with active or done dependents: ${dependents.map(t => t.id).join(", ")}`);
         task.status = "todo";

package/src/terminal-agent.ts

@@ -44,7 +44,7 @@ export class TerminalAgent extends EventEmitter {
       writeFileSync(config, "set -g status off\nset -g prefix None\nset -s extended-keys always\nbind-key -n C-S-Left detach-client\n", { flag: "wx", mode: 0o600 });
       this.files.push(config);
       const exports = Object.entries(this.options.env)
-        .filter(([key, value]) => (key.startsWith("AC_TEAMS_") || key === "HERDR_ENV") && value !== undefined)
+        .filter(([key, value]) => (key.startsWith("AC_TEAMS_") || key === "HERDR_ENV" || key === "ACSTACK_AGENT_ROLE") && value !== undefined)
         .map(([key, value]) => `export ${key}=${quote(value!)}`);
       const command = this.options.command ?? process.env.AC_TEAMS_PI ?? "pi";
       writeFileSync(script, [...exports,

package/src/terminal-ui.ts

@@ -14,10 +14,13 @@ export async function visitMember(ctx: ExtensionContext, host: PanelHost, socket
   if (ctx.mode !== "tui") throw new Error("Live sessions require an interactive terminal");
   if (id === host.self) return;
   const member = (await host.snapshot()).members.find(member => member.id === id);
+  // A member returns to whichever main session attached it by detaching.
+  if (host.child && member?.role === "main") { await exec("tmux", ["-S", socket, "detach-client", "-s", host.self], { timeout: 5000, maxBuffer: 65536 }); return; }
   if (!member || !isLive(member)) throw new Error(`Member ${id} is stopped or unavailable; resume it from /teams`);
-  if (id !== "root" && !member.terminal) throw new Error("This member has no live terminal (it was launched headlessly)");
-  if (host.self !== "root") {
-    await exec("tmux", ["-S", socket, ...(id === "root" ? ["detach-client", "-s", host.self] : ["switch-client", "-t", id])], { timeout: 5000, maxBuffer: 65536 });
+  if (member.role === "main") throw new Error(`${memberName(member)} is a main session in its own terminal; switch to it there`);
+  if (!member.terminal) throw new Error("This member has no live terminal (it was launched headlessly)");
+  if (host.child) {
+    await exec("tmux", ["-S", socket, "switch-client", "-t", id], { timeout: 5000, maxBuffer: 65536 });
     return;
   }
   const code = await ctx.ui.custom<number>((tui, _theme, _keys, done) => {

package/src/types.ts

@@ -43,10 +43,22 @@ export interface Member {
   access?: Access;
   /** Provider fixed at an enforced member's first launch; member telemetry cannot change it. */
   provider?: string;
+  /** Authority: a main session or a member. Absent once a main session has left the team. */
+  role?: "main" | "member";
+  /** State recorded when the coordinator owner stopped this member; the next owner's resume pass consumes it. */
+  handover?: "busy" | "idle" | "input";
+  /** Promotion in progress: the last completed step and what a rollback restores. */
+  promotion?: { step: "stopped" | "moved" | "role" | "entry"; sessionFile: string; parent?: string; access?: Access; provider?: string };
 }
 export const memberNameMaxLength = 40;
 export const memberNamePattern = /^[a-z][a-z0-9]*(?:-[a-z0-9]+)?(?![\s\S])/;
 export function memberName(member: Pick<Member, "id" | "name">): string { return member.id === "root" ? "Main" : member.name ?? member.id; }
+export function isMain(member: Pick<Member, "role"> | undefined): boolean { return member?.role === "main"; }
+/** Mains control every member and other mains; members control only their descendants, never a main. */
+export function canControl(state: TeamState, actor: string, id: string): boolean {
+  const target = state.members[id];
+  return !!target && id !== actor && (isMain(state.members[actor]) ? target.role !== undefined : !isMain(target) && isDescendant(state, id, actor));
+}
 export const taskLabelMaxLength = 60;
 export const taskLabelPattern = /^[^\s\x00-\x1f\x7f-\x9f]+(?: [^\s\x00-\x1f\x7f-\x9f]+){0,2}(?![\s\S])/;
 export function taskName(task: Pick<Task, "number" | "label">): string { return `#${task.number} ${task.label}`; }
@@ -75,9 +87,10 @@ export interface Message {
   time: string;
 }
 export interface TeamState {
-  version: 3;
+  version: 4;
   id: string;
-  root: string;
+  /** Lets an unsandboxed session of the same user add itself as a main session. */
+  key: string;
   limit: number;
   depth: number;
   members: Record<string, Member>;
@@ -120,13 +133,15 @@ export interface AgentArgs {
   access?: AccessRequest;
 }
 export interface UserAction {
-  action: "task_request" | "feedback" | "resume";
+  action: "task_request" | "feedback" | "resume" | "promote" | "leave";
   id?: string;
+  /** Promote: the user approved running a sandboxed member with full access. */
+  confirmed?: boolean;
   text?: string;
   model?: string;
   thinking?: string;
 }
-export type Operation = "agent" | "task" | "message" | "join" | "ack" | "event" | "control_result" | "ui";
+export type Operation = "agent" | "task" | "message" | "join" | "ack" | "event" | "control_result" | "ui" | "add_main";
 export function isLive(member: Pick<Member, "status">): boolean {
   return ["starting", "busy", "idle", "stopping"].includes(member.status);
 }

package/src/ui-types.ts

@@ -10,10 +10,14 @@ export interface TeamSnapshot {
 
 export interface PanelHost {
   self: string;
+  /** True in a member session; false in a main session. */
+  child: boolean;
   snapshot(): Promise<TeamSnapshot>;
   visit(id: string): Promise<void>;
   requestTask(text: string): Promise<string>;
   feedback(task: TaskView, text: string): Promise<string>;
   resume(memberId: string): Promise<void>;
+  /** Stops a member and relaunches it as a main session (user only). */
+  promote(memberId: string): Promise<void>;
   drafts: Map<string, string>;
 }