@tech-leads-club/harness-toolkit 0.2.1

package/src/providers/cursor/cursor.wiring.ts

@@ -0,0 +1,214 @@
+import { join } from "node:path";
+import type { ProviderWiring, RuntimePaths, WiringEntry } from "../../contracts/index.ts";
+import { cursorConfigDir } from "../../platform/paths.ts";
+
+type EntrySpec = {
+  hookEvent: string;
+  handler: string;
+  timeoutSeconds: number;
+  failClosed?: boolean;
+  matcher?: string;
+  loopLimit?: number;
+};
+
+// why: mirrors bin/write-user-hooks.mjs verbatim — same hook keys, timeouts, failClosed/matcher/loopLimit values, and handler order.
+const ENTRY_SPECS: readonly EntrySpec[] = [
+  { hookEvent: "sessionStart", handler: "session-start", timeoutSeconds: 10 },
+  { hookEvent: "sessionEnd", handler: "session-end", timeoutSeconds: 10 },
+  { hookEvent: "beforeSubmitPrompt", handler: "prompt-submit", timeoutSeconds: 5 },
+  { hookEvent: "afterAgentThought", handler: "tool-after", timeoutSeconds: 5 },
+  { hookEvent: "preCompact", handler: "compact-before", timeoutSeconds: 5 },
+  { hookEvent: "subagentStart", handler: "subagent-start", timeoutSeconds: 5, failClosed: true },
+  { hookEvent: "subagentStop", handler: "subagent-stop", timeoutSeconds: 5 },
+  { hookEvent: "preToolUse", handler: "tool-before", timeoutSeconds: 5, failClosed: true },
+  { hookEvent: "postToolUse", handler: "tool-after", timeoutSeconds: 5 },
+  { hookEvent: "postToolUseFailure", handler: "tool-failure", timeoutSeconds: 5 },
+  { hookEvent: "beforeShellExecution", handler: "tool-before", timeoutSeconds: 10, failClosed: true },
+  { hookEvent: "afterShellExecution", handler: "tool-after", timeoutSeconds: 10 },
+  { hookEvent: "beforeMCPExecution", handler: "tool-before", timeoutSeconds: 10 },
+  { hookEvent: "afterMCPExecution", handler: "tool-after", timeoutSeconds: 5 },
+  { hookEvent: "beforeReadFile", handler: "tool-before", timeoutSeconds: 5 },
+  { hookEvent: "afterFileEdit", handler: "tool-after", timeoutSeconds: 30, matcher: "Write" },
+  { hookEvent: "stop", handler: "stop", timeoutSeconds: 120, loopLimit: 5 },
+  { hookEvent: "afterAgentResponse", handler: "response-after", timeoutSeconds: 5, matcher: "AgentResponse" },
+];
+
+function commandFor(runtime: RuntimePaths): { command: string; argsPrefix: string[] } {
+  if (process.platform === "win32") {
+    return { command: "cmd", argsPrefix: ["/c", "node", runtime.launcherPath] };
+  }
+  return { command: "node", argsPrefix: [runtime.launcherPath] };
+}
+
+export function cursorWiring(runtime: RuntimePaths): ProviderWiring {
+  const { command, argsPrefix } = commandFor(runtime);
+  const entries: WiringEntry[] = ENTRY_SPECS.map((spec) => ({
+    hookEvent: spec.hookEvent,
+    handler: spec.handler,
+    command,
+    args: [...argsPrefix, spec.handler],
+    timeoutSeconds: spec.timeoutSeconds,
+    ...(spec.failClosed !== undefined ? { failClosed: spec.failClosed } : {}),
+    ...(spec.matcher !== undefined ? { matcher: spec.matcher } : {}),
+    ...(spec.loopLimit !== undefined ? { loopLimit: spec.loopLimit } : {}),
+  }));
+
+  return {
+    target: join(cursorConfigDir(), "hooks.json"),
+    strategy: "replace",
+    entries,
+  };
+}
+
+export type WiringProblem = { hookEvent: string; reason: string };
+
+/**
+ * hazard: splitting on whitespace broke a quoted path, and the writer quotes precisely because a path can contain
+ * spaces — a macOS home under "Application Support" is an ordinary shape. A checker that mis-tokenises
+ * reports a healthy wiring as broken, which is the failure mode that gets a check switched off.
+ */
+export function commandTokens(command: string): string[] {
+  return [...command.matchAll(/"([^"]*)"|(\S+)/g)].map((match) => match[1] ?? match[2] ?? "");
+}
+
+/**
+ * hazard: health was decided by looking for one string. `isCursorWired` checks whether the file *contains*
+ * `tlc-exec.mjs`, so a file carrying the marker in one entry and a broken command in another read as fully wired and
+ * `doctor` said `wired`. Marker presence answers "is this file ours", which is the right question when deciding
+ * whether to overwrite it and the wrong one when deciding whether the hooks work
+ * ([/decisions/ad-032.md](/decisions/ad-032.md)).
+ *
+ * why: a colleague's session was blocked by a `preToolUse` whose command was a bare `node`, so Node read the hook
+ * payload as a program. The entry was `failClosed`, so the crash blocked the tool rather than merely logging. Nothing
+ * checked that a wired hook could run.
+ *
+ * invariant: only the events this provider declares are inspected, and within them only entries whose command names
+ * our launcher. A hook belonging to another tool is not ours to judge, and flagging it would train an operator to
+ * ignore the check.
+ */
+export function cursorWiringProblems(
+  text: string | null,
+  runtime: RuntimePaths,
+  fileExists: (path: string) => boolean,
+): WiringProblem[] {
+  if (text === null) {
+    return [{ hookEvent: "(file)", reason: "no hooks file at the expected path" }];
+  }
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(text);
+  } catch {
+    return [{ hookEvent: "(file)", reason: "the hooks file is not valid JSON" }];
+  }
+  const hooks =
+    parsed !== null && typeof parsed === "object"
+      ? ((parsed as { hooks?: Record<string, unknown> }).hooks ?? {})
+      : {};
+
+  const problems: WiringProblem[] = [];
+  for (const spec of ENTRY_SPECS) {
+    const list = Array.isArray(hooks[spec.hookEvent]) ? (hooks[spec.hookEvent] as unknown[]) : [];
+    const commands = list
+      .map((row) =>
+        row !== null && typeof row === "object" ? String((row as { command?: unknown }).command ?? "") : "",
+      )
+      // why: our entries are the ones naming our launcher. Everything else in the file belongs to someone else.
+      .filter((command) => command.includes(runtime.launcherPath));
+    if (commands.length === 0) {
+      problems.push({ hookEvent: spec.hookEvent, reason: "no harness entry — run: tlc harness update" });
+      continue;
+    }
+    for (const command of commands) {
+      const tokens = commandTokens(command);
+      const scriptAt = tokens.indexOf(runtime.launcherPath);
+      if (scriptAt < 1) {
+        problems.push({
+          hookEvent: spec.hookEvent,
+          reason: `no executable before the script: \`${command}\``,
+        });
+        continue;
+      }
+      if (!fileExists(runtime.launcherPath)) {
+        problems.push({
+          hookEvent: spec.hookEvent,
+          reason: `the script does not exist: ${runtime.launcherPath}`,
+        });
+        continue;
+      }
+      if (tokens[scriptAt + 1] === undefined || tokens[scriptAt + 1] === "") {
+        problems.push({
+          hookEvent: spec.hookEvent,
+          // why: the exact shape from the incident. A command with the script and no handler makes the launcher
+          // exit 2 with usage, and a command with neither makes Node read the payload as a program.
+          reason: `no handler after the script: \`${command}\``,
+        });
+      }
+    }
+  }
+  return problems;
+}
+
+/** why: bounded, because a fresh install with no wiring produces one problem per declared event. */
+export function formatWiringProblems(problems: readonly WiringProblem[], max = 3): string {
+  const shown = problems
+    .slice(0, max)
+    .map((problem) => `${problem.hookEvent}: ${problem.reason}`)
+    .join("; ");
+  const rest = problems.length - Math.min(problems.length, max);
+  return rest > 0 ? `${shown}; and ${rest} more` : shown;
+}
+
+export type CursorUnwire =
+  | { kind: "absent" }
+  | { kind: "unparsed" }
+  | { kind: "empty"; removed: number }
+  | { kind: "rewritten"; removed: number; text: string };
+
+/**
+ * The inverse of the document `bin/write-user-hooks.mjs` writes.
+ *
+ * invariant: an entry is ours when its command names the launcher — the same test `cursorWiringProblems` applies
+ * one function above. `kind: "empty"` means every entry in the file was ours and the file itself can go; a file
+ * that still holds somebody else's hook is rewritten without ours ([/decisions/ad-066.md](/decisions/ad-066.md)).
+ */
+export function unwireCursorHooks(text: string | null, marker = "tlc-exec.mjs"): CursorUnwire {
+  if (text === null || text.trim() === "") {
+    return { kind: "absent" };
+  }
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(text);
+  } catch {
+    return { kind: "unparsed" };
+  }
+  if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed)) {
+    return { kind: "unparsed" };
+  }
+  const document = parsed as { hooks?: unknown };
+  const hooks =
+    document.hooks !== null && typeof document.hooks === "object" && !Array.isArray(document.hooks)
+      ? (document.hooks as Record<string, unknown>)
+      : {};
+
+  const remaining: Record<string, unknown[]> = {};
+  let removed = 0;
+  let kept = 0;
+  for (const [hookEvent, value] of Object.entries(hooks)) {
+    const list = Array.isArray(value) ? value : [];
+    const foreign = list.filter((row) => !JSON.stringify(row ?? null).includes(marker));
+    removed += list.length - foreign.length;
+    if (foreign.length > 0) {
+      remaining[hookEvent] = foreign;
+      kept += foreign.length;
+    }
+  }
+
+  if (kept === 0) {
+    return { kind: "empty", removed };
+  }
+  return {
+    kind: "rewritten",
+    removed,
+    text: `${JSON.stringify({ ...document, hooks: remaining }, null, 2)}\n`,
+  };
+}

