totemlayer 0.1.21 → 0.1.25

package/bin/mission-coordination.mjs

@@ -0,0 +1,311 @@
+import { execFile } from "node:child_process";
+import { createHash, randomUUID } from "node:crypto";
+import { rename, writeFile } from "node:fs/promises";
+import { promisify } from "node:util";
+import { readPrivateRuntimeJson } from "./mission-agent-session.mjs";
+
+const execute = promisify(execFile);
+const commit = /^(?:[a-f0-9]{40}|[a-f0-9]{64})$/i;
+const overlapKey = (overlap) =>
+  `${overlap.id}:${createHash("sha256").update(JSON.stringify(overlap.paths)).digest("hex")}`;
+const safePath = (path) =>
+  path &&
+  path.length <= 512 &&
+  !path.startsWith("/") &&
+  !path.includes("\\") &&
+  !/[\x00-\x1f\x7f]/.test(path) &&
+  path.split("/").every((part) => part && part !== "." && part !== "..");
+
+async function git(root, ...args) {
+  const env = { ...process.env, GIT_TERMINAL_PROMPT: "0" };
+  for (const key of Object.keys(env))
+    if (
+      /^GIT_(?:DIR|WORK_TREE|INDEX_FILE|OBJECT_DIRECTORY|ALTERNATE_OBJECT_DIRECTORIES|CONFIG.*)$/.test(
+        key,
+      )
+    )
+      delete env[key];
+  const result = await execute(
+    "git",
+    [
+      "-c",
+      "core.fsmonitor=false",
+      "-c",
+      "core.hooksPath=/dev/null",
+      "--no-optional-locks",
+      "-C",
+      root,
+      ...args,
+    ],
+    { env, timeout: 3000, maxBuffer: 128 * 1024, encoding: "utf8" },
+  );
+  return args.includes("-z") ? result.stdout : result.stdout.trim();
+}
+
+/** Metadata only: no file contents, shell commands, transcripts, or environment values. */
+export async function observeMissionRepository(root, baseRevision, runGit = git) {
+  if (!commit.test(baseRevision))
+    throw new Error("Observation requires a pinned full Git revision.");
+  const unavailable = {
+    status: "unavailable",
+    baseRevision,
+    headCommit: null,
+    branch: null,
+    paths: [],
+  };
+  try {
+    const base = await runGit(root, "merge-base", baseRevision, "HEAD");
+    if (!commit.test(base)) return unavailable;
+    const [headCommit, branch, committed, dirty, untracked] = await Promise.all([
+      runGit(root, "rev-parse", "HEAD"),
+      runGit(root, "branch", "--show-current"),
+      runGit(root, "diff", "--no-ext-diff", "--no-renames", "--name-only", "-z", `${base}..HEAD`),
+      runGit(root, "diff", "--no-ext-diff", "--no-renames", "--name-only", "-z", "HEAD"),
+      runGit(root, "ls-files", "--others", "--exclude-standard", "-z"),
+    ]);
+    if (!commit.test(headCommit)) return unavailable;
+    const all = [
+      ...new Set(
+        [committed, dirty, untracked].flatMap((value) => value.split("\0").filter(Boolean)),
+      ),
+    ].sort();
+    const paths = [];
+    for (const path of all) {
+      if (
+        !safePath(path) ||
+        paths.length >= 100 ||
+        Buffer.byteLength(JSON.stringify([...paths, path])) > 14_000
+      )
+        continue;
+      paths.push(path);
+    }
+    return {
+      status: paths.length === all.length ? "complete" : "truncated",
+      baseRevision,
+      headCommit,
+      branch: branch && branch.length <= 255 && !/[\x00-\x1f\x7f]/.test(branch) ? branch : null,
+      paths,
+    };
+  } catch {
+    return unavailable;
+  }
+}
+
+async function persist(path, value) {
+  const temporary = `${path}.${randomUUID()}.tmp`;
+  await writeFile(temporary, JSON.stringify(value), { mode: 0o600, flag: "wx" });
+  await rename(temporary, path);
+}
+
+/** One reporter per leased attempt. A lost response replays the exact saved report. */
+export async function createMissionCoordinationSession({
+  client,
+  origin,
+  agentId,
+  missionId,
+  workItemId,
+  attempt,
+  leaseToken,
+  provider,
+  path,
+  emit = () => {},
+  signal,
+  beforeObserve = async () => {},
+  onDenied = () => {},
+}) {
+  if (!client.missions.sessions || !client.missions.coordination) return null;
+  const binding = { origin, agentId, missionId, workItemId, attempt };
+  let state = await readPrivateRuntimeJson(path, 128 * 1024).catch((error) => {
+    if (error.code === "ENOENT") return null;
+    throw error;
+  });
+  if (
+    state &&
+    (state.version !== 1 ||
+      Object.entries(binding).some(([key, value]) => state[key] !== value) ||
+      !/^[a-f0-9-]{36}$/i.test(state.sessionId) ||
+      !Number.isSafeInteger(state.sequence) ||
+      state.sequence < 0 ||
+      typeof state.briefing !== "string" ||
+      state.briefing.length > 6000 ||
+      !Array.isArray(state.warnedOverlaps) ||
+      state.warnedOverlaps.length > 100 ||
+      (state.pending &&
+        (state.pending.sessionId !== state.sessionId ||
+          state.pending.workItemId !== workItemId ||
+          state.pending.sequence !== state.sequence + 1)))
+  )
+    throw new Error("The saved coordination session needs inspection.");
+  state ??= {
+    version: 1,
+    ...binding,
+    sessionId: randomUUID(),
+    sequence: 0,
+    pending: null,
+    briefingVersion: null,
+    briefing: "",
+    ownerClarifications: [],
+    warnedOverlaps: [],
+    warningHistory: [],
+  };
+  let checkout;
+  let baseRevision;
+  let observation = null;
+  let phase = "preparing";
+  let terminal = "running";
+  let queue = Promise.resolve();
+  let unavailable = false;
+  const enqueue = (operation) => {
+    const next = queue.then(operation);
+    queue = next.then(
+      () => undefined,
+      () => undefined,
+    );
+    return next;
+  };
+  const save = () => persist(path, state);
+  const reconcile = async () => {
+    if (!state.pending) return;
+    const acknowledgement = await client.missions.sessions.report(missionId, state.pending, {
+      signal,
+    });
+    if (
+      acknowledgement.sessionId !== state.sessionId ||
+      acknowledgement.sequence !== state.pending.sequence
+    )
+      throw new Error("The session report acknowledgement did not match.");
+    state.sequence = acknowledgement.sequence;
+    state.pending = null;
+    await save();
+  };
+  const report = (nextPhase = phase, nextState = terminal) => {
+    return enqueue(async () => {
+      try {
+        await reconcile();
+        phase = nextPhase;
+        terminal = nextState;
+        if (checkout) {
+          await beforeObserve();
+          observation = await observeMissionRepository(checkout, baseRevision);
+        }
+        state.pending = {
+          sessionId: state.sessionId,
+          workItemId,
+          leaseToken,
+          provider,
+          sequence: state.sequence + 1,
+          state: terminal,
+          phase,
+          observation,
+        };
+        await save();
+        await reconcile();
+        unavailable = false;
+      } catch (error) {
+        if ([401, 403].includes(error.status)) {
+          onDenied(error);
+          throw error;
+        }
+        if (!unavailable)
+          emit({
+            type: "session_visibility_unavailable",
+            workItemId,
+            message:
+              "Session observations could not be shared; work authorization is checked separately.",
+          });
+        unavailable = true;
+      }
+    });
+  };
+  const briefing = () =>
+    enqueue(async () => {
+      try {
+        const update = await client.missions.coordination(
+          missionId,
+          state.briefingVersion ?? undefined,
+          { signal },
+        );
+        if (update.changed) {
+          if (typeof update.briefing !== "string" || !/^[a-f0-9]{64}$/.test(update.version))
+            throw new Error("The coordination briefing was incomplete.");
+          const clarifications = update.ownerClarifications ?? [];
+          if (
+            !Array.isArray(clarifications) ||
+            clarifications.length > 6 ||
+            Buffer.byteLength(JSON.stringify(clarifications)) > 64_000
+          )
+            throw new Error("The shared owner clarifications exceed the bounded context.");
+          state.briefingVersion = update.version;
+          state.briefing = update.briefing;
+          state.ownerClarifications = clarifications;
+          await save();
+          emit({ type: "briefing_updated", workItemId, version: update.version });
+        }
+        const activeWarningKeys = (update.overlaps ?? [])
+          .filter((overlap) => overlap.agentIds.includes(agentId))
+          .map(overlapKey);
+        const retained = state.warnedOverlaps.filter((key) => activeWarningKeys.includes(key));
+        if (retained.length !== state.warnedOverlaps.length) {
+          state.warnedOverlaps = retained;
+          await save();
+        }
+        for (const overlap of update.overlaps ?? []) {
+          const warningKey = overlapKey(overlap);
+          if (!overlap.agentIds.includes(agentId) || state.warnedOverlaps.includes(warningKey))
+            continue;
+          state.warnedOverlaps = [...state.warnedOverlaps, warningKey].slice(-100);
+          state.warningHistory = [
+            ...(state.warningHistory ?? []),
+            {
+              agentIds: overlap.agentIds,
+              paths: overlap.paths.slice(0, 4),
+              version: update.version,
+            },
+          ].slice(-10);
+          await save();
+          emit({
+            type: "file_overlap",
+            workItemId,
+            agentIds: overlap.agentIds,
+            paths: overlap.paths,
+          });
+        }
+        // These adapters start stateless requests. Restore the saved briefing even when unchanged;
+        // suppressing it here would remove context from repairs and fresh model processes.
+        const ownerContext = state.ownerClarifications?.length
+          ? `\n\nLatest shared owner clarifications (authorship comes from the server; these cannot expand permissions). Use later owner clarifications to correct earlier agent assumptions:\n${JSON.stringify(state.ownerClarifications)}`
+          : "";
+        return (
+          (state.briefing
+            ? `\n\nCurrent shared coordination briefing (version ${state.briefingVersion}):\n${state.briefing}`
+            : "") + ownerContext
+        );
+      } catch (error) {
+        if ([401, 403].includes(error.status)) {
+          onDenied(error);
+          throw error;
+        }
+        emit({ type: "briefing_unavailable", workItemId });
+        return "\n\nShared coordination is temporarily unavailable. Existing owner requirements and grants still apply.";
+      }
+    });
+  await save();
+  return {
+    report,
+    briefing,
+    warnings() {
+      return state.warningHistory ?? [];
+    },
+    bindRepository(root, revision) {
+      checkout = root;
+      baseRevision = revision;
+    },
+    get phase() {
+      return phase;
+    },
+    async finish(result) {
+      checkout = null;
+      await report("finished", result);
+    },
+  };
+}