pi-amq 0.1.1

package/extension/worker-tools.ts

@@ -0,0 +1,276 @@
+import type {
+  AgentToolResult,
+  ExtensionAPI,
+  ExtensionContext,
+} from "@earendil-works/pi-coding-agent";
+import { Type, type Static } from "typebox";
+
+const Difficulty = Type.Union([
+  Type.Literal("easy"),
+  Type.Literal("medium"),
+  Type.Literal("hard"),
+]);
+const Channel = Type.Union([Type.Literal("json-result"), Type.Literal("rpc")]);
+const SideEffectPolicy = Type.Union([
+  Type.Literal("none"),
+  Type.Literal("idempotent"),
+  Type.Literal("reconcilable"),
+  Type.Literal("external"),
+]);
+const WorkerContext = Type.Union([Type.Literal("fresh"), Type.Literal("fork")]);
+const ReportField = Type.Object({
+  type: Type.Union([
+    Type.Literal("string"), Type.Literal("number"), Type.Literal("boolean"),
+    Type.Literal("object"), Type.Literal("array"), Type.Literal("null"),
+  ]),
+});
+const ReportSchema = Type.Object({
+  schema: Type.Literal(1),
+  required: Type.Array(Type.String()),
+  properties: Type.Record(Type.String(), ReportField),
+});
+const AcceptanceCheck = Type.Object({
+  command: Type.String(),
+  args: Type.Array(Type.String()),
+});
+const IntegerBudgetLimit = Type.Union([
+  Type.Object({ kind: Type.Literal("limited"), value: Type.Integer({ minimum: 1 }) }),
+  Type.Object({ kind: Type.Literal("unlimited") }),
+]);
+const NumberBudgetLimit = Type.Union([
+  Type.Object({ kind: Type.Literal("limited"), value: Type.Number({ exclusiveMinimum: 0 }) }),
+  Type.Object({ kind: Type.Literal("unlimited") }),
+]);
+const WorkerBudget = Type.Object({
+  max_attempts: IntegerBudgetLimit,
+  max_wall_clock_ms: IntegerBudgetLimit,
+  max_tokens: IntegerBudgetLimit,
+  max_cost_usd: NumberBudgetLimit,
+  max_output_bytes: IntegerBudgetLimit,
+});
+const Model = Type.Object({
+  provider: Type.String(),
+  id: Type.String(),
+  thinking_level: Type.Optional(Type.String()),
+});
+const Workspace = Type.Object({
+  path: Type.String(),
+  mode: Type.Union([Type.Literal("read-only"), Type.Literal("mutating")]),
+  worktree_path: Type.Optional(Type.String()),
+});
+const ContentRef = Type.Object({
+  kind: Type.Union([Type.Literal("file"), Type.Literal("session"), Type.Literal("artifact")]),
+  value: Type.String(),
+  hash: Type.Optional(Type.String()),
+});
+
+const SpawnParameters = Type.Object({
+  request_key: Type.String(),
+  difficulty: Type.Optional(Difficulty),
+  role: Type.Optional(Type.String({ minLength: 1 })),
+  audits_worker_id: Type.Optional(Type.String()),
+  continue_worker_id: Type.Optional(Type.String()),
+  context: Type.Optional(WorkerContext),
+  goal: Type.String(),
+  acceptance: Type.Array(Type.String(), { minItems: 1 }),
+  constraints: Type.Array(Type.String()),
+  budget: WorkerBudget,
+  model: Type.Optional(Model),
+  fallback_models: Type.Optional(Type.Array(Model, { maxItems: 4 })),
+  capabilities: Type.Optional(Type.Array(Type.String())),
+  workspace: Workspace,
+  context_refs: Type.Array(ContentRef),
+  channel: Channel,
+  side_effect_policy: SideEffectPolicy,
+  report_schema: Type.Optional(ReportSchema),
+  requires_human_approval: Type.Optional(Type.Boolean()),
+  acceptance_check: Type.Optional(AcceptanceCheck),
+});
+const ListParameters = Type.Object({
+  limit: Type.Optional(Type.Integer({ minimum: 1, maximum: 100 })),
+});
+const CollectParameters = Type.Object({
+  worker_ids: Type.Array(Type.String(), { minItems: 1, maxItems: 32 }),
+  structured_reports: Type.Optional(Type.Record(Type.String(), Type.Unknown())),
+});
+const CancelParameters = Type.Object({ worker_id: Type.String(), reason: Type.String() });
+const SteerParameters = Type.Object({
+  worker_id: Type.String(),
+  message: Type.String(),
+  correlation: Type.Optional(Type.String({ minLength: 1, maxLength: 256 })),
+});
+const ReviseParameters = Type.Object({
+  worker_id: Type.String(),
+  correlation: Type.Optional(Type.String({ minLength: 1, maxLength: 256 })),
+  goal: Type.Optional(Type.String()),
+  acceptance: Type.Optional(Type.Array(Type.String(), { minItems: 1 })),
+  constraints: Type.Optional(Type.Array(Type.String())),
+  report_schema: Type.Optional(ReportSchema),
+  requires_human_approval: Type.Optional(Type.Boolean()),
+  acceptance_check: Type.Optional(AcceptanceCheck),
+});
+const CleanupRunsParameters = Type.Object({
+  older_than_ms: Type.Integer({ minimum: 1 }),
+  dry_run: Type.Optional(Type.Boolean()),
+  yes: Type.Optional(Type.Boolean()),
+});
+const WorkflowDoctorParameters = Type.Object({});
+
+export type SpawnWorkerToolParameters = Static<typeof SpawnParameters>;
+export type ListWorkersToolParameters = Static<typeof ListParameters>;
+export type CollectWorkerToolParameters = Static<typeof CollectParameters>;
+export type CancelWorkerToolParameters = Static<typeof CancelParameters>;
+export type SteerWorkerToolParameters = Static<typeof SteerParameters>;
+export type ReviseContractToolParameters = Static<typeof ReviseParameters>;
+export type CleanupRunsToolParameters = Static<typeof CleanupRunsParameters>;
+
+export interface WorkerToolProvider {
+  spawn(
+    params: SpawnWorkerToolParameters,
+    signal: AbortSignal | undefined,
+    ctx: ExtensionContext,
+  ): Promise<unknown>;
+  list(params: ListWorkersToolParameters, ctx: ExtensionContext): Promise<unknown>;
+  collect(
+    params: CollectWorkerToolParameters,
+    signal: AbortSignal | undefined,
+    ctx: ExtensionContext,
+  ): Promise<unknown>;
+  cancel(
+    params: CancelWorkerToolParameters,
+    signal: AbortSignal | undefined,
+    ctx: ExtensionContext,
+  ): Promise<unknown>;
+  steer(
+    params: SteerWorkerToolParameters,
+    signal: AbortSignal | undefined,
+    ctx: ExtensionContext,
+  ): Promise<unknown>;
+  reviseContract(
+    params: ReviseContractToolParameters,
+    signal: AbortSignal | undefined,
+    ctx: ExtensionContext,
+  ): Promise<unknown>;
+  cleanupRuns(
+    params: CleanupRunsToolParameters,
+    signal: AbortSignal | undefined,
+    ctx: ExtensionContext,
+  ): Promise<unknown>;
+  doctorWorkflow(signal: AbortSignal | undefined, ctx: ExtensionContext): Promise<unknown>;
+}
+
+export function registerWorkerTools(pi: ExtensionAPI, provider: WorkerToolProvider): void {
+  pi.registerTool({
+    name: "spawn_worker",
+    label: "Spawn Worker",
+    description: "Create one durable worker contract and start its supervised process, optionally continuing a proven-dead terminal worker session.",
+    promptSnippet: "Spawn a bounded supervised worker",
+    promptGuidelines: [
+      "Choose scout, worker, reviewer, oracle, or researcher; user role declarations may override these builtins.",
+      "Worker context defaults to fresh; context=fork copies the driver current leaf into an independent child session without changing the parent.",
+      "fallback_models is an ordered bounded chain used only for child launch-validation or provider auth, quota, and capacity failures.",
+      "Explicit difficulty and capabilities override role defaults. A reviewer auditing a named worker is floored to that worker's model capability.",
+      "When tier selection is unavailable or uncertain, omit model so the current model is used.",
+      "Keep acceptance criteria falsifiable and grant only the required workspace and capabilities.",
+      "Use continue_worker_id only for deliberate continuation after the prior worker is terminal and proven dead; the new request remains a fresh contract.",
+    ],
+    parameters: SpawnParameters,
+    async execute(_id, params, signal, _onUpdate, ctx) {
+      return invoke(() => provider.spawn(params, signal, ctx));
+    },
+  });
+
+  pi.registerTool({
+    name: "list_workers",
+    label: "List Workers",
+    description: "List the current run's bounded durable worker, Gate, revision, and stall projections.",
+    parameters: ListParameters,
+    async execute(_id, params, _signal, _onUpdate, ctx) {
+      return invoke(() => provider.list(params, ctx));
+    },
+  });
+
+  pi.registerTool({
+    name: "collect",
+    label: "Collect Workers",
+    description: "Observe worker candidates and Gate facts without treating collection itself as done.",
+    parameters: CollectParameters,
+    async execute(_id, params, signal, _onUpdate, ctx) {
+      return invoke(() => provider.collect(params, signal, ctx));
+    },
+  });
+
+  pi.registerTool({
+    name: "cancel",
+    label: "Cancel Worker",
+    description: "Record the sole cancellation verb before signaling the supervised process group.",
+    parameters: CancelParameters,
+    async execute(_id, params, signal, _onUpdate, ctx) {
+      return invoke(() => provider.cancel(params, signal, ctx));
+    },
+  });
+
+  pi.registerTool({
+    name: "steer",
+    label: "Steer Worker",
+    description: "Deliver already-authorized new input to an RPC worker; waking a typed wait requires its exact correlation.",
+    parameters: SteerParameters,
+    async execute(_id, params, signal, _onUpdate, ctx) {
+      return invoke(() => provider.steer(params, signal, ctx));
+    },
+  });
+
+  pi.registerTool({
+    name: "revise_contract",
+    label: "Revise Worker Contract",
+    description: "Record an immutable contract revision and deliver it at the next inference boundary; waking a typed wait requires its exact correlation.",
+    parameters: ReviseParameters,
+    async execute(_id, params, signal, _onUpdate, ctx) {
+      return invoke(() => provider.reviseContract(params, signal, ctx));
+    },
+  });
+
+  pi.registerTool({
+    name: "cleanup_runs",
+    label: "Cleanup Workflow Runs",
+    description: "Preview or explicitly delete old terminal workflow runs, worker sessions, and artifacts.",
+    promptGuidelines: [
+      "Dry-run is the default. Set dry_run=false only when deletion is intended.",
+      "TUI deletion always requires user confirmation; headless deletion also requires yes=true.",
+    ],
+    parameters: CleanupRunsParameters,
+    async execute(_id, params, signal, _onUpdate, ctx) {
+      return invoke(() => provider.cleanupRuns(params, signal, ctx));
+    },
+  });
+
+  pi.registerTool({
+    name: "workflow_doctor",
+    label: "Workflow Doctor",
+    description: "Read-only workflow diagnostics for run ledgers, processes, leases, sessions, and disk usage.",
+    parameters: WorkflowDoctorParameters,
+    async execute(_id, _params, signal, _onUpdate, ctx) {
+      return invoke(() => provider.doctorWorkflow(signal, ctx));
+    },
+  });
+}
+
+async function invoke(operation: () => Promise<unknown>): Promise<AgentToolResult<unknown>> {
+  try {
+    const details = await operation();
+    return rendered(details);
+  } catch (error) {
+    return rendered({ error: { category: "worker-runtime", message: toError(error).message } });
+  }
+}
+
+function rendered(details: unknown): AgentToolResult<unknown> {
+  return {
+    content: [{ type: "text", text: JSON.stringify(details, null, 2) }],
+    details,
+  };
+}
+
+function toError(error: unknown): Error {
+  return error instanceof Error ? error : new Error(String(error));
+}

