gsd-pi 2.73.1-dev.d987996 → 2.74.0-dev.0306a2e

package/src/resources/extensions/gsd/uok/gate-runner.ts

@@ -0,0 +1,146 @@
+import type { FailureClass, GateResult } from "./contracts.js";
+import { insertGateRun } from "../gsd-db.js";
+import { buildAuditEnvelope, emitUokAuditEvent } from "./audit.js";
+
+export interface GateRunnerContext {
+  basePath: string;
+  traceId: string;
+  turnId: string;
+  milestoneId?: string;
+  sliceId?: string;
+  taskId?: string;
+  unitType?: string;
+  unitId?: string;
+}
+
+export interface GateExecutionInput {
+  id: string;
+  type: string;
+  execute: (ctx: GateRunnerContext, attempt: number) => Promise<{
+    outcome: "pass" | "fail" | "retry" | "manual-attention";
+    rationale?: string;
+    findings?: string;
+    failureClass?: FailureClass;
+  }>;
+}
+
+const RETRY_MATRIX: Record<FailureClass, number> = {
+  none: 0,
+  policy: 0,
+  input: 0,
+  execution: 1,
+  artifact: 1,
+  verification: 1,
+  closeout: 1,
+  git: 1,
+  timeout: 2,
+  "manual-attention": 0,
+  unknown: 0,
+};
+
+export class UokGateRunner {
+  private readonly registry = new Map<string, GateExecutionInput>();
+
+  register(gate: GateExecutionInput): void {
+    this.registry.set(gate.id, gate);
+  }
+
+  list(): GateExecutionInput[] {
+    return Array.from(this.registry.values());
+  }
+
+  async run(id: string, ctx: GateRunnerContext): Promise<GateResult> {
+    const gate = this.registry.get(id);
+    if (!gate) {
+      return {
+        gateId: id,
+        gateType: "unknown",
+        outcome: "manual-attention",
+        failureClass: "unknown",
+        rationale: `Gate ${id} not registered`,
+        attempt: 1,
+        maxAttempts: 1,
+        retryable: false,
+        evaluatedAt: new Date().toISOString(),
+      };
+    }
+
+    let attempt = 0;
+    let final: GateResult | null = null;
+    const maxAttemptsByFailureClass = RETRY_MATRIX;
+
+    while (attempt < 3) {
+      attempt += 1;
+      const now = new Date().toISOString();
+      const result = await gate.execute(ctx, attempt);
+      const failureClass = result.failureClass ?? (result.outcome === "pass" ? "none" : "unknown");
+      const retryBudget = maxAttemptsByFailureClass[failureClass] ?? 0;
+      const retryable = result.outcome !== "pass" && attempt <= retryBudget;
+
+      final = {
+        gateId: gate.id,
+        gateType: gate.type,
+        outcome: retryable ? "retry" : result.outcome,
+        failureClass,
+        rationale: result.rationale,
+        findings: result.findings,
+        attempt,
+        maxAttempts: Math.max(1, retryBudget),
+        retryable,
+        evaluatedAt: now,
+      };
+
+      insertGateRun({
+        traceId: ctx.traceId,
+        turnId: ctx.turnId,
+        gateId: final.gateId,
+        gateType: final.gateType,
+        unitType: ctx.unitType,
+        unitId: ctx.unitId,
+        milestoneId: ctx.milestoneId,
+        sliceId: ctx.sliceId,
+        taskId: ctx.taskId,
+        outcome: final.outcome,
+        failureClass: final.failureClass,
+        rationale: final.rationale,
+        findings: final.findings,
+        attempt: final.attempt,
+        maxAttempts: final.maxAttempts,
+        retryable: final.retryable,
+        evaluatedAt: final.evaluatedAt,
+      });
+
+      emitUokAuditEvent(
+        ctx.basePath,
+        buildAuditEnvelope({
+          traceId: ctx.traceId,
+          turnId: ctx.turnId,
+          category: "gate",
+          type: "gate-run",
+          payload: {
+            gateId: final.gateId,
+            gateType: final.gateType,
+            outcome: final.outcome,
+            failureClass: final.failureClass,
+            attempt: final.attempt,
+            maxAttempts: final.maxAttempts,
+            retryable: final.retryable,
+          },
+        }),
+      );
+
+      if (!retryable) break;
+    }
+
+    return final ?? {
+      gateId: gate.id,
+      gateType: gate.type,
+      outcome: "manual-attention",
+      failureClass: "unknown",
+      attempt: 1,
+      maxAttempts: 1,
+      retryable: false,
+      evaluatedAt: new Date().toISOString(),
+    };
+  }
+}

