pi-amq 0.1.1

package/workflow/workflow-types.ts

@@ -0,0 +1,367 @@
+export type RunId = `run_${string}`;
+export type StepId = `step_${string}`;
+export type WorkerId = `worker_${string}`;
+export type AttemptId = `attempt_${string}`;
+export type AmbiguityId = `ambiguity_${string}`;
+export type ContractRevisionId = `revision_${string}`;
+export type PeerMessageId = `peer_${string}`;
+
+export interface ReportFieldSchema {
+  readonly type: "string" | "number" | "boolean" | "object" | "array" | "null";
+}
+
+export interface ReportSchemaV1 {
+  readonly schema: 1;
+  readonly required: readonly string[];
+  readonly properties: Readonly<Record<string, ReportFieldSchema>>;
+}
+
+export interface AcceptanceCheck {
+  readonly command: string;
+  readonly args: readonly string[];
+}
+
+export type BudgetLimit =
+  | { readonly kind: "limited"; readonly value: number }
+  | { readonly kind: "unlimited" };
+
+export interface RunBudget {
+  readonly maxWorkers: BudgetLimit;
+  readonly maxConcurrency: BudgetLimit;
+  readonly maxDepth: BudgetLimit;
+  readonly maxAttempts: BudgetLimit;
+  readonly maxWallClockMs: BudgetLimit;
+  readonly maxTokens: BudgetLimit;
+  readonly maxCostUsd: BudgetLimit;
+  readonly maxOutputBytes: BudgetLimit;
+}
+
+export interface WorkerBudget {
+  readonly maxAttempts: BudgetLimit;
+  readonly maxWallClockMs: BudgetLimit;
+  readonly maxTokens: BudgetLimit;
+  readonly maxCostUsd: BudgetLimit;
+  readonly maxOutputBytes: BudgetLimit;
+}
+
+export interface EvidenceNode {
+  readonly id: string;
+  readonly kind: "claim" | "artifact";
+  readonly assertion: string;
+  readonly verifier: string;
+  readonly requires: readonly string[];
+}
+
+export interface ObjectiveContract {
+  readonly schema: 1;
+  readonly goal: string;
+  readonly acceptance: readonly string[];
+  readonly constraints: readonly string[];
+  readonly permissions: readonly string[];
+  readonly budget: RunBudget;
+  readonly evidenceGraph?: { readonly nodes: readonly EvidenceNode[] };
+}
+
+export interface RunSource {
+  readonly kind: "interactive" | "amq" | "external-engine";
+  readonly amqMessageId: string | null;
+  readonly driverSessionId: string;
+}
+
+export interface ModelSpec {
+  readonly provider: string;
+  readonly id: string;
+  readonly thinkingLevel?: string;
+}
+
+export interface WorkspaceGrant {
+  readonly path: string;
+  readonly mode: "read-only" | "mutating";
+  readonly worktreePath?: string;
+}
+
+export interface ContentRef {
+  readonly kind: "file" | "session" | "artifact";
+  readonly value: string;
+  readonly hash?: string;
+}
+
+export interface WorkerRoleContract {
+  readonly name: string;
+  readonly tier: string;
+  readonly charter: string;
+  readonly presetSource: "builtin" | "user" | "project";
+  readonly presetFingerprint: string;
+}
+
+export type WorkerProposalEditableField = "role" | "task" | "model" | "difficulty" | "budget";
+
+export interface WorkerProposalProvenance {
+  readonly source: "tool" | "human-edited";
+  readonly confirmSpawns: "on" | "multi-worker-only" | "off";
+  readonly disposition: "accepted" | "skipped-policy-off" | "skipped-single-worker";
+  readonly humanEditedFields: readonly WorkerProposalEditableField[];
+}
+
+export type WorkerContextMode = "fresh" | "fork";
+
+export interface WorkerForkSource {
+  readonly sourceSessionFile: string;
+  readonly branchPointId: string;
+  readonly inheritedEntries: number;
+  readonly inheritedBytes: number;
+}
+
+export interface WorkerRequest {
+  readonly schema: 1;
+  readonly requestKey: string;
+  readonly difficulty?: "hard" | "medium" | "easy";
+  readonly role?: WorkerRoleContract;
+  readonly proposal?: WorkerProposalProvenance;
+  readonly context?: WorkerContextMode;
+  readonly forkSource?: WorkerForkSource;
+  readonly goal: string;
+  readonly acceptance: readonly string[];
+  readonly constraints: readonly string[];
+  readonly budget: WorkerBudget;
+  readonly model: ModelSpec;
+  readonly modelFallbacks?: readonly ModelSpec[];
+  readonly capabilities: readonly string[];
+  readonly workspace: WorkspaceGrant;
+  readonly contextRefs: readonly ContentRef[];
+  readonly channel: "json-result" | "rpc";
+  readonly sideEffectPolicy: "none" | "idempotent" | "reconcilable" | "external";
+  readonly report_schema?: ReportSchemaV1;
+  readonly requires_human_approval?: boolean;
+  readonly acceptance_check?: AcceptanceCheck;
+}
+
+export interface WorkerContract extends WorkerRequest {
+  readonly context: WorkerContextMode;
+  readonly runId: RunId;
+  readonly workerId: WorkerId;
+  readonly createdByDriverSessionId: string;
+}
+
+export interface WorkerLaunchContractV1 {
+  readonly schema: 1;
+  readonly runId: RunId;
+  readonly workerId: WorkerId;
+  readonly attemptId: AttemptId;
+  readonly workerAttemptGeneration: string;
+  readonly supervisorGeneration: string;
+  readonly transportMode: "send-only";
+  readonly channel: "json-result" | "rpc";
+  readonly depth: number;
+  readonly model: ModelSpec;
+  readonly capabilities: readonly string[];
+  readonly tools: readonly string[];
+  readonly workspace: WorkspaceGrant;
+  readonly sessionDirectory: string;
+  readonly continuedSessionFile?: string;
+  readonly forkedSessionFile?: string;
+  readonly projectTrust: "trusted" | "untrusted";
+  readonly parentLivenessFd: 3;
+  readonly budget: WorkerBudget;
+  readonly sideEffectPolicy: WorkerRequest["sideEffectPolicy"];
+}
+
+export interface WorkerContinuationProvenance {
+  readonly priorWorkerId: WorkerId;
+  readonly priorAttemptId: AttemptId;
+  readonly priorLeaseGeneration: string;
+  readonly sessionFile: string;
+}
+
+export interface ProcessStartEvidence {
+  readonly pid: number | null;
+  readonly processStartIdentity: string | null;
+  readonly bootIdentity: string | null;
+  readonly executable: string | null;
+  readonly hostname: string | null;
+  readonly spawnedAt: string | null;
+  readonly observedExitAt: string | null;
+  readonly exitStatus: {
+    readonly code: number | null;
+    readonly signal: string | null;
+  } | null;
+}
+
+export interface AttemptUsageProjection {
+  readonly tokens: number;
+  readonly costUsd: number;
+  readonly outputBytes: number;
+}
+
+export interface WorkerAttemptProjection {
+  readonly attemptId: AttemptId;
+  readonly attemptNumber: number;
+  readonly workerAttemptGeneration: string;
+  readonly supervisorGeneration: string;
+  readonly state: "pending" | "running" | "blocked" | "ambiguous" | "done" | "failed" | "cancelled";
+  readonly session: {
+    readonly path: string;
+    readonly file: string | null;
+    readonly leaseGeneration: string | null;
+  };
+  readonly launchContract: WorkerLaunchContractV1 | null;
+  readonly modelSelection?: {
+    readonly model: ModelSpec;
+    readonly fallbackReason: string | null;
+  };
+  readonly pidStartEvidence: ProcessStartEvidence;
+  readonly usage: AttemptUsageProjection;
+  readonly candidateOutcome: { readonly valueOrRef: string | null; readonly hash: string | null };
+  readonly sideEffects: {
+    readonly policy: WorkerRequest["sideEffectPolicy"];
+    readonly status: "none" | "known" | "uncertain";
+  };
+  readonly control: {
+    readonly status: "attached" | "detached";
+    readonly reason: string | null;
+    readonly recordedAt: string | null;
+  };
+  readonly cancellation: {
+    readonly reason: string | null;
+    readonly requestedAt: string | null;
+    readonly sentAt: string | null;
+    readonly observedAt: string | null;
+  };
+}
+
+export interface ContractRevisionProjection {
+  readonly revisionId: ContractRevisionId;
+  readonly revision: number;
+  readonly contract: WorkerContract;
+  readonly status: "pending" | "delivered";
+  readonly correlation: string | null;
+  readonly requestedAt: string;
+  readonly deliveredAt: string | null;
+}
+
+export interface WorkerWaitProjection {
+  readonly attemptId: AttemptId;
+  readonly workerAttemptGeneration: string;
+  readonly reason: string;
+  readonly correlation: string;
+  readonly status: "waiting" | "satisfied";
+  readonly declaredAt: string;
+  readonly satisfiedAt: string | null;
+  readonly satisfiedBy: "steer" | "revise_contract" | "peer_message" | null;
+}
+
+export interface WorkerStallProjection {
+  readonly silent: {
+    readonly detected: boolean;
+    readonly expectedCadenceMs: number | null;
+    readonly recordedAt: string | null;
+  };
+  readonly noProgress: {
+    readonly detected: boolean;
+    readonly fingerprint: string | null;
+    readonly identicalRounds: number;
+    readonly recordedAt: string | null;
+  };
+}
+
+export interface WorkerGateProjection {
+  readonly evidenceExists: boolean;
+  readonly reportMatches: boolean | null;
+  readonly acceptanceCheckExitCode: number | null;
+  readonly humanApproved: boolean | null;
+  readonly blockers: readonly string[];
+}
+
+export interface PeerMessageProjection {
+  readonly messageId: PeerMessageId;
+  readonly senderWorkerId: WorkerId;
+  readonly recipientWorkerId: WorkerId;
+  readonly grant: string;
+  readonly correlation: string;
+  readonly messageHash: string;
+  readonly status: "pending" | "delivered" | "indeterminate";
+  readonly requestedAt: string;
+  readonly deliveredAt: string | null;
+  readonly diagnostic: string | null;
+}
+
+export interface WorkerProjection {
+  readonly workerId: WorkerId;
+  readonly spawnRequestKey: string;
+  readonly atomicCallStepId: StepId;
+  readonly contractFingerprint: string;
+  readonly contract: WorkerContract;
+  readonly continuation: WorkerContinuationProvenance | null;
+  readonly parentWorkerId: WorkerId | null;
+  readonly depth: number;
+  readonly state: WorkerAttemptProjection["state"];
+  readonly lastLedgerAt: string;
+  readonly attempts: readonly WorkerAttemptProjection[];
+  readonly contractRevisions: readonly ContractRevisionProjection[];
+  readonly peerMessages: readonly PeerMessageProjection[];
+  readonly waits: readonly WorkerWaitProjection[];
+  readonly stall: WorkerStallProjection;
+  readonly gate: WorkerGateProjection;
+  readonly acceptedOutcome: null;
+}
+
+export interface RunBudgetProjection {
+  readonly limits: RunBudget;
+  readonly reserved: {
+    readonly workers: number;
+    readonly attempts: number;
+    readonly tokens: number | "unlimited";
+    readonly costUsd: number | "unlimited";
+    readonly outputBytes: number | "unlimited";
+  };
+  readonly spent: {
+    readonly tokens: number;
+    readonly costUsd: number;
+    readonly outputBytes: number;
+  };
+  readonly remaining: {
+    readonly workers: BudgetLimit;
+    readonly attempts: BudgetLimit;
+    readonly tokens: BudgetLimit;
+    readonly wallClockMs: BudgetLimit;
+    readonly costUsd: BudgetLimit;
+    readonly outputBytes: BudgetLimit;
+  };
+}
+
+export interface AmbiguityProjection {
+  readonly ambiguityId: AmbiguityId;
+  readonly status: "needs-reconcile";
+  readonly reason: string;
+  readonly relatedIds: readonly string[];
+  readonly recordedAt: string;
+}
+
+export const RUN_STATES = [
+  "open",
+  "verifying",
+  "done",
+  "blocked",
+  "cancel-requested",
+  "cancelled",
+  "ambiguous",
+  "needs-attention",
+] as const;
+
+export type RunState = (typeof RUN_STATES)[number];
+
+export interface RunProjectionV2 {
+  readonly schema: 2;
+  readonly runId: RunId;
+  readonly requestKey: string;
+  readonly requestFingerprint: string;
+  readonly source: RunSource;
+  readonly objective: ObjectiveContract;
+  readonly budget: RunBudgetProjection;
+  readonly state: RunState;
+  readonly workers: Readonly<Record<string, WorkerProjection>>;
+  readonly unresolvedAmbiguities: readonly AmbiguityProjection[];
+  readonly ledger: { readonly throughSeq: number; readonly chainHash: string };
+  readonly createdAt: string;
+  readonly updatedAt: string;
+}

package/workflow/workspace-paths.ts

@@ -0,0 +1,32 @@
+import { createHash } from "node:crypto";
+import { homedir } from "node:os";
+import { isAbsolute, join, normalize, resolve } from "node:path";
+
+export function defaultPiStateDirectory(): string {
+  return join(homedir(), ".pi", "agent");
+}
+
+export function workflowWorkspaceId(workspacePath: string): string {
+  const canonical = canonicalWorkspacePath(workspacePath);
+  return createHash("sha256").update(canonical).digest("hex");
+}
+
+export function workflowNamespaceDirectory(
+  piStateDirectory: string,
+  workspacePath: string,
+): string {
+  if (!isAbsolute(piStateDirectory)) {
+    throw new TypeError("Pi state directory must be absolute");
+  }
+  return join(
+    normalize(piStateDirectory),
+    "workspaces",
+    workflowWorkspaceId(workspacePath),
+    "pi-amq-workflow",
+  );
+}
+
+function canonicalWorkspacePath(workspacePath: string): string {
+  if (!isAbsolute(workspacePath)) throw new TypeError("Workspace path must be absolute");
+  return normalize(resolve(workspacePath));
+}