@galaxyproject/orbit 0.0.0 → 0.9.0

package/extensions/orbit/teams/dispatcher.ts

@@ -0,0 +1,210 @@
+import { validateTeamSpec } from "./validate";
+import { parseCriticResponse } from "./critic-parser";
+import type { DispatchDeps, TeamResult, TeamSpec, TeamTurn } from "./types";
+
+export interface DispatchOptions {
+  tokenCeiling?: number; // default 300_000
+}
+
+export type OnTurnUpdate = (snapshot: {
+  round: number;
+  max_rounds: number;
+  current_role: string;
+  turns: TeamTurn[];
+}) => void;
+
+const DEFAULT_TOKEN_CEILING = 300_000;
+
+/**
+ * Run the two-role critic loop to completion.
+ * `deps.runRoleTurn` is injected so this function is unit-testable without
+ * a real Pi runtime.
+ */
+export async function runTeamDispatch(
+  spec: TeamSpec,
+  deps: DispatchDeps,
+  signal: AbortSignal,
+  onTurn?: OnTurnUpdate,
+  options: DispatchOptions = {},
+): Promise<TeamResult> {
+  validateTeamSpec(spec);
+
+  const tokenCeiling = options.tokenCeiling ?? DEFAULT_TOKEN_CEILING;
+  const maxRounds = spec.max_rounds ?? 5;
+  const [proposer, critic] = spec.roles;
+  const transcript: TeamTurn[] = [];
+  let totalUsage = { input_tokens: 0, output_tokens: 0 };
+  let currentProposal = "";
+  let currentCritique: string | null = null;
+  let round = 0;
+
+  try {
+    for (round = 1; round <= maxRounds; round++) {
+      // --- Proposer turn ---
+      if (signal.aborted) return aborted(transcript, round, currentProposal, totalUsage);
+      const proposerInput = renderProposerInput(spec.description, currentCritique);
+      const proposerPreamble = buildPreamble(spec, proposer, "proposer");
+      const proposerResult = await deps.runRoleTurn(
+        proposer,
+        proposerPreamble,
+        proposerInput,
+        signal,
+      );
+      currentProposal = proposerResult.content;
+      transcript.push({
+        round,
+        role: proposer.name,
+        content: currentProposal,
+      });
+      totalUsage = add(totalUsage, proposerResult.usage);
+      onTurn?.({ round, max_rounds: maxRounds, current_role: proposer.name, turns: transcript });
+
+      if (exceedsCeiling(totalUsage, tokenCeiling)) {
+        return budgetExhausted(transcript, round, currentProposal, totalUsage);
+      }
+
+      // --- Critic turn ---
+      if (signal.aborted) return aborted(transcript, round, currentProposal, totalUsage);
+      const criticInput = renderCriticInput(spec.description, currentProposal);
+      const criticPreamble = buildPreamble(spec, critic, "critic");
+      const criticResult = await deps.runRoleTurn(critic, criticPreamble, criticInput, signal);
+      const verdict = parseCriticResponse(criticResult.content);
+      transcript.push({
+        round,
+        role: critic.name,
+        content: criticResult.content,
+        approved: verdict.approved,
+      });
+      totalUsage = add(totalUsage, criticResult.usage);
+      onTurn?.({ round, max_rounds: maxRounds, current_role: critic.name, turns: transcript });
+
+      if (verdict.approved) {
+        return {
+          converged: true,
+          rounds: round,
+          final_output: currentProposal,
+          transcript,
+          usage: totalUsage,
+        };
+      }
+      if (exceedsCeiling(totalUsage, tokenCeiling)) {
+        return budgetExhausted(transcript, round, currentProposal, totalUsage);
+      }
+      currentCritique = verdict.critique;
+    }
+
+    return {
+      converged: false,
+      rounds: maxRounds,
+      final_output: currentProposal,
+      transcript,
+      usage: totalUsage,
+    };
+  } catch (err) {
+    if (isAbortError(err) || signal.aborted) {
+      return aborted(transcript, round, currentProposal, totalUsage);
+    }
+    return {
+      converged: false,
+      rounds: round,
+      final_output: currentProposal,
+      transcript,
+      usage: totalUsage,
+      error: err instanceof Error ? err.message : String(err),
+    };
+  }
+}
+
+// --- helpers ------------------------------------------------------------
+
+function renderProposerInput(description: string, priorCritique: string | null): string {
+  if (priorCritique === null) {
+    return `Team task: ${description}\n\nProduce your first proposal.`;
+  }
+  return (
+    `Team task: ${description}\n\n` +
+    `The critic raised the following issues with your previous proposal:\n${priorCritique}\n\n` +
+    `Produce a revised proposal that addresses them.`
+  );
+}
+
+function renderCriticInput(description: string, proposal: string): string {
+  return (
+    `Team task: ${description}\n\n` +
+    `Proposer output:\n${proposal}\n\n` +
+    `Critique the proposal. End your response with a JSON line of shape ` +
+    `{"approved": boolean, "critique": string}.`
+  );
+}
+
+function buildPreamble(
+  spec: TeamSpec,
+  role: { system_prompt: string },
+  kind: "proposer" | "critic",
+): string {
+  const teamContext =
+    `You are one role in a two-agent team collaborating on the task: "${spec.description}". ` +
+    `Respond only from your role's perspective.`;
+  const criticContract =
+    kind === "critic"
+      ? ` When you have finished critiquing, finish your response with a JSON line: ` +
+        `{"approved": boolean, "critique": "one paragraph"}.`
+      : "";
+  return `${teamContext}${criticContract}\n\n${role.system_prompt}`;
+}
+
+function add(
+  a: { input_tokens: number; output_tokens: number },
+  b: { input_tokens: number; output_tokens: number },
+) {
+  return {
+    input_tokens: a.input_tokens + b.input_tokens,
+    output_tokens: a.output_tokens + b.output_tokens,
+  };
+}
+
+function exceedsCeiling(
+  u: { input_tokens: number; output_tokens: number },
+  ceiling: number,
+): boolean {
+  return u.input_tokens + u.output_tokens > ceiling;
+}
+
+function aborted(
+  transcript: TeamTurn[],
+  round: number,
+  finalOutput: string,
+  usage: { input_tokens: number; output_tokens: number },
+): TeamResult {
+  return {
+    converged: false,
+    aborted: true,
+    rounds: round,
+    final_output: finalOutput,
+    transcript,
+    usage,
+  };
+}
+
+function budgetExhausted(
+  transcript: TeamTurn[],
+  round: number,
+  finalOutput: string,
+  usage: { input_tokens: number; output_tokens: number },
+): TeamResult {
+  return {
+    converged: false,
+    budget_exhausted: true,
+    rounds: round,
+    final_output: finalOutput,
+    transcript,
+    usage,
+  };
+}
+
+function isAbortError(err: unknown): boolean {
+  return (
+    err instanceof Error &&
+    (err.name === "AbortError" || err.message.toLowerCase().includes("abort"))
+  );
+}

