@akagilnc/pi-workflow-roles 0.1.1751

package/src/collector-receipt.ts

@@ -0,0 +1,87 @@
+import { COLLECTOR_HOST } from "./collector-config.ts";
+import type { CollectorClock, CollectorEvidenceRecord, CollectorSnapshot } from "./collector-evidence.ts";
+import type { CollectorLedger, CollectorRequestAttempt } from "./collector-ledger.ts";
+import { extractCollectorEvidenceIdentityGroups, type ExtractedCollectorIdentityGroup } from "./collector-identity.ts";
+import { validateAcceptedCollectorReceipt } from "./package-contracts/collector-output.ts";
+
+export { validateAcceptedCollectorReceipt };
+
+export type CollectorReceipt = {
+  host: "github.com";
+  repository: string;
+  prNumber: number;
+  manifestDigest: string;
+  activationTime: string;
+  deadlineTime: string;
+  finalObservationTime: string;
+  finalSnapshotId: string;
+  targetHead: string;
+  groups: ExtractedCollectorIdentityGroup[];
+  requestAttempts: CollectorRequestAttempt[];
+  snapshots: CollectorSnapshot[];
+  evidenceRecords: CollectorEvidenceRecord[];
+};
+
+function fail(message: string): never { throw new Error(message); }
+
+/** Runtime output is intentionally empty: observed typed groups are the sole receipt source. */
+export function buildCollectorReceipt(
+  ledger: CollectorLedger,
+  _candidateRaw: unknown,
+  clock?: CollectorClock,
+): CollectorReceipt {
+  ledger.assertNotFatal();
+  if (ledger.outputAccepted) fail("Collector output is singleton");
+  if (ledger.unresolvedTransportFailure) fail("Collector cannot output while a transport failure is unrecovered");
+  if (ledger.latestCompleteSnapshotId === undefined) fail("Collector output requires a complete final snapshot");
+  if (ledger.activationTime === undefined || ledger.deadlineTime === undefined) fail("Collector output requires activation timeline");
+
+  if (clock !== undefined) ledger.assertOutputObservationLaw(clock);
+  else if (ledger.observedGeneration !== ledger.mutationGeneration ||
+    (ledger.finalObservationRequired && !ledger.finalObservationCompleted)) {
+    fail("Collector output requires a complete observe after the latest request/wait mutation");
+  }
+
+  const finalSnapshot = ledger.getSnapshot(ledger.latestCompleteSnapshotId);
+  if (finalSnapshot === undefined || !finalSnapshot.complete) fail("Collector final snapshot is incomplete");
+  if (finalSnapshot.prState !== "OPEN") fail("Collector final snapshot PR state is not OPEN");
+
+  const evidenceRecords = [...ledger.allEvidence()];
+  const snapshots = [...ledger.allSnapshots()];
+  const evidenceIndex = new Map(evidenceRecords.map((record) => [record.evidenceId, record]));
+  const snapshotIndex = new Map(snapshots.map((snapshot) => [snapshot.snapshotId, snapshot]));
+  if (evidenceIndex.size !== evidenceRecords.length) fail("Collector receipt evidenceId collision");
+  if (snapshotIndex.size !== snapshots.length) fail("Collector receipt snapshotId collision");
+  for (const id of evidenceIndex.keys()) if (snapshotIndex.has(id)) fail(`Collector receipt id "${id}" is ambiguous`);
+  if (!snapshotIndex.has(finalSnapshot.snapshotId)) fail("Collector receipt lacks final snapshot");
+  for (const snapshot of snapshots) {
+    for (const id of snapshot.evidenceIds) if (!evidenceIndex.has(id)) fail(`Collector snapshot ref "${id}" does not resolve`);
+  }
+
+  const groups = extractCollectorEvidenceIdentityGroups(evidenceRecords, finalSnapshot.headOid);
+  for (const group of groups) {
+    if (group.attendance !== true) fail("Collector group lacks attendance");
+    for (const material of group.materials) {
+      if (material.evidenceId === undefined || !evidenceIndex.has(material.evidenceId)) fail("Collector material lacks a receipt-local evidence ref");
+    }
+    for (const finding of group.findings) {
+      if (finding.source.evidenceId === undefined || !evidenceIndex.has(finding.source.evidenceId)) fail("Collector finding lacks a receipt-local evidence ref");
+    }
+  }
+
+  return {
+    host: COLLECTOR_HOST,
+    repository: ledger.config.repository.canonical,
+    prNumber: ledger.config.prNumber,
+    manifestDigest: ledger.config.manifest.digest,
+    activationTime: ledger.activationTime.toISOString(),
+    deadlineTime: ledger.deadlineTime.toISOString(),
+    finalObservationTime: finalSnapshot.completedAt ?? finalSnapshot.observedAt,
+    finalSnapshotId: finalSnapshot.snapshotId,
+    targetHead: finalSnapshot.headOid,
+    groups,
+    requestAttempts: [...ledger.requestAttempts()],
+    snapshots,
+    evidenceRecords,
+  };
+}

