talon-agent 5.24.1 → 5.25.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "talon-agent",
-  "version": "5.24.1",
+  "version": "5.25.1",
   "description": "Multi-frontend AI agent with full tool access, streaming, cron jobs, and plugin system",
   "author": "The Falconry",
   "license": "Apache-2.0",
@@ -90,6 +90,7 @@
     "knip": "knip",
     "format": "prettier --write src/ prompts/",
     "format:check": "prettier --check src/ prompts/",
+    "preflight": "bash scripts/preflight.sh",
     "ci:protect": "node .github/scripts/enforce-ci-gate.mjs",
     "build:gleam": "cd native/scheduler-core && gleam build --target javascript && node embed.mjs",
     "build:zig": "node native/textops-wasm/build.mjs",

package/src/core/agents/index.ts

@@ -33,5 +33,5 @@ export {
   deliverToAgent,
   initAgentDelivery,
 } from "./delivery.js";
-export { describeParent } from "./prompt.js";
+export { describeParent, wantsPreflight } from "./prompt.js";
 export type { AgentCaps, AgentParent, AgentRecord } from "./types.js";

package/src/core/agents/prompt.ts

@@ -50,11 +50,38 @@ export function buildAgentSystemPrompt(args: {
   });
 }
 
+/**
+ * The standing pre-flight instruction appended to a PR-opening agent's
+ * brief: run the light CI suite locally, push only on green. GitHub then
+ * confirms a change instead of being the first compiler it meets.
+ */
+const PREFLIGHT_INSTRUCTION =
+  "[Pre-flight lane] Before every `git push`, run `npm run preflight` in " +
+  "the repo (or call the run_preflight tool with cwd set to your checkout). " +
+  "Push only when it is green. If it is red, fix it — or, when a failure " +
+  "is genuinely out of scope, say in the PR body which step failed and why " +
+  "you pushed anyway.";
+
+/** A brief that opens, updates or talks about a pull request. */
+const PR_BRIEF = /\bPRs?\b|pull[ -]requests?/i;
+
+/**
+ * Whether a spawn gets the pre-flight instruction: the caller's explicit
+ * choice when given, otherwise on for any brief that mentions a PR.
+ */
+export function wantsPreflight(brief: string, explicit?: boolean): boolean {
+  return explicit ?? PR_BRIEF.test(brief);
+}
+
 /** The activation prompt — the brief, framed as the job to start on. */