package/src/providers/cursor/index.ts

@@ -0,0 +1,17 @@
+import type { ProviderPort } from "../provider.port.ts";
+import { cursorCapabilities } from "./cursor.capabilities.ts";
+import { detectCursor } from "./cursor.detect.ts";
+import { cursorToEvent } from "./cursor.inbound.ts";
+import { cursorRender } from "./cursor.outbound.ts";
+import { cursorPolicyDefaults } from "./cursor.policy-defaults.ts";
+import { cursorWiring } from "./cursor.wiring.ts";
+
+export const cursorProvider: ProviderPort = {
+  name: "cursor",
+  detect: detectCursor,
+  capabilities: cursorCapabilities,
+  policyDefaults: cursorPolicyDefaults,
+  toEvent: cursorToEvent,
+  render: cursorRender,
+  wiring: cursorWiring,
+};

package/src/providers/index.ts

@@ -0,0 +1,9 @@
+export { renderClaudeLessonsView } from "./claude/claude.lessons-view.ts";
+export type { TranscriptUsage } from "./claude/claude.transcript.ts";
+export { readClaudeUsage } from "./claude/claude.transcript.ts";
+export { renderCursorLessonsView } from "./cursor/cursor.lessons-view.ts";
+export type { DegradeOptions } from "./provider.degrade.ts";
+export { degrade, truncateContext } from "./provider.degrade.ts";
+export type { ProviderPort } from "./provider.port.ts";
+export type { ResolveResult } from "./provider.registry.ts";
+export { providers, resolveFromRegistry, resolveProvider } from "./provider.registry.ts";