package/src/collector-role.ts

@@ -0,0 +1,592 @@
+import type {
+  ExtensionAPI,
+  ExtensionContext,
+} from "@earendil-works/pi-coding-agent";
+import type { Static } from "typebox";
+
+import {
+  COLLECTOR_FIXED_KICKOFF,
+  emptyCollectorManifest,
+  loadCollectorManifest,
+  parseCollectorPrNumber,
+  parseCollectorRepository,
+  type CollectorManifest,
+  type CollectorRepository,
+} from "./collector-config.ts";
+import {
+  createSystemCollectorClock,
+  type CollectorClock,
+} from "./collector-evidence.ts";
+import type { CollectorGitHubTransport } from "./collector-github.ts";
+import {
+  COLLECTOR_OBSERVE_TOOL,
+  COLLECTOR_OUTPUT_TOOL,
+  COLLECTOR_REQUEST_TOOL,
+  COLLECTOR_WAIT_TOOL,
+  createCollectorLedger,
+  type CollectorLedger,
+} from "./collector-ledger.ts";
+import {
+  buildCollectorReceipt,
+  type CollectorReceipt,
+} from "./collector-receipt.ts";
+import {
+  collectorObserveArgsSchema,
+  collectorOutputArgsSchema,
+  collectorRequestArgsSchema,
+  collectorWaitArgsSchema,
+} from "./collector-tool-schemas.ts";
+
+export { COLLECTOR_FIXED_KICKOFF } from "./collector-config.ts";
+export {
+  COLLECTOR_OBSERVE_TOOL,
+  COLLECTOR_OUTPUT_TOOL,
+  COLLECTOR_REQUEST_TOOL,
+  COLLECTOR_WAIT_TOOL,
+};
+
+export const COLLECTOR_REQUIRED_TOOLS = [
+  COLLECTOR_OBSERVE_TOOL,
+  COLLECTOR_REQUEST_TOOL,
+  COLLECTOR_WAIT_TOOL,
+  COLLECTOR_OUTPUT_TOOL,
+] as const;
+
+const observeSchema = collectorObserveArgsSchema;
+const requestSchema = collectorRequestArgsSchema;
+const waitSchema = collectorWaitArgsSchema;
+const outputSchema = collectorOutputArgsSchema;
+
+// Well below the fixed 183s package-tool silence clock while avoiding noisy UI
+// churn during Collector's legal five-minute wait.
+const COLLECTOR_WAIT_PROGRESS_INTERVAL_MS = 60_000;
+
+type RequestParams = Static<typeof requestSchema>;
+type WaitParams = Static<typeof waitSchema>;
+type OutputParams = Static<typeof outputSchema>;
+
+export type CollectorRoleDependencies = {
+  loadSoul(): Promise<string>;
+  createTransport(): CollectorGitHubTransport;
+  createClock?(): CollectorClock;
+  packageExtensionPath?: string;
+};
+
+export type CollectorRoleHostActions = {
+  failInfrastructure(error: unknown, ctx: ExtensionContext, toolCallId?: string): never;
+};
+
+type CollectorActivation = {
+  soul: string;
+  repository: CollectorRepository;
+  prNumber: number;
+  manifest: CollectorManifest;
+  ledger: CollectorLedger;
+  transport: CollectorGitHubTransport;
+  clock: CollectorClock;
+};
+
+/** Sole-final at the output execution seam (same shape as other terminating roles). */
+function assertSoleFinalCollectorOutput(
+  toolCallId: string,
+  ctx: ExtensionContext,
+): void {
+  const leaf = ctx.sessionManager.getLeafEntry();
+  if (leaf?.type !== "message" || leaf.message.role !== "assistant") {
+    throw new Error("Collector output must be the sole final tool call");
+  }
+  const calls = leaf.message.content.filter((part) => part.type === "toolCall");
+  const call = calls[0];
+  if (
+    calls.length !== 1 ||
+    call === undefined ||
+    call.id !== toolCallId ||
+    call.name !== COLLECTOR_OUTPUT_TOOL
+  ) {
+    throw new Error("Collector output must be the sole final tool call");
+  }
+}
+
+function buildMethodContext(activation: CollectorActivation): string {
+  return [
+    "<collector_method>",
+    "Observe all GitHub review materials; machine identity groups are runtime-owned.",
+    "Use ak_collector_request only when an optional configured request is needed.",
+    "Wait and cutoff only stop observation; they never imply absent observers.",
+    "After a complete final observation, submit ak_collector_output with an empty object.",
+    `host: github.com`,
+    `repository: ${activation.repository.canonical}`,
+    `prNumber: ${activation.prNumber}`,
+    `requests: ${JSON.stringify(activation.manifest.requests.map((request) => ({ id: request.id })))}`,
+    "</collector_method>",
+  ].join("\n");
+}
+
+export function createCollectorRoleRuntime(
+  pi: ExtensionAPI,
+  dependencies: CollectorRoleDependencies,
+  hostActions: CollectorRoleHostActions,
+): {
+  activate(
+    ctx: ExtensionContext,
+    event: { reason: string },
+  ): Promise<void>;
+} {
+  let activation: CollectorActivation | undefined;
+  let inputCount = 0;
+  let lifecycleRegistered = false;
+  let toolsRegistered = false;
+  let firstDispatchDone = false;
+
+  pi.registerFlag("ak-collector-repo", {
+    description:
+      "GitHub owner/repo target for Collector (github.com only; conservative ASCII grammar). Collector forbids every Skill, including command-only Skills.",
+    type: "string",
+  });
+  pi.registerFlag("ak-collector-pr", {
+    description:
+      "Positive safe-integer pull request number for Collector. Supported profile: --no-skills, --no-extensions with only the explicit Collector package extension, no prompt templates/context files, one print/JSON prompt",
+    type: "string",
+  });
+  pi.registerFlag("ak-collector-request-manifest", {
+    description:
+      "Path to the Collector v1 request manifest JSON file. In Pi latest, late hostile sibling-extension Skill injection is unsupported and fail-closed when detected; drift prevention only, not a security boundary or provider-zero guarantee",
+    type: "string",
+  });
+
+  const ensureLifecycle = (): void => {
+    if (lifecycleRegistered) return;
+    lifecycleRegistered = true;
+
+    pi.on("input", (event, ctx) => {
+      if (activation === undefined) {
+        // role not active
+        return { action: "continue" as const };
+      }
+      if (inputCount >= 1) {
+        activation.ledger.latchFatal(
+          "Collector is one-shot and rejects later inputs",
+        );
+        if (process.exitCode === undefined || process.exitCode === 0) {
+          process.exitCode = 1;
+        }
+        console.error("Collector rejected later input");
+        return { action: "handled" as const };
+      }
+      inputCount += 1;
+      return {
+        action: "transform" as const,
+        text: COLLECTOR_FIXED_KICKOFF,
+        images: [],
+      };
+    });
+
+    pi.on("before_agent_start", (event, ctx) => {
+      if (activation === undefined) return;
+
+      // Detectable ambient instruction resources on the supported prompt surface.
+      const options = event.systemPromptOptions;
+      if (options.skills && options.skills.length > 0) {
+        hostActions.failInfrastructure(
+          activation.ledger.latchFatal(
+            "Collector detected ambient skills in systemPromptOptions",
+          ),
+          ctx,
+        );
+      }
+      if (options.contextFiles && options.contextFiles.length > 0) {
+        hostActions.failInfrastructure(
+          activation.ledger.latchFatal(
+            "Collector detected ambient context files in systemPromptOptions",
+          ),
+          ctx,
+        );
+      }
+      if (
+        typeof options.appendSystemPrompt === "string" &&
+        options.appendSystemPrompt.trim().length > 0
+      ) {
+        hostActions.failInfrastructure(
+          activation.ledger.latchFatal(
+            "Collector detected appendSystemPrompt drift",
+          ),
+          ctx,
+        );
+      }
+
+      if (event.prompt !== COLLECTOR_FIXED_KICKOFF) {
+        hostActions.failInfrastructure(
+          activation.ledger.latchFatal(
+            "Collector first prompt must be the fixed packaged kickoff",
+          ),
+          ctx,
+        );
+      }
+
+      if (!firstDispatchDone) {
+        firstDispatchDone = true;
+        activation.ledger.recordActivation(activation.clock);
+      }
+
+      return {
+        systemPrompt: [
+          event.systemPrompt,
+          "",
+          "<collector_soul>",
+          activation.soul,
+          "</collector_soul>",
+          "",
+          buildMethodContext(activation),
+        ].join("\n"),
+      };
+    });
+
+    pi.on("tool_call", (event) => {
+      if (activation === undefined) return;
+      if (activation.ledger.fatal) {
+        return {
+          block: true,
+          reason: activation.ledger.fatalReason ?? "Collector fatal state",
+        };
+      }
+      if (!(COLLECTOR_REQUIRED_TOOLS as readonly string[]).includes(event.toolName)) {
+        return {
+          block: true,
+          reason: `Collector forbids tool ${event.toolName}`,
+        };
+      }
+      // Concurrency is owned at execute (beginOperational), not announced-batch preflight.
+      // Pi may emit tool_call for every part before any execute runs (ADR 0041).
+      if (
+        activation.ledger.outputAccepted &&
+        event.toolName !== COLLECTOR_OUTPUT_TOOL
+      ) {
+        return {
+          block: true,
+          reason: "Collector output already accepted; no further operations",
+        };
+      }
+      return undefined;
+    });
+
+    pi.on("tool_result", (event) => {
+      if (activation === undefined) return;
+      activation.ledger.completeOperational(event.toolCallId);
+    });
+
+    pi.on("session_shutdown", () => {
+      if (activation === undefined) return;
+      if (!activation.ledger.outputAccepted || activation.ledger.fatal) {
+        if (process.exitCode === undefined || process.exitCode === 0) {
+          process.exitCode = 1;
+        }
+      }
+    });
+  };
+
+  const registerTools = (): void => {
+    if (toolsRegistered) return;
+    toolsRegistered = true;
+
+    pi.registerTool({
+      name: COLLECTOR_OBSERVE_TOOL,
+      label: "Collector Observe",
+      description:
+        "Fetch complete GitHub PR evidence for the configured target and store an immutable snapshot in the invocation ledger.",
+      promptSnippet: "Observe configured PR evidence",
+      promptGuidelines: [
+        "Call ak_collector_observe with no arguments to refresh the latest complete snapshot.",
+      ],
+      parameters: observeSchema,
+      async execute(toolCallId, _params, signal, _onUpdate, ctx) {
+        if (activation === undefined) {
+          throw new Error("Collector is not activated");
+        }
+        try {
+          activation.ledger.beginOperational(COLLECTOR_OBSERVE_TOOL, toolCallId);
+          const { snapshot, modelView } = await activation.ledger.observe(
+            activation.transport,
+            activation.clock,
+            signal,
+          );
+          activation.ledger.completeOperational(toolCallId);
+          if (snapshot.prState !== "OPEN") {
+            // Non-OPEN observed as latest complete snapshot is target-state failure at output,
+            // but observe itself may return the fact. If this is a final observation, still return.
+          }
+          return {
+            content: [{
+              type: "text" as const,
+              text: JSON.stringify(modelView),
+            }],
+            details: modelView,
+          };
+        } catch (error) {
+          hostActions.failInfrastructure(error, ctx);
+        }
+      },
+    });
+
+    pi.registerTool({
+      name: COLLECTOR_REQUEST_TOOL,
+      label: "Collector Request",
+      description:
+        "Post one configured request body plus its correlation marker at the cited latest snapshot HEAD.",
+      promptSnippet: "Post a configured request",
+      promptGuidelines: [
+        "Call ak_collector_request only with a configured request-capable requestId and the latest snapshotId.",
+      ],
+      parameters: requestSchema,
+      async execute(toolCallId, params: RequestParams, signal, _onUpdate, ctx) {
+        if (activation === undefined) {
+          throw new Error("Collector is not activated");
+        }
+        try {
+          activation.ledger.beginOperational(COLLECTOR_REQUEST_TOOL, toolCallId);
+          const details = await activation.ledger.request(
+            params,
+            activation.transport,
+            activation.clock,
+            signal,
+          );
+          activation.ledger.completeOperational(toolCallId);
+          return {
+            content: [{
+              type: "text" as const,
+              text: `Request attempt recorded for request ${params.requestId}`,
+            }],
+            details,
+          };
+        } catch (error) {
+          hostActions.failInfrastructure(error, ctx);
+        }
+      },
+    });
+
+    pi.registerTool({
+      name: COLLECTOR_WAIT_TOOL,
+      label: "Collector Wait",
+      description:
+        "Wait before re-observing; each call is capped to five minutes and to remaining eligibility.",
+      promptSnippet: "Wait within the eligibility cutoff",
+      promptGuidelines: [
+        "Call ak_collector_wait with a positive durationMs; runtime caps each wait to five minutes and to remaining eligibility.",
+      ],
+      parameters: waitSchema,
+      async execute(toolCallId, params: WaitParams, signal, onUpdate, ctx) {
+        if (activation === undefined) {
+          throw new Error("Collector is not activated");
+        }
+        const currentActivation = activation;
+        let progressTimer: ReturnType<typeof setTimeout> | undefined;
+        try {
+          currentActivation.ledger.beginOperational(COLLECTOR_WAIT_TOOL, toolCallId);
+          const waitStartedMono = currentActivation.clock.monoNow();
+          let lastElapsedMs = 0;
+          const scheduleProgress = (): void => {
+            if (onUpdate === undefined) return;
+            progressTimer = setTimeout(() => {
+              const elapsedMs = Math.max(
+                0,
+                Math.floor(currentActivation.clock.monoNow() - waitStartedMono),
+              );
+              if (elapsedMs > lastElapsedMs) {
+                lastElapsedMs = elapsedMs;
+                onUpdate({
+                  content: [],
+                  details: { kind: "collector_wait_progress", elapsedMs },
+                });
+              }
+              scheduleProgress();
+            }, COLLECTOR_WAIT_PROGRESS_INTERVAL_MS);
+          };
+          scheduleProgress();
+          const details = await currentActivation.ledger.wait(
+            params,
+            currentActivation.clock,
+            signal,
+          );
+          currentActivation.ledger.completeOperational(toolCallId);
+          return {
+            content: [{
+              type: "text" as const,
+              text: `Waited ${String((details as { effectiveMs: number }).effectiveMs)}ms`,
+            }],
+            details,
+          };
+        } catch (error) {
+          hostActions.failInfrastructure(error, ctx);
+        } finally {
+          if (progressTimer !== undefined) clearTimeout(progressTimer);
+        }
+      },
+    });
+
+    pi.registerTool({
+      name: COLLECTOR_OUTPUT_TOOL,
+      label: "Collector Output",
+      description:
+        "Submit after observation. Runtime builds the self-contained typed-group receipt.",
+      promptSnippet: "Submit the Collector receipt",
+      promptGuidelines: [
+        "Use ak_collector_output as the sole final Collector action after a complete observation.",
+      ],
+      parameters: outputSchema,
+      async execute(toolCallId, params: OutputParams, _signal, _onUpdate, ctx) {
+        if (activation === undefined) {
+          throw new Error("Collector is not activated");
+        }
+        try {
+          assertSoleFinalCollectorOutput(toolCallId, ctx);
+          activation.ledger.beginOperational(COLLECTOR_OUTPUT_TOOL, toolCallId);
+          const receipt: CollectorReceipt = buildCollectorReceipt(
+            activation.ledger,
+            params,
+            activation.clock,
+          );
+          activation.ledger.markOutputAccepted();
+          activation.ledger.completeOperational(toolCallId);
+          return {
+            content: [{
+              type: "text" as const,
+              text: "Collector receipt accepted",
+            }],
+            details: receipt,
+            terminate: true as const,
+          };
+        } catch (error) {
+          // Output validation errors are model-visible rejections when non-fatal.
+          if (
+            error instanceof Error &&
+            (error as { collectorFatal?: boolean }).collectorFatal === true
+          ) {
+            hostActions.failInfrastructure(error, ctx, toolCallId);
+          }
+          throw error;
+        }
+      },
+    });
+  };
+
+  return {
+    async activate(ctx, event) {
+      activation = undefined;
+      ensureLifecycle();
+
+      if (ctx.mode !== "print" && ctx.mode !== "json") {
+          throw new Error(
+            `Collector supports only print or json mode (got ${ctx.mode})`,
+          );
+        }
+        if (
+          event.reason === "resume" ||
+          event.reason === "fork" ||
+          event.reason === "reload"
+        ) {
+          throw new Error(
+            `Collector does not support session_start reason ${event.reason}`,
+          );
+        }
+
+        const soul = (await dependencies.loadSoul()).trim();
+        if (soul.length === 0) throw new Error("Collector soul is empty");
+
+        const repoFlag = pi.getFlag("ak-collector-repo");
+        const prFlag = pi.getFlag("ak-collector-pr");
+        const requestManifestFlag = pi.getFlag("ak-collector-request-manifest");
+        if (typeof repoFlag !== "string" || repoFlag.trim().length === 0) {
+          throw new Error("Collector requires --ak-collector-repo");
+        }
+        if (typeof prFlag !== "string" && typeof prFlag !== "number") {
+          throw new Error("Collector requires --ak-collector-pr");
+        }
+        const repository = parseCollectorRepository(repoFlag);
+        const prNumber = parseCollectorPrNumber(prFlag);
+        const manifest = typeof requestManifestFlag === "string" && requestManifestFlag.trim().length > 0
+          ? await loadCollectorManifest(requestManifestFlag)
+          : emptyCollectorManifest();
+
+        // Detectable ambient command surface (skills/templates) when exposed.
+        const commands = pi.getCommands?.() ?? [];
+        const ambientCommands = commands.filter((command) => {
+          const name = command.name.toLowerCase();
+          return (
+            name.includes("skill") ||
+            name.includes("prompt") ||
+            name.startsWith("template")
+          );
+        });
+        if (ambientCommands.length > 0) {
+          throw new Error(
+            `Collector detected ambient instruction commands: ${
+              ambientCommands.map((c) => c.name).join(", ")
+            }`,
+          );
+        }
+
+        // Fail closed if a required name is already occupied before Collector registers.
+        const preExisting = pi.getAllTools();
+        for (const required of COLLECTOR_REQUIRED_TOOLS) {
+          const prior = preExisting.filter((tool) => tool.name === required);
+          if (prior.length > 0) {
+            throw new Error(`Collector required tool name collision: ${required}`);
+          }
+        }
+
+        registerTools();
+
+        const allTools = pi.getAllTools();
+        for (const required of COLLECTOR_REQUIRED_TOOLS) {
+          const matches = allTools.filter((tool) => tool.name === required);
+          if (matches.length === 0) {
+            throw new Error(`Collector required tool missing: ${required}`);
+          }
+          if (matches.length > 1) {
+            throw new Error(`Collector required tool name collision: ${required}`);
+          }
+          const tool = matches[0]!;
+          if (
+            dependencies.packageExtensionPath !== undefined &&
+            tool.sourceInfo?.path !== undefined &&
+            tool.sourceInfo.path !== dependencies.packageExtensionPath &&
+            !tool.sourceInfo.path.includes("role-runtime")
+          ) {
+            throw new Error(
+              `Collector required tool ${required} is overridden by ${tool.sourceInfo.path}`,
+            );
+          }
+        }
+
+        pi.setActiveTools([...COLLECTOR_REQUIRED_TOOLS]);
+        const active = new Set(pi.getActiveTools());
+        for (const required of COLLECTOR_REQUIRED_TOOLS) {
+          if (!active.has(required)) {
+            throw new Error(`Collector failed to activate required tool ${required}`);
+          }
+        }
+        for (const name of active) {
+          if (!(COLLECTOR_REQUIRED_TOOLS as readonly string[]).includes(name)) {
+            throw new Error(`Collector active tool surface includes unexpected ${name}`);
+          }
+        }
+
+        const clock = dependencies.createClock?.() ?? createSystemCollectorClock();
+        const transport = dependencies.createTransport();
+        const ledger = createCollectorLedger({
+          repository,
+          prNumber,
+          manifest,
+        });
+
+      activation = {
+        soul,
+        repository,
+        prNumber,
+        manifest,
+        ledger,
+        transport,
+        clock,
+      };
+    },
+  };
+}