-export function buildAgentPrompt(brief: string): string {
+export function buildAgentPrompt(
+  brief: string,
+  options: { preflight?: boolean } = {},
+): string {
+  const lane = options.preflight ? `\n\n${PREFLIGHT_INSTRUCTION}` : "";
   return (
     `[System: AGENT BRIEF. Work this to a conclusion, then call ` +
-    `report_result exactly once.]\n\n${brief}`
+    `report_result exactly once.]\n\n${brief}${lane}`
   );
 }
 

package/src/core/agents/runner.ts

@@ -308,7 +308,9 @@ async function buildRunParams(
     agentLogHeader(record, model),
   );
   return {
-    prompt: buildAgentPrompt(record.brief),
+    prompt: buildAgentPrompt(record.brief, {
+      preflight: spec.preflight === true,
+    }),
     systemPrompt: buildAgentSystemPrompt({
       agentId: record.id,
       label: record.label,

package/src/core/agents/types.ts

@@ -101,6 +101,12 @@ export interface AgentSpawnSpec {
   readonly reasoningEffort?: ReasoningEffortLevel;
   /** Hard wall-clock cap. Defaults to `agents.defaultTimeoutMs`. */
   readonly timeoutMs?: number;
+  /**
+   * Append the pre-flight lane instruction (run `npm run preflight` before
+   * every push) to the brief. Resolved by the spawn tool: explicit value,
+   * else on when the brief mentions a PR.
+   */
+  readonly preflight?: boolean;
 }
 
 /** `spawnAgent`'s answer — an error here is a tool error, never a throw. */

package/src/core/engine/gateway-actions/agents/control.ts

@@ -20,6 +20,7 @@ import {
   getAgentCaps,
   killAgent,
   spawnAgent,
+  wantsPreflight,
   type AgentParent,
   type AgentRecord,
 } from "../../../agents/index.js";
@@ -150,6 +151,7 @@ function readSpawnBody(body: Record<string, unknown>):
       model?: string;
       reasoningEffort?: ReasoningEffortLevel;
       timeoutMs?: number;
+      preflight: boolean;
     }
   | { ok: false; error: string } {
   const brief = String(body.brief ?? "").trim();
@@ -168,10 +170,15 @@ function readSpawnBody(body: Record<string, unknown>):
   if (timeoutS !== undefined && !Number.isFinite(timeoutS)) {
     return { ok: false, error: "timeout_s must be a number of seconds" };
   }
+  const preflight = body.preflight;
+  if (preflight !== undefined && typeof preflight !== "boolean") {
+    return { ok: false, error: "preflight must be true or false" };
+  }
   return {
     ok: true,
     brief,
     label,
+    preflight: wantsPreflight(brief, preflight),
     ...(body.backend ? { backendId: String(body.backend) } : {}),
     ...(body.model ? { model: String(body.model) } : {}),
     ...(effort !== undefined
@@ -200,6 +207,7 @@ export const agentControlHandlers: SharedActionHandlers = {
       ...(parsed.timeoutMs !== undefined
         ? { timeoutMs: parsed.timeoutMs }
         : {}),
+      preflight: parsed.preflight,
     });
     if (!outcome.ok) return { ok: false, error: outcome.error };
     const timeoutS = Math.round(clampTimeout(parsed.timeoutMs) / 1000);
@@ -211,6 +219,7 @@ export const agentControlHandlers: SharedActionHandlers = {
         `Backend: ${outcome.backendId}/${outcome.model}` +
         `${outcome.routing ? ` (routed: ${outcome.routing})` : ""}\n` +
         `Timeout: ${timeoutS}s\n` +
+        (parsed.preflight ? `Pre-flight lane: on\n` : "") +
         `It runs in the background. You will be woken with its report — ` +
         `carry on with what you were doing.`,
     };

package/src/core/engine/gateway-actions/agents/index.ts

@@ -6,6 +6,8 @@
  *   - `report`  — what a sub-agent calls about itself and its siblings:
  *     report_result / message_parent / check_inbox / list_peers /
  *     message_peer.
+ *   - `preflight` — run_preflight: the pre-flight lane (light CI suite) in
+ *     the caller's checkout, so an agent pushes only on green.
  *
  * Both sets are reachable from an `agent:<id>` context: the gateway routes
  * those chat keys straight here (see `Gateway.handleAction`), because a
@@ -15,11 +17,13 @@
 
 import type { SharedActionHandlers } from "../types.js";
 import { agentControlHandlers } from "./control.js";
+import { agentPreflightHandlers } from "./preflight.js";
 import { agentReportHandlers } from "./report.js";
 
 export const agentHandlers: SharedActionHandlers = {
   ...agentControlHandlers,
   ...agentReportHandlers,
+  ...agentPreflightHandlers,
 };
 
 /**

package/src/core/engine/gateway-actions/agents/preflight.ts

@@ -0,0 +1,215 @@
+/**
+ * `run_preflight` — run a checkout's pre-flight lane and return its verdict.
+ *
+ * The pre-flight lane (`scripts/preflight.sh`, `npm run preflight`) is the
+ * light CI suite an agent runs before `git push`, so GitHub confirms a change
+ * instead of being the first compiler it meets. This action runs it in the
+ * caller's checkout on the daemon host and answers with the one-line verdict,
+ * the per-step table and the tail of every failing step's log — enough to
+ * fix the change without re-running anything by hand.
+ *
+ * Available from a chat and from inside a sub-agent (it is in
+ * `agentContextActions`), because agents are the ones opening PRs.
+ */
+
+import { spawn } from "node:child_process";
+import { readFile, stat } from "node:fs/promises";
+import { join } from "node:path";
+import { dirs } from "../../../../util/paths.js";
+import { resolvePathParam } from "../native/params.js";
+import type { ActionResult } from "../../../types.js";
+import type { SharedActionHandlers } from "../types.js";
+
+/** Relative path of the lane inside a checkout. */
+const SCRIPT = join("scripts", "preflight.sh");
+/** Hard cap on one run. The lane targets ≤5 min; this is the backstop. */
+const PREFLIGHT_TIMEOUT_MS = 600_000;
+/** Grace between SIGTERM and SIGKILL of the run's process group. */
+const KILL_GRACE_MS = 5_000;
+/** Lines of each failing step's log to hand back. */
+const FAIL_TAIL_LINES = 30;
+
+interface PreflightStep {
+  readonly name: string;
+  readonly status: "pass" | "fail" | "skipped";
+  readonly ms: number;
+  readonly note?: string;
+}
+
+interface PreflightSummary {
+  readonly verdict: "green" | "red";
+  readonly ok: boolean;
+  readonly base: string;
+  readonly totalMs: number;
+  readonly failed: readonly string[];
+  readonly steps: readonly PreflightStep[];
+}
+
+interface RunOutcome {
+  readonly code: number | null;
+  readonly timedOut: boolean;
+  readonly output: string;
+}
+
+/** The checkout root for `dir`: its git toplevel, else `dir` itself. */
+function repoRoot(dir: string): Promise<string> {
+  return new Promise((resolveRoot) => {
+    const child = spawn("git", ["rev-parse", "--show-toplevel"], { cwd: dir });
+    let out = "";
+    child.stdout.on("data", (chunk: Buffer) => (out += chunk.toString()));
+    child.on("error", () => resolveRoot(dir));
+    child.on("close", (code) =>
+      resolveRoot(code === 0 && out.trim() ? out.trim() : dir),
+    );
+  });
+}
+
+async function isFile(path: string): Promise<boolean> {
+  try {
+    return (await stat(path)).isFile();
+  } catch {
+    return false;
+  }
+}
+
+/** Run the lane in its own process group so a timeout takes every child. */
+function runLane(root: string, timeoutMs: number): Promise<RunOutcome> {
+  return new Promise((resolveRun) => {
+    const child = spawn("bash", [SCRIPT], {
+      cwd: root,
+      detached: process.platform !== "win32",
+      env: { ...process.env, PREFLIGHT_QUIET: "1", CI: "1" },
+    });
+    let output = "";
+    const keep = (chunk: Buffer): void => {
+      output = (output + chunk.toString()).slice(-8_000);
+    };
+    child.stdout.on("data", keep);
+    child.stderr.on("data", keep);
+    let timedOut = false;
+    const killGroup = (signal: NodeJS.Signals): void => {
+      try {
+        if (child.pid && process.platform !== "win32") {
+          process.kill(-child.pid, signal);
+        } else child.kill(signal);
+      } catch {
+        // Already gone.
+      }
+    };
+    const timer = setTimeout(() => {
+      timedOut = true;
+      killGroup("SIGTERM");
+      setTimeout(() => killGroup("SIGKILL"), KILL_GRACE_MS).unref();
+    }, timeoutMs);
+    child.on("error", (err) => {
+      clearTimeout(timer);
+      resolveRun({ code: null, timedOut, output: String(err) });
+    });
+    child.on("close", (code) => {
+      clearTimeout(timer);
+      resolveRun({ code, timedOut, output });
+    });
+  });
+}
+
+async function readSummary(root: string): Promise<PreflightSummary | null> {
+  try {
+    const raw = await readFile(join(root, ".preflight", "last.json"), "utf8");
+    return JSON.parse(raw) as PreflightSummary;
+  } catch {
+    return null;
+  }
+}
+
+async function logTail(root: string, step: string): Promise<string> {
+  try {
+    const raw = await readFile(join(root, ".preflight", `${step}.log`), "utf8");
+    return raw.trimEnd().split("\n").slice(-FAIL_TAIL_LINES).join("\n");
+  } catch {
+    return "(no log)";
+  }
+}
+
+function stepLine(step: PreflightStep): string {
+  const mark =
+    step.status === "pass" ? "✓" : step.status === "fail" ? "✗" : "·";
+  const time =
+    step.status === "skipped" ? "" : ` (${Math.round(step.ms / 1000)}s)`;
+  const note = step.status === "skipped" && step.note ? ` — ${step.note}` : "";
+  return `${mark} ${step.name}${time}${note}`;
+}
+
+/** Render the summary a model can act on: verdict, table, failing tails. */
+async function renderPreflight(
+  root: string,
+  summary: PreflightSummary,
+): Promise<string> {
+  const verdict = summary.ok
+    ? `Pre-flight GREEN in ${Math.round(summary.totalMs / 1000)}s — safe to push.`
+    : `Pre-flight RED in ${Math.round(summary.totalMs / 1000)}s — failed: ` +
+      `${summary.failed.join(", ")}. Fix before pushing, or explain in the PR body.`;
+  const parts = [
+    verdict,
+    `Base: ${summary.base}. Summary: ${join(root, ".preflight", "last.json")}`,
+    "",
+    ...summary.steps.map(stepLine),
+  ];
+  for (const name of summary.failed) {
+    parts.push("", `── ${name} (last ${FAIL_TAIL_LINES} lines) ──`);
+    parts.push(await logTail(root, name));
+  }
+  return parts.join("\n");
+}
+
+/** Run the lane in `dir`'s checkout and describe the result. */
+async function runPreflight(
+  dir: string,
+  timeoutMs: number = PREFLIGHT_TIMEOUT_MS,
+): Promise<ActionResult> {
+  try {
+    if (!(await stat(dir)).isDirectory()) {
+      return { ok: false, error: `cwd is not a directory: ${dir}` };
+    }
+  } catch {
+    return { ok: false, error: `Working directory does not exist: ${dir}` };
+  }
+  const root = await repoRoot(dir);
+  if (!(await isFile(join(root, SCRIPT)))) {
+    return {
+      ok: false,
+      error:
+        `No ${SCRIPT} in ${root}. Pass cwd = the root of a talon checkout ` +
+        `(a branch that has the pre-flight lane).`,
+    };
+  }
+  const run = await runLane(root, timeoutMs);
+  if (run.timedOut) {
+    return {
+      ok: false,
+      error:
+        `Pre-flight did not finish within ${Math.round(timeoutMs / 1000)}s ` +
+        `and was killed. Tail of its output:\n${run.output.slice(-2_000)}`,
+    };
+  }
+  const summary = await readSummary(root);
+  if (!summary) {
+    return {
+      ok: false,
+      error:
+        `Pre-flight exited ${run.code} without writing .preflight/last.json. ` +
+        `Output:\n${run.output.slice(-2_000)}`,
+    };
+  }
+  // A red lane is a successful tool call with a red verdict — the model is
+  // meant to read it and act, not treat it as the tool breaking.
+  return { ok: true, text: await renderPreflight(root, summary) };
+}
+
+export const agentPreflightHandlers: SharedActionHandlers = {
+  run_preflight: (body) => {
+    const raw =
+      typeof body.cwd === "string" && body.cwd.trim() ? body.cwd.trim() : "";
+    const dir = raw ? resolvePathParam(raw, undefined) : dirs.workspace;
+    return runPreflight(dir);
+  },
+};

package/src/core/tools/bridge.ts

@@ -28,6 +28,8 @@ const LONG_ACTION_TIMEOUTS_MS: Record<string, number> = {
   // must sit above it so the layer that gives up is the tool (which reports
   // the agent's live state), never the transport.
   wait_for_agent: 180_000,
+  // The pre-flight lane caps itself at 600s; same margin rule as above.
+  run_preflight: 660_000,
   device_pull_file: 3_600_000,
   device_push_file: 3_600_000,
   device_read_file: 3_600_000,

package/src/core/tools/index.ts

@@ -15,7 +15,7 @@ import { mediaTools } from "./chat/media.js";
 import { stickerTools } from "./chat/stickers.js";
 import { schedulingTools } from "./ops/scheduling.js";
 import { triggerTools } from "./ops/triggers.js";
-import { agentTools } from "./ops/agents.js";
+import { agentTools, preflightTools } from "./ops/agents.js";
 import { goalTools } from "./ops/goals.js";
 import { memoryTools } from "./content/memory.js";
 import { scriptTools } from "./ops/scripts.js";
@@ -56,6 +56,7 @@ export const ALL_TOOLS: readonly ToolDefinition[] = [
   // system prompt (see compose-tools.test.ts).
   ...agentTools,
   ...backupTools,
+  ...preflightTools,
 ];
 
 /**

package/src/core/tools/ops/agents.ts

@@ -83,6 +83,12 @@ export const agentTools: ToolDefinition[] = [
         .describe(
           "Hard wall-clock cap in seconds (default 900, min 30, max 3600). On timeout the agent is aborted and you are told.",
         ),
+      preflight: z
+        .boolean()
+        .optional()
+        .describe(
+          "Tell the agent to run the pre-flight lane (`npm run preflight` / run_preflight) before every git push and push only on green. Default: on when the brief mentions a PR, off otherwise.",
+        ),
     },
     execute: (params, bridge) => bridge("spawn_agent", params),
     tag: "agents",
@@ -214,3 +220,25 @@ export const agentTools: ToolDefinition[] = [
     tag: "agents",
   },
 ];
+
+/**
+ * The pre-flight lane tool. Its own list so it can be appended at the END of
+ * ALL_TOOLS (the prompt-cache prefix) rather than beside the agent family.
+ */
+export const preflightTools: ToolDefinition[] = [
+  {
+    name: "run_preflight",
+    description:
+      "Run the pre-flight lane (`npm run preflight`: typecheck, lint, format, architecture/knip/ratchet gates, the unit tests touched by your diff, gitleaks) in a talon checkout on the daemon host and get its verdict. Run it before every `git push` on a PR branch and push only when it is GREEN; a RED result lists each failing step with the tail of its log. Takes a few minutes (hard cap 10). Needs `npm ci` done in the checkout.",
+    schema: {
+      cwd: z
+        .string()
+        .optional()
+        .describe(
+          "Path inside the checkout to check (its git root is used), e.g. /tmp/fix-foo. Defaults to the workspace.",
+        ),
+    },
+    execute: (params, bridge) => bridge("run_preflight", params),
+    tag: "agents",
+  },
+];