package/src/resources/extensions/gsd/uok/gitops.ts

@@ -0,0 +1,75 @@
+import { isDbAvailable, upsertTurnGitTransaction } from "../gsd-db.js";
+import type { TurnCloseoutRecord } from "./contracts.js";
+import { buildAuditEnvelope, emitUokAuditEvent } from "./audit.js";
+
+export type TurnGitStage = "turn-start" | "stage" | "checkpoint" | "publish" | "record";
+
+interface GitTxArgs {
+  basePath: string;
+  traceId: string;
+  turnId: string;
+  unitType?: string;
+  unitId?: string;
+  stage: TurnGitStage;
+  action: "commit" | "snapshot" | "status-only";
+  push: boolean;
+  status: "ok" | "failed";
+  error?: string;
+  metadata?: Record<string, unknown>;
+}
+
+export function writeTurnGitTransaction(args: GitTxArgs): void {
+  if (!isDbAvailable()) return;
+  upsertTurnGitTransaction({
+    traceId: args.traceId,
+    turnId: args.turnId,
+    unitType: args.unitType,
+    unitId: args.unitId,
+    stage: args.stage,
+    action: args.action,
+    push: args.push,
+    status: args.status,
+    error: args.error,
+    metadata: args.metadata,
+    updatedAt: new Date().toISOString(),
+  });
+
+  emitUokAuditEvent(
+    args.basePath,
+    buildAuditEnvelope({
+      traceId: args.traceId,
+      turnId: args.turnId,
+      category: "gitops",
+      type: `turn-git-${args.stage}`,
+      payload: {
+        unitType: args.unitType,
+        unitId: args.unitId,
+        action: args.action,
+        push: args.push,
+        status: args.status,
+        error: args.error,
+        ...(args.metadata ?? {}),
+      },
+    }),
+  );
+}
+
+export function writeTurnCloseoutGitRecord(basePath: string, record: TurnCloseoutRecord): void {
+  writeTurnGitTransaction({
+    basePath,
+    traceId: record.traceId,
+    turnId: record.turnId,
+    unitType: record.unitType,
+    unitId: record.unitId,
+    stage: "record",
+    action: record.gitAction,
+    push: record.gitPushed,
+    status: record.failureClass === "git" ? "failed" : "ok",
+    error: record.failureClass === "git" ? "git closeout failure" : undefined,
+    metadata: {
+      turnStatus: record.status,
+      finishedAt: record.finishedAt,
+      activityFile: record.activityFile,
+    },
+  });
+}

package/src/resources/extensions/gsd/uok/kernel.ts

