@workit-dev/core 0.0.1 → 1.0.0

package/src/hooks/deadline.ts

@@ -0,0 +1,228 @@
+// The hook's own deadline (issue #309). A host kills a hook past its timeout
+// and discards its output; under machine load that silently drops the Workit
+// context and gates. Past this deadline, below every host timeout, the hook
+// answers a minimal valid result naming the skip and records it for doctor.
+import { appendFileSync, mkdirSync } from "node:fs";
+import path from "node:path";
+import { resolveStateDir } from "../core/logger";
+import { dispatchHook } from "./handle";
+import type { HookDecision, HookEventKind, HostAdapter, RenderedHook } from "./protocol";
+
+export const HOOK_SKIP_TEXT = "workit context skipped: host under load";
+
+/** For a host without its own row; Claude Code's prompt/tool/subagent value. */
+export const HOOK_DEADLINE_MS = 8_000;
+
+/**
+ * Per host, by native event ("" for the rest): a margin below the host's own
+ * timeout, left for a dispatch that started in time. Claude Code registers
+ * 15 s (20 s for SessionStart and Stop); Codex defaults to 600 s and Workit
+ * registers 20 s for Stop; Cursor defaults to 60 s.
+ */
+export const HOST_DEADLINES: Readonly<Record<string, Readonly<Record<string, number>>>> = {
+  claude_code: { "": 8_000, SessionStart: 16_000, Stop: 16_000 },
+  codex_cli: { "": 45_000, Stop: 16_000 },
+  codex_desktop: { "": 45_000, Stop: 16_000 },
+  cursor: { "": 45_000 },
+};
+
+/** One JSON HookSkip per line; `workit doctor` (hook_deadline) reads it. */
+export const HOOK_SKIPS_FILE = "hook-skips.jsonl";
+
+/** `skip`: the hook answered the minimal result; `late`: it answered in full, past the deadline. */
+export type HookSkip = {
+  at: string;
+  host: string;
+  event: HookEventKind | null;
+  outcome: "skip" | "late";
+  stage: "input" | "dispatch" | "done";
+  elapsedMs: number;
+};
+
+export type HookDeadline = {
+  /** Milliseconds from `startedAt`; by default WORKIT_HOOK_DEADLINE_MS, else HOST_DEADLINES. */
+  deadlineMs?: number;
+  /**
+   * Epoch ms the budget counts from; the call by default. A hook-process
+   * entry passes PROCESS_START so its start-up and module load count too.
+   */
+  startedAt?: number;
+  now?: () => number;
+  /** The handler step; dispatchHook unless a host handles the event itself. */
+  dispatch?: (
+    adapter: HostAdapter,
+    raw: unknown,
+    env: NodeJS.ProcessEnv,
+  ) => (RenderedHook & { error: string | null }) | Promise<RenderedHook & { error: string | null }>;
+  record?: (skip: HookSkip) => void;
+};
+
+export type DeadlineResult = RenderedHook & { error: string | null; skipped: boolean };
+
+const override = (env: NodeJS.ProcessEnv): number | null => {
+  const value = Number(env.WORKIT_HOOK_DEADLINE_MS);
+  return Number.isFinite(value) && value > 0 ? value : null;
+};
+
+/** The deadline for one native event; `native` undefined gives the host's shortest. */
+export const hookDeadlineMs = (env: NodeJS.ProcessEnv, host = "", native?: string): number => {
+  const row = HOST_DEADLINES[host];
+  return (
+    override(env) ??
+    (row
+      ? native === undefined
+        ? Math.min(...Object.values(row))
+        : (row[native] ?? row[""])
+      : HOOK_DEADLINE_MS)
+  );
+};
+
+const skipsFile = (stateDir: string) => path.join(stateDir, HOOK_SKIPS_FILE);
+
+/** Best effort: a read-only state dir never changes the hook's answer. */
+export const recordHookSkip = (skip: HookSkip, stateDir: string = resolveStateDir()): void => {
+  try {
+    mkdirSync(stateDir, { recursive: true });
+    appendFileSync(skipsFile(stateDir), `${JSON.stringify(skip)}\n`);
+  } catch {
+    // The skip still reached the host; only the doctor count is lost.
+  }
+};
+
+const QUIET: ReadonlySet<HookEventKind | null> = new Set([
+  "stop",
+  "subagent.stop",
+  "shell.post",
+  "compact.pre",
+  "prompt.submit",
+  null,
+]);
+
+/** The minimal answer: the skip named where the event has a model channel, else no decision. */
+const skipDecision = (event: HookEventKind | null): HookDecision =>
+  QUIET.has(event) ? { kind: "none" } : { kind: "context", text: HOOK_SKIP_TEXT };
+
+const TIMED_OUT = Symbol("timed out");
+
+/** Resolves to `work`'s value, or TIMED_OUT when `ms` passes first. */
+export const within = async <T>(work: Promise<T>, ms: number): Promise<T | typeof TIMED_OUT> => {
+  let timer: ReturnType<typeof setTimeout> | undefined;
+  const expired = new Promise<typeof TIMED_OUT>((resolve) => {
+    timer = setTimeout(() => resolve(TIMED_OUT), Math.max(0, ms));
+    timer.unref?.();
+  });
+  try {
+    return await Promise.race([work, expired]);
+  } finally {
+    clearTimeout(timer);
+  }
+};
+
+export const isTimedOut = (value: unknown): value is typeof TIMED_OUT => value === TIMED_OUT;
+
+type Budget = Required<Pick<HookDeadline, "now" | "record">> & {
+  startedAt: number;
+  /** The host's shortest until the payload names its event. */
+  deadlineMs: number;
+  /** The host whose HOST_DEADLINES row refines it per event; null when the caller fixed it. */
+  host: string | null;
+};
+
+/** Epoch ms this process started. */
+export const PROCESS_START = performance.timeOrigin;
+
+export const hookBudget = (
+  env: NodeJS.ProcessEnv,
+  options: HookDeadline = {},
+  host = "",
+): Budget => {
+  const now = options.now ?? Date.now;
+  return {
+    now,
+    record: options.record ?? ((skip) => recordHookSkip(skip)),
+    startedAt: options.startedAt ?? now(),
+    deadlineMs: options.deadlineMs ?? hookDeadlineMs(env, host),
+    host: options.deadlineMs === undefined ? host : null,
+  };
+};
+
+/** Reads the whole payload, or null when the deadline passes first. */
+export const readWithin = async (
+  stdin: AsyncIterable<unknown> | Iterable<unknown>,
+  budget: Budget,
+): Promise<string | null> => {
+  const read = (async () => {
+    let text = "";
+    for await (const chunk of stdin) text += String(chunk);
+    return text;
+  })();
+  const text = await within(read, budget.startedAt + budget.deadlineMs - budget.now());
+  return isTimedOut(text) ? null : text;
+};
+
+/** Records one outcome; returns the parsed native event name for rendering. */
+const note = (
+  adapter: HostAdapter,
+  raw: unknown,
+  env: NodeJS.ProcessEnv,
+  budget: Budget,
+  outcome: HookSkip["outcome"],
+  stage: HookSkip["stage"],
+): { native: string | null; event: HookEventKind | null } => {
+  const parsed = raw === undefined ? null : adapter.parse(raw, env);
+  const event = parsed ? (parsed.ok ? parsed.input.event.kind : parsed.event) : null;
+  budget.record({
+    at: new Date(budget.now()).toISOString(),
+    host: adapter.descriptor.host,
+    event,
+    outcome,
+    stage,
+    elapsedMs: Math.round(budget.now() - budget.startedAt),
+  });
+  return { native: parsed?.native ?? null, event };
+};
+
+/** The minimal result for a skipped hook, rendered in the host's own shape. */
+export const skippedHook = (
+  adapter: HostAdapter,
+  raw: unknown,
+  env: NodeJS.ProcessEnv,
+  budget: Budget,
+  stage: HookSkip["stage"],
+): DeadlineResult => {
+  const { native, event } = note(adapter, raw, env, budget, "skip", stage);
+  return {
+    ...adapter.render(skipDecision(event), native),
+    error: `${HOOK_SKIP_TEXT} (past the ${budget.deadlineMs} ms hook deadline)`,
+    skipped: true,
+  };
+};
+
+/**
+ * dispatchHook under the deadline: a hook already past it answers the
+ * minimal result without running the handler, and a handler that overruns
+ * it is abandoned. A synchronous handler cannot be interrupted once started;
+ * one that finishes late answers in full and is recorded as late.
+ */
+export const dispatchWithin = async (
+  adapter: HostAdapter,
+  raw: unknown,
+  env: NodeJS.ProcessEnv,
+  budget: Budget,
+  dispatch: NonNullable<HookDeadline["dispatch"]> = dispatchHook,
+): Promise<DeadlineResult> => {
+  const native = (raw as { hook_event_name?: unknown } | null)?.hook_event_name;
+  if (budget.host !== null && typeof native === "string")
+    budget.deadlineMs = hookDeadlineMs(env, budget.host, native);
+  const remaining = () => budget.startedAt + budget.deadlineMs - budget.now();
+  const result =
+    remaining() > 0
+      ? await within(
+          Promise.resolve().then(() => dispatch(adapter, raw, env)),
+          remaining(),
+        )
+      : TIMED_OUT;
+  if (isTimedOut(result)) return skippedHook(adapter, raw, env, budget, "dispatch");
+  if (remaining() < 0) note(adapter, raw, env, budget, "late", "done");
+  return { ...result, skipped: false };
+};