package/extensions/orbit/teams/is-enabled.ts

@@ -0,0 +1,22 @@
+import { loadConfig } from "../config";
+import { readEnv } from "../../../shared/orbit-env.js";
+
+/**
+ * Whether the experimental team_dispatch tool is opted in.
+ *
+ * Resolution order (env wins so a developer can flip it for one session
+ * without touching ~/.orbit/config.json):
+ *   1. LOOM_TEAM_DISPATCH env var -- "1" -> on, "0" -> off (explicit
+ *      override of an on-config), anything else -> defer to config.
+ *   2. config.experiments.teamDispatch -- boolean.
+ *   3. Default: off.
+ *
+ * Intended to be called once at extension boot, not in a hot path --
+ * each call hits loadConfig() / disk.
+ */
+export function isTeamDispatchEnabled(): boolean {
+  const env = readEnv("TEAM_DISPATCH");
+  if (env === "1") return true;
+  if (env === "0") return false;
+  return loadConfig().experiments?.teamDispatch === true;
+}

package/extensions/orbit/teams/tool.ts

@@ -0,0 +1,187 @@
+import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { Type } from "@sinclair/typebox";
+import { Text } from "@earendil-works/pi-tui";
+// pi 0.80 moved the global API to /compat. The extension loader aliases the
+// root at runtime, but the typecheck resolves the published types, so import
+// the real path.
+import { completeSimple } from "@earendil-works/pi-ai/compat";
+import type { Model } from "@earendil-works/pi-ai/compat";
+import { runTeamDispatch } from "./dispatcher";
+import { modelScriptRefusal } from "../model-script";
+import { validateTeamSpec } from "./validate";
+import type { DispatchDeps, RoleTurnResult, TeamSpec, RoleSpec } from "./types";
+import { TEAM_DISPATCH_KIND } from "../../../shared/team-dispatch-contract.js";
+import type { TeamDispatchDetails } from "../../../shared/team-dispatch-contract.js";
+
+const RoleSchema = Type.Object({
+  name: Type.String({ minLength: 1 }),
+  system_prompt: Type.String({ minLength: 1 }),
+  model: Type.Optional(Type.String()),
+});
+
+const TeamSpecSchema = Type.Object({
+  description: Type.String({ minLength: 1 }),
+  roles: Type.Array(RoleSchema, { minItems: 2, maxItems: 2 }),
+  max_rounds: Type.Optional(Type.Integer({ minimum: 1, maximum: 20 })),
+  model: Type.Optional(Type.String()),
+});
+
+export function registerTeamTools(pi: ExtensionAPI): void {
+  pi.registerTool({
+    name: "team_dispatch",
+    label: "Dispatch specialist team",
+    description:
+      "Run a two-role critic loop (proposer → critic) to converge on a result. " +
+      "Use when the user asks for a 'team' to handle a bounded sub-task such as " +
+      "literature review or cross-checking findings. Each role is a pure-reasoning " +
+      "LLM call (no tools); gather any external data with your own tools first and " +
+      "include it in the `description`. Returns the converged result; persist useful " +
+      "output by editing notebook.md when the researcher wants it retained.",
+    parameters: TeamSpecSchema,
+    async execute(_toolCallId, params, signal, onUpdate, ctx) {
+      const spec = params as TeamSpec;
+      const scripted = modelScriptRefusal("team_dispatch");
+      if (scripted) return errorResult(new Error(scripted));
+
+      // 1. Spec validation (fail fast).
+      try {
+        validateTeamSpec(spec);
+      } catch (err) {
+        return errorResult(err);
+      }
+
+      // 2. Build the runRoleTurn binding over pi-ai.completeSimple.
+      const deps: DispatchDeps = {
+        runRoleTurn: async (
+          role: RoleSpec,
+          preamble,
+          userMessage,
+          runSignal,
+        ): Promise<RoleTurnResult> => {
+          const model = resolveModel(ctx, role.model ?? spec.model);
+          if (!model) {
+            throw new Error(
+              `No model available: neither role "${role.name}" nor the team spec nor the session provides one.`,
+            );
+          }
+          const msg = await completeSimple(
+            model,
+            {
+              systemPrompt: preamble,
+              messages: [{ role: "user", content: userMessage, timestamp: Date.now() }],
+            },
+            { signal: runSignal },
+          );
+          const content = extractText(msg);
+          // Count cache tokens too so the budget ceiling is honest on
+          // providers that charge for cache reads/writes (Anthropic).
+          const cacheRead = msg.usage.cacheRead ?? 0;
+          const cacheWrite = msg.usage.cacheWrite ?? 0;
+          return {
+            content,
+            usage: {
+              input_tokens: msg.usage.input + cacheRead + cacheWrite,
+              output_tokens: msg.usage.output,
+            },
+          };
+        },
+      };
+
+      // 3. Drive the loop; stream progress to the tool card.
+      const abort = signal ?? new AbortController().signal;
+      const result = await runTeamDispatch(spec, deps, abort, (snapshot) => {
+        const details: TeamDispatchDetails = {
+          kind: TEAM_DISPATCH_KIND,
+          spec: {
+            description: spec.description,
+            roles: spec.roles.map((r) => ({ name: r.name, model: r.model ?? spec.model })),
+          },
+          turns: snapshot.turns,
+          summary: `Round ${snapshot.round}/${snapshot.max_rounds} — ${snapshot.current_role} responding…`,
+        };
+        onUpdate?.({
+          content: [],
+          details,
+        });
+      });
+
+      // 4. Final tool-card summary.
+      const finalSummary = result.converged
+        ? `Team converged in ${result.rounds} round${result.rounds === 1 ? "" : "s"}`
+        : result.aborted
+          ? `Team aborted after ${result.rounds} round${result.rounds === 1 ? "" : "s"}`
+          : result.budget_exhausted
+            ? `Team halted on token budget after ${result.rounds} round${result.rounds === 1 ? "" : "s"}`
+            : result.error
+              ? `Team errored after ${result.rounds} round${result.rounds === 1 ? "" : "s"}: ${result.error}`
+              : `Team did not converge (${result.rounds}/${spec.max_rounds ?? 5} rounds — best-so-far returned)`;
+
+      const finalDetails: TeamDispatchDetails = {
+        kind: TEAM_DISPATCH_KIND,
+        spec: {
+          description: spec.description,
+          roles: spec.roles.map((r) => ({ name: r.name, model: r.model ?? spec.model })),
+        },
+        turns: result.transcript,
+        summary: finalSummary,
+      };
+      return {
+        content: [{ type: "text" as const, text: JSON.stringify(result, null, 2) }],
+        details: finalDetails,
+      };
+    },
+    renderResult: (result) => {
+      const d = result.details as { summary?: string } | undefined;
+      return new Text(d?.summary ?? "team_dispatch finished");
+    },
+  });
+}
+
+// --- helpers ------------------------------------------------------------
+
+/**
+ * Resolve a Model<any> from a "provider:modelId" string, a bare Anthropic
+ * model id, or by falling back to the session model.
+ */
+function resolveModel(
+  ctx: ExtensionContext,
+  modelSpec: string | undefined,
+): Model<any> | undefined {
+  if (modelSpec && modelSpec.trim().length > 0) {
+    const colon = modelSpec.indexOf(":");
+    const provider = colon >= 0 ? modelSpec.slice(0, colon) : "anthropic";
+    const modelId = colon >= 0 ? modelSpec.slice(colon + 1) : modelSpec;
+    const found = ctx.modelRegistry.find(provider, modelId);
+    if (!found) {
+      throw new Error(
+        `Unknown model "${modelSpec}" (provider="${provider}", modelId="${modelId}"). ` +
+          `Check ctx.modelRegistry, or omit the model field to use the session default.`,
+      );
+    }
+    return found;
+  }
+  return ctx.model;
+}
+
+/** Flatten an AssistantMessage's text chunks into a single string. */
+function extractText(msg: { content: Array<{ type: string; text?: string }> }): string {
+  return msg.content
+    .filter((c) => c.type === "text" && typeof c.text === "string")
+    .map((c) => c.text as string)
+    .join("");
+}
+
+function errorResult(err: unknown) {
+  const message = err instanceof Error ? err.message : String(err);
+  const details: TeamDispatchDetails = {
+    kind: TEAM_DISPATCH_KIND,
+    error: message,
+    summary: `team_dispatch failed: ${message}`,
+  };
+  return {
+    content: [
+      { type: "text" as const, text: JSON.stringify({ ok: false, error: message }, null, 2) },
+    ],
+    details,
+  };
+}

