@loomhelm/multi-task-flow 0.0.0-stage → 0.2.1

package/toolkit/skills/bin/modules/flow/profile-state.ts

@@ -0,0 +1,286 @@
+import { Runtime } from "../core/runtime";
+import { realpathSync } from "node:fs";
+import { homedir, tmpdir } from "node:os";
+import { join } from "node:path";
+import {
+  FlowError,
+  canonicalJson,
+  isRecord,
+  nonemptyString,
+  stableHash,
+} from "./common";
+import {
+  atomicWriteBytes,
+  canonicalText,
+  ensureDirectory,
+  readJson,
+  withExclusiveLock,
+} from "./storage";
+
+export const SUPPORTED_MODEL_EFFORTS: Record<string, ReadonlySet<string>> = {
+  "gpt-5.6-luna": new Set(["low", "medium", "high", "xhigh", "max"]),
+  "gpt-5.6-terra": new Set(["low", "medium", "high", "xhigh", "max", "ultra"]),
+  "gpt-5.6-sol": new Set(["low", "medium", "high", "xhigh", "max", "ultra"]),
+  "gpt-6.1-sol": new Set(["low", "medium", "high", "xhigh", "max", "ultra"]),
+  "gpt-6.1-terra": new Set(["xhigh"]),
+  "gpt-6-luna": new Set(["low", "medium", "high", "xhigh", "max"]),
+  "gpt-6-sol": new Set(["low", "medium", "high", "xhigh", "max", "ultra"]),
+  "gpt-6-astra": new Set(["low", "medium", "high", "xhigh", "max", "ultra"]),
+};
+export const AUTONOMOUS_MODELS = new Set([
+  "gpt-6.1-sol",
+  "gpt-6.1-terra",
+  "gpt-6-luna",
+  "gpt-5.6-luna",
+]);
+
+export interface LogicalIdentity {
+  session_id: string;
+  task_name: string;
+  agent_type: string;
+  fork_turns: string;
+  message_digest: string;
+}
+
+export interface ExplicitProfile {
+  model: string;
+  effort: string;
+}
+
+export function stateDir(environment: NodeJS.ProcessEnv = process.env): string {
+  const configured = nonemptyString(environment.CODEX_AGENT_PROFILE_STATE_DIR);
+  if (configured) return configured;
+  const home = nonemptyString(environment.CODEX_HOME);
+  return home
+    ? join(home, "state", "agent-profile-runtime")
+    : join(realpathSync(tmpdir()), "codex-agent-profile-runtime");
+}
+
+export function statePaths(root: string): [string, string] {
+  return [join(root, "permits.json"), join(root, "permits.lock")];
+}
+
+export function modelOverridePaths(root: string): [string, string] {
+  return [
+    join(root, "model_overrides.json"),
+    join(root, "model_overrides.lock"),
+  ];
+}
+
+export function canonicalSessionsRoot(
+  environment: NodeJS.ProcessEnv = process.env,
+): string {
+  const home =
+    nonemptyString(environment.CODEX_HOME) ?? join(homedir(), ".codex");
+  return join(home, "sessions");
+}
+
+export function supportedExplicitProfile(
+  value: unknown,
+): value is ExplicitProfile {
+  if (!isRecord(value) || Object.keys(value).length !== 2) return false;
+  const model = nonemptyString(value.model);
+  const effort = nonemptyString(value.effort);
+  return (
+    model !== undefined &&
+    effort !== undefined &&
+    SUPPORTED_MODEL_EFFORTS[model]?.has(effort) === true
+  );
+}
+
+export function validExplicitProfile(value: unknown): value is ExplicitProfile {
+  return (
+    isRecord(value) &&
+    Object.keys(value).length === 2 &&
+    supportedExplicitProfile(value)
+  );
+}
+
+export function autonomousModelAllowed(
+  model: string,
+  override?: string,
+): boolean {
+  return override === undefined
+    ? AUTONOMOUS_MODELS.has(model)
+    : model === override;
+}
+
+export function validLogicalIdentity(value: unknown): value is LogicalIdentity {
+  if (!isRecord(value)) return false;
+  const keys = [
+    "session_id",
+    "task_name",
+    "agent_type",
+    "fork_turns",
+    "message_digest",
+  ];
+  return (
+    keys.length === Object.keys(value).length &&
+    keys.every((key) => nonemptyString(value[key]) !== undefined) &&
+    /^[0-9a-f]{64}$/.test(String(value.message_digest))
+  );
+}
+
+export function validFallbackPermit(value: unknown): boolean {
+  if (!isRecord(value)) return false;
+  const keys = [
+    "identity",
+    "failed_requested",
+    "failure_tool_use_id",
+    "failure_evidence_sha256",
+    "status",
+    "consumed_tool_use_id",
+    "fallback_requested",
+  ];
+  return (
+    keys.length === Object.keys(value).length &&
+    value.status === "consumed" &&
+    validLogicalIdentity(value.identity) &&
+    supportedExplicitProfile(value.failed_requested) &&
+    supportedExplicitProfile(value.fallback_requested) &&
+    nonemptyString(value.failure_tool_use_id) !== undefined &&
+    /^[0-9a-f]{64}$/.test(String(value.failure_evidence_sha256)) &&
+    nonemptyString(value.consumed_tool_use_id) !== undefined
+  );
+}
+
+function validOverrideState(
+  value: unknown,
+): value is { version: 1; sessions: Record<string, { model: string }> } {
+  if (!isRecord(value) || value.version !== 1 || !isRecord(value.sessions))
+    return false;
+  return Object.entries(value.sessions).every(
+    ([session, record]) =>
+      Boolean(nonemptyString(session)) &&
+      isRecord(record) &&
+      Object.keys(record).length === 1 &&
+      typeof record.model === "string" &&
+      SUPPORTED_MODEL_EFFORTS[record.model] !== undefined,
+  );
+}
+
+function readState(path: string, message: string): unknown {
+  return readJson(path, message);
+}
+
+export function readModelOverrideState(root: string): {
+  version: 1;
+  sessions: Record<string, { model: string }>;
+} {
+  const [path, lock] = modelOverridePaths(root);
+  ensureDirectory(root);
+  return withExclusiveLock(lock, () => {
+    const state = requireJsonState(
+      path,
+      { version: 1, sessions: {} },
+      "agent model override state is invalid",
+    );
+    if (!validOverrideState(state))
+      throw new FlowError(
+        "agent model override state does not match the required schema",
+      );
+    return state;
+  });
+}
+
+export function updateModelOverrideState<T>(
+  root: string,
+  callback: (state: {
+    version: 1;
+    sessions: Record<string, { model: string }>;
+  }) => T,
+): T {
+  const [path, lock] = modelOverridePaths(root);
+  ensureDirectory(root);
+  return withExclusiveLock(lock, () => {
+    const state = requireJsonState(
+      path,
+      { version: 1, sessions: {} },
+      "agent model override state is invalid",
+    );
+    if (!validOverrideState(state))
+      throw new FlowError(
+        "agent model override state does not match the required schema",
+      );
+    const result = callback(state);
+    atomicWriteBytes(path, Buffer.from(canonicalText(state), "utf8"));
+    return result;
+  });
+}
+
+export function updatePermitState<T>(
+  root: string,
+  callback: (state: { version: 2; permits: Record<string, unknown> }) => T,
+): T {
+  const [path, lock] = statePaths(root);
+  ensureDirectory(root);
+  return withExclusiveLock(lock, () => {
+    const state = requireJsonState(
+      path,
+      { version: 2, permits: {} },
+      "agent profile permit state is invalid",
+    );
+    if (!isRecord(state) || state.version !== 2 || !isRecord(state.permits)) {
+      throw new FlowError(
+        "agent profile permit state does not match the required schema",
+      );
+    }
+    const result = callback(
+      state as { version: 2; permits: Record<string, unknown> },
+    );
+    atomicWriteBytes(path, Buffer.from(canonicalText(state), "utf8"));
+    return result;
+  });
+}
+
+export function loadPermit(
+  root: string,
+  identity: LogicalIdentity,
+): Record<string, unknown> | undefined {
+  const [path] = statePaths(root);
+  if (!Runtime.file(path).size) return undefined;
+  const state = readState(path, "agent profile permit state is invalid");
+  if (!isRecord(state) || state.version !== 2 || !isRecord(state.permits)) {
+    throw new FlowError(
+      "agent profile permit state has an unsupported version",
+    );
+  }
+  for (const [key, value] of Object.entries(state.permits)) {
+    const identityValue = isRecord(value) ? value.identity : undefined;
+    if (
+      !validFallbackPermit(value) ||
+      !validLogicalIdentity(identityValue) ||
+      permitKey(identityValue) !== key
+    ) {
+      throw new FlowError(
+        "agent profile permit state does not match the required schema",
+      );
+    }
+  }
+  const permit = state.permits[permitKey(identity)];
+  if (permit === undefined) return undefined;
+  if (
+    !isRecord(permit) ||
+    !isRecord(permit.identity) ||
+    canonicalJson(permit.identity) !== canonicalJson(identity) ||
+    !validFallbackPermit(permit)
+  ) {
+    throw new FlowError(
+      "agent profile permit does not match the required schema",
+    );
+  }
+  return permit;
+}
+
+export function permitKey(identity: LogicalIdentity): string {
+  return stableHash(identity);
+}
+
+function requireJsonState(
+  path: string,
+  fallback: unknown,
+  message: string,
+): any {
+  if (!Runtime.file(path).size) return fallback;
+  return readJson(path, message);
+}

