ac-teams 0.0.17 → 0.0.19

package/docs/operations.md

@@ -53,7 +53,25 @@ Choose concurrency using resource readings and observed progress. These advisori
 
 Idle members keep Pi and its extensions alive. Stop unneeded members to release their owned processes, then resume their saved sessions when needed.
 
-This preserves transcripts, tasks, messages, and worktrees. Extension-owned language servers and scanners can dominate memory; ac-teams does not disable them or share them across sessions.
+This preserves transcripts, tasks, messages, and worktrees. Extension-owned language servers and scanners can dominate memory; ac-teams does not disable checks or manage their processes.
+
+### Choose pi-lens reuse or separate analysis
+
+Teammate launches default to `analysis: "auto"`, which sets `PI_LENS_WARM_ATTACH=1` in the child. Active pi-lens can then try its existing same-workspace reuse, including providers outside this team. ac-teams does not install or enable pi-lens; without it, launch proceeds normally.
+
+Choose `analysis: "separate"` for different environments or rules, uncertain compatibility, suspicious diagnostics, or independent analyzer state. This sets the flag to `0` without disabling checks. Different assignments alone do not require separate analyzers.
+
+An inherited `0` remains an explicit opt-out even with `auto`. Other nonempty values besides `1` stay unchanged. Restricted members always receive `0`; the wrapper adds no sharing channels or access.
+
+Resume keeps the member's saved preference unless overridden. Older member records default to `auto`. This choice applies to teammate startup, not live processes or main-session resume.
+
+Launch, list, and status results include `analysis`. When this coordinator launched the member, `analysisPolicy` also reports the effective `warmAttach` value and reason. `reuse requested` does not mean attachment succeeded.
+
+The coordinator does not persist effective startup details; after recovery they appear when the member next launches.
+
+pi-lens owns peer selection, supported shared analysis, and fallback to local analysis. No eligible provider means ordinary local analysis, not a launch failure. An existing leader participates only if its session started with warm attach enabled.
+
+The wrapper leaves plugin configuration, data directories, tool paths, and caches unchanged. It does not prove matching environments or rules, team-only routing, successful attachment, or memory savings. Choose `separate` when those existing pi-lens limitations matter.
 
 ### Avoid repeated work without dropping updates
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ac-teams",
-  "version": "0.0.17",
+  "version": "0.0.19",
   "description": "Small, persistent teams for Pi",
   "type": "module",
   "license": "MIT",

package/src/analysis.ts

@@ -0,0 +1,10 @@
+import type { Member } from "./types.ts";
+
+/** Launch policy only: pi-lens owns attachment, compatibility, and fallback. */
+export function analysisPolicy(member: Pick<Member, "analysis" | "access">, inherited = process.env.PI_LENS_WARM_ATTACH) {
+  if (member.access) return { warmAttach: "0", reason: "separate: restricted access" };
+  if (member.analysis === "separate") return { warmAttach: "0", reason: "separate requested" };
+  if (inherited === "0") return { warmAttach: "0", reason: "separate: explicit opt-out" };
+  if (inherited && inherited !== "1") return { warmAttach: inherited, reason: "inherited setting unchanged" };
+  return { warmAttach: "1", reason: "reuse requested" };
+}

package/src/coordinator.ts

@@ -13,6 +13,7 @@ import { Store, processAlive, processIdentity } from "./store.ts";
 import { stateRoot } from "./config.ts";
 import { RpcAgent } from "./rpc-agent.ts";
 import { hostResources, type HostResources } from "./resources.ts";
+import { analysisPolicy } from "./analysis.ts";
 import { TerminalAgent, tmux } from "./terminal-agent.ts";
 import { authentic, isRecord, readLines, send } from "./connection.ts";
 import { validate } from "./schemas.ts";
