@workit-dev/core 0.0.1 → 1.0.0

package/src/hooks/repeat-failure.ts

@@ -0,0 +1,115 @@
+// A repeated identical failing Workit call (#435): the second failure in a row
+// of the same tool and args (or the same `workit …` command) in a session ends
+// with one line naming the exact corrected next call, instead of the same error.
+import { createHash } from "node:crypto";
+
+export const SAME_CALL_FAILED = "Same call failed twice:";
+
+/** The last failing call's hash per session, in the host plugin's own state. */
+export type FailureMemo = Map<string, string>;
+
+const MAX_SESSIONS = 256;
+
+const stable = (value: unknown): string =>
+  JSON.stringify(value, (_key, entry: unknown) =>
+    entry && typeof entry === "object" && !Array.isArray(entry)
+      ? Object.fromEntries(Object.entries(entry).toSorted(([a], [b]) => a.localeCompare(b)))
+      : entry,
+  ) ?? "null";
+
+const hashOf = (call: string): string =>
+  createHash("sha256").update(call).digest("hex").slice(0, 32);
+
+/**
+ * Record this call's outcome for the session. A success clears the memo; a
+ * failure returns the escalation line when the previous call failed the same
+ * way and a corrected call is known.
+ */
+const record = (
+  memo: FailureMemo,
+  sessionId: string,
+  call: string,
+  failed: boolean,
+  next: string | null,
+): string | null => {
+  const previous = memo.get(sessionId);
+  memo.delete(sessionId);
+  if (!failed) return null;
+  const hash = hashOf(call);
+  memo.set(sessionId, hash);
+  if (memo.size > MAX_SESSIONS) memo.delete(memo.keys().next().value!);
+  return previous === hash && next ? `${SAME_CALL_FAILED} ${next}` : null;
+};
+
+type Failed = { ok: false; error: string; details?: { guidance?: unknown } };
+
+const isFailure = (result: unknown): result is Failed =>
+  result !== null &&
+  typeof result === "object" &&
+  (result as { ok?: unknown }).ok === false &&
+  typeof (result as { error?: unknown }).error === "string";
+
+/** A failed tool result's corrected payload: its `Example:` or, failing that, its guidance. */
+const correctedPayload = (tool: string, result: Failed): string | null => {
+  const example = /Example: (\{.*\})\s*$/.exec(result.error)?.[1];
+  if (example) return `${tool} ${example}`;
+  const guidance = result.details?.guidance;
+  return typeof guidance === "string" && guidance ? guidance : null;
+};
+
+/**
+ * A Workit tool result, with the escalation line appended to its error when
+ * the same tool and args failed on the session's previous call too.
+ */
+export const escalateToolFailure = <T>(
+  memo: FailureMemo,
+  sessionId: string,
+  tool: string,
+  input: unknown,
+  result: T,
+): T => {
+  const failed = isFailure(result);
+  const line = record(
+    memo,
+    sessionId,
+    `tool\0${tool}\0${stable(input)}`,
+    failed,
+    failed ? correctedPayload(tool, result) : null,
+  );
+  return line && failed ? { ...result, error: `${result.error}\n${line}` } : result;
+};
+
+const WORKIT_COMMAND = /^\s*(?:[A-Za-z_][A-Za-z0-9_]*=\S*\s+)*workit\s/;
+
+const unblockOf = (output: string): string | null => {
+  const human = /^\s*unblock: (.+)$/m.exec(output)?.[1];
+  if (human) return human.trim();
+  const json = /"unblock":("(?:[^"\\]|\\.)*")/.exec(output)?.[1];
+  if (!json) return null;
+  try {
+    return JSON.parse(json) as string;
+  } catch {
+    return null;
+  }
+};
+
+/**
+ * The escalation line for a finished `workit …` shell command, or null: a
+ * failed run is one whose output carries the CLI's error envelope.
+ */
+export const repeatedCliFailure = (
+  memo: FailureMemo,
+  sessionId: string,
+  command: string,
+  output: string,
+): string | null => {
+  if (!WORKIT_COMMAND.test(command)) return null;
+  const failed = /^workit: /m.test(output) || /"ok":\s*false/.test(output);
+  return record(
+    memo,
+    sessionId,
+    `cli\0${command.trim()}`,
+    failed,
+    failed ? unblockOf(output) : null,
+  );
+};