package/extensions/orbit/teams/types.ts

@@ -0,0 +1,57 @@
+/**
+ * Public types for the team_dispatch feature.
+ * See docs/superpowers/specs/2026-04-17-multi-agent-dispatch-design.md.
+ */
+
+export interface TeamSpec {
+  description: string;
+  roles: RoleSpec[];
+  max_rounds?: number;
+  model?: string;
+}
+
+export interface RoleSpec {
+  name: string;
+  system_prompt: string;
+  model?: string;
+}
+
+export interface TeamResult {
+  converged: boolean;
+  rounds: number;
+  final_output: string;
+  transcript: TeamTurn[];
+  usage: { input_tokens: number; output_tokens: number };
+  aborted?: boolean;
+  budget_exhausted?: boolean;
+  error?: string;
+}
+
+export interface TeamTurn {
+  round: number;
+  role: string;
+  content: string;
+  approved?: boolean;
+}
+
+/**
+ * Side-effect surface the dispatcher needs.
+ * Injected so the dispatcher is testable without a real LLM runtime.
+ *
+ * MVP: roles are pure-reasoning — each turn is a single LLM call with no
+ * tool access. Main agent pre-gathers any external data and includes it
+ * in TeamSpec.description before dispatching.
+ */
+export interface DispatchDeps {
+  runRoleTurn: (
+    role: RoleSpec,
+    systemPreamble: string,
+    userMessage: string,
+    signal: AbortSignal,
+  ) => Promise<RoleTurnResult>;
+}
+
+export interface RoleTurnResult {
+  content: string;
+  usage: { input_tokens: number; output_tokens: number };
+}

