owlrunkit 0.13.0

package/scripts/runkit-contract/inspect-presentation.mjs

@@ -0,0 +1,183 @@
+function latestIndexedCloseout(executions) {
+  return [...executions].reverse().find(execution => execution.lifecycle === "closed") ?? null;
+}
+
+function compareCodeUnits(left, right) {
+  return left < right ? -1 : left > right ? 1 : 0;
+}
+
+function escapeHumanControls(input) {
+  return String(input).replace(/[\u0000-\u001f\u007f-\u009f]/g, character => (
+    `\\u${character.codePointAt(0).toString(16).padStart(4, "0")}`
+  ));
+}
+
+function selectedFocus(inspected) {
+  const selectedRunId = inspected.recovery.selectedRunId;
+  if (selectedRunId) {
+    return inspected.executions.find(execution => execution.runId === selectedRunId) ?? null;
+  }
+  return inspected.recovery.state === "no_active_execution"
+    ? latestIndexedCloseout(inspected.executions)
+    : null;
+}
+
+export function buildInspectSummary(inspected) {
+  const focus = selectedFocus(inspected);
+  const latestClosed = latestIndexedCloseout(inspected.executions);
+  const holders = inspected.executions
+    .flatMap(execution => (execution.recovery?.lease?.activeWorkItemIds ?? []).map(workItemId => ({
+      runId: execution.runId,
+      workItemId,
+    })))
+    .sort((left, right) => compareCodeUnits(
+      `${left.runId}/${left.workItemId}`,
+      `${right.runId}/${right.workItemId}`,
+    ));
+  const delivery = focus?.recovery?.delivery ?? null;
+  const verification = focus?.recovery?.verification ?? null;
+  const resource = focus?.recovery?.resourcePreflight ?? { status: "none", selected: null };
+  const selectedResource = resource.selected ?? null;
+  const reasons = [
+    ...(inspected.recovery.state === "multiple_active_executions"
+      ? ["Multiple active executions require explicit selection."]
+      : (focus?.recovery?.issues ?? [])),
+    ...(inspected.controlIssues ?? []),
+    ...(selectedResource?.blockers ?? []),
+  ].filter((reason, index, all) => all.indexOf(reason) === index);
+  return {
+    schemaVersion: "OwlCodaRunKitInspectSummaryV1",
+    currentExecution: {
+      state: inspected.recovery.state,
+      selectedRunId: inspected.recovery.selectedRunId,
+      activeRunIds: [...inspected.recovery.activeRunIds],
+      openCount: inspected.recovery.activeRunIds.length,
+    },
+    latestIndexedCloseout: latestClosed
+      ? {
+          runId: latestClosed.runId,
+          decision: latestClosed.closeout?.decision ?? "invalid",
+          trustLevel: latestClosed.recovery?.evidenceTrustLevel ?? "invalid",
+        }
+      : null,
+    source: {
+      status: delivery?.status ?? "none",
+      sourceFingerprint: delivery?.sourceFingerprint ?? verification?.sourceFingerprint ?? null,
+    },
+    leases: {
+      activeCount: holders.length,
+      holders,
+    },
+    evidence: {
+      status: verification?.status ?? "none",
+      decision: verification?.decision ?? null,
+      activeReceiptSha256: verification?.activeReceiptSha256 ?? null,
+      trustLevel: focus?.recovery?.evidenceTrustLevel ?? "none",
+    },
+    resourcePreflight: {
+      status: resource.status,
+      preflightId: selectedResource?.preflightId ?? null,
+      sequence: selectedResource?.sequence ?? null,
+      evaluatedAt: selectedResource?.evaluatedAt ?? null,
+      validUntil: selectedResource?.validUntil ?? null,
+      decision: selectedResource?.status ?? null,
+      nextAllowedAction: selectedResource?.nextAllowedAction ?? null,
+      blockers: [...(selectedResource?.blockers ?? [])],
+      warnings: [...(selectedResource?.warnings ?? [])],
+      receiptReuse: selectedResource?.receiptReuse ?? { reusableCount: 0, appliedCount: 0 },
+      estimate: selectedResource?.estimate ?? {
+        calls: 0,
+        inputTokens: 0,
+        outputTokens: 0,
+        totalTokens: 0,
+        elapsedMs: 0,
+        cost: { status: "unknown", knownSubtotalUsd: 0, unknownResources: [] },
+      },
+      resources: [...(selectedResource?.resources ?? [])],
+    },
+    dominantGap: {
+      code: inspected.recovery.nextAllowedAction,
+      reasons: [...reasons],
+    },
+    nextAllowedAction: inspected.recovery.nextAllowedAction,
+    authorizationGranted: false,
+    gitAuthorization: false,
+    releaseAuthorization: false,
+  };
+}
+
+function value(value) {
+  if (value === null || value === undefined || value === "") return "none";
+  return String(value);
+}
+
+function summaryLines(summary) {
+  const latest = summary.latestIndexedCloseout
+    ? `${summary.latestIndexedCloseout.runId} ${summary.latestIndexedCloseout.decision}`
+    : "none";
+  const visibleHolders = summary.leases.holders.slice(0, 5)
+    .map(holder => `${holder.runId}/${holder.workItemId}`);
+  const holders = visibleHolders.length === 0
+    ? "none"
+    : `${visibleHolders.join(", ")}${summary.leases.holders.length > visibleHolders.length
+      ? ` (+${summary.leases.holders.length - visibleHolders.length} more)`
+      : ""}`;
+  return [
+    `Current execution: ${value(summary.currentExecution.selectedRunId)}`,
+    `Latest indexed closeout: ${latest}`,
+    `Source status: ${summary.source.status}`,
+    `Active leases: ${summary.leases.activeCount}`,
+    `Lease holders: ${holders}`,
+    `Open executions: ${summary.currentExecution.openCount}`,
+    `Evidence: ${summary.evidence.status}`,
+    `Resource preflight: ${summary.resourcePreflight.status}`,
+    `Model estimate: ${summary.resourcePreflight.estimate.calls} calls, ${summary.resourcePreflight.estimate.totalTokens} tokens`,
+    `Model cost: ${summary.resourcePreflight.estimate.cost.status === "known"
+      ? `$${summary.resourcePreflight.estimate.cost.valueUsd}`
+      : "unknown"}`,
+    `Receipt reuse: ${summary.resourcePreflight.receiptReuse.appliedCount}/${summary.resourcePreflight.receiptReuse.reusableCount}`,
+    `Dominant gap: ${summary.dominantGap.code}`,
+    `Next allowed action: ${summary.nextAllowedAction}`,
+    `Release authorization: ${summary.releaseAuthorization}`,
+  ].map(escapeHumanControls);
+}
+
+function formatHistory(inspected) {
+  const closed = inspected.executions.filter(execution => execution.lifecycle === "closed");
+  return [
+    "Indexed closeout history",
+    ...(closed.length === 0
+      ? ["none"]
+      : closed.map(execution => [
+          execution.runId,
+          execution.closeout?.decision ?? "invalid",
+          execution.recovery?.evidenceTrustLevel ?? "invalid",
+        ].join("  "))),
+    "Release authorization: false",
+  ].map(escapeHumanControls).join("\n");
+}
+
+function formatExecution(execution) {
+  const recovery = execution.recovery ?? {};
+  const holders = recovery.lease?.activeWorkItemIds ?? [];
+  const issues = recovery.issues ?? [];
+  return [
+    `Execution: ${execution.runId}`,
+    `Lifecycle: ${execution.lifecycle}`,
+    `Engine pin: ${execution.enginePin?.status ?? "invalid"}`,
+    `Lease state: ${recovery.lease?.status ?? "none"}`,
+    `Lease holders: ${holders.length > 0 ? holders.join(", ") : "none"}`,
+    `Source status: ${recovery.delivery?.status ?? "none"}`,
+    `Evidence: ${recovery.verification?.status ?? "none"}`,
+    `Trust level: ${recovery.evidenceTrustLevel ?? "invalid"}`,
+    `Next allowed action: ${recovery.nextAllowedAction ?? "repair_execution_artifacts"}`,
+    `Issues: ${issues.length > 0 ? issues.join(" | ") : "none"}`,
+    "Release authorization: false",
+  ].map(escapeHumanControls).join("\n");
+}
+
+export function formatInspectHuman(inspected) {
+  if (inspected.view?.mode === "history") return `${formatHistory(inspected)}\n`;
+  if (inspected.view?.mode === "execution") return `${formatExecution(inspected.view.execution)}\n`;
+  return `${summaryLines(inspected.summary).join("\n")}\n`;
+}

