killeros 2.0.22 → 2.1.22

package/killeros/goal-state.ts

@@ -2,9 +2,12 @@ import { createHash } from "node:crypto";
 import type { Stats } from "node:fs";
 import { lstat, open, type FileHandle } from "node:fs/promises";
 import path from "node:path";
-import type { GoalBlockerAudit, GoalFileBaseline, GoalFileVerification, GoalState, GoalStateCommon, GoalStatus } from "./runtime.ts";
+import type { GoalBlockerAudit, GoalCompletionCheck, GoalFileBaseline, GoalFileVerification, GoalState, GoalStateCommon, GoalStatus } from "./runtime.ts";
 
+export const DEFAULT_GOAL_MAX_TURNS = 20;
 export const GOAL_OBJECTIVE_LIMIT = 4_000;
+export const GOAL_MAX_TURNS = 10_000;
+export const GOAL_CHECK_NAME_PATTERN = /^[a-z0-9][a-z0-9._-]{0,63}$/u;
 export const GOAL_VERSION = 1;
 const FILE_HASH_CHUNK_SIZE = 64 * 1024;
 export const FILE_HASH_LIMIT = 64 * 1024 * 1024;
@@ -25,6 +28,20 @@ function finiteNonNegative(value: unknown): value is number {
   return typeof value === "number" && Number.isFinite(value) && value >= 0;
 }
 
+function safeNonNegativeInteger(value: unknown): value is number {
+  return typeof value === "number" && Number.isSafeInteger(value) && value >= 0;
+}
+
+function incrementableNonNegativeInteger(value: unknown): value is number {
+  return safeNonNegativeInteger(value) && value < Number.MAX_SAFE_INTEGER;
+}
+
+function addGoalMilliseconds(accumulated: number, interval: number): number {
+  const total = accumulated + interval;
+  if (!safeNonNegativeInteger(total)) throw new Error("Goal active duration exceeds the safe integer range");
+  return total;
+}
+
 function isUnknownRecord(value: unknown): value is Record<string, unknown> {
   return typeof value === "object" && value !== null && !Array.isArray(value);
 }
@@ -56,12 +73,27 @@ function isGoalFileVerification(value: unknown): value is GoalFileVerification {
     && isGoalFileBaseline(value.baseline);
 }
 