package/src/providers/provider.degrade.ts

@@ -0,0 +1,152 @@
+import type { Decision, HarnessEvent, ProviderCapabilities } from "../contracts/index.ts";
+
+export type DegradeOptions = {
+  /** Character budget for `context` text. Undefined means no truncation. */
+  contextBudgetChars?: number;
+};
+
+/**
+ * why: the only rule this layer may name. Every other decision arrives with its rule already set by the rail that
+ * made it, and degrade preserves it ([/decisions/ad-061.md](/decisions/ad-061.md)).
+ */
+export const DEGRADE_RULES = { rewriteUnavailable: "rewrite-unavailable" } as const;
+
+const ESCALATION_PREFIX = "Escalation unavailable on this provider — ";
+const NO_HUMAN_PREFIX = "No operator is answering prompts in this permission mode — ";
+
+// hazard: these modes exist to stop prompting the operator, so an `ask` raised under them reaches
+// nobody. Whether the provider drops it or silently allows the call is undocumented, and a gate
+// whose outcome depends on undocumented behaviour is not a gate — deny and say why instead.
+const NO_HUMAN_MODES = new Set(["bypassPermissions", "dontAsk"]);
+const ADVISORY_PREFIX = "ADVISORY — this provider cannot enforce: ";
+const TRUNCATION_MARKER = "\n…(truncated — over context budget)";
+
+function isEnforcing(decision: Decision): boolean {
+  return (
+    decision.kind === "deny" ||
+    decision.kind === "ask" ||
+    decision.kind === "continue" ||
+    decision.kind === "rewriteInput"
+  );
+}
+
+function describeDecision(decision: Decision): string {
+  switch (decision.kind) {
+    case "deny":
+    case "ask":
+      return decision.reason;
+    case "continue":
+      return decision.text;
+    case "rewriteInput":
+      return `${decision.reason} (proposed input: ${JSON.stringify(decision.input)})`;
+    default:
+      return "";
+  }
+}
+
+export function truncateContext(text: string, budgetChars: number): string {
+  if (text.length <= budgetChars) {
+    return text;
+  }
+  if (budgetChars <= 0) {
+    return "";
+  }
+  const marker =
+    TRUNCATION_MARKER.length <= budgetChars ? TRUNCATION_MARKER : TRUNCATION_MARKER.slice(0, budgetChars);
+  const keep = Math.max(0, budgetChars - marker.length);
+  return `${text.slice(0, keep)}${marker}`;
+}
+
+function canCarryContext(event: HarnessEvent, capabilities: ProviderCapabilities): boolean {
+  if (event.event === "tool.before") {
+    return capabilities.contextAtToolBefore;
+  }
+  if (event.event === "tool.after") {
+    return capabilities.contextAtToolAfter;
+  }
+  // hazard: the docs gate raises an advisory here. Cursor's `stop` schema carries `followup_message` and nothing
+  // else, so the advisory was rendered into `additional_context` and read by no one. `followup_message` is not the
+  // fallback — it auto-submits, and the advisory says in its own words that it does not block the stop.
+  if (event.event === "stop") {
+    return capabilities.contextAtStop;
+  }
+  // why: `session.start` stays true even where the host loses the text. Cursor's drop is a race rather than a
+  // refusal, so the emission is free when lost and delivered when won — the durable view is the second route,
+  // not the replacement ([/decisions/ad-050.md](/decisions/ad-050.md)).
+  return true;
+}
+
+function applyContextBudget(decision: Decision, budgetChars: number | undefined): Decision {
+  if (decision.kind !== "context" || budgetChars === undefined) {
+    return decision;
+  }
+  const truncated = truncateContext(decision.text, budgetChars);
+  if (truncated === decision.text) {
+    return decision;
+  }
+  return { ...decision, text: truncated };
+}
+
+export function degrade(
+  decision: Decision,
+  event: HarnessEvent,
+  capabilities: ProviderCapabilities,
+  options: DegradeOptions = {},
+): Decision {
+  if (!capabilities.enforcesHooks && isEnforcing(decision)) {
+    return applyContextBudget(
+      { kind: "context", text: `${ADVISORY_PREFIX}${describeDecision(decision)}` },
+      options.contextBudgetChars,
+    );
+  }
+
+  if (decision.kind === "ask") {
+    if (!capabilities.askSupportedOn.includes(event.event)) {
+      // invariant: the rule is carried through, never replaced. This is the one place a decision changes shape,
+      // so it is the case an operator most needs attributed — and inventing a rule here would attribute a refusal
+      // to the transport rather than to the rail that made it ([/decisions/ad-061.md](/decisions/ad-061.md)).
+      return {
+        kind: "deny",
+        reason: `${ESCALATION_PREFIX}${decision.reason}`,
+        userNote: decision.userNote,
+        rule: decision.rule,
+      };
+    }
+    if (event.permissionMode !== undefined && NO_HUMAN_MODES.has(event.permissionMode)) {
+      return {
+        kind: "deny",
+        reason: `${NO_HUMAN_PREFIX}${decision.reason}`,
+        userNote: decision.userNote,
+        rule: decision.rule,
+      };
+    }
+    return decision;
+  }
+
+  if (decision.kind === "rewriteInput" && !capabilities.toolInputRewrite) {
+    return {
+      kind: "ask",
+      reason: `Input rewrite unavailable on this provider — proposed input: ${JSON.stringify(decision.input)}. ${decision.reason}`,
+      // why: a rewrite carries no rule of its own — nothing refused anything — so the degraded ask names the
+      // transport limit that produced it. It is the one rule this layer owns.
+      rule: DEGRADE_RULES.rewriteUnavailable,
+    };
+  }
+
+  if (decision.kind === "context") {
+    // hazard: contextAtToolBefore and contextAtToolAfter were declared by every adapter and read by
+    // nothing. A provider that cannot carry context on the current event would have had the text rendered
+    // into a field it ignores, leaving the caller believing it was delivered. Abstaining is the honest
+    // answer: context is informative, so there is nothing to escalate to.
+    if (!canCarryContext(event, capabilities)) {
+      return { kind: "abstain" };
+    }
+    if (decision.env && !capabilities.sessionEnv) {
+      const { env: _droppedEnv, ...withoutEnv } = decision;
+      return applyContextBudget(withoutEnv, options.contextBudgetChars);
+    }
+    return applyContextBudget(decision, options.contextBudgetChars);
+  }
+
+  return decision;
+}