@@ -0,0 +1,105 @@
+import type { ExtensionAPI, ExtensionContext } from "@gsd/pi-coding-agent";
+import { appendFileSync, mkdirSync } from "node:fs";
+import { join } from "node:path";
+
+import type { AutoSession } from "../auto/session.js";
+import type { LoopDeps } from "../auto/loop-deps.js";
+import { gsdRoot } from "../paths.js";
+import { buildAuditEnvelope, emitUokAuditEvent } from "./audit.js";
+import { setUnifiedAuditEnabled } from "./audit-toggle.js";
+import { resolveUokFlags } from "./flags.js";
+import { createTurnObserver } from "./loop-adapter.js";
+
+interface RunAutoLoopWithUokArgs {
+  ctx: ExtensionContext;
+  pi: ExtensionAPI;
+  s: AutoSession;
+  deps: LoopDeps;
+  runLegacyLoop: (
+    ctx: ExtensionContext,
+    pi: ExtensionAPI,
+    s: AutoSession,
+    deps: LoopDeps,
+  ) => Promise<void>;
+}
+
+function parityLogPath(basePath: string): string {
+  return join(gsdRoot(basePath), "runtime", "uok-parity.jsonl");
+}
+
+function writeParityEvent(basePath: string, event: Record<string, unknown>): void {
+  try {
+    mkdirSync(join(gsdRoot(basePath), "runtime"), { recursive: true });
+    appendFileSync(parityLogPath(basePath), `${JSON.stringify(event)}\n`, "utf-8");
+  } catch {
+    // parity telemetry must never block orchestration
+  }
+}
+
+function resolveKernelPathLabel(flags: ReturnType<typeof resolveUokFlags>): "uok-wrapper" | "legacy-wrapper" | "legacy-fallback" {
+  if (flags.legacyFallback) return "legacy-fallback";
+  return flags.enabled ? "uok-wrapper" : "legacy-wrapper";
+}
+
+export async function runAutoLoopWithUok(args: RunAutoLoopWithUokArgs): Promise<void> {
+  const { ctx, pi, s, deps, runLegacyLoop } = args;
+  const prefs = deps.loadEffectiveGSDPreferences()?.preferences;
+  const flags = resolveUokFlags(prefs);
+  setUnifiedAuditEnabled(flags.auditUnified);
+
+  writeParityEvent(s.basePath, {
+    ts: new Date().toISOString(),
+    path: resolveKernelPathLabel(flags),
+    flags,
+    phase: "enter",
+  });
+
+  if (flags.auditUnified) {
+    emitUokAuditEvent(
+      s.basePath,
+      buildAuditEnvelope({
+        traceId: `session:${String(s.autoStartTime || Date.now())}`,
+        category: "orchestration",
+        type: "uok-kernel-enter",
+        payload: {
+          flags,
+          sessionId: ctx.sessionManager?.getSessionId?.(),
+        },
+      }),
+    );
+  }
+
+  const decoratedDeps: LoopDeps = flags.enabled
+    ? {
+        ...deps,
+        uokObserver: createTurnObserver({
+          basePath: s.basePath,
+          gitAction: flags.gitopsTurnAction,
+          gitPush: flags.gitopsTurnPush,
+          enableAudit: flags.auditUnified,
+          enableGitops: flags.gitops,
+        }),
+      }
+    : deps;
+
+  try {
+    await runLegacyLoop(ctx, pi, s, decoratedDeps);
+    writeParityEvent(s.basePath, {
+      ts: new Date().toISOString(),
+      path: resolveKernelPathLabel(flags),
+      flags,
+      phase: "exit",
+      status: "ok",
+    });
+  } catch (err) {
+    writeParityEvent(s.basePath, {
+      ts: new Date().toISOString(),
+      path: resolveKernelPathLabel(flags),
+      flags,
+      phase: "exit",
+      status: "error",
+      error: err instanceof Error ? err.message : String(err),
+    });
+    throw err;
+  }
+}

package/src/resources/extensions/gsd/uok/loop-adapter.ts

