@midhunxavier/code-flow 0.0.0-stage → 0.1.0-preview.1

package/src/team-templates.js

@@ -0,0 +1,117 @@
+const idPattern = /^[a-z][a-z0-9-]{0,39}$/;
+const object = (v) => !!v && typeof v === "object" && !Array.isArray(v);
+const fail = (message) => {
+  throw new Error(message);
+};
+const text = (v, max = 4e3) => typeof v === "string" && v.length <= max && !v.includes("\0") ? v : fail("Template text is missing or too long");
+const ident = (v) => typeof v === "string" && idPattern.test(v) ? v : fail("Use lowercase template identifiers (up to 40 characters)");
+const list = (v, max = 24) => Array.isArray(v) && v.length <= max ? v.map((x) => text(x)) : fail("Invalid template list");
+function validateTeamTemplate(raw) {
+  if (!object(raw) || raw.schemaVersion !== 1) return fail("Expected a version 1 team template");
+  const keys = ["schemaVersion", "id", "version", "name", "description", "scope", "project", "autoEnabled", "parameters", "roles", "tasks", "contracts", "workflow", "task", "criteria", "preferences"];
+  if (Object.keys(raw).some((k) => !keys.includes(k))) return fail("Templates cannot contain permissions, credentials, sessions, or unsupported fields");
+  if (!Number.isSafeInteger(raw.version) || raw.version < 1 || !["builtin", "personal", "project"].includes(raw.scope) || typeof raw.autoEnabled !== "boolean") return fail("Invalid template version or scope");
+  if (raw.scope === "project" !== (typeof raw.project === "string" && !!raw.project)) return fail("Project templates need a project; personal templates cannot bind one");
+  const parameters = list(raw.parameters).map(ident), roles = list(raw.roles, 6).map(ident);
+  if (new Set(parameters).size !== parameters.length || new Set(roles).size !== roles.length) return fail("Duplicate template parameters or roles");
+  if (!Array.isArray(raw.tasks) || raw.tasks.length > 24) return fail("A template can contain at most 24 tasks");
+  const tasks = raw.tasks.map((t) => {
+    if (!object(t) || Object.keys(t).some((k) => !["id", "title", "role", "kind", "instructions", "dependsOn", "dependencyTypes", "paths", "acceptance"].includes(k)) || !["implementation", "investigation"].includes(t.kind)) return fail("Invalid template task");
+    const task = { id: ident(t.id), title: text(t.title, 200), role: ident(t.role), kind: t.kind, instructions: text(t.instructions, 8e3), dependsOn: list(t.dependsOn).map(ident), paths: list(t.paths), acceptance: list(t.acceptance) };
+    if (t.dependencyTypes !== void 0) {
+      if (!object(t.dependencyTypes) || Object.entries(t.dependencyTypes).some(([id, kind]) => !task.dependsOn.includes(id) || !["completion", "artifact", "knowledge"].includes(kind))) return fail("Invalid template dependency types");
+      task.dependencyTypes = { ...t.dependencyTypes };
+    }
+    if (!roles.includes(task.role) || !task.title.trim() || !task.instructions.trim() || !task.acceptance.length || task.acceptance.some((c) => !c.trim()) || !task.paths.length) return fail("Every task needs a role, instructions, owned paths, and acceptance criteria");
+    for (const path of task.paths) if (!validTemplatePath(path)) return fail("Template paths must be repository relative");
+    return task;
+  });
+  const ids = new Set(tasks.map((t) => t.id));
+  if (ids.size !== tasks.length) return fail("Duplicate template task IDs");
+  const seen = /* @__PURE__ */ new Set(), visiting = /* @__PURE__ */ new Set();
+  const visit = (id) => {
+    if (visiting.has(id)) return fail("Template dependencies contain a cycle");
+    if (seen.has(id)) return;
+    const task = tasks.find((t) => t.id === id);
+    if (!task) return fail(`Unknown template dependency ${id}`);
+    visiting.add(id);
+    task.dependsOn.forEach(visit);
+    visiting.delete(id);
+    seen.add(id);
+  };
+  tasks.forEach((t) => visit(t.id));
+  const workflow = raw.workflow === void 0 ? void 0 : ident(raw.workflow);
+  if (workflow && tasks.length || !workflow && !tasks.length) return fail("Choose a fixed workflow or a task graph");
+  if (workflow && raw.autoEnabled) return fail("Fixed workflows are manual templates; Auto composes validated task graphs");
+  const result = { schemaVersion: 1, id: ident(raw.id), version: raw.version, name: text(raw.name, 100), description: text(raw.description), scope: raw.scope, ...raw.project ? { project: text(raw.project, 200) } : {}, autoEnabled: raw.autoEnabled, parameters, roles, tasks, contracts: list(raw.contracts), ...workflow ? { workflow } : {}, task: text(raw.task, 1e5), criteria: list(raw.criteria, 100) };
+  if (!result.name.trim() || !result.task.trim()) return fail("Give the template a name and a task prompt");
+  if (raw.preferences !== void 0) result.preferences = templatePreferences(raw.preferences);
+  const body = JSON.stringify([tasks, result.contracts, result.task, result.criteria]);
+  for (const match of body.matchAll(/\{\{([a-z][a-z0-9-]*)\}\}/g)) if (!parameters.includes(match[1])) return fail(`Undeclared parameter ${match[1]}`);
+  if (JSON.stringify(result).length > 15e4) return fail("Template is too large");
+  return result;
+}
+function templatePreferences(raw) {
+  if (!object(raw) || Object.keys(raw).some((k) => !["roles", "options", "agentSettings", "roleSettings"].includes(k))) return fail("Template preferences may contain only roles, options and model settings");
+  const record = (v, parse) => {
+    if (!object(v) || Object.keys(v).length > 64 || Object.keys(v).some((k) => !/^[a-zA-Z][a-zA-Z0-9_:/.-]{0,150}$/.test(k) || ["constructor", "prototype", "__proto__"].includes(k))) return fail("Invalid template preference record");
+    return Object.fromEntries(Object.entries(v).map(([k, value]) => [k, parse(value)]));
+  };
+  const settings = (v) => record(v, (value) => {
+    if (!object(value) || Object.keys(value).some((k) => !["model", "effort", "variants"].includes(k))) return fail("Only model and effort preferences are supported");
+    if (value.variants !== void 0 && (!Array.isArray(value.variants) || value.variants.length > 128)) return fail("Invalid model variants");
+    const variants = value.variants?.map((v2) => {
+      if (!object(v2) || Object.keys(v2).some((k) => !["model", "effort"].includes(k))) return fail("Invalid model variant");
+      return { model: text(v2.model, 256), ...v2.effort !== void 0 ? { effort: text(v2.effort, 64) } : {} };
+    });
+    return { ...value.model !== void 0 ? { model: text(value.model, 256) } : {}, ...value.effort !== void 0 ? { effort: text(value.effort, 64) } : {}, ...variants ? { variants } : {} };
+  });
+  return { roles: record(raw.roles ?? {}, (value) => list(value, 6)), options: record(raw.options ?? {}, (value) => typeof value === "boolean" || typeof value === "number" && Number.isFinite(value) ? value : fail("Invalid workflow option")), agentSettings: settings(raw.agentSettings ?? {}), roleSettings: record(raw.roleSettings ?? {}, settings) };
+}
+function validTemplatePath(path) {
+  return path === "*" || !!path && !/^[/-]|^[A-Za-z]:|[\\\x00-\x1f]/.test(path) && !path.split("/").some((p) => !p || p === "." || p === ".." || p === ".git") && !path.includes("*");
+}
+function fillTeamTemplate(template, inputs) {
+  if (Object.keys(inputs).some((k) => !template.parameters.includes(k))) return fail("Unknown template input");
+  for (const key of template.parameters) if (typeof inputs[key] !== "string" || !inputs[key].trim() || inputs[key].length > 1e4) return fail(`Enter a value for ${key}`);
+  const fill = (s) => s.replace(/\{\{([a-z][a-z0-9-]*)\}\}/g, (_, key) => inputs[key]);
+  return validateTeamTemplate({ ...template, task: fill(template.task), criteria: template.criteria.map(fill), contracts: template.contracts.map(fill), tasks: template.tasks.map((t) => ({ ...t, title: fill(t.title), instructions: fill(t.instructions), acceptance: t.acceptance.map(fill), paths: t.paths.map(fill) })) });
+}
+function expandTemplateUses(plan, catalog) {
+  const tasks = [...plan.tasks], contracts = [...plan.contracts];
+  if ((plan.templateUses?.length ?? 0) > 6) return fail("Too many template uses");
+  const uses = /* @__PURE__ */ new Set();
+  for (const use of plan.templateUses ?? []) {
+    if (!/^[a-z][a-z0-9-]{0,11}$/.test(use.id) || uses.has(use.id)) return fail("Template instance IDs must be unique and at most 12 characters");
+    uses.add(use.id);
+    const source = catalog.find((t) => t.id === use.templateId && t.version === use.version && !t.workflow);
+    if (!source) return fail("Template version is not in this run's pinned catalog");
+    const inputs = Object.fromEntries(use.inputs.map((i) => [i.name, i.value]));
+    const assignments = Object.fromEntries(use.assignments.map((a) => [a.role, a.memberId]));
+    if (Object.keys(inputs).length !== use.inputs.length || Object.keys(assignments).length !== use.assignments.length || Object.keys(assignments).some((r) => !source.roles.includes(r))) return fail("Duplicate or unknown template bindings");
+    const template = fillTeamTemplate(source, inputs);
+    for (const role of template.roles) if (!assignments[role]) return fail(`Assign the ${role} template role`);
+    for (const t of template.tasks) {
+      const id = `${use.id}-${t.id}`;
+      if (id.length > 40) return fail("Expanded task ID is too long");
+      tasks.push({ id, title: t.title, kind: t.kind, owner: assignments[t.role], instructions: `${t.instructions}${use.instructions ? `
+Task-specific additions:
+${text(use.instructions)}` : ""}`, dependsOn: [...use.dependsOn, ...t.dependsOn.map((d) => `${use.id}-${d}`)], ...t.dependencyTypes ? { dependencyTypes: Object.fromEntries(Object.entries(t.dependencyTypes).map(([id2, kind]) => [`${use.id}-${id2}`, kind])) } : {}, requirements: [...use.requirements], paths: [...t.paths], acceptance: [...t.acceptance] });
+    }
+    contracts.push(...template.contracts, ...template.criteria);
+  }
+  if (tasks.length > 24 || contracts.length > 24) return fail("Expanded templates exceed the run's task or contract limits");
+  return { ...plan, tasks, contracts };
+}
+function templateFromPlan(plan, input) {
+  const owners = [...new Set(plan.tasks.map((t) => t.owner))];
+  const role = (owner) => `worker-${owners.indexOf(owner) + 1}`;
+  return validateTeamTemplate({ schemaVersion: 1, ...input, version: 1, description: "Strategy saved from a run. Review task-specific instructions and replace them with parameters before reuse.", autoEnabled: false, parameters: ["task"], roles: owners.map(role), task: "{{task}}", criteria: [], contracts: [...plan.contracts], tasks: plan.tasks.map((t) => ({ id: t.id, role: role(t.owner), title: t.title, kind: t.kind, instructions: t.instructions, dependsOn: [...t.dependsOn], ...t.dependencyTypes ? { dependencyTypes: { ...t.dependencyTypes } } : {}, paths: [...t.paths], acceptance: [...t.acceptance] })) });
+}
+export {
+  expandTemplateUses,
+  fillTeamTemplate,
+  templateFromPlan,
+  templatePreferences,
+  validateTeamTemplate
+};