+function isGoalCompletionCheck(value: unknown): value is GoalCompletionCheck {
+  return isUnknownRecord(value)
+    && value.kind === "named-command"
+    && typeof value.name === "string"
+    && GOAL_CHECK_NAME_PATTERN.test(value.name)
+    && typeof value.configHash === "string"
+    && /^[a-f0-9]{64}$/u.test(value.configHash);
+}
+
+function isMaxTurns(value: unknown): value is number {
+  return typeof value === "number" && Number.isInteger(value) && value >= 1 && value <= GOAL_MAX_TURNS;
+}
+
 function isGoalBlockerAudit(value: unknown, turns: number, status: GoalStatus): value is GoalBlockerAudit {
   if (!isUnknownRecord(value)
     || typeof value.key !== "string"
     || !/^[a-z0-9][a-z0-9._-]{0,119}$/u.test(value.key)
     || typeof value.streak !== "number" || !Number.isInteger(value.streak) || value.streak < 1 || value.streak > 3
-    || typeof value.lastTurn !== "number" || !Number.isInteger(value.lastTurn) || value.lastTurn < 1 || value.lastTurn > turns) {
+    || typeof value.lastTurn !== "number" || !Number.isInteger(value.lastTurn) || value.lastTurn < 1 || value.lastTurn > turns
+    || value.evidence !== undefined && (typeof value.evidence !== "string"
+      || value.evidence !== value.evidence.trim() || !value.evidence || value.evidence.length > 2_000)) {
     return false;
   }
   if (status === "complete") return false;
@@ -86,21 +118,24 @@ export function parseGoalState(value: unknown): GoalState | undefined {
     resumeAfterManualCompaction,
     blockerAudit,
     verification,
+    completionCheck,
+    maxTurns,
   } = value;
   if (version !== GOAL_VERSION
-    || typeof revision !== "number" || !Number.isInteger(revision) || revision < 1
+    || !incrementableNonNegativeInteger(revision) || revision < 1
     || typeof objective !== "string" || !objective.trim() || [...objective].length > GOAL_OBJECTIVE_LIMIT
     || !isGoalStatus(status)
-    || !finiteNonNegative(createdAt)
-    || !finiteNonNegative(updatedAt)
-    || !finiteNonNegative(activeMilliseconds)
-    || typeof turns !== "number" || !Number.isInteger(turns) || turns < 0
+    || !safeNonNegativeInteger(createdAt)
+    || !safeNonNegativeInteger(updatedAt)
+    || !incrementableNonNegativeInteger(activeMilliseconds)
+    || !incrementableNonNegativeInteger(turns)
     || blockedAuditStartTurn !== undefined
-      && (typeof blockedAuditStartTurn !== "number" || !Number.isInteger(blockedAuditStartTurn)
-        || blockedAuditStartTurn < 0 || blockedAuditStartTurn > turns)
-    || !finiteNonNegative(baselineTokens)
+      && (!safeNonNegativeInteger(blockedAuditStartTurn) || blockedAuditStartTurn > turns)
+    || !safeNonNegativeInteger(baselineTokens)
     || result !== undefined && typeof result !== "string"
     || verification !== undefined && !isGoalFileVerification(verification)
+    || completionCheck !== undefined && !isGoalCompletionCheck(completionCheck)
+    || maxTurns !== undefined && !isMaxTurns(maxTurns)
     || resumeAfterManualCompaction !== undefined && resumeAfterManualCompaction !== true
     || blockerAudit !== undefined && !isGoalBlockerAudit(blockerAudit, turns, status)) {
     return undefined;
@@ -117,10 +152,12 @@ export function parseGoalState(value: unknown): GoalState | undefined {
     blockedAuditStartTurn: blockedAuditStartTurn ?? 0,
     baselineTokens,
     ...(verification === undefined ? {} : { verification }),
+    ...(completionCheck === undefined ? {} : { completionCheck }),
+    ...(maxTurns === undefined ? {} : { maxTurns }),
   };
   switch (status) {
     case "active":
-      if (!finiteNonNegative(activeStartedAt) || resumeAfterManualCompaction !== undefined) return undefined;
+      if (!safeNonNegativeInteger(activeStartedAt) || resumeAfterManualCompaction !== undefined) return undefined;
       return {
         ...common,
         status,
@@ -250,7 +287,7 @@ export function validateGoalObjective(input: string): string | undefined {
 
 export function goalElapsedMilliseconds(state: GoalState, now: number): number {
   const activeInterval = state.status === "active" ? Math.max(0, now - state.activeStartedAt) : 0;
-  return state.activeMilliseconds + activeInterval;
+  return addGoalMilliseconds(state.activeMilliseconds, activeInterval);
 }
 
 export function commonGoalState(state: GoalState): GoalStateCommon {
@@ -265,13 +302,15 @@ export function commonGoalState(state: GoalState): GoalStateCommon {
     blockedAuditStartTurn: state.blockedAuditStartTurn,
     baselineTokens: state.baselineTokens,
     ...(state.verification === undefined ? {} : { verification: state.verification }),
+    ...(state.completionCheck === undefined ? {} : { completionCheck: state.completionCheck }),
+    ...(state.maxTurns === undefined ? {} : { maxTurns: state.maxTurns }),
   };
 }
 
 export function stopGoalClock(state: GoalState, now: number): GoalStateCommon {
   const common = commonGoalState(state);
   return state.status === "active"
-    ? { ...common, activeMilliseconds: common.activeMilliseconds + Math.max(0, now - state.activeStartedAt) }
+    ? { ...common, activeMilliseconds: addGoalMilliseconds(common.activeMilliseconds, Math.max(0, now - state.activeStartedAt)) }
     : common;
 }
 
@@ -280,6 +319,7 @@ export function createNewGoalState(
   baselineTokens: number,
   verification: GoalFileVerification | undefined,
   now: number,
+  controls: { completionCheck?: GoalCompletionCheck; maxTurns?: number } = {},
 ): GoalState {
   return {
     version: GOAL_VERSION,
@@ -294,6 +334,8 @@ export function createNewGoalState(
     blockedAuditStartTurn: 0,
     baselineTokens,
     ...(verification === undefined ? {} : { verification }),
+    ...(controls.completionCheck === undefined ? {} : { completionCheck: controls.completionCheck }),
+    ...(controls.maxTurns === undefined ? {} : { maxTurns: controls.maxTurns }),
   };
 }
 
@@ -317,6 +359,46 @@ export function editGoalState(
   };
 }
 
+export function updateGoalControlsState(
+  state: Exclude<GoalState, { status: "complete" }>,
+  controls: { completionCheck?: GoalCompletionCheck; maxTurns?: number },
+  now: number,
+): GoalState {
+  const stopped = stopGoalClock(state, now);
+  const { completionCheck: _completionCheck, maxTurns: _maxTurns, ...common } = stopped;
+  const nextCommon: GoalStateCommon = {
+    ...common,
+    revision: common.revision + 1,
+    updatedAt: now,
+    ...(controls.completionCheck === undefined ? {} : { completionCheck: controls.completionCheck }),
+    ...(controls.maxTurns === undefined ? {} : { maxTurns: controls.maxTurns }),
+  };
+  if (state.status === "active") {
+    return {
+      ...nextCommon,
+      status: "active",
+      activeStartedAt: now,
+      ...(state.result === undefined ? {} : { result: state.result }),
+      ...(state.blockerAudit === undefined ? {} : { blockerAudit: state.blockerAudit }),
+    };
+  }
+  if (state.status === "paused") {
+    return {
+      ...nextCommon,
+      status: "paused",
+      ...(state.result === undefined ? {} : { result: state.result }),
+      ...(state.blockerAudit === undefined ? {} : { blockerAudit: state.blockerAudit }),
+      ...(state.resumeAfterManualCompaction === undefined ? {} : { resumeAfterManualCompaction: true }),
+    };
+  }
+  return {
+    ...nextCommon,
+    status: "blocked",
+    result: state.result,
+    ...(state.blockerAudit === undefined ? {} : { blockerAudit: state.blockerAudit }),
+  };
+}
+
 export function beginGoalTurnState(
   current: Extract<GoalState, { status: "active" }>,
   now: number,

package/killeros/hooks.ts

@@ -1,12 +1,16 @@
+import { createHash } from "node:crypto";
 import {
   spawn,
   type SpawnOptionsWithStdioTuple,
 } from "node:child_process";
+import { EventEmitter } from "node:events";
 import { closeSync, existsSync, fstatSync, lstatSync, openSync, readSync, realpathSync } from "node:fs";
 import path from "node:path";
 import { StringDecoder } from "node:string_decoder";
 import { CONFIG_DIR_NAME, type ExtensionAPI, type ExtensionContext } from "@earendil-works/pi-coding-agent";
 import { errorMessage, reportError } from "./errors.ts";
+import { GOAL_CHECK_NAME_PATTERN } from "./goal-state.ts";
+import type { GoalCompletionCheck } from "./runtime.ts";
 import { safeTerminalText } from "./safe-terminal-text.ts";
 
 type KillerosHookEvent = "tool_call" | "tool_result" | "agent_settled";
@@ -17,8 +21,14 @@ interface KillerosHook {
   timeoutMs?: number;
 }
 
+interface KillerosGoalCheck {
+  command: string;
+  timeoutMs?: number;
+}
+
 interface KillerosHookConfig {
   hooks?: Partial<Record<KillerosHookEvent, KillerosHook[]>>;
+  goalChecks?: Record<string, KillerosGoalCheck>;
 }
 
 interface HookExecutionResult {
@@ -58,7 +68,10 @@ const HOOK_EVENTS: readonly KillerosHookEvent[] = ["tool_call", "tool_result", "
 const HOOK_CONFIG_LIMIT = 64 * 1024;
 const HOOK_OUTPUT_LIMIT = 16 * 1024;
 const HOOK_PAYLOAD_LIMIT = 8_000;
+const HOOK_TIMEOUT_DEFAULT_MS = 30_000;
 const HOOK_TIMEOUT_MAX_MS = 300_000;
+const GOAL_CHECK_LIMIT = 32;
+const GOAL_CHECK_COMMAND_LIMIT = 8_000;
 
 // Reads executable project configuration through a bounded, project-local file descriptor.
 function readHookConfig(configPath: string, projectRoot: string): string {
@@ -109,11 +122,12 @@ function isUnknownRecord(value: unknown): value is Record<string, unknown> {
   return typeof value === "object" && value !== null && !Array.isArray(value);
 }
 
-function loadKillerosHooks(ctx: ExtensionContext): KillerosHookConfig {
+function loadKillerosConfig(ctx: ExtensionContext, strictGoalChecks = false): KillerosHookConfig {
   const configPath = path.join(ctx.cwd, CONFIG_DIR_NAME, "killeros-hooks.json");
   if (!existsSync(configPath)) return {};
   const displayPath = safeTerminalText(configPath).replaceAll("\n", "");
   if (!ctx.isProjectTrusted()) {
+    if (strictGoalChecks) throw new Error("Goal completion checks require a trusted project");
     ctx.ui.notify(`Ignored untrusted project hooks in ${displayPath}`, "warning");
     return {};
   }
@@ -166,8 +180,35 @@ function loadKillerosHooks(ctx: ExtensionContext): KillerosHookConfig {
       }
       hooks[event] = accepted;
     }
-    return { hooks };
+
+    let goalChecks: Record<string, KillerosGoalCheck> | undefined;
+    try {
+      const candidates = parsed.goalChecks;
+      if (candidates !== undefined) {
+        if (!isUnknownRecord(candidates)) throw new Error("goalChecks must contain a JSON object");
+        const entries = Object.entries(candidates);
+        if (entries.length > GOAL_CHECK_LIMIT) throw new Error(`goalChecks may contain at most ${GOAL_CHECK_LIMIT} checks`);
+        goalChecks = {};
+        for (const [name, candidate] of entries) {
+          if (!GOAL_CHECK_NAME_PATTERN.test(name)) throw new Error(`Invalid goal check name: ${JSON.stringify(name)}`);
+          if (!isUnknownRecord(candidate)) throw new Error(`Goal check ${name} must contain a JSON object`);
+          const { command, timeoutMs } = candidate;
+          if (typeof command !== "string" || command.trim().length < 1 || command.trim().length > GOAL_CHECK_COMMAND_LIMIT) {
+            throw new Error(`Goal check ${name} command must contain 1 to ${GOAL_CHECK_COMMAND_LIMIT} characters`);
+          }
+          if (timeoutMs !== undefined && (typeof timeoutMs !== "number" || !Number.isSafeInteger(timeoutMs) || timeoutMs < 1 || timeoutMs > HOOK_TIMEOUT_MAX_MS)) {
+            throw new Error(`Goal check ${name} timeoutMs must be an integer from 1 to ${HOOK_TIMEOUT_MAX_MS}`);
+          }
+          goalChecks[name] = { command: command.trim(), ...(timeoutMs === undefined ? {} : { timeoutMs }) };
+        }
+      }
+    } catch (error) {
+      if (strictGoalChecks) throw error;
+      reportError(ctx, `Invalid ${CONFIG_DIR_NAME}/killeros-hooks.json goalChecks`, error);
+    }
+    return { hooks, ...(goalChecks === undefined ? {} : { goalChecks }) };
   } catch (error) {
+    if (strictGoalChecks) throw error;
     reportError(ctx, `Invalid ${CONFIG_DIR_NAME}/killeros-hooks.json`, error);
     return {};
   }
@@ -265,7 +306,7 @@ export function executeHook(
     command,
     cwd,
     environment,
-    timeoutMs = 30_000,
+    timeoutMs = HOOK_TIMEOUT_DEFAULT_MS,
     spawnProcess = spawn,
     signal,
   } = options;
@@ -331,18 +372,19 @@ export function executeHook(
         }, 2_000);
         return;
       }
-      terminateHookProcess(child, false);
       forceTimer = setTimeout(() => {
         if (completed) return;
         terminateHookProcess(child, true);
         settleTimer = setTimeout(() => finish(terminationCode(), true), 1_000);
       }, 1_000);
+      terminateHookProcess(child, false);
     };
     const abort = (): void => beginTermination("cancelled");
-    signal?.addEventListener("abort", abort, { once: true });
-    if (signal?.aborted) beginTermination("cancelled");
     child.stdout.on("data", (chunk) => appendBounded(stdout, chunk));
     child.stderr.on("data", (chunk) => appendBounded(stderr, chunk));
+    const captureStreamError = (error: Error): void => appendBounded(stderr, error.message);
+    if (child.stdout instanceof EventEmitter) child.stdout.on("error", captureStreamError);
+    if (child.stderr instanceof EventEmitter) child.stderr.on("error", captureStreamError);
     child.on("error", (error) => {
       appendBounded(stderr, error.message);
       if (!windowsCleanupPending) finish(termination ? terminationCode() : 1);
@@ -350,12 +392,23 @@ export function executeHook(
     child.once("close", (code) => {
       if (!windowsCleanupPending) finish(termination ? terminationCode() : code ?? 1);
     });
-    timer = setTimeout(() => beginTermination("timeout"), Math.max(1, Math.min(timeoutMs, HOOK_TIMEOUT_MAX_MS)));
+    if (completed) return;
+    const boundedTimeoutMs = Number.isNaN(timeoutMs)
+      ? HOOK_TIMEOUT_DEFAULT_MS
+      : Math.max(1, Math.min(timeoutMs, HOOK_TIMEOUT_MAX_MS));
+    timer = setTimeout(() => beginTermination("timeout"), boundedTimeoutMs);
+    signal?.addEventListener("abort", abort, { once: true });
+    if (signal?.aborted) beginTermination("cancelled");
   });
 }
 
 function serializeHookPayload(payload: unknown): string {
-  const serialized = JSON.stringify(payload) ?? "null";
+  let serialized: string;
+  try {
+    serialized = JSON.stringify(payload) ?? "null";
+  } catch {
+    return JSON.stringify({ serializationError: true });
+  }
   if (serialized.length <= HOOK_PAYLOAD_LIMIT) return serialized;
   const previewLength = Math.floor((HOOK_PAYLOAD_LIMIT - 64) / 2);
   return JSON.stringify({ truncated: true, preview: serialized.slice(0, previewLength) });
@@ -374,9 +427,51 @@ function hookFailureMessage(result: HookExecutionResult): string {
   return safeTerminalText(`Hook failed${result.timedOut ? " (timed out)" : ""}${result.exitUnconfirmed ? " (process exit unconfirmed)" : ""}\n${detail}`);
 }
 
+function goalCheckHash(check: KillerosGoalCheck): string {
+  return createHash("sha256")
+    .update(JSON.stringify({ command: check.command, timeoutMs: check.timeoutMs ?? HOOK_TIMEOUT_DEFAULT_MS }))
+    .digest("hex");
+}
+
+/** Lists validated completion-check names without exposing their definitions. */
+export function listGoalCompletionChecks(ctx: ExtensionContext): readonly string[] {
+  if (!ctx.isProjectTrusted()) throw new Error("Goal completion checks require a trusted project");
+  return Object.keys(loadKillerosConfig(ctx, true).goalChecks ?? {}).sort();
+}
+
+export function resolveGoalCompletionCheck(ctx: ExtensionContext, name: string): GoalCompletionCheck {
+  if (!GOAL_CHECK_NAME_PATTERN.test(name)) throw new Error("Invalid goal completion check name");
+  if (!ctx.isProjectTrusted()) throw new Error("Goal completion checks require a trusted project");
+  const check = loadKillerosConfig(ctx, true).goalChecks?.[name];
+  if (!check) throw new Error(`Unknown goal completion check: ${safeTerminalText(name)}`);
+  return { kind: "named-command", name, configHash: goalCheckHash(check) };
+}
+
+export async function runGoalCompletionCheck(
+  ctx: ExtensionContext,
+  bound: GoalCompletionCheck,
+  signal?: AbortSignal,
+): Promise<void> {
+  if (!ctx.isProjectTrusted()) throw new Error("Goal completion checks require a trusted project");
+  const check = loadKillerosConfig(ctx, true).goalChecks?.[bound.name];
+  if (!check) throw new Error(`Unknown goal completion check: ${safeTerminalText(bound.name)}`);
+  if (goalCheckHash(check) !== bound.configHash) {
+    throw new Error(`Goal completion check ${safeTerminalText(bound.name)} changed; run /goal check ${safeTerminalText(bound.name)} to approve it`);
+  }
+  const result = await executeHook({
+    command: check.command,
+    cwd: ctx.cwd,
+    environment: { KILLEROS_EVENT: "goal_check", KILLEROS_GOAL_CHECK: bound.name },
+    timeoutMs: check.timeoutMs,
+    signal,
+  });
+  if (result.cancelled) throw new Error(`Goal completion check ${safeTerminalText(bound.name)} was cancelled`);
+  if (result.code !== 0) throw new Error(hookFailureMessage(result).replace(/^Hook failed/u, `Goal completion check ${safeTerminalText(bound.name)} failed`));
+}
+
 export function registerLifecycleHooks(pi: ExtensionAPI): void {
   let config: KillerosHookConfig = {};
-  pi.on("session_start", (_event, ctx) => { config = loadKillerosHooks(ctx); });
+  pi.on("session_start", (_event, ctx) => { config = loadKillerosConfig(ctx); });
 
   pi.on("tool_call", async (event, ctx) => {
     for (const hook of config.hooks?.tool_call ?? []) {

package/killeros/runtime.ts

@@ -26,6 +26,7 @@ export interface GoalBlockerAudit {
   key: string;
   streak: number;
   lastTurn: number;
+  evidence?: string;
 }
 
 export type GoalFileBaseline =
@@ -38,6 +39,12 @@ export interface GoalFileVerification {
   baseline: GoalFileBaseline;
 }
 
+export interface GoalCompletionCheck {
+  kind: "named-command";
+  name: string;
+  configHash: string;
+}
+
 export interface GoalStateCommon {
   version: 1;
   revision: number;
@@ -49,6 +56,8 @@ export interface GoalStateCommon {
   blockedAuditStartTurn: number;
   baselineTokens: number;
   verification?: GoalFileVerification;
+  completionCheck?: GoalCompletionCheck;
+  maxTurns?: number;
 }
 
 export type GoalState = GoalStateCommon & (