@@ -0,0 +1,162 @@
+import type {
+  TurnCloseoutRecord,
+  TurnContract,
+  TurnResult,
+  UokTurnObserver,
+} from "./contracts.js";
+import { buildAuditEnvelope, emitUokAuditEvent } from "./audit.js";
+import { writeTurnCloseoutGitRecord, writeTurnGitTransaction } from "./gitops.js";
+
+export interface CreateTurnObserverOptions {
+  basePath: string;
+  gitAction: "commit" | "snapshot" | "status-only";
+  gitPush: boolean;
+  enableAudit: boolean;
+  enableGitops: boolean;
+}
+
+export function createTurnObserver(options: CreateTurnObserverOptions): UokTurnObserver {
+  let current: TurnContract | null = null;
+  const phaseResults: TurnResult["phaseResults"] = [];
+
+  return {
+    onTurnStart(contract): void {
+      current = contract;
+      phaseResults.length = 0;
+
+      if (options.enableGitops) {
+        writeTurnGitTransaction({
+          basePath: options.basePath,
+          traceId: contract.traceId,
+          turnId: contract.turnId,
+          unitType: contract.unitType,
+          unitId: contract.unitId,
+          stage: "turn-start",
+          action: options.gitAction,
+          push: options.gitPush,
+          status: "ok",
+          metadata: {
+            iteration: contract.iteration,
+            sidecarKind: contract.sidecarKind,
+          },
+        });
+      }
+
+      if (options.enableAudit) {
+        emitUokAuditEvent(
+          options.basePath,
+          buildAuditEnvelope({
+            traceId: contract.traceId,
+            turnId: contract.turnId,
+            category: "orchestration",
+            type: "turn-start",
+            payload: {
+              iteration: contract.iteration,
+              unitType: contract.unitType,
+              unitId: contract.unitId,
+              sidecarKind: contract.sidecarKind,
+            },
+          }),
+        );
+      }
+    },
+
+    onPhaseResult(phase, action, data): void {
+      phaseResults.push({
+        phase,
+        action,
+        ts: new Date().toISOString(),
+        data,
+      });
+
+      if (!current || !options.enableGitops) return;
+      if (phase === "dispatch") {
+        writeTurnGitTransaction({
+          basePath: options.basePath,
+          traceId: current.traceId,
+          turnId: current.turnId,
+          unitType: data?.unitType as string | undefined,
+          unitId: data?.unitId as string | undefined,
+          stage: "stage",
+          action: options.gitAction,
+          push: options.gitPush,
+          status: "ok",
+          metadata: { action },
+        });
+      }
+      if (phase === "unit") {
+        writeTurnGitTransaction({
+          basePath: options.basePath,
+          traceId: current.traceId,
+          turnId: current.turnId,
+          unitType: data?.unitType as string | undefined,
+          unitId: data?.unitId as string | undefined,
+          stage: "checkpoint",
+          action: options.gitAction,
+          push: options.gitPush,
+          status: "ok",
+          metadata: { action },
+        });
+      }
+      if (phase === "finalize") {
+        writeTurnGitTransaction({
+          basePath: options.basePath,
+          traceId: current.traceId,
+          turnId: current.turnId,
+          unitType: data?.unitType as string | undefined,
+          unitId: data?.unitId as string | undefined,
+          stage: "publish",
+          action: options.gitAction,
+          push: options.gitPush,
+          status: "ok",
+          metadata: { action },
+        });
+      }
+    },
+
+    onTurnResult(result): void {
+      const merged: TurnResult = {
+        ...result,
+        phaseResults: result.phaseResults.length > 0 ? result.phaseResults : [...phaseResults],
+      };
+
+      if (options.enableAudit) {
+        emitUokAuditEvent(
+          options.basePath,
+          buildAuditEnvelope({
+            traceId: merged.traceId,
+            turnId: merged.turnId,
+            category: "orchestration",
+            type: "turn-result",
+            payload: {
+              unitType: merged.unitType,
+              unitId: merged.unitId,
+              status: merged.status,
+              failureClass: merged.failureClass,
+              error: merged.error,
+              phaseCount: merged.phaseResults.length,
+            },
+          }),
+        );
+      }
+
+      if (options.enableGitops) {
+        const closeout: TurnCloseoutRecord = merged.closeout ?? {
+          traceId: merged.traceId,
+          turnId: merged.turnId,
+          unitType: merged.unitType,
+          unitId: merged.unitId,
+          status: merged.status,
+          failureClass: merged.failureClass,
+          gitAction: options.gitAction,
+          gitPushed: options.gitPush,
+          finishedAt: merged.finishedAt,
+        };
+        writeTurnCloseoutGitRecord(options.basePath, closeout);
+      }
+
+      current = null;
+      phaseResults.length = 0;
+    },
+  };
+}