package/scripts/runkit-contract/install-codex-skill.mjs

@@ -0,0 +1,239 @@
+#!/usr/bin/env node
+
+import { createHash } from "node:crypto";
+import {
+  cp,
+  lstat,
+  mkdir,
+  mkdtemp,
+  readFile,
+  readdir,
+  rename,
+  rm,
+  writeFile,
+} from "node:fs/promises";
+import path from "node:path";
+
+import { isDirectExecution } from "./core-contract.mjs";
+
+const MANIFEST_FILE = ".owlcoda-install-manifest.json";
+
+function sha256(value) {
+  return createHash("sha256").update(value).digest("hex");
+}
+
+async function exists(filePath) {
+  try {
+    await lstat(filePath);
+    return true;
+  } catch (error) {
+    if (error?.code === "ENOENT") return false;
+    throw error;
+  }
+}
+
+async function fileMap(root, { excludeManifest = true } = {}) {
+  const files = {};
+  async function walk(directory, prefix = "") {
+    const entries = await readdir(directory, { withFileTypes: true });
+    entries.sort((left, right) => left.name < right.name ? -1 : left.name > right.name ? 1 : 0);
+    for (const entry of entries) {
+      const relativePath = prefix ? `${prefix}/${entry.name}` : entry.name;
+      if (excludeManifest && relativePath === MANIFEST_FILE) continue;
+      const absolutePath = path.join(directory, entry.name);
+      if (entry.isDirectory()) await walk(absolutePath, relativePath);
+      else if (entry.isFile()) files[relativePath] = sha256(await readFile(absolutePath));
+      else throw new Error(`unsupported_skill_entry:${relativePath}`);
+    }
+  }
+  await walk(root);
+  return files;
+}
+
+function contentSha256(files) {
+  const stream = Object.entries(files).map(([name, hash]) => `${name}\tsha256:${hash}\n`).join("");
+  return sha256(stream);
+}
+
+async function buildManifest(root, repositoryRoot) {
+  const wholeFileSha256 = await fileMap(root);
+  const manifestSha256 = contentSha256(wholeFileSha256);
+  return {
+    schemaVersion: "OwlCodaRunKitSkillInstallManifestV1",
+    skillName: "owlcoda-runkit",
+    manifestSha256: `sha256:${manifestSha256}`,
+    sourceRef: `artifact:sha256:${manifestSha256}`,
+    sourceRepository: path.resolve(repositoryRoot),
+    fileCount: Object.keys(wholeFileSha256).length,
+    wholeFileSha256,
+  };
+}
+
+async function replaceManifestAtomically(targetRoot, manifest) {
+  const temporaryRoot = await mkdtemp(path.join(path.dirname(targetRoot), ".owlcoda-runkit.manifest-"));
+  try {
+    const temporaryManifest = path.join(temporaryRoot, MANIFEST_FILE);
+    await writeFile(temporaryManifest, `${JSON.stringify(manifest, null, 2)}\n`, { flag: "wx" });
+    await rename(temporaryManifest, path.join(targetRoot, MANIFEST_FILE));
+  } finally {
+    await rm(temporaryRoot, { recursive: true, force: true });
+  }
+}
+
+async function assemble({ repositoryRoot, stagingRoot }) {
+  const skillSource = path.join(repositoryRoot, "integrations/codex/skills/owlcoda-runkit");
+  const coreSource = path.join(repositoryRoot, "scripts/runkit-contract");
+  const attestSource = path.join(repositoryRoot, "packages/attest");
+  const contractV01Source = path.join(repositoryRoot, "docs/architecture/OWLCODA_RUN_KIT_CONTRACT_V0_1.md");
+  const contractV02Source = path.join(repositoryRoot, "docs/architecture/OWLCODA_RUN_KIT_CONTRACT_V0_2.md");
+  for (const required of [path.join(skillSource, "SKILL.md"), path.join(skillSource, "agents/openai.yaml"), coreSource, attestSource, contractV01Source, contractV02Source]) {
+    if (!await exists(required)) throw new Error(`missing_authoritative_skill_source:${required}`);
+  }
+  await cp(skillSource, stagingRoot, { recursive: true });
+  await mkdir(path.join(stagingRoot, "scripts"), { recursive: true });
+  await cp(coreSource, path.join(stagingRoot, "scripts/runkit-contract"), { recursive: true });
+  await mkdir(path.join(stagingRoot, "packages"), { recursive: true });
+  await cp(attestSource, path.join(stagingRoot, "packages/attest"), { recursive: true });
+  await mkdir(path.join(stagingRoot, "references"), { recursive: true });
+  await cp(contractV01Source, path.join(stagingRoot, "references/contract-v0.1.md"));
+  await cp(contractV02Source, path.join(stagingRoot, "references/contract-v0.2.md"));
+  const manifest = await buildManifest(stagingRoot, repositoryRoot);
+  await writeFile(path.join(stagingRoot, MANIFEST_FILE), `${JSON.stringify(manifest, null, 2)}\n`, { flag: "wx" });
+  return manifest;
+}
+
+export async function inspectInstalledSkill({ targetRoot } = {}) {
+  if (typeof targetRoot !== "string" || targetRoot.length === 0) throw new Error("targetRoot is required");
+  if (!await exists(targetRoot)) return { status: "missing", valid: false };
+  const manifestPath = path.join(targetRoot, MANIFEST_FILE);
+  if (!await exists(manifestPath)) {
+    const wholeFileSha256 = await fileMap(targetRoot);
+    return {
+      status: "unmanaged",
+      valid: false,
+      manifestSha256: `sha256:${contentSha256(wholeFileSha256)}`,
+      wholeFileSha256,
+    };
+  }
+  let manifest;
+  try {
+    manifest = JSON.parse(await readFile(manifestPath, "utf8"));
+  } catch {
+    return { status: "drifted", valid: false, issues: ["invalid install manifest"] };
+  }
+  const actualFiles = await fileMap(targetRoot);
+  const actualSha256 = `sha256:${contentSha256(actualFiles)}`;
+  const issues = [];
+  if (manifest.schemaVersion !== "OwlCodaRunKitSkillInstallManifestV1") issues.push("unsupported install manifest schema");
+  if (manifest.manifestSha256 !== actualSha256) issues.push("installed_skill_drift: content fingerprint mismatch");
+  if (JSON.stringify(manifest.wholeFileSha256) !== JSON.stringify(actualFiles)) issues.push("installed_skill_drift: file map mismatch");
+  return {
+    status: issues.length === 0 ? "valid" : "drifted",
+    valid: issues.length === 0,
+    manifestSha256: actualSha256,
+    wholeFileSha256: actualFiles,
+    manifest,
+    issues,
+  };
+}
+
+export async function installCodexSkill({
+  repositoryRoot,
+  targetRoot,
+  archiveRoot,
+  expectedUnmanagedManifestSha256 = null,
+} = {}) {
+  if (typeof repositoryRoot !== "string" || typeof targetRoot !== "string" || typeof archiveRoot !== "string") {
+    throw new Error("repositoryRoot, targetRoot, and archiveRoot are required");
+  }
+  const parent = path.dirname(targetRoot);
+  await mkdir(parent, { recursive: true });
+  const stagingRoot = await mkdtemp(path.join(parent, ".owlcoda-runkit.install-"));
+  let stagingPresent = true;
+  try {
+    const desired = await assemble({ repositoryRoot: path.resolve(repositoryRoot), stagingRoot });
+    let prior = await inspectInstalledSkill({ targetRoot });
+    if (prior.status === "missing") {
+      await rename(stagingRoot, targetRoot);
+      stagingPresent = false;
+      return { status: "installed", manifestSha256: desired.manifestSha256, previousInstallation: null };
+    }
+    if (prior.status === "unmanaged") {
+      if (prior.manifestSha256 === desired.manifestSha256) {
+        await writeFile(path.join(targetRoot, MANIFEST_FILE), `${JSON.stringify(desired, null, 2)}\n`, { flag: "wx" });
+        return { status: "adopted", manifestSha256: desired.manifestSha256, previousInstallation: null };
+      }
+      if (prior.manifestSha256 !== expectedUnmanagedManifestSha256) {
+        throw new Error("installed_skill_drift: unmanaged installation differs from authoritative source and expected prior manifest");
+      }
+      prior = { ...prior, valid: true };
+    }
+    if (!prior.valid) throw new Error(`installed_skill_drift: ${prior.issues.join("; ")}`);
+    if (prior.manifestSha256 === desired.manifestSha256) {
+      if (prior.manifest.sourceRepository !== desired.sourceRepository) {
+        await replaceManifestAtomically(targetRoot, desired);
+        return { status: "provenance_updated", manifestSha256: desired.manifestSha256, previousInstallation: null };
+      }
+      return { status: "unchanged", manifestSha256: desired.manifestSha256, previousInstallation: null };
+    }
+
+    await mkdir(archiveRoot, { recursive: true });
+    const archivePath = path.join(archiveRoot, `owlcoda-runkit-${prior.manifestSha256.slice(7)}`);
+    if (await exists(archivePath)) throw new Error(`archive_already_exists:${archivePath}`);
+    await rename(targetRoot, archivePath);
+    try {
+      await rename(stagingRoot, targetRoot);
+      stagingPresent = false;
+    } catch (error) {
+      await rename(archivePath, targetRoot);
+      throw error;
+    }
+    return {
+      status: "updated",
+      manifestSha256: desired.manifestSha256,
+      previousInstallation: { manifestSha256: prior.manifestSha256, archivePath },
+    };
+  } finally {
+    if (stagingPresent) await rm(stagingRoot, { recursive: true, force: true });
+  }
+}
+
+function parseOptions(values) {
+  const options = {};
+  for (let index = 0; index < values.length; index += 2) {
+    const flag = values[index];
+    const value = values[index + 1];
+    if (!flag?.startsWith("--") || value === undefined) throw new Error("Options must be --name value pairs");
+    options[flag.slice(2)] = value;
+  }
+  return options;
+}
+
+export async function runCli(argv = process.argv.slice(2)) {
+  try {
+    const [command, ...rest] = argv;
+    const options = parseOptions(rest);
+    if (command === "install") {
+      const output = await installCodexSkill({
+        repositoryRoot: options.repository,
+        targetRoot: options.target,
+        archiveRoot: options.archive,
+        expectedUnmanagedManifestSha256: options["expected-unmanaged"] ?? null,
+      });
+      return { exitCode: 0, ...output };
+    }
+    if (command === "inspect") {
+      const output = await inspectInstalledSkill({ targetRoot: options.target });
+      return { exitCode: output.valid ? 0 : 2, ...output };
+    }
+    throw new Error("Usage: install-codex-skill.mjs <install|inspect> [options]");
+  } catch (error) {
+    return { status: "invalid_input", exitCode: 3, issues: [error instanceof Error ? error.message : String(error)] };
+  }
+}
+
+if (isDirectExecution(import.meta.url)) {
+  const result = await runCli();
+  process.stdout.write(`${JSON.stringify(result)}\n`);
+  process.exitCode = result.exitCode;
+}