package/integration/confirmed-bind-onboarding.ts

@@ -0,0 +1,296 @@
+import { isAbsolute, normalize } from "node:path";
+
+import type { AmqCommandResult, AmqRunOptions } from "../transport/amq-cli-adapter.js";
+import {
+  BindingResolver,
+  type BindingProjectionV1,
+  type BindingResolution,
+} from "../transport/binding-resolver.js";
+
+interface JsonRunner {
+  runJson<T = unknown>(
+    argv: readonly string[],
+    options?: AmqRunOptions<T>,
+  ): Promise<AmqCommandResult<T>>;
+}
+
+export interface ConfirmedBindRequest {
+  readonly projectDirectory: string;
+  readonly root: string;
+  readonly handle: string;
+  readonly agents: readonly string[];
+  readonly environment?: Readonly<NodeJS.ProcessEnv>;
+}
+
+export interface ConfirmedBindPreview {
+  readonly kind: "existing" | "bootstrap";
+  readonly projectDirectory: string;
+  readonly root: string;
+  readonly session: string;
+  readonly project: string;
+  readonly handle: string;
+  readonly agents: readonly string[];
+  readonly command: readonly string[];
+  readonly commandText: string;
+  readonly effects: readonly string[];
+}
+
+export type ConfirmedBindResult =
+  | { readonly kind: "cancelled"; readonly diagnostic: string }
+  | { readonly kind: "refused"; readonly diagnostic: string }
+  | { readonly kind: "bound"; readonly binding: BindingProjectionV1 };
+
+interface WhoAgent {
+  readonly handle: string;
+}
+
+interface WhoSession {
+  readonly name: string;
+  readonly agents: readonly WhoAgent[];
+}
+
+interface WhoProjection {
+  readonly initialized: boolean;
+  readonly sessions: readonly WhoSession[];
+}
+
+interface EnvPreview {
+  readonly root: string;
+  readonly session: string;
+  readonly project: string;
+}
+
+/** Owns the confirmation-gated first-run boundary; it never guesses authority. */
+export class ConfirmedBindOnboarding {
+  readonly #runner: JsonRunner;
+  readonly #resolver: BindingResolver;
+
+  constructor(runner: JsonRunner, resolver = new BindingResolver(runner)) {
+    this.#runner = runner;
+    this.#resolver = resolver;
+  }
+
+  async preview(request: ConfirmedBindRequest): Promise<ConfirmedBindPreview> {
+    const projectDirectory = absolute(request.projectDirectory, "project directory");
+    const root = absolute(request.root, "AMQ root");
+    const handle = agentHandle(request.handle, "chosen handle");
+    const requestedAgents = roster(request.agents, handle);
+    const environment = request.environment ?? process.env;
+    const who = await this.#runner.runJson(
+      ["who", "--root", root],
+      { env: commandEnvironment(environment), parse: parseWho },
+    );
+
+    if (who.ok && who.json?.initialized) {
+      const existingAgents = unique(who.json.sessions.flatMap((session) =>
+        session.agents.map((agent) => agent.handle),
+      ));
+      if (!existingAgents.includes(handle)) {
+        throw new Error(
+          `Chosen handle ${handle} is not provisioned in the existing AMQ roster: ${existingAgents.join(",")}`,
+        );
+      }
+      const live = await this.#runner.runJson(
+        ["env", "--root", root, "--me", handle],
+        { env: commandEnvironment(environment), parse: parseEnvPreview },
+      );
+      if (!live.ok || !live.json) {
+        throw new Error(literalFailure(live, "Existing AMQ root could not be inspected"));
+      }
+      return {
+        kind: "existing",
+        projectDirectory,
+        root: live.json.root,
+        session: live.json.session,
+        project: live.json.project,
+        handle,
+        agents: existingAgents,
+        command: [],
+        commandText: "No initialization command; verify and bind the selected existing mailbox",
+        effects: ["Persist pi-amq-binding/v1 only after live mailbox verification"],
+      };
+    }
+    if (!(who.ok && who.json && !who.json.initialized) && !bootstrapEligible(who)) {
+      throw new Error(literalFailure(who, "AMQ roster discovery failed"));
+    }
+
+    const command = ["amq", "coop", "init", "--root", root, "--agents", requestedAgents.join(",")];
+    return {
+      kind: "bootstrap",
+      projectDirectory,
+      root,
+      session: "",
+      project: projectDirectory,
+      handle,
+      agents: requestedAgents,
+      command,
+      commandText: command.map(shellWord).join(" "),
+      effects: [
+        `Create the physical AMQ root at ${root}`,
+        `Provision the complete roster: ${requestedAgents.join(",")}`,
+        `Write ${projectDirectory}/.amqrc`,
+        `Update ${projectDirectory}/.gitignore when needed`,
+      ],
+    };
+  }
+
+  async confirm(
+    preview: ConfirmedBindPreview,
+    confirmed: boolean,
+    environment: Readonly<NodeJS.ProcessEnv> = process.env,
+  ): Promise<ConfirmedBindResult> {
+    if (!confirmed) return { kind: "cancelled", diagnostic: "AMQ bind cancelled; no state changed" };
+
+    if (preview.kind === "bootstrap") {
+      const initialized = await this.#runner.runJson(
+        preview.command.slice(1),
+        { cwd: preview.projectDirectory, env: commandEnvironment(environment) },
+      );
+      if (!initialized.ok) {
+        return {
+          kind: "refused",
+          diagnostic: literalFailure(initialized, "AMQ roster bootstrap failed; pi-amq remains dormant"),
+        };
+      }
+    }
+
+    const resolution = await this.#resolver.resolve({
+      flags: { handle: preview.handle, root: preview.root },
+      environment: clearInheritedBinding(environment),
+    });
+    if (resolution.kind !== "bound") return refusedResolution(resolution);
+    if (resolution.binding.root !== preview.root || resolution.binding.handle !== preview.handle) {
+      return {
+        kind: "refused",
+        diagnostic: "Post-provision binding differs from the confirmed root or handle; pi-amq remains dormant",
+      };
+    }
+
+    const who = await this.#runner.runJson(
+      ["who", "--root", preview.root],
+      { env: commandEnvironment(environment), parse: parseWho },
+    );
+    if (!who.ok || !who.json?.initialized) {
+      return {
+        kind: "refused",
+        diagnostic: literalFailure(who, "Post-provision roster verification failed; pi-amq remains dormant"),
+      };
+    }
+    const verifiedAgents = unique(who.json.sessions.flatMap((session) =>
+      session.agents.map((agent) => agent.handle),
+    ));
+    if (!sameRoster(verifiedAgents, preview.agents)) {
+      return {
+        kind: "refused",
+        diagnostic: `Post-provision roster mismatch: confirmed ${preview.agents.join(",")}; live ${verifiedAgents.join(",")}`,
+      };
+    }
+    return { kind: "bound", binding: resolution.binding };
+  }
+}
+
+export function parseRosterInput(value: string, handle: string): readonly string[] {
+  return roster(value.split(","), agentHandle(handle, "chosen handle"));
+}
+
+function parseWho(value: unknown): WhoProjection {
+  if (value === null) return { initialized: false, sessions: [] };
+  if (!Array.isArray(value)) throw new Error("amq who --json must return an array");
+  const sessions = value.map((rawSession, sessionIndex) => {
+    const session = record(rawSession, `amq who session ${sessionIndex}`);
+    if (!Array.isArray(session.agents)) throw new Error("amq who session agents must be an array");
+    return {
+      name: stringField(session, "name"),
+      agents: session.agents.map((rawAgent, agentIndex) => {
+        const agent = record(rawAgent, `amq who agent ${agentIndex}`);
+        return { handle: agentHandle(stringField(agent, "handle"), "AMQ roster handle") };
+      }),
+    };
+  });
+  return { initialized: true, sessions };
+}
+
+function parseEnvPreview(value: unknown): EnvPreview {
+  const object = record(value, "amq env --json");
+  return {
+    root: absolute(stringField(object, "root"), "live AMQ root"),
+    session: stringField(object, "session_name"),
+    project: stringField(object, "project"),
+  };
+}
+
+function bootstrapEligible(result: AmqCommandResult<unknown>): boolean {
+  return result.category === "not-found"
+    || (result.category === "error" && /(?:not initialized|missing|not found|no such file)/i.test(result.stderr));
+}
+
+function refusedResolution(resolution: Exclude<BindingResolution, { readonly kind: "bound" }>): ConfirmedBindResult {
+  return {
+    kind: "refused",
+    diagnostic: `${resolution.diagnostic}; pi-amq remains dormant`,
+  };
+}
+
+function roster(values: readonly string[], handle: string): readonly string[] {
+  const normalized = values
+    .flatMap((value) => value.split(","))
+    .map((value) => value.trim())
+    .filter((value) => value.length > 0)
+    .map((value) => agentHandle(value, "roster handle"));
+  return unique([...normalized, handle, "user"]);
+}
+
+function unique(values: readonly string[]): readonly string[] {
+  return [...new Set(values)].sort((left, right) => left.localeCompare(right));
+}
+
+function sameRoster(left: readonly string[], right: readonly string[]): boolean {
+  const normalizedLeft = unique(left);
+  const normalizedRight = unique(right);
+  return normalizedLeft.length === normalizedRight.length
+    && normalizedLeft.every((value, index) => value === normalizedRight[index]);
+}
+
+function absolute(value: string, name: string): string {
+  if (!isAbsolute(value)) throw new TypeError(`${name} must be absolute`);
+  return normalize(value);
+}
+
+function agentHandle(value: string, name: string): string {
+  const normalized = value.trim();
+  if (!/^[a-z0-9][a-z0-9._-]*$/.test(normalized)) {
+    throw new TypeError(`${name} must use lowercase AMQ handle syntax`);
+  }
+  return normalized;
+}
+
+function clearInheritedBinding(environment: Readonly<NodeJS.ProcessEnv>): NodeJS.ProcessEnv {
+  const cleared: NodeJS.ProcessEnv = { ...environment };
+  for (const key of ["AM_ROOT", "AM_ROOT_ID", "AM_BASE_ROOT", "AM_BASE_ROOT_ID", "AM_SESSION", "AM_ME"]) {
+    delete cleared[key];
+  }
+  return cleared;
+}
+
+function commandEnvironment(environment: Readonly<NodeJS.ProcessEnv>): NodeJS.ProcessEnv {
+  return { ...environment };
+}
+
+function shellWord(value: string): string {
+  return /^[A-Za-z0-9_./,:=-]+$/.test(value) ? value : `'${value.replaceAll("'", `'\"'\"'`)}'`;
+}
+
+function literalFailure(result: AmqCommandResult<unknown>, fallback: string): string {
+  return result.stderr.trim() || result.jsonError?.message || result.processError?.message || fallback;
+}
+
+function record(value: unknown, name: string): Record<string, unknown> {
+  if (!value || typeof value !== "object" || Array.isArray(value)) throw new Error(`${name} must be an object`);
+  return value as Record<string, unknown>;
+}
+
+function stringField(object: Record<string, unknown>, key: string): string {
+  const value = object[key];
+  if (typeof value !== "string") throw new Error(`${key} must be a string`);
+  return value;
+}