package/src/resources/extensions/gsd/uok/model-policy.ts

@@ -0,0 +1,112 @@
+import type { TaskMetadata } from "../complexity-classifier.js";
+import { computeTaskRequirements, filterToolsForProvider } from "../model-router.js";
+import { buildAuditEnvelope, emitUokAuditEvent } from "./audit.js";
+
+export interface ModelCandidate {
+  id: string;
+  provider: string;
+  api: string;
+}
+
+export interface ModelPolicyDecision {
+  modelId: string;
+  provider: string;
+  allowed: boolean;
+  reason: string;
+}
+
+export interface ModelPolicyOptions {
+  basePath: string;
+  traceId: string;
+  turnId?: string;
+  unitType?: string;
+  taskMetadata?: TaskMetadata;
+  currentProvider?: string;
+  allowCrossProvider?: boolean;
+  requiredTools?: string[];
+  deniedProviders?: string[];
+  allowedApis?: string[];
+}
+
+export function buildRequirementVector(unitType?: string, taskMetadata?: TaskMetadata): Partial<Record<string, number>> {
+  if (!unitType) return {};
+  return computeTaskRequirements(unitType, taskMetadata) as unknown as Partial<Record<string, number>>;
+}
+
+export function applyModelPolicyFilter<T extends ModelCandidate>(
+  candidates: T[],
+  options: ModelPolicyOptions,
+): {
+  eligible: T[];
+  decisions: ModelPolicyDecision[];
+  requirements: Partial<Record<string, number>>;
+} {
+  const requiredTools = options.requiredTools ?? [];
+  const deniedProviders = new Set((options.deniedProviders ?? []).map((p) => p.toLowerCase()));
+  const allowedApis = options.allowedApis ? new Set(options.allowedApis) : null;
+  const requirements = buildRequirementVector(options.unitType, options.taskMetadata);
+  const decisions: ModelPolicyDecision[] = [];
+  const eligible: T[] = [];
+
+  for (const model of candidates) {
+    let allowed = true;
+    let reason = "allowed";
+
+    if (options.allowCrossProvider === false && options.currentProvider && model.provider !== options.currentProvider) {
+      allowed = false;
+      reason = `cross-provider routing disabled (${model.provider} != ${options.currentProvider})`;
+    }
+
+    if (allowed && deniedProviders.has(model.provider.toLowerCase())) {
+      allowed = false;
+      reason = `provider denied by policy: ${model.provider}`;
+    }
+
+    if (allowed && allowedApis && !allowedApis.has(model.api)) {
+      allowed = false;
+      reason = `transport/api denied by policy: ${model.api}`;
+    }
+
+    if (allowed && requiredTools.length > 0) {
+      const compatibility = filterToolsForProvider(requiredTools, model.api);
+      if (compatibility.filtered.length > 0) {
+        allowed = false;
+        reason = `tool policy denied (${compatibility.filtered.join(", ")}) for ${model.api}`;
+      }
+    }
+
+    const decision: ModelPolicyDecision = {
+      modelId: model.id,
+      provider: model.provider,
+      allowed,
+      reason,
+    };
+    decisions.push(decision);
+
+    emitUokAuditEvent(
+      options.basePath,
+      buildAuditEnvelope({
+        traceId: options.traceId,
+        turnId: options.turnId,
+        category: "model-policy",
+        type: allowed ? "model-policy-allow" : "model-policy-deny",
+        payload: {
+          modelId: model.id,
+          provider: model.provider,
+          api: model.api,
+          reason,
+          unitType: options.unitType,
+          requirements,
+        },
+      }),
+    );
+
+    if (allowed) eligible.push(model);
+  }
+
+  return {
+    eligible,
+    decisions,
+    requirements,
+  };
+}