package/src/team-tool-client.mjs

@@ -0,0 +1,79 @@
+#!/usr/bin/env node
+// Dependency-free stdio MCP transport. Only the parent-created member capability is used;
+// this process has no file, shell, permission-approval, or identity-selection operations.
+import { createInterface } from "node:readline";
+import { readFileSync, unlinkSync } from "node:fs";
+
+let connection;
+try {
+  if (process.argv[2] === "--connection") {
+    connection = JSON.parse(readFileSync(process.argv[3], "utf8"));
+    // Read once, then gone: every CLI on this machine runs as the same user, so a credential
+    // left on disk could be read by another member's shell for as long as the turn lasts.
+    try { unlinkSync(process.argv[3]); } catch { /* already removed */ }
+  }
+} catch { process.exit(1); }
+const endpoint = connection?.endpoint ?? process.env.CODEFLOW_TEAM_ENDPOINT;
+const token = connection?.token ?? process.env.CODEFLOW_TEAM_CAPABILITY;
+delete process.env.CODEFLOW_TEAM_CAPABILITY;
+delete process.env.CODEFLOW_TOKEN;
+if (!endpoint || !/^http:\/\/127\.0\.0\.1:\d+\/v1\/runs\//.test(endpoint) || !token) process.exit(1);
+
+let initialized = false;
+const send = (value) => process.stdout.write(`${JSON.stringify(value)}\n`);
+async function bridge(body) {
+  const response = await fetch(endpoint, {
+    method: "POST", redirect: "error", signal: AbortSignal.timeout(10_000),
+    headers: { "content-type": "application/json", authorization: `Bearer ${token}` },
+    body: JSON.stringify(body),
+  });
+  const result = await response.json();
+  if (!response.ok || result.error) throw new Error(result.error ?? "Team bridge request failed");
+  return result;
+}
+async function request(message) {
+  // JSON can parse successfully without yielding a JSON-RPC object (for example null).
+  // Reject the envelope before dereferencing it so malformed input cannot terminate MCP.
+  const validId = (id) => typeof id === "string" || typeof id === "number" && Number.isFinite(id);
+  if (!message || typeof message !== "object" || Array.isArray(message) || message.jsonrpc !== "2.0" ||
+      typeof message.method !== "string" || (message.id !== undefined && !validId(message.id))) {
+    send({ jsonrpc: "2.0", id: validId(message?.id) ? message.id : null, error: { code: -32600, message: "Invalid request" } }); return;
+  }
+  const id = message.id;
+  if (id === undefined) return;
+  try {
+    let result;
+    if (message.method === "initialize") {
+      initialized = true;
+      const supported = ["2025-11-25", "2025-06-18", "2025-03-26", "2024-11-05"];
+      result = { protocolVersion: supported.includes(message.params?.protocolVersion) ? message.params.protocolVersion : "2025-03-26", capabilities: { tools: {} }, serverInfo: { name: "code-flow-team", version: "1.0.0" } };
+    } else if (message.method === "ping") result = {};
+    else if (!initialized) throw new Error("Initialize the team bridge first");
+    else if (message.method === "tools/list") result = await bridge({ method: "tools/list" });
+    else if (message.method === "tools/call") {
+      try {
+        const value = await bridge({ name: message.params?.name, arguments: message.params?.arguments ?? {} });
+        result = { content: [{ type: "text", text: JSON.stringify(value.result) }], isError: false };
+      } catch (error) { result = { content: [{ type: "text", text: error instanceof Error ? error.message : "Team command failed" }], isError: true }; }
+    } else {
+      send({ jsonrpc: "2.0", id, error: { code: -32601, message: "Method not found" } }); return;
+    }
+    send({ jsonrpc: "2.0", id, result });
+  } catch (error) { send({ jsonrpc: "2.0", id, error: { code: -32603, message: error instanceof Error ? error.message : "Team bridge failed" } }); }
+}
+
+const input = createInterface({ input: process.stdin, crlfDelay: Infinity });
+let inflight = 0;
+const limit = (id) => send({ jsonrpc: "2.0", id, error: { code: -32600, message: "Request exceeds bridge limits" } });
+/** The id of an envelope too large to parse, so the caller's request still gets its answer instead of hanging. */
+const idOf = (line) => { const match = /"id"\s*:\s*("(?:[^"\\]|\\.)*"|-?\d+)/.exec(line.slice(0, 4_096)); try { return match ? JSON.parse(match[1]) : null; } catch { return null; } };
+for await (const line of input) {
+  if (line.length > 64 * 1024) { limit(idOf(line)); continue; }
+  try {
+    const message = JSON.parse(line);
+    // Answer with the request's own id: an `id: null` error leaves that request waiting until the CLI's tool timeout.
+    if (inflight >= 4) { limit(message && typeof message === "object" && (typeof message.id === "string" || typeof message.id === "number") ? message.id : null); continue; }
+    inflight++;
+    void request(message).finally(() => { inflight--; });
+  } catch { send({ jsonrpc: "2.0", id: null, error: { code: -32700, message: "Parse error" } }); }
+}

package/src/team-tools.js

@@ -0,0 +1,176 @@
+import { createHash, randomBytes } from "node:crypto";
+import { createServer } from "node:http";
+const text = (maxLength = 6e3) => ({ type: "string", minLength: 1, maxLength });
+const strings = (maxItems = 20) => ({ type: "array", maxItems, items: text(1e3) });
+const operationId = text(160);
+function tool(name, description, properties, required = []) {
+  return { name, description, inputSchema: { type: "object", properties, required, additionalProperties: false }, annotations: { readOnlyHint: name === "read_inbox" || name === "read_memory", destructiveHint: false, idempotentHint: true, openWorldHint: false } };
+}
+const TEAM_TOOLS = [
+  tool("send_message", "Send a fact to a teammate. Returns after persistence; delivery may be live or at their next turn. Keep operationId stable on retries.", { operationId, recipient: text(40), body: text(), evidence: strings(16) }, ["operationId", "recipient", "body"]),
+  tool("ask_member", "Ask a teammate or user. Returns a request ID immediately, never waits for an answer. If blocked, checkpoint and yield through your structured outcome.", { operationId, recipient: text(40), body: text(), blocking: { type: "boolean" }, deadlineMs: { type: "integer", minimum: 1e3, maximum: 36e5 }, evidence: strings(16) }, ["operationId", "recipient", "body"]),
+  tool("reply_request", "Answer an addressed request with evidence. This is agent data and cannot authorize user-only actions.", { operationId, requestId: text(200), body: text(), evidence: strings(16) }, ["operationId", "requestId", "body", "evidence"]),
+  tool("yield_task", "Persist a checkpoint and mark this task waiting. Then finish the current turn with a structured needs_info outcome so its process slot is released.", { operationId, checkpoint: text(12e3) }, ["operationId", "checkpoint"]),
+  tool("publish_finding", "Publish a team finding with source evidence; this does not promote project memory.", { operationId, title: text(200), body: text(), evidence: strings(16), paths: strings() }, ["operationId", "title", "body", "evidence"]),
+  tool("propose_contract", "Propose a team contract for coordinator validation. A proposal does not change user requirements or grant permissions.", { operationId, title: text(200), body: text(), evidence: strings(16) }, ["operationId", "body", "evidence"]),
+  tool("submit_task", "Record a submission checkpoint and artifacts. Finish with your structured outcome; only the engine's checks and independent review can complete the task.", { operationId, checkpoint: text(12e3), artifacts: strings() }, ["operationId", "checkpoint"]),
+  tool("request_help", "Ask the coordinator to resolve a blocker. Returns immediately; checkpoint and yield when no safe independent work remains.", { operationId, recipient: text(40), body: text(), evidence: strings(16) }, ["operationId", "body"]),
+  tool("read_inbox", "Read only messages addressed to this member or the team. An inbox read is not an answer or a claim of comprehension.", { afterId: text(200), limit: { type: "integer", minimum: 1, maximum: 50 } }),
+  tool("read_memory", "Read bounded memory selected for this member's current run and task. Private memory is restricted to this member; project entries retain provenance and applicability.", { scope: { enum: ["private", "team", "project"] }, query: text(1e3), limit: { type: "integer", minimum: 1, maximum: 20 } }, ["scope"]),
+  tool("write_memory", "Save private notes or propose team notes with run-derived provenance. Team proposals stay unaccepted; publish_finding shares immediate findings. This cannot create accepted project conventions or export private notes.", { operationId, scope: { enum: ["private", "team"] }, title: text(200), body: text(12e3), tags: strings(), paths: strings() }, ["operationId", "scope", "title", "body"]),
+  tool("propose_project_memory", "Propose a reusable project lesson for later review. Acceptance, trust, and repository applicability remain controlled by the server and user.", { operationId, title: text(200), body: text(12e3), tags: strings(), paths: strings() }, ["operationId", "title", "body"])
+];
+const definitions = new Map(TEAM_TOOLS.map((value) => [value.name, value]));
+const MAX_BODY = 64 * 1024;
+const MAX_RESPONSE = 128 * 1024;
+const MAX_TTL = 25 * 60 * 6e4;
+function validateTeamToolRequest(value) {
+  if (!value || typeof value !== "object" || Array.isArray(value)) throw new Error("Invalid tool request");
+  const input = value;
+  if (Object.keys(input).some((key) => key !== "name" && key !== "arguments")) throw new Error("Unexpected tool request field");
+  const definition = definitions.get(input.name);
+  if (!definition) throw new Error("Unknown team tool");
+  const args = input.arguments ?? {};
+  if (!args || typeof args !== "object" || Array.isArray(args)) throw new Error("Tool arguments must be an object");
+  const schema = definition.inputSchema;
+  const fields = schema.properties;
+  for (const key of Object.keys(args)) if (!Object.hasOwn(fields, key)) throw new Error(`Unexpected argument: ${key}`);
+  for (const key of schema.required) if (!Object.hasOwn(args, key)) throw new Error(`Missing argument: ${key}`);
+  for (const [key, value2] of Object.entries(args)) {
+    const field = fields[key];
+    if (field.enum && !field.enum.includes(value2)) throw new Error(`Invalid argument: ${key}`);
+    if (field.type === "string" && (typeof value2 !== "string" || !value2.trim() || value2.length > field.maxLength)) throw new Error(`Invalid argument: ${key}`);
+    if (field.type === "boolean" && typeof value2 !== "boolean") throw new Error(`Invalid argument: ${key}`);
+    if (field.type === "integer" && (typeof value2 !== "number" || !Number.isSafeInteger(value2) || value2 < field.minimum || value2 > field.maximum)) throw new Error(`Invalid argument: ${key}`);
+    if (field.type === "array" && (!Array.isArray(value2) || value2.length > field.maxItems || value2.some((item) => typeof item !== "string" || !item.trim() || item.length > field.items.maxLength))) throw new Error(`Invalid argument: ${key}`);
+  }
+  return { name: definition.name, arguments: args };
+}
+class TeamToolBridge {
+  server;
+  listening;
+  grants = /* @__PURE__ */ new Map();
+  async issue(options) {
+    const { identity } = options;
+    if (!identity.runId || !identity.memberId || !identity.attemptId) throw new Error("A team capability requires a run, member and attempt");
+    if (options.signal?.aborted) throw new Error("Cannot issue a team capability for a stopped turn");
+    const base = await this.listen();
+    if (options.signal?.aborted) throw new Error("Cannot issue a team capability for a stopped turn");
+    const token = randomBytes(32).toString("base64url");
+    const key = digest(token);
+    const path = `/v1/runs/${encodeURIComponent(identity.runId)}/members/${encodeURIComponent(identity.memberId)}/attempts/${encodeURIComponent(identity.attemptId)}`;
+    const ttl = typeof options.ttlMs === "number" && Number.isFinite(options.ttlMs) ? Math.max(1, Math.min(MAX_TTL, options.ttlMs)) : 30 * 6e4;
+    const expiresAt = Date.now() + ttl;
+    this.grants.set(key, { identity: Object.freeze({ ...identity }), path, expiresAt, handler: options.handler, isActive: options.isActive, pending: 0 });
+    let timer;
+    const revoke = () => {
+      this.grants.delete(key);
+      clearTimeout(timer);
+      options.signal?.removeEventListener("abort", revoke);
+    };
+    timer = setTimeout(revoke, ttl);
+    timer.unref();
+    options.signal?.addEventListener("abort", revoke, { once: true });
+    return { connection: { endpoint: base + path, token, expiresAt }, revoke };
+  }
+  async close() {
+    this.grants.clear();
+    const server = this.server;
+    this.server = void 0;
+    this.listening = void 0;
+    if (server) await new Promise((resolve) => {
+      server.close(() => resolve());
+      server.closeAllConnections();
+    });
+  }
+  listen() {
+    if (this.listening) return this.listening;
+    const server = createServer((req, res) => {
+      void this.handle(req, res);
+    });
+    this.server = server;
+    server.requestTimeout = 1e4;
+    server.headersTimeout = 1e4;
+    server.maxHeadersCount = 30;
+    this.listening = new Promise((resolve, reject) => {
+      server.once("error", (error) => {
+        this.listening = void 0;
+        this.server = void 0;
+        reject(error);
+      });
+      server.listen(0, "127.0.0.1", () => {
+        server.unref();
+        const address = server.address();
+        if (!address || typeof address === "string") {
+          reject(new Error("Could not start team bridge"));
+          return;
+        }
+        resolve(`http://127.0.0.1:${address.port}`);
+      });
+    });
+    return this.listening;
+  }
+  async handle(req, res) {
+    const reply = (status, body) => {
+      if (res.destroyed || res.writableEnded) return;
+      const json = JSON.stringify(body ?? null);
+      res.writeHead(status, { "content-type": "application/json", "cache-control": "no-store", "x-content-type-options": "nosniff" });
+      res.end(json.length <= MAX_RESPONSE ? json : JSON.stringify({ error: "Tool response exceeded its context limit" }));
+    };
+    if (req.method !== "POST" || req.headers.origin || req.headers["content-type"] !== "application/json") {
+      reply(403, { error: "Forbidden team bridge request" });
+      return;
+    }
+    const auth = req.headers.authorization;
+    const token = typeof auth === "string" && /^Bearer [A-Za-z0-9_-]{43}$/.test(auth) ? auth.slice(7) : "";
+    const grant = token ? this.grants.get(digest(token)) : void 0;
+    if (!grant || req.url !== grant.path || grant.expiresAt <= Date.now() || grant.isActive?.() === false) {
+      reply(403, { error: "Invalid or expired member capability" });
+      return;
+    }
+    if (grant.pending >= 4) {
+      reply(429, { error: "Too many active member commands" });
+      return;
+    }
+    grant.pending++;
+    try {
+      const chunks = [];
+      let size = 0;
+      for await (const chunk of req) {
+        size += chunk.length;
+        if (size > MAX_BODY) {
+          reply(413, { error: "Team command is too large" });
+          return;
+        }
+        chunks.push(chunk);
+      }
+      if (this.grants.get(digest(token)) !== grant || grant.expiresAt <= Date.now() || grant.isActive?.() === false) {
+        reply(403, { error: "Invalid or expired member capability" });
+        return;
+      }
+      const body = JSON.parse(Buffer.concat(chunks).toString("utf8"));
+      if (body?.method === "tools/list" && Object.keys(body).length === 1) {
+        reply(200, { tools: TEAM_TOOLS });
+        return;
+      }
+      const request = validateTeamToolRequest(body);
+      const value = await grant.handler(request, grant.identity);
+      reply(200, { result: value ?? null });
+    } catch (error) {
+      const message = error instanceof Error ? error.message : "Team command failed";
+      reply(message.includes("no longer active") ? 403 : 400, { error: message.replaceAll(token, "[redacted]").slice(0, 1e3) });
+    } finally {
+      grant.pending--;
+    }
+  }
+}
+function digest(token) {
+  return createHash("sha256").update(token).digest("hex");
+}
+const teamToolBridge = new TeamToolBridge();
+export {
+  TEAM_TOOLS,
+  TeamToolBridge,
+  teamToolBridge,
+  validateTeamToolRequest
+};

package/src/templates.js

@@ -0,0 +1,62 @@
+const templates = [
+  {
+    id: "fix-issue",
+    name: "Fix an issue",
+    description: "Plan, build and review a fix for a GitHub issue; the PR closes it.",
+    pattern: "pipeline",
+    needs: "issue",
+    task: "Fix issue #{number}. Add a test that fails without the fix."
+  },
+  {
+    id: "fix-ci",
+    name: "Fix failing CI",
+    description: "Hand a PR's failing checks and their logs to an agent; push the fix to the PR.",
+    pattern: "pipeline",
+    needs: "pr",
+    ciLogs: true,
+    task: "Make CI pass on pull request #{number}. The failing checks and their logs are below. Fix the cause; don't disable, skip or weaken tests."
+  },
+  {
+    id: "review-pr",
+    name: "Review a PR as a council",
+    description: "Several agents review the PR independently; a chair merges their findings. You choose whether to post it.",
+    pattern: "council",
+    needs: "pr",
+    task: "Review pull request #{number}. Look for bugs, security problems, missing tests, and anything that doesn't match its description."
+  },
+  {
+    id: "upgrade-dependency",
+    name: "Upgrade a dependency",
+    description: "Bump a package, read its changelog for breaking changes, and keep the tests green.",
+    pattern: "pipeline",
+    task: "Upgrade PACKAGE to its latest version. Read its changelog for breaking changes, update every call site, and keep the tests passing."
+  },
+  {
+    id: "sweep-issues",
+    name: "Fix open issues",
+    description: "List the open issues, pick the ones to fix, and start one Plan \u2192 Build \u2192 Review run each. Results wait in your inbox.",
+    pattern: "pipeline",
+    sweep: "issues",
+    task: "Fix the GitHub issue below. Add a test that fails without the fix."
+  },
+  {
+    id: "sweep-dependabot",
+    name: "Fix Dependabot PRs",
+    description: "Every Dependabot PR whose CI fails gets a run that fixes it; approving pushes the fix to the PR. Green ones are left for you to merge.",
+    pattern: "pipeline",
+    sweep: "dependabot",
+    ciLogs: true,
+    task: "Make CI pass on the Dependabot pull request below by adapting the code to the new version. Don't pin it back, and don't disable, skip or weaken tests."
+  },
+  {
+    id: "sweep-alerts",
+    name: "Fix security alerts",
+    description: "Dependabot alerts (one run per package) and code scanning alerts (one per alert). Leaked secrets are listed for you to rotate; agents never get them.",
+    pattern: "pipeline",
+    sweep: "alerts",
+    task: "Fix the security alert below. Fix the cause rather than suppressing the alert, and keep the tests passing."
+  }
+];
+export {
+  templates
+};

package/src/transcript.js

@@ -0,0 +1,134 @@
+import { constants } from "node:fs";
+import { open } from "node:fs/promises";
+import { join } from "node:path";
+import { RUNS_DIR, waitForRunWrites } from "./store.js";
+const TRANSCRIPT_LIMITS = { events: 500, bytes: 1024 * 1024, recordBytes: 64 * 1024 * 1024, scanBytes: 16 * 1024 * 1024, fieldChars: 32 * 1024 };
+class TranscriptCursorError extends Error {
+}
+function transcriptPreview(event) {
+  const shorten = (value) => value.length > TRANSCRIPT_LIMITS.fieldChars ? value.slice(0, TRANSCRIPT_LIMITS.fieldChars) + "\n[Preview shortened; the complete event is in the run export.]" : value;
+  if (event.type === "log") return { ...event, text: shorten(event.text) };
+  if (event.type !== "agent") return event;
+  return { ...event, event: Object.fromEntries(Object.entries(event.event).map(([key, value]) => [key, typeof value === "string" ? shorten(value) : value])) };
+}
+async function* reverseLines(file, end) {
+  let position = end, pending = [], pendingBytes = 0;
+  while (position > 0) {
+    const size = Math.min(position, 64 * 1024);
+    position -= size;
+    const chunk = Buffer.allocUnsafe(size);
+    const { bytesRead } = await file.read(chunk, 0, size, position);
+    if (bytesRead !== size) throw new TranscriptCursorError("Transcript changed; reload its latest page");
+    let right = size;
+    for (let index = size - 1; index >= 0; index--) {
+      if (chunk[index] !== 10) continue;
+      const part = chunk.subarray(index + 1, right);
+      if (part.length + pendingBytes > TRANSCRIPT_LIMITS.recordBytes) throw new Error("Transcript record exceeds the 64 MiB bound");
+      if (part.length || pendingBytes) {
+        const text = pending.length ? Buffer.concat([part, ...pending.reverse()], part.length + pendingBytes).toString("utf8") : part.toString("utf8");
+        yield { text, offset: position + index + 1 };
+      } else {
+        while (index > 0 && chunk[index - 1] === 10) index--;
+        yield { text: "", offset: position === 0 && index === 0 ? 0 : position + index + 1 };
+      }
+      pending = [];
+      pendingBytes = 0;
+      right = index;
+    }
+    if (right) {
+      const part = chunk.subarray(0, right);
+      pending.push(part);
+      pendingBytes += part.length;
+    }
+    if (pendingBytes > TRANSCRIPT_LIMITS.recordBytes) throw new Error("Transcript record exceeds the 64 MiB bound");
+  }
+  if (pendingBytes) yield { text: Buffer.concat(pending.reverse(), pendingBytes).toString("utf8"), offset: 0 };
+}
+async function transcriptPage(id, input = {}, reader = reverseLines) {
+  if (!/^[a-zA-Z0-9][a-zA-Z0-9._-]{0,199}$/.test(id)) throw new TranscriptCursorError("Invalid run ID");
+  const limit = input.limit ?? TRANSCRIPT_LIMITS.events;
+  if (!Number.isInteger(limit) || limit < 1 || limit > TRANSCRIPT_LIMITS.events) throw new TranscriptCursorError("Invalid transcript page size");
+  await waitForRunWrites(id);
+  input.signal?.throwIfAborted();
+  const file = await open(join(RUNS_DIR, `${id}.jsonl`), constants.O_RDONLY | (constants.O_NOFOLLOW ?? 0));
+  try {
+    const info = await file.stat({ bigint: true });
+    if (!info.isFile()) throw new Error("Transcript must be a regular file");
+    let end = Number(info.size);
+    if (input.before) {
+      let cursor;
+      try {
+        if (input.before.length > 1024) throw new Error();
+        cursor = JSON.parse(Buffer.from(input.before, "base64url").toString());
+      } catch {
+        throw new TranscriptCursorError("Invalid transcript cursor");
+      }
+      if (!cursor || cursor.run !== id || cursor.dev !== String(info.dev) || cursor.ino !== String(info.ino) || !Number.isSafeInteger(cursor.offset) || cursor.offset < 0 || cursor.offset > end) throw new TranscriptCursorError("Transcript changed; reload its latest page");
+      end = cursor.offset;
+      if (end) {
+        const byte = Buffer.alloc(1);
+        await file.read(byte, 0, 1, end - 1);
+        if (byte[0] !== 10) throw new TranscriptCursorError("Invalid transcript boundary");
+      }
+    }
+    const events = [];
+    let bytes = 0, offset = end, latestSeq = 0, resumed = input.after === 0;
+    for await (const line of reader(file, end)) {
+      input.signal?.throwIfAborted();
+      const skip = () => {
+        offset = line.offset;
+        return end - offset >= TRANSCRIPT_LIMITS.scanBytes;
+      };
+      if (!line.text.trim()) {
+        if (skip()) break;
+        continue;
+      }
+      let event;
+      try {
+        event = JSON.parse(line.text);
+      } catch {
+        if (skip()) break;
+        continue;
+      }
+      if (!event || event.runId !== id || !Number.isSafeInteger(event.seq)) {
+        if (skip()) break;
+        continue;
+      }
+      latestSeq = Math.max(latestSeq, event.seq);
+      if (input.after !== void 0 && event.seq <= input.after) {
+        resumed = true;
+        break;
+      }
+      if ((event.type === "agent" || event.type === "log") && (!input.step || event.type === "agent" && event.stepId === input.step)) {
+        if (event.type === "agent" && (!event.event || typeof event.event !== "object") || event.type === "log" && typeof event.text !== "string") {
+          if (skip()) break;
+          continue;
+        }
+        let preview = transcriptPreview(event), size = Buffer.byteLength(JSON.stringify(preview));
+        if (size > TRANSCRIPT_LIMITS.bytes) {
+          const text = "[Preview omitted because this event exceeds the display limit; the complete event is in the run export.]";
+          const ts = Number.isFinite(event.ts) ? event.ts : 0;
+          preview = event.type === "agent" ? { type: "agent", runId: id, stepId: typeof event.stepId === "string" ? event.stepId.slice(0, 200) : "", seq: event.seq, ts, event: { kind: "status", text } } : { type: "log", runId: id, seq: event.seq, ts, level: "info", text };
+          size = Buffer.byteLength(JSON.stringify(preview));
+        }
+        if (events.length >= limit || bytes + size > TRANSCRIPT_LIMITS.bytes) break;
+        events.push(preview);
+        bytes += size;
+      }
+      offset = line.offset;
+      if (end - offset >= TRANSCRIPT_LIMITS.scanBytes) break;
+    }
+    const after = await file.stat({ bigint: true });
+    if (after.size < info.size) throw new TranscriptCursorError("Transcript changed; reload its latest page");
+    const before = offset > 0 ? Buffer.from(JSON.stringify({ run: id, dev: String(info.dev), ino: String(info.ino), offset })).toString("base64url") : void 0;
+    return { events: events.reverse(), before, latestSeq, bytes, scannedBytes: end - offset, resumed: input.after !== void 0 && input.after <= latestSeq && (resumed || !before) };
+  } finally {
+    await file.close();
+  }
+}
+export {
+  TRANSCRIPT_LIMITS,
+  TranscriptCursorError,
+  transcriptPage,
+  transcriptPreview
+};

package/src/verification-integrity.js

@@ -0,0 +1,27 @@
+import { git } from "./git.js";
+class VerificationIntegrityError extends Error {
+}
+async function verificationIntegrity(repo, signal) {
+  const options = { signal, timeoutMs: 1e4 };
+  const initial = await git(["rev-parse", "--verify", "HEAD^{commit}"], repo, options);
+  const tree = await git(["rev-parse", "--verify", "HEAD^{tree}"], repo, options);
+  if (initial.code || tree.code) throw new VerificationIntegrityError("Cannot pin the verification checkout commit");
+  const assert = async (stage) => {
+    if (signal?.aborted) throw new VerificationIntegrityError("Verification was cancelled");
+    const [head, index, unstaged, flags] = await Promise.all([
+      git(["rev-parse", "--verify", "HEAD^{commit}"], repo, options),
+      git(["write-tree"], repo, options),
+      git(["diff", "--no-ext-diff", "--no-textconv", "--ignore-submodules=none", "--quiet", "--exit-code", "--"], repo, options),
+      git(["ls-files", "-v", "-z"], repo, options)
+    ]);
+    if (signal?.aborted) throw new VerificationIntegrityError("Verification was cancelled");
+    const hiddenFiles = flags.stdout.split("\0").some((file) => /^[a-zS] /.test(file));
+    if (head.code || index.code || unstaged.code || flags.code || hiddenFiles || head.stdout.trim() !== initial.stdout.trim() || index.stdout.trim() !== tree.stdout.trim()) throw new VerificationIntegrityError(`Verification ${stage} changed tracked files, the staged tree or the checkout commit, or hid tracked files from comparison. The original commit was not verified.`);
+  };
+  await assert("starting checkout");
+  return { head: initial.stdout.trim(), assert };
+}
+export {
+  VerificationIntegrityError,
+  verificationIntegrity
+};