@@ -89,6 +90,7 @@ export class Coordinator {
   private plans = new Map<string, SandboxPlan>();
   private releasing = new Map<string, Promise<void>>();
   private sessionDirs = new Map<string, string>();
+  private analysisPolicies = new Map<string, ReturnType<typeof analysisPolicy>>();
   private sandbox?: { status: SandboxStatus; at: number };
 
   private options: CoordinatorOptions;
@@ -340,7 +342,7 @@ export class Coordinator {
   }
   private publicMember(member: Member) {
     const { token: _token, identity: _identity, ...view } = member;
-    return view;
+    return member.role === "member" ? { ...view, analysis: member.analysis ?? "auto", analysisPolicy: this.analysisPolicies.get(member.id) } : view;
   }
   sandboxStatus(): SandboxStatus {
     if (!this.options.credentials) return { available: false, backend: "docker", reason: "This Pi root cannot broker provider credentials" };
@@ -449,7 +451,10 @@ export class Coordinator {
     if (!args.model || !args.model.includes("/")) throw new Error("A provider/model is required (normally inherited from the requesting member)");
     const resumed = args.action === "resume" ? state.members[args.id ?? ""] : undefined;
     if (args.action === "resume" && (!resumed || !resumed.sessionFile || !canControl(state, actor, resumed.id))) throw new Error("Resume requires a stopped member you control with a native session file");
-    if (resumed && isMain(resumed)) return this.resumeMain(resumed.id);
+    if (resumed && isMain(resumed)) {
+      if (args.analysis !== undefined) throw new Error("Analysis can only be set for teammate launches; a main session keeps its own environment");
+      return this.resumeMain(resumed.id);
+    }
     if (resumed && this.cleaning.has(resumed.id)) throw new Error("Worktree cleanup is running; cannot resume this member");
     if (resumed && (isLive(resumed) || (resumed.pid && processAlive(resumed.pid, resumed.identity)))) throw new Error("Cannot resume a live or uncertain member");
     const depth = resumed ? resumed.depth : parent.depth + 1;
@@ -474,6 +479,8 @@ export class Coordinator {
     const locked = resumed ? resumed.provider : parent.access?.network.allow ? parent.provider : undefined;
     if (access?.network.allow && locked && provider !== locked) throw new Error(`A member with restricted network access can only use ${locked} models`);
     const member: Member = resumed ? { ...resumed, token: randomUUID(), status: "starting", error: undefined, contextUsage: undefined, modelName: undefined, handover: undefined } : { id, name: args.name, role: "member", parent: actor, depth, token: randomUUID(), cwd, status: "starting", notified: 0, access, provider: access ? provider : undefined };
+    member.analysis = args.analysis ?? resumed?.analysis ?? "auto";
+    const policy = analysisPolicy(member);
     const resources = this.resources();
     for (const warning of resources.warnings) this.options.warning(warning);
     const assigned = args.task === undefined ? undefined : state.tasks[args.task];
@@ -483,6 +490,7 @@ export class Coordinator {
       next.members[id] = member;
       if (assigned) Object.assign(next.tasks[assigned.id], { owner: id, delegator: actor, revision: next.tasks[assigned.id].revision + 1 });
     });
+    this.analysisPolicies.set(id, policy);
     const brief = assigned ? `${args.brief}\n\nYou own team task ${taskName(assigned)} [${assigned.id}], delegated by ${memberName(parent)}. Start it, and finish with team_task complete and an outcome summary; that one call reports back.` : args.brief;
     this.publishStatus();
     member.model = args.model; member.thinking = args.thinking ?? "off";
@@ -513,7 +521,7 @@ export class Coordinator {
       const rpcArgs = [...(this.options.interactive ? [] : ["--mode", "rpc"]), "--session-dir", sessions, "-e", this.options.extension, "--provider", provider, "--model", modelId, "--thinking", args.thinking ?? "off"];
       if (resumed?.sessionFile) rpcArgs.push("--session", resumed.sessionFile);
       // ACSTACK_AGENT_ROLE tells ACStack hooks this is not a main session; children inherit it.
-      const identity = { HERDR_ENV: "0", ACSTACK_AGENT_ROLE: "member", AC_TEAMS_SOCKET: this.socketPath, AC_TEAMS_MEMBER: id, AC_TEAMS_TOKEN: member.token, AC_TEAMS_ACCESS: JSON.stringify(access ? { enforced: true, ...access } : { enforced: false }) };
+      const identity = { PI_LENS_WARM_ATTACH: policy.warmAttach, HERDR_ENV: "0", ACSTACK_AGENT_ROLE: "member", AC_TEAMS_SOCKET: this.socketPath, AC_TEAMS_MEMBER: id, AC_TEAMS_TOKEN: member.token, AC_TEAMS_ACCESS: JSON.stringify(access ? { enforced: true, ...access } : { enforced: false }) };
       const spawnOptions = access
         ? await this.sandboxed(id, access, member.cwd, provider, modelId, rpcArgs, identity, sessions)
         : { cwd: member.cwd, args: rpcArgs, command: this.options.command, env: { ...process.env, ...identity, AC_TEAMS_TERMINAL_SOCKET: join(this.store.dir, "t.sock") } };

package/src/index.ts

@@ -303,7 +303,7 @@ export default function teams(pi: ExtensionAPI) {
   const taskTrackingGuidance = "Before delegating a deliverable through team_agent, create or reuse a team_task and pass it as the launch task; its owner's completion outcome reports back to you. Use one shared task list for your own work and delegated work; do not create one task per teammate by default. Quick lookups and brief second opinions need no separate task unless their results need coordination or follow-up.";
   pi.registerTool({
     name: "team_agent", label: "Team agent", description: "Launch/resume Pi members, list/status, stop owned subtrees, change root limits, and explicitly clean stopped worktrees. Create or reuse team_task entries for delegated deliverables; quick lookups need no task unless results need coordination or follow-up.",
-    promptGuidelines: [guidance, taskTrackingGuidance, "Delegation needs the user's authorization. Give each new member a unique descriptive name (one or two lowercase words, hyphenated if two), plus a bounded brief. Names remain stable on resume. Avoid concurrent writers in the same cwd. Worktrees are opt-in."],
+    promptGuidelines: [guidance, taskTrackingGuidance, "Analysis defaults to auto: request existing pi-lens same-workspace reuse, possibly from sessions outside this team. If pi-lens is absent or disabled, launch proceeds without enabling it. Explicit environment opt-outs win; restricted members stay separate. Choose analysis: separate for different environments or rules, uncertain compatibility, suspicious diagnostics, or independent analyzer state. Different assignments alone do not require separation. This is a launch/resume preference, not proof of attachment or compatibility; an existing leader participates only if warm attach was already enabled there.", "Delegation needs the user's authorization. Give each new member a unique descriptive name (one or two lowercase words, hyphenated if two), plus a bounded brief. Names remain stable on resume. Avoid concurrent writers in the same cwd. Worktrees are opt-in."],
     parameters: AgentSchema,
     ...teamToolRenderers("team_agent", memberLabels),
     async execute(_id, args, _signal, _update, ctx) { return output(await handle("agent", args, ctx)); },

package/src/schemas.ts

@@ -10,6 +10,7 @@ export const AgentSchema = Type.Object({
   id: Type.Optional(id), brief: Type.Optional(text), cwd: Type.Optional(Type.String({ minLength: 1, maxLength: 4096 })),
   model: Type.Optional(Type.String({ minLength: 1, maxLength: 256 })),
   thinking: Type.Optional(Type.Union(["off", "minimal", "low", "medium", "high", "xhigh"].map(v => Type.Literal(v)))),
+  analysis: Type.Optional(Type.Union([Type.Literal("auto"), Type.Literal("separate")], { description: "Launch/resume only: auto (default) requests existing pi-lens same-workspace reuse, possibly outside this team; explicit environment opt-outs win. Choose separate for different environments or rules, uncertain compatibility, or independent analyzer state. Does not disable checks or guarantee attachment. Resume keeps the saved preference unless overridden; restricted members always use separate analysis." })),
   worktree: Type.Optional(Type.Boolean()), base: Type.Optional(id), target: Type.Optional(id),
   limit: Type.Optional(Type.Integer({ minimum: 1, maximum: 100 })),
   depth: Type.Optional(Type.Integer({ minimum: 0, maximum: 10 })),
@@ -33,16 +34,16 @@ export const TaskSchema = Type.Object({
   offset: Type.Optional(Type.Integer({ minimum: 0 })), limit: Type.Optional(Type.Integer({ minimum: 1, maximum: 100 })),
   action: Type.Union(["create", "list", "read", "edit", "claim", "start", "release", "complete", "reopen"].map(v => Type.Literal(v))),
   id: Type.Optional(id), ...taskFields,
-  summary: Type.Optional(Type.String({ minLength: 1, maxLength: 16000, description: "Complete: the outcome, published atomically with done: what was done, how it was checked, and caveats. Start with the result itself (e.g. 37 lines); the first line is the one people see. Complete enough that the delegator can act without reading detail." })),
-  detail: Type.Optional(Type.String({ minLength: 1, maxLength: 16000, description: "Complete: optional supporting detail, read on demand." })),
+  summary: Type.Optional(Type.String({ minLength: 1, maxLength: 16000, description: "Complete: brief outcome, required action, and critical caveats, published atomically with done and delivered in notices. Put supporting evidence, file references, and check-by-check results in detail." })),
+  detail: Type.Optional(Type.String({ minLength: 1, maxLength: 16000, description: "Complete: optional supporting evidence, checks run, file references, and fuller limitations, read on demand." })),
   tasks: Type.Optional(Type.Array(Type.Object({ ...taskFields, title: Type.String({ minLength: 1, maxLength: 500 }) }, { additionalProperties: false }), { minItems: 1, maxItems: 100, description: "Create several tasks atomically. Use instead of top-level task fields. Dependencies must refer to existing task IDs, not items in this batch." })),
 }, { additionalProperties: false });
 export const MessageSchema = Type.Object({
   action: Type.Union(["send", "history", "search", "wait"].map(v => Type.Literal(v))),
   tasks: Type.Optional(Type.Array(id, { maxItems: 100, uniqueItems: true, description: "Wait: also wake on posts linked to these tasks, e.g. ones you delegated." })),
   recipients: Type.Optional(Type.Array(id, { minItems: 1, maxItems: 100, uniqueItems: true, description: "Exact teammate names or member IDs." })),
-  summary: Type.Optional(Type.String({ minLength: 1, maxLength: 16000, description: "Send: delivered directly to recipients. Start with the point (the first line is the one people see) and what it changes; complete enough to act on." })),
-  detail: Type.Optional(Type.String({ minLength: 1, maxLength: 16000, description: "Send: optional supporting detail, read only when needed." })),
+  summary: Type.Optional(Type.String({ minLength: 1, maxLength: 16000, description: "Send: brief outcome, question, or update, with any required action and critical caveats, delivered directly to recipients. Put supporting evidence, file references, and check-by-check results in detail." })),
+  detail: Type.Optional(Type.String({ minLength: 1, maxLength: 16000, description: "Send: optional supporting evidence, checks run, file references, and fuller limitations, read only when needed." })),
   task: Type.Optional(Type.String({ minLength: 1, maxLength: 128, description: "Send: link an existing task; its owner and delegator receive the post." })),
   replyTo: Type.Optional(Type.String({ minLength: 1, maxLength: 128, description: "Send: the post ID this answers; its author receives the reply and it stays on that post's task." })),
   query: Type.Optional(Type.String({ minLength: 1, maxLength: 500 })),
@@ -75,6 +76,7 @@ export function validate(operation: string, value: unknown): void {
     const args = value as { action: string; name?: string };
     if (args.action === "launch" && !args.name) throw new Error("A descriptive teammate name is required on launch");
     if (args.action !== "launch" && args.name !== undefined) throw new Error("A teammate name can only be set on launch");
+    if (args.action !== "launch" && args.action !== "resume" && (value as { analysis?: unknown }).analysis !== undefined) throw new Error("Analysis can only be set on launch or resume");
     if (args.action !== "launch" && (value as { task?: unknown }).task !== undefined) throw new Error("A task can only be assigned on launch");
     if (args.action !== "launch" && (value as { access?: unknown }).access !== undefined) throw new Error("Access can only be set on launch; resume keeps the member's access");
   }

package/src/store.ts

@@ -116,6 +116,7 @@ function validate(state: unknown): asserts state is TeamState {
     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.waiting === undefined || (object(member.waiting) && Array.isArray(member.waiting.tasks) && member.waiting.tasks.every(task => typeof task === "string" && Object.hasOwn(state.tasks as object, task))), "Invalid member wait");
+    requireValue(member.analysis === undefined || member.analysis === "auto" || member.analysis === "separate", "Invalid member analysis preference");
     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");

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" || key === "ACSTACK_AGENT_ROLE") && value !== undefined)
+        .filter(([key, value]) => (key.startsWith("AC_TEAMS_") || key === "HERDR_ENV" || key === "ACSTACK_AGENT_ROLE" || key === "PI_LENS_WARM_ATTACH") && 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/types.ts

@@ -36,6 +36,8 @@ export interface Member {
   modelName?: string;
   contextUsage?: ContextUsage;
   thinking?: string;
+  /** Launch-time pi-lens preference; absent older records default to auto. */
+  analysis?: "auto" | "separate";
   activity?: string;
   summary?: string;
   terminal?: boolean;
@@ -153,6 +155,7 @@ export interface AgentArgs {
   cwd?: string;
   model?: string;
   thinking?: string;
+  analysis?: "auto" | "separate";
   worktree?: boolean;
   base?: string;
   target?: string;