package/extensions/orbit/teams/validate.ts

@@ -0,0 +1,42 @@
+import type { TeamSpec } from "./types";
+
+export class ValidationError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = "ValidationError";
+  }
+}
+
+export function validateTeamSpec(spec: TeamSpec): void {
+  if (!spec.description || spec.description.trim().length === 0) {
+    throw new ValidationError("TeamSpec.description must be a non-empty string");
+  }
+
+  const roles = spec.roles;
+  if (!Array.isArray(roles) || roles.length < 2) {
+    throw new ValidationError("TeamSpec.roles must contain at least 2 roles");
+  }
+  if (roles.length > 2) {
+    throw new ValidationError(
+      "TeamSpec.roles contains more than 2 roles; >2 roles is not implemented in this MVP",
+    );
+  }
+
+  const seen = new Set<string>();
+  for (const role of roles) {
+    if (typeof role.name !== "string" || role.name.trim().length === 0) {
+      throw new ValidationError("Every RoleSpec must have a non-empty name");
+    }
+    if (seen.has(role.name)) {
+      throw new ValidationError(`RoleSpec.name must be unique; duplicate: "${role.name}"`);
+    }
+    seen.add(role.name);
+  }
+
+  const max = spec.max_rounds;
+  if (max !== undefined) {
+    if (!Number.isInteger(max) || max < 1 || max > 20) {
+      throw new ValidationError("TeamSpec.max_rounds must be an integer in [1, 20]");
+    }
+  }
+}