package/src/hooks/run.ts

@@ -0,0 +1,54 @@
+// Hook-process entry by host name: maps each process host to its adapter and
+// runs it (process.ts). Host bundles import process.ts with their own adapter,
+// so they carry none of the others.
+import { PROCESS_START, type HookDeadline } from "./deadline";
+import { claudeCodeAdapter } from "./hosts/claude-code";
+import { codexAdapter } from "./hosts/codex";
+import { cursorAdapter } from "./hosts/cursor";
+import { runAdapterHook } from "./process";
+import type { HostAdapter, HostId } from "./protocol";
+
+type ProcessHost = Exclude<HostId, "opencode" | "pi">;
+
+export const HOOK_ADAPTERS: Record<ProcessHost, HostAdapter> = {
+  claude_code: claudeCodeAdapter,
+  codex_cli: codexAdapter,
+  codex_desktop: codexAdapter,
+  cursor: cursorAdapter,
+};
+
+type Sink = { write(chunk: string): unknown };
+
+/** Runs one hook invocation and returns the process exit code. A broken
+ * payload never throws: the host's fail policy decides what is written. Past
+ * the deadline the host gets a minimal result naming the skip. */
+export const runHookProcess = (
+  host: ProcessHost | HostAdapter,
+  stdin: AsyncIterable<unknown> | Iterable<unknown>,
+  stdout: Sink,
+  stderr: Sink = process.stderr,
+  env: NodeJS.ProcessEnv = process.env,
+  deadline: HookDeadline = {},
+): Promise<number> =>
+  typeof host === "string"
+    ? runAdapterHook(HOOK_ADAPTERS[host], stdin, stdout, stderr, env, deadline, host)
+    : runAdapterHook(host, stdin, stdout, stderr, env, deadline);
+
+if (import.meta.main) {
+  const host = process.argv[2] as ProcessHost;
+  if (!Object.hasOwn(HOOK_ADAPTERS, host)) {
+    process.stderr.write(`usage: run.ts <${Object.keys(HOOK_ADAPTERS).join("|")}>\n`);
+    process.exitCode = 64;
+  } else {
+    process.exitCode = await runHookProcess(
+      host,
+      process.stdin,
+      process.stdout,
+      process.stderr,
+      process.env,
+      { startedAt: PROCESS_START },
+    );
+    // A payload that never ended must not keep the process alive past its answer.
+    process.stdin.destroy();
+  }
+}

package/src/hooks/session-marker.ts