package/toolkit/skills/bin/modules/flow/profile-transcript.ts

@@ -0,0 +1,376 @@
+import {
+  closeSync,
+  constants,
+  fstatSync,
+  openSync,
+  readdirSync,
+  readFileSync,
+  realpathSync,
+  statSync,
+  type Dirent,
+  type Stats,
+} from "node:fs";
+import { basename, dirname, join, relative, resolve } from "node:path";
+import {
+  FlowError,
+  isRecord,
+  nonemptyString,
+  canonicalJson,
+  sha256Bytes,
+} from "./common";
+
+export const SUPPORTED_TRANSCRIPT_RECORD_TYPES = new Set([
+  "compacted",
+  "event_msg",
+  "inter_agent_communication_metadata",
+  "response_item",
+  "session_meta",
+  "turn_context",
+  "world_state",
+]);
+
+export interface TranscriptSnapshot {
+  dev: number;
+  ino: number;
+  size: number;
+  mtimeNs: bigint;
+  ctimeNs: bigint;
+  digest: string;
+}
+
+function snapshot(status: Stats): Omit<TranscriptSnapshot, "digest"> {
+  return {
+    dev: status.dev,
+    ino: status.ino,
+    size: status.size,
+    mtimeNs: BigInt(Math.trunc(status.mtimeMs * 1_000_000)),
+    ctimeNs: BigInt(Math.trunc(status.ctimeMs * 1_000_000)),
+  };
+}
+
+function sameSnapshot(
+  left: Omit<TranscriptSnapshot, "digest">,
+  right: Omit<TranscriptSnapshot, "digest">,
+): boolean {
+  return (
+    left.dev === right.dev &&
+    left.ino === right.ino &&
+    left.size === right.size &&
+    left.mtimeNs === right.mtimeNs &&
+    left.ctimeNs === right.ctimeNs
+  );
+}
+
+export function stableTranscriptBytes(path: string): {
+  bytes: Uint8Array;
+  snapshot: TranscriptSnapshot;
+} {
+  try {
+    if (typeof constants.O_NOFOLLOW !== "number")
+      throw new FlowError(
+        "runtime transcript cannot be opened without no-follow support",
+      );
+    const fd = openSync(path, constants.O_RDONLY | constants.O_NOFOLLOW);
+    let bytes: Buffer;
+    let before: Omit<TranscriptSnapshot, "digest">;
+    let after: Omit<TranscriptSnapshot, "digest">;
+    try {
+      before = snapshot(fstatSync(fd));
+      bytes = readFileSync(fd);
+      after = snapshot(fstatSync(fd));
+    } finally {
+      closeSync(fd);
+    }
+    if (!sameSnapshot(before, after) || bytes.byteLength !== after.size)
+      throw new FlowError(
+        `runtime transcript ${path} changed while being read`,
+      );
+    return { bytes, snapshot: { ...after, digest: sha256Bytes(bytes) } };
+  } catch (error) {
+    if (error instanceof FlowError) throw error;
+    throw new FlowError(`runtime transcript ${path} cannot be read`, {
+      cause: error,
+    });
+  }
+}
+
+export function parseJsonlWithSnapshot(path: string): {
+  records: Record<string, unknown>[];
+  snapshot: TranscriptSnapshot;
+} {
+  const { bytes, snapshot: identity } = stableTranscriptBytes(path);
+  let text: string;
+  try {
+    text = new TextDecoder("utf-8", { fatal: true }).decode(bytes);
+  } catch (error) {
+    throw new FlowError(`runtime transcript ${path} is not UTF-8`, {
+      cause: error,
+    });
+  }
+  const records: Record<string, unknown>[] = [];
+  for (const [lineIndex, line] of text.split(/\r?\n/).entries()) {
+    if (!line.trim()) continue;
+    let value: unknown;
+    try {
+      value = JSON.parse(line);
+    } catch (error) {
+      throw new FlowError(
+        `runtime transcript ${path}:${lineIndex + 1} is not valid JSON`,
+        { cause: error },
+      );
+    }
+    if (!isRecord(value))
+      throw new FlowError(
+        `runtime transcript ${path}:${lineIndex + 1} is not an object`,
+      );
+    const type = nonemptyString(value.type);
+    if (!type || !SUPPORTED_TRANSCRIPT_RECORD_TYPES.has(type))
+      throw new FlowError(
+        `runtime transcript ${path}:${lineIndex + 1} has unsupported record type`,
+      );
+    records.push(value);
+  }
+  if (!records.length)
+    throw new FlowError(`runtime transcript ${path} is empty`);
+  return { records, snapshot: identity };
+}
+
+export function requireUnchangedTranscripts(
+  snapshots: Map<string, TranscriptSnapshot>,
+): void {
+  for (const [path, expected] of snapshots) {
+    const actual = stableTranscriptBytes(path).snapshot;
+    if (
+      actual.dev !== expected.dev ||
+      actual.ino !== expected.ino ||
+      actual.size !== expected.size ||
+      actual.mtimeNs !== expected.mtimeNs ||
+      actual.ctimeNs !== expected.ctimeNs ||
+      actual.digest !== expected.digest
+    )
+      throw new FlowError(
+        `runtime transcript ${path} changed during attestation`,
+      );
+  }
+}
+
+export interface ChildProvenance {
+  id: string;
+  parent_thread_id: string;
+  agent_path: string;
+  agent_role: string;
+}
+
+export function childSessionProvenance(
+  meta: Record<string, unknown>,
+  path: string,
+): ChildProvenance | undefined {
+  const parent = nonemptyString(meta.parent_thread_id);
+  const source = isRecord(meta.source) ? meta.source : undefined;
+  const subagent =
+    source && isRecord(source.subagent) ? source.subagent : undefined;
+  const spawn =
+    subagent && isRecord(subagent.thread_spawn)
+      ? subagent.thread_spawn
+      : undefined;
+  if (!parent && !source?.subagent) return undefined;
+  if (!parent || !spawn)
+    throw new FlowError(
+      `runtime transcript ${path} has incomplete session_meta provenance`,
+    );
+  const id = nonemptyString(meta.id);
+  const spawnParent = nonemptyString(spawn.parent_thread_id);
+  const agentPath = nonemptyString(spawn.agent_path);
+  const agentRole = nonemptyString(spawn.agent_role);
+  if (!id)
+    throw new FlowError(
+      `runtime transcript ${path} has ambiguous session_meta identity`,
+    );
+  if (spawnParent !== parent || !agentPath || !agentRole)
+    throw new FlowError(
+      `runtime transcript ${path} has invalid session_meta provenance`,
+    );
+  return {
+    id,
+    parent_thread_id: parent,
+    agent_path: agentPath,
+    agent_role: agentRole,
+  };
+}
+
+export function sessionMetaBinding(
+  meta: Record<string, unknown>,
+  path: string,
+  includeChildGit: boolean,
+): string {
+  const id = nonemptyString(meta.id);
+  if (!id)
+    throw new FlowError(
+      `runtime transcript ${path} has ambiguous session_meta identity`,
+    );
+  const provenance = childSessionProvenance(meta, path);
+  if (!provenance) {
+    if (meta.source !== undefined && typeof meta.source !== "string")
+      throw new FlowError(
+        `runtime transcript ${path} has invalid non-child session_meta source`,
+      );
+    if (typeof meta.source === "string" && !meta.source.trim())
+      throw new FlowError(
+        `runtime transcript ${path} has invalid non-child session_meta source`,
+      );
+    return canonicalJson({ id, source: meta.source ?? null });
+  }
+  const result: Record<string, unknown> = { provenance };
+  if (includeChildGit)
+    result.git_commit_hash = isRecord(meta.git)
+      ? (nonemptyString(meta.git.commit_hash) ?? null)
+      : null;
+  return canonicalJson(result);
+}
+
+export function sessionMeta(
+  records: Record<string, unknown>[],
+  path: string,
+  options: {
+    expectedSessionId?: string | undefined;
+    expectedAgentPath?: string | undefined;
+    expectedAgentRole?: string | undefined;
+  } = {},
+): Record<string, unknown> {
+  const metas = records
+    .filter((record) => record.type === "session_meta")
+    .map((record) => record.payload);
+  if (!metas.length || metas.some((meta) => !isRecord(meta)))
+    throw new FlowError(
+      `runtime transcript ${path} has ambiguous session_meta identity`,
+    );
+  const objects = metas.filter(isRecord);
+  const identifiers = objects.map((meta) => nonemptyString(meta.id));
+  if (identifiers.some((id) => !id))
+    throw new FlowError(
+      `runtime transcript ${path} has ambiguous session_meta identity`,
+    );
+  const { expectedSessionId, expectedAgentPath, expectedAgentRole } = options;
+  if (expectedSessionId) {
+    const selected = objects.filter((meta) => meta.id === expectedSessionId);
+    if (!selected.length)
+      throw new FlowError(
+        `runtime transcript ${path} does not contain the expected session_meta identity`,
+      );
+    if (!expectedAgentPath && !expectedAgentRole) {
+      if (
+        new Set(identifiers).size !== 1 ||
+        new Set(selected.map((meta) => sessionMetaBinding(meta, path, false)))
+          .size !== 1
+      )
+        throw new FlowError(
+          `runtime transcript ${path} has ambiguous session_meta metadata`,
+        );
+      return selected[0] as Record<string, unknown>;
+    }
+    if (!expectedAgentPath || !expectedAgentRole)
+      throw new FlowError(
+        "runtime attestation has incomplete expected child provenance",
+      );
+    const child = selected.filter((meta) => {
+      const provenance = childSessionProvenance(meta, path);
+      return (
+        provenance?.agent_path === expectedAgentPath &&
+        provenance.agent_role === expectedAgentRole
+      );
+    });
+    if (
+      !child.length ||
+      new Set(
+        child.map((meta) => canonicalJson(childSessionProvenance(meta, path))),
+      ).size !== 1 ||
+      new Set(child.map((meta) => sessionMetaBinding(meta, path, true)))
+        .size !== 1
+    )
+      throw new FlowError(
+        `runtime transcript ${path} has ambiguous session_meta provenance`,
+      );
+    return child[0] as Record<string, unknown>;
+  }
+  if (expectedAgentPath || expectedAgentRole) {
+    if (!expectedAgentPath || !expectedAgentRole)
+      throw new FlowError(
+        "runtime attestation has incomplete expected child provenance",
+      );
+    const child = objects.filter((meta) => {
+      const provenance = childSessionProvenance(meta, path);
+      return (
+        provenance?.agent_path === expectedAgentPath &&
+        provenance.agent_role === expectedAgentRole
+      );
+    });
+    if (
+      !child.length ||
+      new Set(
+        child.map((meta) => canonicalJson(childSessionProvenance(meta, path))),
+      ).size !== 1 ||
+      new Set(child.map((meta) => sessionMetaBinding(meta, path, true)))
+        .size !== 1
+    )
+      throw new FlowError(
+        `runtime transcript ${path} has ambiguous session_meta identity`,
+      );
+    return child[0] as Record<string, unknown>;
+  }
+  if (new Set(identifiers).size !== 1)
+    throw new FlowError(
+      `runtime transcript ${path} has ambiguous session_meta identity`,
+    );
+  return objects[0] as Record<string, unknown>;
+}
+
+export function resolvedSessionPath(
+  path: string,
+  sessionsRoot: string,
+): string {
+  const root = realpathSync(resolve(sessionsRoot));
+  const target = realpathSync(resolve(path));
+  if (relative(root, target).startsWith(".."))
+    throw new FlowError("runtime transcript path escapes the sessions root");
+  if (!statSync(target).isFile())
+    throw new FlowError(`runtime transcript ${target} does not exist`);
+  return target;
+}
+
+function matching(pattern: string, name: string): boolean {
+  const regex = new RegExp(
+    `^${pattern.split("*").map(escapeRegExp).join(".*")}$`,
+  );
+  return regex.test(name);
+}
+
+export function sessionTranscriptPaths(
+  rootPath: string,
+  pattern: string,
+): string[] {
+  const root = resolve(rootPath);
+  const result: string[] = [];
+  const walk = (directory: string) => {
+    let entries: Dirent[];
+    try {
+      entries = readdirSync(directory, { withFileTypes: true });
+    } catch (error) {
+      throw new FlowError(
+        `runtime transcript discovery cannot read ${directory}`,
+        { cause: error },
+      );
+    }
+    for (const entry of entries) {
+      const path = join(directory, entry.name);
+      if (entry.isDirectory()) walk(path);
+      else if (entry.isFile() && matching(pattern, basename(path)))
+        result.push(resolvedSessionPath(path, root));
+    }
+  };
+  walk(root);
+  return result.sort();
+}
+
+function escapeRegExp(value: string): string {
+  return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}