package/extensions/orbit/tester-id-command.ts

@@ -0,0 +1,133 @@
+/**
+ * /tester-id -- the get-or-set counterpart to buildTesterIdBlock (#189/#191).
+ *
+ * With no argument it prints the current tester ID; with an argument it sets it.
+ *
+ * Beta onboarding asks testers to put a `testerId` in ~/.orbit/config.json. That
+ * file is a credential store, so the agent's edit/write to it is floored by the
+ * exec-guard -- a hard deny on low-capability models and an unreachable
+ * read-then-edit on every tier once #194 landed (issue #222). This gives the
+ * user a deterministic, model-independent path that sets ONLY the testerId key.
+ *
+ * It deliberately reads/echoes ONLY the testerId field (a non-secret tester code
+ * like "orbit-007", which already passes #194 redaction), never any other config
+ * value, so it cannot become a way to surface the API keys that #183/#194 lock
+ * down.
+ */
+
+import fs from "node:fs";
+import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { getConfigPath, loadConfig, saveConfig } from "./config.js";
+import { readEnv } from "../../shared/orbit-env.js";
+
+// Tester codes are opaque, non-secret strings (e.g. "orbit-007"). Constrain the
+// shape so neither a fat-fingered user nor a pasted blob can smuggle a newline,
+// JSON, or a giant value into the key: first char alphanumeric, then a few safe
+// separators, capped length.
+const TESTER_ID_RE = /^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$/;
+
+export type ValidateResult = { ok: true; id: string } | { ok: false; error: string };
+
+export function validateTesterId(raw: string): ValidateResult {
+  const id = (raw ?? "").trim();
+  if (!id) {
+    return { ok: false, error: "Usage: /tester-id <id>  (e.g. /tester-id orbit-007)" };
+  }
+  if (!TESTER_ID_RE.test(id)) {
+    return {
+      ok: false,
+      error:
+        "Tester ID must be 1-64 characters: letters, digits, and . _ - only, " +
+        "starting with a letter or digit (e.g. orbit-007).",
+    };
+  }
+  return { ok: true, id };
+}
+
+/**
+ * The currently-effective tester ID and where it came from. Mirrors
+ * buildTesterIdBlock's precedence (config wins over the env override). Reads
+ * ONLY testerId -- never another config field.
+ */
+export function getCurrentTesterId(): { id: string; source: "config" | "env" } | null {
+  const fromConfig = loadConfig().testerId;
+  if (fromConfig) return { id: fromConfig, source: "config" };
+  const fromEnv = readEnv("TESTER_ID");
+  if (fromEnv) return { id: fromEnv, source: "env" };
+  return null;
+}
+
+/**
+ * Set ONLY the testerId key. Loads the full config so existing fields (API keys
+ * included) ride straight back to disk unchanged, mutates the single key, and
+ * persists via the shared atomic writer. No other field is read out, returned,
+ * or echoed.
+ *
+ * Fails closed: loadConfig() silently returns {} when an existing config can't
+ * be read or parsed, so writing that back would wipe the user's stored API
+ * keys. We refuse rather than clobber -- a genuinely absent file is still fine
+ * to create. A save failure is rewrapped in a fixed message so the raw error
+ * (whatever it carries) can never be surfaced through this command.
+ */
+export function setTesterId(id: string): void {
+  const configPath = getConfigPath();
+  if (fs.existsSync(configPath)) {
+    try {
+      JSON.parse(fs.readFileSync(configPath, "utf-8"));
+    } catch (err) {
+      throw new Error(
+        "~/.orbit/config.json couldn't be read, so it wasn't changed -- fix or remove the file and try again.",
+        { cause: err },
+      );
+    }
+  }
+  const cfg = loadConfig();
+  cfg.testerId = id;
+  try {
+    saveConfig(cfg);
+  } catch (err) {
+    throw new Error(
+      "Couldn't write ~/.orbit/config.json -- check file permissions and free space, then try again.",
+      { cause: err },
+    );
+  }
+}
+
+export function registerTesterIdCommand(pi: ExtensionAPI): void {
+  pi.registerCommand("tester-id", {
+    description:
+      "Show or set your Orbit beta tester ID (writes only testerId to ~/.orbit/config.json).",
+    handler: async (args: string | undefined, ctx: ExtensionContext) => {
+      const raw = (args ?? "").trim();
+
+      if (!raw) {
+        const current = getCurrentTesterId();
+        if (!current) {
+          ctx.ui.notify(
+            "No tester ID set. Set one with /tester-id <id>  (e.g. /tester-id orbit-007).",
+            "info",
+          );
+          return;
+        }
+        const suffix = current.source === "env" ? " (from LOOM_TESTER_ID)" : "";
+        ctx.ui.notify(`Tester ID: ${current.id}${suffix}`, "info");
+        return;
+      }
+
+      const result = validateTesterId(raw);
+      if (!result.ok) {
+        ctx.ui.notify(result.error, "error");
+        return;
+      }
+      try {
+        setTesterId(result.id);
+      } catch (err) {
+        // setTesterId only throws messages it authored -- never a raw error
+        // that could carry config contents -- so showing it is safe.
+        ctx.ui.notify(err instanceof Error ? err.message : "Failed to save tester ID.", "error");
+        return;
+      }
+      ctx.ui.notify(`Tester ID set to ${result.id}.`, "info");
+    },
+  });
+}