@@ -0,0 +1,151 @@
+// The per-session nudge marker in the workspace store
+// (`<store>/hooks/skills-<session hash>.json`): which skills a session was
+// nudged about or loaded, and which raw-git nudge kinds it was shown, so each
+// nudge fires once per session. Each hook is a fresh process, so the marker
+// lives on disk. Every failure reads as an empty marker: hooks fail open.
+import { createHash } from "node:crypto";
+import fs from "node:fs";
+import path from "node:path";
+import { resolveStore } from "../store/paths";
+import type { HookInput } from "./protocol";
+
+export type SessionMarker = {
+  nudged: string[];
+  loaded: string[];
+  raw: string[];
+  /** Stop obligations already raised, `<kind>:<head>`: each blocks once per head. */
+  stops: string[];
+  /** Verifier and reviewer subagents of this lead that started and have not stopped. */
+  judges: string[];
+  /** The last model the session reported (Codex #435): a change re-sends the contract. */
+  model: string | null;
+};
+
+/**
+ * The marker in the workspace's store (null outside one: nothing is nudged or
+ * recorded there). `store` names the store directly when the command acts in
+ * another checkout than the hook's cwd.
+ */
+export const sessionMarkerFile = (
+  input: HookInput,
+  session: string,
+  store?: string,
+): string | null => {
+  let dir = store;
+  if (dir === undefined) {
+    const location = resolveStore(input.cwd);
+    if (location instanceof Error || !location.shared) return null;
+    dir = location.dir;
+  }
+  const name = createHash("sha256").update(`${input.host}\0${session}`).digest("hex").slice(0, 32);
+  return path.join(dir, "hooks", `skills-${name}.json`);
+};
+
+const list = (value: unknown): string[] =>
+  Array.isArray(value) ? value.filter((item): item is string => typeof item === "string") : [];
+
+const EMPTY: SessionMarker = {
+  nudged: [],
+  loaded: [],
+  raw: [],
+  stops: [],
+  judges: [],
+  model: null,
+};
+
+const readRaw = (file: string): string => {
+  try {
+    return fs.readFileSync(file, "utf8");
+  } catch {
+    return "";
+  }
+};
+
+const parseMarker = (text: string): SessionMarker => {
+  try {
+    const value = JSON.parse(text) as Record<string, unknown>;
+    return {
+      nudged: list(value.nudged),
+      loaded: list(value.loaded),
+      raw: list(value.raw),
+      stops: list(value.stops),
+      judges: list(value.judges),
+      model: typeof value.model === "string" ? value.model : null,
+    };
+  } catch {
+    return { ...EMPTY };
+  }
+};
+
+export const readSessionMarker = (file: string): SessionMarker => parseMarker(readRaw(file));
+
+/** Write through a temp file in the same directory and rename: a reader never sees half a marker. */
+const writeAtomic = (file: string, marker: SessionMarker): void => {
+  fs.mkdirSync(path.dirname(file), { recursive: true });
+  const temp = `${file}.${process.pid}.${Math.random().toString(36).slice(2)}.tmp`;
+  try {
+    fs.writeFileSync(temp, JSON.stringify(marker));
+    fs.renameSync(temp, file);
+  } catch (error) {
+    fs.rmSync(temp, { force: true });
+    throw error;
+  }
+};
+
+export const writeSessionMarker = (file: string, marker: SessionMarker): void => {
+  try {
+    writeAtomic(file, marker);
+  } catch {
+    // Fail open: without a marker a later nudge repeats.
+  }
+};
+
+/**
+ * Read-modify-write: `change` maps the marker as read to the marker to keep.
+ * Another hook's rename between the read and ours is detected (the file's
+ * text changed) and `change` runs once more on the fresh marker, so an entry
+ * of a concurrent hook is not lost. Fails open like the rest.
+ */
+export const updateSessionMarker = (
+  file: string,
+  change: (marker: SessionMarker) => SessionMarker,
+): void => {
+  try {
+    for (let attempt = 0; attempt < 2; attempt++) {
+      const before = readRaw(file);
+      const next = change(parseMarker(before));
+      if (attempt === 0 && readRaw(file) !== before) continue;
+      writeAtomic(file, next);
+      return;
+    }
+  } catch {
+    // Fail open: without a marker a later nudge repeats.
+  }
+};
+
+/** Record that a verifier or reviewer subagent of this lead started or stopped. */
+export const trackJudge = (input: HookInput, agentId: string | null, running: boolean): void => {
+  const session = input.session.id;
+  const file = session && agentId ? sessionMarkerFile(input, session) : null;
+  if (!file || !agentId) return;
+  updateSessionMarker(file, (marker) => {
+    const rest = marker.judges.filter((id) => id !== agentId);
+    return { ...marker, judges: running ? [...rest, agentId] : rest };
+  });
+};
+
+/**
+ * Record the session's model and say whether it differs from the last one
+ * recorded (the hook is a fresh process each time). The first model is a
+ * start, not a switch. Fails open: no store or no model reads as no switch.
+ */
+export const modelSwitchedOnDisk = (input: HookInput): boolean => {
+  const session = input.session.id;
+  const model = input.model;
+  const file = session && model ? sessionMarkerFile(input, session) : null;
+  if (!file || !model) return false;
+  const previous = readSessionMarker(file).model;
+  if (previous === model) return false;
+  updateSessionMarker(file, (marker) => ({ ...marker, model }));
+  return previous !== null;
+};