package/src/collector-tool-schemas.ts

@@ -0,0 +1,19 @@
+import { Type, type Static } from "typebox";
+import { COLLECTOR_ELIGIBILITY_MS } from "./collector-evidence.ts";
+
+export const collectorObserveArgsSchema = Type.Object({}, { additionalProperties: false });
+export const collectorRequestArgsSchema = Type.Object({
+  requestId: Type.String({ minLength: 1, description: "Configured request identity." }),
+  snapshotId: Type.String({ minLength: 1, description: "Latest retained observation snapshot." }),
+}, { additionalProperties: false });
+export const collectorWaitArgsSchema = Type.Object({
+  durationMs: Type.Integer({ minimum: 1, maximum: COLLECTOR_ELIGIBILITY_MS }),
+}, { additionalProperties: false });
+/** Runtime owns the observed groups; the model only signals sole-final submission. */
+export const collectorOutputArgsSchema = Type.Object({}, { additionalProperties: true });
+(collectorOutputArgsSchema as unknown as { required: string[] }).required = [];
+
+export type CollectorObserveArgs = Static<typeof collectorObserveArgsSchema>;
+export type CollectorRequestArgs = Static<typeof collectorRequestArgsSchema>;
+export type CollectorWaitArgs = Static<typeof collectorWaitArgsSchema>;
+export type CollectorOutputArgs = Static<typeof collectorOutputArgsSchema>;