package/src/providers/provider.port.ts

@@ -0,0 +1,20 @@
+import type {
+  Decision,
+  HarnessEvent,
+  ProviderCapabilities,
+  ProviderPolicyDefaults,
+  ProviderWiring,
+  Rendered,
+  RuntimePaths,
+} from "../contracts/index.ts";
+
+/** Core never imports this type — it receives a HarnessEvent and ProviderCapabilities as plain arguments instead. */
+export type ProviderPort = {
+  readonly name: string;
+  detect(raw: unknown): boolean;
+  capabilities(): ProviderCapabilities;
+  policyDefaults(): ProviderPolicyDefaults;
+  toEvent(raw: Record<string, unknown>): HarnessEvent | null;
+  render(decision: Decision, event: HarnessEvent): Rendered;
+  wiring(runtime: RuntimePaths): ProviderWiring;
+};

package/src/providers/provider.registry.ts

@@ -0,0 +1,28 @@
+import { claudeProvider } from "./claude/index.ts";
+import { cursorProvider } from "./cursor/index.ts";
+import type { ProviderPort } from "./provider.port.ts";
+
+export type ResolveResult = {
+  provider: ProviderPort | null;
+  ambiguous: boolean;
+  matchedNames: readonly string[];
+};
+
+// invariant: detection order is registry order — deterministic, never re-sorted.
+export const providers: ProviderPort[] = [cursorProvider, claudeProvider];
+
+export function resolveFromRegistry(raw: unknown, registry: readonly ProviderPort[]): ResolveResult {
+  const matched = registry.filter((provider) => provider.detect(raw));
+  if (matched.length === 0) {
+    return { provider: null, ambiguous: false, matchedNames: [] };
+  }
+  return {
+    provider: matched[0] ?? null,
+    ambiguous: matched.length > 1,
+    matchedNames: matched.map((provider) => provider.name),
+  };
+}
+
+export function resolveProvider(raw: unknown): ResolveResult {
+  return resolveFromRegistry(raw, providers);
+}