package/src/hooks/delivery-verbs.ts

@@ -0,0 +1,182 @@
+// The Workit verbs a host may run without asking (issue #297, decision
+// mvk5q3io): delivery and state verbs whose own gates (grants, non-author
+// verdicts, branch policy) decide. One list for every host's permission
+// block: Claude Code `Bash(workit <verb> *)`, Codex `prefix_rule`, Cursor
+// `Shell(workit <verb>)`, and the OpenCode plugin's ask-to-allow.
+//
+// Never listed: verbs that run an arbitrary command (`check -- <cmd>`,
+// `lock run -- <cmd>`, `test-audit`, `fanout check`), change authority
+// (`grant`), install or remove host config (`init`, `upgrade`, `setup`,
+// `uninstall`, `launch`), delete data (`gc`), import state (`state`) or write
+// outside the forge flow (`youtrack`, `changelog`, `knowledge`, `handoff`).
+// Pure string work: the OpenCode plugin bundles it.
+import { segmentsOf, type ShellDialect } from "./shell-words";
+
+export const WORKIT_ALLOWED_VERBS = [
+  "git",
+  "pr",
+  "ci",
+  "stack",
+  "release",
+  "task",
+  "ledger",
+  "evidence",
+  "finding",
+  "decision",
+  "worker",
+  "verify-delivery",
+  "policy",
+  "doctor",
+  "help",
+] as const;
+
+/**
+ * Flags that override a Workit gate: a host never allows them unasked.
+ * Workit has no `--admin` flag and refuses a bare `--force` push itself.
+ */
+export const WORKIT_BYPASS_FLAGS = ["--unverified", "--overwrite-unintegrated"] as const;
+
+/**
+ * Calls only the user runs (issue #615). The CLI's TTY and agent-marker check
+ * deters a cooperating agent; the host's prompt is what stops a determined
+ * one, so no host rule or hook allow may cover these. `release` is an allowed
+ * verb and `release notes approve` is inside it, so each host also asks or
+ * denies these words explicitly.
+ */
+export const WORKIT_USER_ONLY: readonly (readonly string[])[] = [
+  ["release", "notes", "approve"],
+  ["grant", "set"],
+  ["grant", "raise"],
+];
+
+const ALLOWED = new Set<string>(WORKIT_ALLOWED_VERBS);
+
+/** Do `needle`'s words appear in order in `words` (flags and values between them still match)? */
+const hasWordsInOrder = (words: readonly string[], needle: readonly string[]): boolean => {
+  let at = 0;
+  for (const word of words) if (word === needle[at] && (at += 1) === needle.length) return true;
+  return false;
+};
+
+const isBypass = (word: string): boolean =>
+  WORKIT_BYPASS_FLAGS.some((flag) => word === flag || word.startsWith(`${flag}=`));
+
+/** `workit`, `workit-cli`, or either by path. */
+const isWorkitWord = (word: string): boolean => /^(?:.*[\\/])?workit(?:-cli)?$/u.test(word);
+
+/**
+ * Is `words` one Workit call of an allowed verb? Global `--json` and
+ * `--cwd <dir>` may come first (they mean the same anywhere before `--`);
+ * `--session` may not (it changes the acting identity). A bypass flag before
+ * `--` disqualifies it, and so does a word the shell expands there (`expands`,
+ * indexes into `words`): `${F:---unverified}` could become one.
+ */
+export const isAllowedWorkitCall = (
+  words: readonly string[],
+  expands: readonly number[] = [],
+): boolean => {
+  if (words[0] !== "workit") return false;
+  let at = 1;
+  for (;;) {
+    const word = words[at];
+    if (word === "--json") at += 1;
+    else if (word === "--cwd") at += 2;
+    else if (word?.startsWith("--cwd=")) at += 1;
+    else break;
+  }
+  const verb = words[at];
+  if (verb === undefined) return false;
+  if (verb === "--version") return at === words.length - 1;
+  if (!ALLOWED.has(verb)) return false;
+  const end = words.indexOf("--");
+  const limit = end < 0 ? words.length : end;
+  const call = words.slice(at, limit);
+  if (WORKIT_USER_ONLY.some((needle) => hasWordsInOrder(call, needle))) return false;
+  return !words.slice(0, limit).some(isBypass) && !expands.some((index) => index < limit);
+};
+
+const bypassReason = (flag: string) =>
+  `Workit: \`${flag}\` overrides a Workit gate, so the user decides this call (no allow rule covers it).`;
+
+/**
+ * The ask reason for a Workit call in `command` that carries a bypass flag
+ * before its `--`, or null. A word the shell expands (`$F`, `${F:---unverified}`) is not read: its text is not what runs, and the
+ * merge grant and `--reason` stay the gate. Words are read after shell quoting, so `"--unverified"`,
+ * `--unverif''ied` or a tab-separated flag are found where a host's string
+ * rule could miss them. A command the tokenizer cannot analyze is judged on
+ * its text with quotes and backslashes removed.
+ */
+export const workitBypassFlag = (
+  command: string,
+  dialect: ShellDialect = "posix",
+): string | null => {
+  for (const segment of segmentsOf(command, dialect)) {
+    if (segment.unanalyzable) {
+      const text = command.replaceAll(/['"\\`]/gu, "");
+      if (!/\bworkit\b/u.test(text)) return null;
+      const found = WORKIT_BYPASS_FLAGS.find((flag) => text.includes(flag));
+      return found ? bypassReason(found) : null;
+    }
+    const start = segment.words.findIndex(isWorkitWord);
+    if (start < 0) continue;
+    const words = segment.words.slice(start + 1);
+    const end = words.indexOf("--");
+    const flag = (end < 0 ? words : words.slice(0, end)).find(isBypass);
+    if (flag) return bypassReason(flag.split("=")[0] ?? flag);
+  }
+  return null;
+};
+
+/**
+ * The user-only words (`WORKIT_USER_ONLY`) a Workit call in `command` runs,
+ * or null. Each shell segment is read like `workitBypassFlag` does, so global
+ * `--json`, `--cwd <dir>`, `--cwd=<dir>` and `--session <id>` may come before
+ * the verb, which stays anchored: `workit help grant set` is not a match.
+ */
+export const userOnlyWorkitCall = (
+  command: string,
+  dialect: ShellDialect = "posix",
+): string[] | null => {
+  for (const segment of segmentsOf(command, dialect)) {
+    if (segment.unanalyzable) continue;
+    const start = segment.words.findIndex(isWorkitWord);
+    if (start < 0) continue;
+    const words = segment.words.slice(start + 1);
+    const end = words.indexOf("--");
+    const args = end < 0 ? words : words.slice(0, end);
+    let at = 0;
+    for (;;) {
+      const word = args[at];
+      if (word === "--json") at += 1;
+      else if (word === "--cwd" || word === "--session") at += 2;
+      else if (word?.startsWith("--cwd=")) at += 1;
+      else break;
+    }
+    const call = args.slice(at);
+    const found = WORKIT_USER_ONLY.find(
+      (needle) => call[0] === needle[0] && hasWordsInOrder(call, needle),
+    );
+    if (found) return [...found];
+  }
+  return null;
+};
+
+/**
+ * Is the whole shell `command` allowed Workit calls only? Every segment must
+ * be one, with no substitution, redirect, group or heredoc anywhere.
+ */
+export const isAllowedWorkitCommand = (command: string): boolean => {
+  const segments = segmentsOf(command);
+  return (
+    segments.length > 0 &&
+    segments.every(
+      (s) =>
+        !s.unanalyzable &&
+        !s.group &&
+        !s.subs?.length &&
+        !s.stdin?.length &&
+        !s.redirects.length &&
+        isAllowedWorkitCall(s.words, s.expands),
+    )
+  );
+};

package/src/hooks/descriptor.ts

@@ -0,0 +1,124 @@
+// Per-host capability descriptor. Each host states what it supports, with a
+// citation; workit derives engine capabilities from it. An `undocumented`
+// axis is treated as `none`: it never backs a guarantee (fail-closed).
+import type { Assurance, Capability } from "../core/task-contract";
+import type { HookEventKind, HostId } from "./protocol";
+
+export type Support = "native" | "partial" | "none" | "undocumented";
+
+export type HostDescriptor = {
+  host: HostId;
+  /** Human label used in model-visible text, e.g. "Codex". */
+  label: string;
+  verifiedAgainst: string;
+  docs: string[];
+  transport: "hook-process" | "in-process-plugin";
+  events: Record<HookEventKind, { support: Support; native: string | null }>;
+  shellPolicy: {
+    deny: Support;
+    channel: "permissionDecision" | "exit2+json" | "effect" | "block" | null;
+    /** A parse or handler failure on a pre-tool gate denies instead of passing. */
+    failClosed: boolean;
+    /** The pre-shell hook can replace the command before it runs (the heavy-command lease). */
+    rewrite: Support;
+  };
+  context: {
+    sessionStart: Support;
+    perTurn: Support;
+    afterCompact: Support;
+    /** How the session's current task is chosen: by a session bound to the task
+     * record, or the workspace's single active task when sessions never bind. */
+    task: "session-bound" | "single-active";
+    /** `on-change`: the host keeps each injected context in the transcript, so
+     * the core resends per-turn context only when it changed; `every-turn`:
+     * the core sends it on every turn (an in-process system-prompt hook needs
+     * it each time, or the host plugin dedups itself); `per-session`: the
+     * host plugin sends it once per session and again after compaction. */
+    turnResend: "on-change" | "every-turn" | "per-session";
+  };
+  subagents: {
+    identity: Support;
+    parentBinding: Support;
+    blockStart: Support;
+    worktreeIsolation: Support;
+    maxConcurrency: number | "undocumented";
+    /** How a Workit agent type is spelled: plugin-namespaced (`workit:verifier`)
+     * on hosts that namespace plugin agents, else a plain `workit-verifier`. */
+    agentPrefix: "workit:" | "workit-";
+  };
+  provenance: { sessionId: Support; agentIdOnTool: Support; postToolObserve: Support };
+  /** Host-native interaction boundaries workit can observe. */
+  interaction: { questions: Support; writeBoundary: Support };
+  stopControl: Support;
+  shellAvailable: Support;
+  perEventCost: "low" | "npx-network";
+  capabilities: CapabilityRule[];
+};
+
+/** Descriptor axes a capability can depend on. */
+export type Axis =
+  | `event:${HookEventKind}`
+  | "shellPolicy.deny"
+  | `context.${"sessionStart" | "perTurn" | "afterCompact"}`
+  | `subagents.${"identity" | "parentBinding" | "blockStart" | "worktreeIsolation"}`
+  | `provenance.${"sessionId" | "agentIdOnTool" | "postToolObserve"}`
+  | `interaction.${"questions" | "writeBoundary"}`
+  | "stopControl"
+  | "shellAvailable";
+
+/**
+ * One engine capability claim. `assurance` is granted only when every
+ * `requires` axis is supported and every `observed` runtime flag is true;
+ * `enforced` additionally needs at least one axis, all `native`, and degrades
+ * to `agent_guided` otherwise.
+ */
+export type CapabilityRule = {
+  name: string;
+  surface: string;
+  refs: string[];
+  requires: Axis[];
+  /** Runtime facts only the running dispatcher can attest (e.g. "subagent.start", "ui"). */
+  observed?: string[];
+  assurance: Assurance;
+  reason: string;
+  unavailableReason?: string;
+};
+
+export const support = (descriptor: HostDescriptor, axis: Axis): Support => {
+  if (axis.startsWith("event:"))
+    return descriptor.events[axis.slice("event:".length) as HookEventKind].support;
+  if (axis === "shellPolicy.deny") return descriptor.shellPolicy.deny;
+  if (axis === "stopControl" || axis === "shellAvailable") return descriptor[axis];
+  const [group, key] = axis.split(".") as [
+    "context" | "subagents" | "provenance" | "interaction",
+    string,
+  ];
+  return (descriptor[group] as Record<string, Support>)[key];
+};
+
+const usable = (value: Support) => value === "native" || value === "partial";
+
+export const capabilitiesFor = (
+  descriptor: HostDescriptor,
+  observed: Partial<Record<string, boolean>> = {},
+): Capability[] =>
+  descriptor.capabilities.map((rule) => {
+    const levels = rule.requires.map((axis) => support(descriptor, axis));
+    const available =
+      rule.assurance !== "unavailable" &&
+      levels.every(usable) &&
+      (rule.observed ?? []).every((flag) => observed[flag] === true);
+    const assurance: Assurance = !available
+      ? "unavailable"
+      : rule.assurance === "enforced" &&
+          (levels.length === 0 || levels.some((level) => level !== "native"))
+        ? "agent_guided"
+        : rule.assurance;
+    return {
+      name: rule.name,
+      surface: rule.surface,
+      assurance,
+      reason: assurance === "unavailable" ? (rule.unavailableReason ?? rule.reason) : rule.reason,
+      refs: rule.refs.map((handle) => ({ kind: "host" as const, host: descriptor.host, handle })),
+    };
+  });