@pylonsync/functions 0.4.27 → 0.4.28

package/dist/agent.d.ts

@@ -57,8 +57,11 @@ export interface AgentDefinition {
     tools?: Record<string, AgentTool>;
     /** Model override (subject to the server's allowlist). */
     model?: string;
-    /** Max model↔tool round-trips per invocation (default 16). Hitting
-     *  the cap fails the run rather than looping forever. */
+    /** Max model↔tool round-trips per invocation (default 64). Hitting
+     *  the cap fails the run rather than looping forever. Steering input
+     *  drained mid-invocation extends the same invocation, so this bounds
+     *  a steered turn too. The run row's cumulative `steps` counts every
+     *  invocation and is not capped. */
     maxSteps?: number;
     /** max_tokens per completion (default: server default). */
     maxTokens?: number;
@@ -70,13 +73,19 @@ export interface AgentDefinition {
 }
 /** The synthesized action's args. */
 export interface AgentCallArgs {
-    /** The user's message for this turn. */
-    input: string;
+    /** The user's message for this turn. Required unless `cancel`. */
+    input?: string;
     /** Continue an existing run (must belong to the caller and this
-     *  agent). Omit to start a new run. */
+     *  agent). Omit to start a new run. Sending while the run is already
+     *  generating queues the message for that generation rather than
+     *  refusing it — see {@link AgentResult.queued}. */
     runId?: string;
     /** Optional display title, stored on new runs. */
     title?: string;
+    /** Ask the run to stop. Requires `runId`, ignores `input`, and
+     *  returns as soon as the request is recorded — a live generation
+     *  stops at its next turn boundary. */
+    cancel?: boolean;
 }
 /** What the agent action resolves with (also the `event: result`
  *  payload on the SSE stream). */
@@ -84,12 +93,19 @@ export interface AgentResult {
     runId: string;
     /** Concatenated text of the final assistant message. */
     text: string;
-    /** Round-trips consumed. */
+    /** Round-trips consumed by THIS invocation. */
     steps: number;
     usage: {
         input_tokens: number;
         output_tokens: number;
     };
+    /** The message was queued onto a generation already in flight
+     *  instead of starting a turn. No model call happened on this call;
+     *  the running loop picks the message up at its next boundary. */
+    queued?: boolean;
+    /** The run stopped because cancel was requested. `text` holds
+     *  whatever the model had produced by then. */
+    cancelled?: boolean;
 }
 /** Convert one `v.*` validator to a JSON-Schema fragment. */
 export declare function validatorToJsonSchema(val: AnyValidator): Record<string, unknown>;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pylonsync/functions",
-  "version": "0.4.27",
+  "version": "0.4.28",
   "description": "TypeScript function runtime for pylon — defines server-side queries, mutations, and actions.",
   "type": "module",
   "main": "src/index.ts",

package/src/agent-internals.ts

@@ -20,10 +20,23 @@ interface RunRow {
   [key: string]: unknown;
 }
 
+/** Bounds on the steering queue. A user typing at a busy run must not
+ *  be able to grow one row without limit, and the drained text is
+ *  replayed into model context, so it is billed. */
+const MAX_PENDING_INPUTS = 32;
+const MAX_PENDING_CHARS = 32 * 1024;
+
 function nowIso(): string {
   return new Date().toISOString();
 }
 
+/** The steering queue as a string list, tolerating a null/garbled column. */
+function pendingInputOf(run: Record<string, unknown>): string[] {
+  const raw = run.pendingInput;
+  if (!Array.isArray(raw)) return [];
+  return raw.filter((v): v is string => typeof v === "string");
+}
+
 /** Ownership fence: admins pass; otherwise the run must belong to the
  *  caller. Missing and foreign runs are indistinguishable (NOT_FOUND). */
 function requireOwnedRun(
@@ -61,6 +74,27 @@ export function registerAgentInternals(
     },
   } as unknown as FnDefinition);
 
+  // Liveness probe for a loop that is mid-turn. Deliberately does NOT
+  // load the transcript the way __pylon_agent_read does — the loop
+  // calls this on a timer while a tool handler runs, and pulling every
+  // message each time would scale the poll cost with the conversation.
+  registry.set("__pylon_agent_poll", {
+    type: "query",
+    internal: true,
+    auth: "user",
+    handler: async (ctx: QueryCtx, args: Record<string, unknown>) => {
+      const run = requireOwnedRun(
+        ctx,
+        await ctx.db.get("AgentRun", String(args.runId ?? "")),
+      );
+      return {
+        status: run.status,
+        cancelRequested: run.cancelRequested === true,
+        pending: pendingInputOf(run).length,
+      };
+    },
+  } as unknown as FnDefinition);
+
   registry.set("__pylon_agent_write", {
     type: "mutation",
     internal: true,
@@ -91,6 +125,9 @@ export function registerAgentInternals(
             title: args.title ?? null,
             streamId: null,
             error: null,
+            pendingInput: [],
+            cancelRequested: false,
+            steps: 0,
             createdAt: nowIso(),
             updatedAt: nowIso(),
           });
@@ -126,10 +163,12 @@ export function registerAgentInternals(
         case "setStatus": {
           const runId = String(args.runId ?? "");
           const run = requireOwnedRun(ctx, await ctx.db.get("AgentRun", runId));
-          // The loop's pre-flight RUN_BUSY check races with itself
-          // across concurrent turns; this in-transaction guard is the
-          // authoritative claim. A "running" row older than staleMs is
-          // a dead generation (process crash) and may be taken over.
+          // The authoritative claim on the run. A caller that finds
+          // the run live queues its message instead of reaching here,
+          // so this guards the narrower race: two turns that both read
+          // a non-running row and both try to start generating. A
+          // "running" row older than staleMs is a dead generation
+          // (process crash) and may be taken over.
           if (args.guardNotRunning === true && run.status === "running") {
             const staleMs = Number(args.staleMs) || 0;
             const updatedAt = Date.parse(String(run.updatedAt ?? "")) || 0;
@@ -141,15 +180,109 @@ export function registerAgentInternals(
               throw err;
             }
           }
+          const status = String(args.status ?? "idle");
           const patch: Record<string, unknown> = {
-            status: String(args.status ?? "idle"),
+            status,
             updatedAt: nowIso(),
           };
           if (args.error !== undefined) patch.error = args.error;
           if (args.streamId !== undefined) patch.streamId = args.streamId;
+          if (args.steps !== undefined) patch.steps = Number(args.steps) || 0;
+          // Claiming the run starts a new generation, which supersedes
+          // a cancel left set by one that died before acting on it.
+          // Terminal statuses clear it because it has been honoured.
+          if (status === "running" || status === "cancelled") {
+            patch.cancelRequested = false;
+          }
           const updated = await ctx.db.update("AgentRun", runId, patch);
           return { updated };
         }
+        case "enqueueInput": {
+          // Steering: the caller sent a message while a generation was
+          // in flight. Queue it on the run instead of refusing it; the
+          // loop folds it into the transcript at the next turn
+          // boundary, where the message order stays replayable.
+          const runId = String(args.runId ?? "");
+          const run = requireOwnedRun(ctx, await ctx.db.get("AgentRun", runId));
+          const input = String(args.input ?? "");
+          if (input === "") {
+            const err = new Error("Steering input must not be empty");
+            (err as { code?: string }).code = "AGENT_INPUT_REQUIRED";
+            throw err;
+          }
+          const queue = pendingInputOf(run);
+          const chars =
+            queue.reduce((n, s) => n + s.length, 0) + input.length;
+          if (queue.length >= MAX_PENDING_INPUTS || chars > MAX_PENDING_CHARS) {
+            const err = new Error(
+              "Too much input queued for this run — wait for the agent to catch up",
+            );
+            (err as { code?: string }).code = "AGENT_INPUT_QUEUE_FULL";
+            throw err;
+          }
+          queue.push(input);
+          // Deliberately NOT touching updatedAt: that column is the
+          // liveness clock the staleness takeover reads. Bumping it
+          // here would let a user typing at a dead generation keep it
+          // looking alive forever.
+          await ctx.db.update("AgentRun", runId, { pendingInput: queue });
+          return { queued: queue.length };
+        }
+        case "drainInput": {
+          // One atomic turn-boundary check: take everything queued,
+          // report whether cancel was requested, and (at the terminal
+          // boundary) settle the run as completed only if nothing
+          // arrived in the meantime. Doing all three in one
+          // transaction is what closes the race where a message lands
+          // between the last turn and the completed write.
+          const runId = String(args.runId ?? "");
+          const run = requireOwnedRun(ctx, await ctx.db.get("AgentRun", runId));
+          const queue = pendingInputOf(run);
+          const cancelRequested = run.cancelRequested === true;
+          const patch: Record<string, unknown> = { updatedAt: nowIso() };
+          if (queue.length > 0) patch.pendingInput = [];
+          if (args.steps !== undefined) patch.steps = Number(args.steps) || 0;
+          let completed = false;
+          if (
+            queue.length === 0 &&
+            !cancelRequested &&
+            args.completeIfEmpty === true
+          ) {
+            patch.status = "completed";
+            completed = true;
+          }
+          await ctx.db.update("AgentRun", runId, patch);
+          return { input: queue, cancelRequested, completed };
+        }
+        case "requestCancel": {
+          const runId = String(args.runId ?? "");
+          const run = requireOwnedRun(ctx, await ctx.db.get("AgentRun", runId));
+          const agent = args.agent === undefined ? null : String(args.agent);
+          if (agent !== null && run.agent !== agent) {
+            const err = new Error(
+              `Run ${runId} belongs to agent "${run.agent}"`,
+            );
+            (err as { code?: string }).code = "AGENT_MISMATCH";
+            throw err;
+          }
+          if (run.status === "running") {
+            // A generation is live. Raise the flag and let the loop
+            // honour it at its next boundary — it owns the terminal
+            // write, so racing it here would garble the transcript.
+            // updatedAt stays put so the staleness clock keeps running.
+            await ctx.db.update("AgentRun", runId, { cancelRequested: true });
+            return { status: "running", accepted: true };
+          }
+          // Nothing is generating, so there is no loop to honour it:
+          // settle terminally and drop anything queued.
+          await ctx.db.update("AgentRun", runId, {
+            status: "cancelled",
+            cancelRequested: false,
+            pendingInput: [],
+            updatedAt: nowIso(),
+          });
+          return { status: "cancelled", accepted: true };
+        }
         default: {
           const err = new Error(`Unknown agent write op "${op}"`);
           (err as { code?: string }).code = "INVALID_OP";

package/src/agent.test.ts

@@ -77,9 +77,23 @@ interface ReadOverride {
   messages?: Array<Record<string, unknown>>;
 }
 
+/** Mutable stand-in for the AgentRun columns the loop steers on, so a
+ *  test can simulate a message or a cancel landing mid-run. */
+interface RunState {
+  pendingInput: string[];
+  cancelRequested: boolean;
+  status: string;
+}
+
 function mockCtx(script: LlmCompleteResponse[], read?: ReadOverride) {
   const writes: WriteOp[] = [];
   const streamed: Array<{ event?: string; data: string }> = [];
+  const state: RunState = {
+    pendingInput: [],
+    cancelRequested: false,
+    status: "running",
+  };
+  let polls = 0;
   let call = 0;
   const ctx = {
     auth: { userId: "u1", isAdmin: false, tenantId: null, roles: [] },
@@ -116,6 +130,14 @@ function mockCtx(script: LlmCompleteResponse[], read?: ReadOverride) {
       },
     },
     async runQuery(name: string, args: Record<string, unknown>) {
+      if (name === "__pylon_agent_poll") {
+        polls += 1;
+        return {
+          status: state.status,
+          cancelRequested: state.cancelRequested,
+          pending: state.pendingInput.length,
+        };
+      }
       if (name === "__pylon_agent_read") {
         return {
           run: {
@@ -142,6 +164,32 @@ function mockCtx(script: LlmCompleteResponse[], read?: ReadOverride) {
       writes.push(args as WriteOp);
       if (args.op === "createRun") return { id: "run_1" };
       if (args.op === "appendMessage") return { id: "m", seq: writes.length };
+      // Mirrors agent-internals' transactional semantics: take the
+      // queue, report the cancel flag, and settle only when nothing
+      // arrived and no cancel is pending.
+      if (args.op === "drainInput") {
+        const input = state.pendingInput.slice();
+        state.pendingInput = [];
+        let completed = false;
+        if (
+          input.length === 0 &&
+          !state.cancelRequested &&
+          args.completeIfEmpty === true
+        ) {
+          state.status = "completed";
+          completed = true;
+        }
+        return { input, cancelRequested: state.cancelRequested, completed };
+      }
+      if (args.op === "enqueueInput") {
+        state.pendingInput.push(String(args.input));
+        return { queued: state.pendingInput.length };
+      }
+      if (args.op === "requestCancel") {
+        state.cancelRequested = true;
+        return { status: state.status, accepted: true };
+      }
+      if (args.op === "setStatus") state.status = String(args.status);
       return { updated: true };
     },
     error(code: string, message: string) {
@@ -150,7 +198,13 @@ function mockCtx(script: LlmCompleteResponse[], read?: ReadOverride) {
       return err;
     },
   };
-  return { ctx: ctx as unknown as ActionCtx, writes, streamed };
+  return {
+    ctx: ctx as unknown as ActionCtx,
+    writes,
+    streamed,
+    state,
+    pollCount: () => polls,
+  };
 }
 
 const done = (text: string): LlmCompleteResponse => ({
@@ -222,23 +276,30 @@ describe("agent loop", () => {
     expect(toolCalls).toEqual([{ q: "pylon" }]);
 
     // Write sequence: createRun, CLAIM (running, guarded, +streamId),
-    // user msg, assistant(tool_use), tool_result, assistant(final),
-    // completed. The claim precedes every message write so a losing
-    // racer never persists a stray turn.
+    // user msg, assistant(tool_use), the tool boundary's drain,
+    // tool_result, assistant(final), then the terminal drain — which
+    // settles the run itself, so there is no separate completed write.
+    // The claim precedes every message write so a losing racer never
+    // persists a stray turn.
     expect(writes.map((w) => `${w.op}:${w.role ?? w.status ?? ""}`)).toEqual([
       "createRun:",
       "setStatus:running",
       "appendMessage:user",
       "appendMessage:assistant",
+      "drainInput:",
       "appendMessage:user", // tool_result batch
       "appendMessage:assistant",
-      "setStatus:completed",
+      "drainInput:",
     ]);
     const running = writes.find((w) => w.status === "running")!;
     expect(running.streamId).toBe("st_test");
     expect(running.guardNotRunning).toBe(true);
     expect(Number(running.staleMs)).toBeGreaterThan(0);
-    const toolResultMsg = writes[4];
+    // The terminal drain settles the run in the same transaction that
+    // proves nothing was queued.
+    const terminal = writes[writes.length - 1];
+    expect(terminal.completeIfEmpty).toBe(true);
+    const toolResultMsg = writes[5];
     const blocks = toolResultMsg.content as Array<Record<string, unknown>>;
     expect(blocks[0].type).toBe("tool_result");
     expect(blocks[0].tool_use_id).toBe("tu_1");
@@ -331,22 +392,27 @@ describe("agent loop", () => {
     ).rejects.toThrow(/belongs to agent/);
   });
 
-  test("a fresh running run is RUN_BUSY; a stale one is taken over", async () => {
+  test("a message to a live run is queued, not refused; a stale one is taken over", async () => {
     const def = agent({ timeout: 600 });
     const busy = mockCtx([done("never")], {
       run: { status: "running", updatedAt: new Date().toISOString() },
     });
-    await expect(
-      (def.handler as unknown as (
-        c: ActionCtx,
-        a: Record<string, unknown>,
-      ) => Promise<unknown>)(busy.ctx, {
-        input: "x",
-        runId: "run_9",
-        __agentName: "helper",
-      }),
-    ).rejects.toThrow(/already generating/);
-    expect(busy.writes).toHaveLength(0);
+    const queued = await (def.handler as unknown as (
+      c: ActionCtx,
+      a: Record<string, unknown>,
+    ) => Promise<Record<string, unknown>>)(busy.ctx, {
+      input: "actually, use the other file",
+      runId: "run_9",
+      __agentName: "helper",
+    });
+    // Steering: the message lands on the queue and no turn starts.
+    expect(queued.queued).toBe(true);
+    expect(queued.runId).toBe("run_9");
+    expect(queued.steps).toBe(0);
+    expect(busy.state.pendingInput).toEqual(["actually, use the other file"]);
+    expect(busy.writes.map((w) => w.op)).toEqual(["enqueueInput"]);
+    // No claim, no transcript write — the live generation owns those.
+    expect(busy.writes.some((w) => w.op === "setStatus")).toBe(false);
 
     // updatedAt older than the timeout window → dead generation,
     // continuation proceeds.
@@ -391,15 +457,35 @@ describe("agent loop", () => {
       runId: "run_9",
       __agentName: "helper",
     });
-    // The repair batch persists BEFORE the new user turn.
+    // The repair rides in the SAME user message as the new input.
+    // Two user messages in a row are rejected by the Messages API just
+    // as a dangling tool_use is, so splitting them would swap one
+    // unreplayable transcript for another.
     const repair = writes[1];
     expect(repair.op).toBe("appendMessage");
+    expect(repair.role).toBe("user");
     const blocks = repair.content as Array<Record<string, unknown>>;
     expect(blocks[0].type).toBe("tool_result");
     expect(blocks[0].tool_use_id).toBe("tu_dead");
     expect(blocks[0].is_error).toBe(true);
     expect(String(blocks[0].content)).toContain("interrupted");
-    expect(writes[2].content).toBe("still there?");
+    expect(blocks[1]).toEqual({ type: "text", text: "still there?" });
+    // tool_result blocks come first — the API requires them at the
+    // head of the user turn that answers a tool_use.
+    expect(blocks.filter((b) => b.type === "tool_result")).toHaveLength(1);
+  });
+
+  test("with nothing to repair the opening turn stays a plain string", async () => {
+    const def = agent({});
+    const { ctx, writes } = mockCtx([done("ok")]);
+    await (def.handler as unknown as (
+      c: ActionCtx,
+      a: Record<string, unknown>,
+    ) => Promise<unknown>)(ctx, { input: "hello", __agentName: "helper" });
+    const opening = writes.find(
+      (w) => w.op === "appendMessage" && w.role === "user",
+    )!;
+    expect(opening.content).toBe("hello");
   });
 
   test("oversized tool results are truncated before persisting", async () => {
@@ -458,6 +544,294 @@ describe("agent loop", () => {
     expect(String(failed.error)).toContain("tool round-trips");
   });
 
+  test("queued input drains at the terminal boundary and extends the turn", async () => {
+    const def = agent({});
+    const { ctx, writes, state } = mockCtx([
+      done("First answer."),
+      done("Second answer."),
+    ]);
+    // The user types while the first response is being produced.
+    const originalStream = (ctx as unknown as { llm: { stream: unknown } }).llm
+      .stream as (...a: unknown[]) => Promise<unknown>;
+    let sent = false;
+    (ctx as unknown as { llm: { stream: unknown } }).llm.stream = async (
+      ...a: unknown[]
+    ) => {
+      const res = await originalStream(...a);
+      if (!sent) {
+        sent = true;
+        state.pendingInput.push("wait, also check the tests");
+      }
+      return res;
+    };
+
+    const result = await (def.handler as unknown as (
+      c: ActionCtx,
+      a: Record<string, unknown>,
+    ) => Promise<Record<string, unknown>>)(ctx, {
+      input: "go",
+      __agentName: "helper",
+    });
+
+    // The run did NOT complete after the first response — the queued
+    // message became the next user turn instead.
+    expect(result.text).toBe("Second answer.");
+    expect(result.steps).toBe(2);
+    const userTurns = writes.filter(
+      (w) => w.op === "appendMessage" && w.role === "user",
+    );
+    expect(userTurns.map((w) => w.content)).toEqual([
+      "go",
+      "wait, also check the tests",
+    ]);
+    expect(state.pendingInput).toEqual([]);
+    expect(state.status).toBe("completed");
+  });
+
+  test("queued input merges into the tool_result turn, results first", async () => {
+    const def = agent({
+      tools: {
+        lookup: {
+          description: "look up",
+          handler: async () => "found",
+        },
+      },
+    });
+    const { ctx, writes, state } = mockCtx([
+      wantsTool("lookup", { q: "a" }),
+      done("Done."),
+    ]);
+    state.pendingInput.push("focus on the second one");
+
+    await (def.handler as unknown as (
+      c: ActionCtx,
+      a: Record<string, unknown>,
+    ) => Promise<unknown>)(ctx, { input: "go", __agentName: "helper" });
+
+    const toolTurn = writes.find(
+      (w) =>
+        w.op === "appendMessage" &&
+        Array.isArray(w.content) &&
+        (w.content as Array<Record<string, unknown>>).some(
+          (b) => b.type === "tool_result",
+        ),
+    )!;
+    const blocks = toolTurn.content as Array<Record<string, unknown>>;
+    // tool_result blocks stay at the head of the turn; the steering
+    // text rides along behind them rather than as a second user
+    // message, which the Messages API would reject.
+    expect(blocks[0].type).toBe("tool_result");
+    expect(blocks[blocks.length - 1]).toEqual({
+      type: "text",
+      text: "focus on the second one",
+    });
+  });
+
+  test("cancel requested mid-run stops at the boundary and marks the run cancelled", async () => {
+    const def = agent({
+      tools: {
+        slow: {
+          description: "slow tool",
+          handler: async () => "done anyway",
+        },
+      },
+    });
+    const { ctx, writes, state } = mockCtx([
+      wantsTool("slow", {}),
+      done("never reached"),
+    ]);
+    state.cancelRequested = true;
+
+    const result = await (def.handler as unknown as (
+      c: ActionCtx,
+      a: Record<string, unknown>,
+    ) => Promise<Record<string, unknown>>)(ctx, {
+      input: "go",
+      __agentName: "helper",
+    });
+
+    expect(result.cancelled).toBe(true);
+    expect(state.status).toBe("cancelled");
+    // The tool_use still got its tool_result — a transcript missing
+    // one cannot be replayed on the next turn.
+    const toolTurn = writes.find(
+      (w) =>
+        w.op === "appendMessage" &&
+        Array.isArray(w.content) &&
+        (w.content as Array<Record<string, unknown>>).some(
+          (b) => b.type === "tool_result",
+        ),
+    )!;
+    expect(toolTurn).toBeDefined();
+    // And the loop stopped instead of asking the model again.
+    expect(
+      writes.filter((w) => w.op === "appendMessage" && w.role === "assistant"),
+    ).toHaveLength(1);
+  });
+
+  test("a cancel racing queued input keeps the queued text in the transcript", async () => {
+    const def = agent({});
+    const { ctx, writes, state } = mockCtx([done("First answer.")]);
+    const originalStream = (ctx as unknown as { llm: { stream: unknown } }).llm
+      .stream as (...a: unknown[]) => Promise<unknown>;
+    (ctx as unknown as { llm: { stream: unknown } }).llm.stream = async (
+      ...a: unknown[]
+    ) => {
+      const res = await originalStream(...a);
+      // Both land while the model is producing its answer.
+      state.pendingInput.push("one more thing");
+      state.cancelRequested = true;
+      return res;
+    };
+
+    const result = await (def.handler as unknown as (
+      c: ActionCtx,
+      a: Record<string, unknown>,
+    ) => Promise<Record<string, unknown>>)(ctx, {
+      input: "go",
+      __agentName: "helper",
+    });
+
+    expect(result.cancelled).toBe(true);
+    // The drain already took the text off the row, so dropping it here
+    // would lose words the user watched themselves type.
+    const userTurns = writes.filter(
+      (w) => w.op === "appendMessage" && w.role === "user",
+    );
+    expect(userTurns.map((w) => w.content)).toEqual(["go", "one more thing"]);
+    expect(state.status).toBe("cancelled");
+  });
+
+  test("cancel: true records the request and starts no turn", async () => {
+    const def = agent({});
+    const { ctx, writes, state } = mockCtx([]); // no LLM script needed
+    const result = await (def.handler as unknown as (
+      c: ActionCtx,
+      a: Record<string, unknown>,
+    ) => Promise<Record<string, unknown>>)(ctx, {
+      runId: "run_9",
+      cancel: true,
+      __agentName: "helper",
+    });
+    expect(result.cancelled).toBe(true);
+    expect(result.runId).toBe("run_9");
+    expect(state.cancelRequested).toBe(true);
+    expect(writes.map((w) => w.op)).toEqual(["requestCancel"]);
+    // The agent name travels with it so a run can't be stopped
+    // through a different agent's action.
+    expect(writes[0].agent).toBe("helper");
+  });
+
+  test("cancel without a runId, and input without either, are refused", async () => {
+    const def = agent({});
+    const call = (a: Record<string, unknown>) =>
+      (def.handler as unknown as (
+        c: ActionCtx,
+        a: Record<string, unknown>,
+      ) => Promise<unknown>)(mockCtx([]).ctx, { __agentName: "helper", ...a });
+    await expect(call({ cancel: true })).rejects.toThrow(/runId/);
+    await expect(call({})).rejects.toThrow(/input is required/);
+  });
+
+  test("a cancel raised while a tool runs aborts ctx.signal and skips the rest", async () => {
+    const seen: string[] = [];
+    const def = agent({
+      tools: {
+        first: {
+          description: "first",
+          handler: async (toolCtx) => {
+            seen.push("first");
+            // The cancel lands while this handler is in flight; the
+            // poller is what notices, so wait past one interval.
+            return await new Promise((resolve) => {
+              const timer = setInterval(() => {
+                if (toolCtx.signal?.aborted) {
+                  clearInterval(timer);
+                  resolve("aborted early");
+                }
+              }, 10);
+            });
+          },
+        },
+        second: {
+          description: "second",
+          handler: async () => {
+            seen.push("second");
+            return "ran";
+          },
+        },
+      },
+    });
+    const { ctx, state } = mockCtx([
+      {
+        model: "m",
+        content: [
+          { type: "tool_use", id: "tu_1", name: "first", input: {} },
+          { type: "tool_use", id: "tu_2", name: "second", input: {} },
+        ],
+        stop_reason: "tool_use",
+        usage: { input_tokens: 1, output_tokens: 1 },
+      },
+      done("never reached"),
+    ]);
+    setTimeout(() => {
+      state.cancelRequested = true;
+    }, 30);
+
+    const result = await (def.handler as unknown as (
+      c: ActionCtx,
+      a: Record<string, unknown>,
+    ) => Promise<Record<string, unknown>>)(ctx, {
+      input: "go",
+      __agentName: "helper",
+    });
+
+    expect(result.cancelled).toBe(true);
+    // The running handler saw the abort, and the queued one never
+    // started.
+    expect(seen).toEqual(["first"]);
+    expect(state.status).toBe("cancelled");
+  }, 10_000);
+
+  test("the default step budget is high enough for a real tool loop", async () => {
+    // 16 was the old default and is nowhere near enough for an agent
+    // that reads files before answering.
+    const def = agent({
+      tools: { step: { description: "one step", handler: async () => "ok" } },
+    });
+    const script: LlmCompleteResponse[] = [];
+    for (let i = 0; i < 40; i += 1) script.push(wantsTool("step", { i }));
+    script.push(done("Finished."));
+    const { ctx } = mockCtx(script);
+    const result = await (def.handler as unknown as (
+      c: ActionCtx,
+      a: Record<string, unknown>,
+    ) => Promise<Record<string, unknown>>)(ctx, {
+      input: "go",
+      __agentName: "helper",
+    });
+    expect(result.text).toBe("Finished.");
+    expect(result.steps).toBe(41);
+  });
+
+  test("cumulative steps carry across invocations", async () => {
+    const def = agent({});
+    const { ctx, writes } = mockCtx([done("Next.")], {
+      run: { status: "completed", steps: 7 },
+    });
+    await (def.handler as unknown as (
+      c: ActionCtx,
+      a: Record<string, unknown>,
+    ) => Promise<unknown>)(ctx, {
+      input: "again",
+      runId: "run_9",
+      __agentName: "helper",
+    });
+    // This invocation ran one step on top of the stored 7.
+    const drains = writes.filter((w) => w.op === "drainInput");
+    expect(Number(drains[drains.length - 1].steps)).toBe(8);
+  });
+
   test("llm failure marks the run failed and rethrows", async () => {
     const def = agent({});
     const { ctx, writes } = mockCtx([]); // script exhausted immediately

package/src/agent.ts

@@ -74,8 +74,11 @@ export interface AgentDefinition {
   tools?: Record<string, AgentTool>;
   /** Model override (subject to the server's allowlist). */
   model?: string;
-  /** Max model↔tool round-trips per invocation (default 16). Hitting
-   *  the cap fails the run rather than looping forever. */
+  /** Max model↔tool round-trips per invocation (default 64). Hitting
+   *  the cap fails the run rather than looping forever. Steering input
+   *  drained mid-invocation extends the same invocation, so this bounds
+   *  a steered turn too. The run row's cumulative `steps` counts every
+   *  invocation and is not capped. */
   maxSteps?: number;
   /** max_tokens per completion (default: server default). */
   maxTokens?: number;
@@ -88,13 +91,19 @@ export interface AgentDefinition {
 
 /** The synthesized action's args. */
 export interface AgentCallArgs {
-  /** The user's message for this turn. */
-  input: string;
+  /** The user's message for this turn. Required unless `cancel`. */
+  input?: string;
   /** Continue an existing run (must belong to the caller and this
-   *  agent). Omit to start a new run. */
+   *  agent). Omit to start a new run. Sending while the run is already
+   *  generating queues the message for that generation rather than
+   *  refusing it — see {@link AgentResult.queued}. */
   runId?: string;
   /** Optional display title, stored on new runs. */
   title?: string;
+  /** Ask the run to stop. Requires `runId`, ignores `input`, and
+   *  returns as soon as the request is recorded — a live generation
+   *  stops at its next turn boundary. */
+  cancel?: boolean;
 }
 
 /** What the agent action resolves with (also the `event: result`
@@ -103,9 +112,16 @@ export interface AgentResult {
   runId: string;
   /** Concatenated text of the final assistant message. */
   text: string;
-  /** Round-trips consumed. */
+  /** Round-trips consumed by THIS invocation. */
   steps: number;
   usage: { input_tokens: number; output_tokens: number };
+  /** The message was queued onto a generation already in flight
+   *  instead of starting a turn. No model call happened on this call;
+   *  the running loop picks the message up at its next boundary. */
+  queued?: boolean;
+  /** The run stopped because cancel was requested. `text` holds
+   *  whatever the model had produced by then. */
+  cancelled?: boolean;
 }
 
 // ---------------------------------------------------------------------------
@@ -179,9 +195,10 @@ export const AGENT_MARKER = "__pylonAgent";
 export function agent(def: AgentDefinition): FnDefinition<AgentCallArgs, AgentResult> {
   const fnDef = action({
     args: {
-      input: v.string(),
+      input: v.optional(v.string()),
       runId: v.optional(v.string()),
       title: v.optional(v.string()),
+      cancel: v.optional(v.boolean()),
     },
     auth: def.auth ?? "user",
     timeout: def.timeout ?? 600,
@@ -204,7 +221,13 @@ export function isAgentDefinition(value: unknown): boolean {
 // The loop
 // ---------------------------------------------------------------------------
 
-const DEFAULT_MAX_STEPS = 16;
+const DEFAULT_MAX_STEPS = 64;
+
+/** How often the loop asks whether cancel was requested while a tool
+ *  handler is running. Only runs during a tool batch: the host blocks
+ *  its per-call read loop for the whole of `ctx.llm.stream`, so no RPC
+ *  the child issues during a generation would be serviced anyway. */
+const CANCEL_POLL_MS = 2000;
 
 /** Tool results persist into AgentMessage rows and replay into every
  *  later completion's context — cap them so one oversized return can't
@@ -223,6 +246,30 @@ interface StoredMessage {
   content: unknown;
 }
 
+/** What one turn-boundary `drainInput` reports back. */
+interface DrainResult {
+  input: string[];
+  cancelRequested: boolean;
+  completed: boolean;
+}
+
+/** Give tool handlers a ctx whose `signal` also aborts on cancel, so a
+ *  handler that already threads `ctx.signal` into fetch stops with the
+ *  run. Prototype-based rather than a spread: ctx's methods keep
+ *  working when invoked on the derived object. */
+function ctxWithSignal(ctx: ActionCtx, signal: AbortSignal): ActionCtx {
+  const combined =
+    ctx.signal && typeof AbortSignal.any === "function"
+      ? AbortSignal.any([ctx.signal, signal])
+      : signal;
+  const derived = Object.create(ctx) as ActionCtx;
+  Object.defineProperty(derived, "signal", {
+    value: combined,
+    enumerable: true,
+  });
+  return derived;
+}
+
 async function runAgentLoop(
   def: AgentDefinition,
   ctx: ActionCtx,
@@ -235,18 +282,59 @@ async function runAgentLoop(
     (args as unknown as Record<string, unknown>).__agentName?.toString() ??
     "agent";
 
+  const noUsage = { input_tokens: 0, output_tokens: 0 };
+
+  // Cancel is a control call, not a turn: record the request and
+  // return. Ownership (and the agent match) is enforced inside the
+  // internal mutation, which runs under this caller's auth.
+  if (args.cancel === true) {
+    if (!args.runId) {
+      throw ctx.error(
+        "AGENT_CANCEL_NEEDS_RUN",
+        "cancel requires the runId of the run to stop",
+      );
+    }
+    await ctx.runMutation("__pylon_agent_write", {
+      op: "requestCancel",
+      runId: args.runId,
+      agent: agentName,
+    });
+    return {
+      runId: args.runId,
+      text: "",
+      steps: 0,
+      usage: noUsage,
+      cancelled: true,
+    };
+  }
+
+  const input = args.input ?? "";
+  if (input === "") {
+    throw ctx.error(
+      "AGENT_INPUT_REQUIRED",
+      "input is required (pass cancel: true to stop a run instead)",
+    );
+  }
+
   // A run left "running" longer than the agent's timeout is a dead
   // generation (the process died before the terminal status write) —
-  // continuations may take it over instead of being RUN_BUSY forever.
+  // continuations may take it over instead of waiting forever.
   const staleMs = Math.max(def.timeout ?? 600, 60) * 1000;
 
   // 1. Create or load the run (ownership enforced inside the internal
   // fns, which run under this caller's auth).
   let runId: string;
   let history: LlmMessage[] = [];
+  let priorSteps = 0;
   if (args.runId) {
     const loaded = await ctx.runQuery<{
-      run: { id: string; agent: string; status: string; updatedAt?: string };
+      run: {
+        id: string;
+        agent: string;
+        status: string;
+        updatedAt?: string;
+        steps?: number;
+      };
       messages: StoredMessage[];
     }>("__pylon_agent_read", { runId: args.runId });
     if (loaded.run.agent !== agentName) {
@@ -258,13 +346,28 @@ async function runAgentLoop(
     if (loaded.run.status === "running") {
       const updatedAt = Date.parse(String(loaded.run.updatedAt ?? "")) || 0;
       if (Date.now() - updatedAt < staleMs) {
-        throw ctx.error(
-          "RUN_BUSY",
-          "This run is already generating — wait for it to finish",
+        // The generation is alive. Hand it the message rather than
+        // refusing the call: the loop drains the queue at its next
+        // turn boundary, which is what lets a user steer mid-run.
+        const queued = await ctx.runMutation<{ queued: number }>(
+          "__pylon_agent_write",
+          { op: "enqueueInput", runId: loaded.run.id, input },
+        );
+        ctx.stream.writeEvent(
+          "queued",
+          JSON.stringify({ runId: loaded.run.id, queued: queued.queued }),
         );
+        return {
+          runId: loaded.run.id,
+          text: "",
+          steps: 0,
+          usage: noUsage,
+          queued: true,
+        };
       }
     }
     runId = loaded.run.id;
+    priorSteps = Number(loaded.run.steps) || 0;
     history = loaded.messages.map(storedToLlmMessage);
   } else {
     const created = await ctx.runMutation<{ id: string }>(
@@ -293,27 +396,33 @@ async function runAgentLoop(
 
   // A crash between persisting an assistant tool_use turn and its
   // tool_results leaves a transcript the LLM API rejects on replay.
-  // Repair with synthetic error results before the new user turn.
+  // Repair with synthetic error results, carried in the SAME user
+  // message as this turn's input: two user messages in a row are
+  // rejected as well, so appending the repair separately would trade
+  // one unreplayable transcript for another.
+  let repairs: LlmContentBlock[] = [];
   const lastMsg = history[history.length - 1];
   if (lastMsg?.role === "assistant" && Array.isArray(lastMsg.content)) {
-    const dangling = lastMsg.content.filter(
-      (b): b is Extract<LlmContentBlock, { type: "tool_use" }> =>
-        (b as { type?: string }).type === "tool_use",
-    );
-    if (dangling.length > 0) {
-      const repairs: LlmContentBlock[] = dangling.map((b) => ({
+    repairs = lastMsg.content
+      .filter(
+        (b): b is Extract<LlmContentBlock, { type: "tool_use" }> =>
+          (b as { type?: string }).type === "tool_use",
+      )
+      .map((b) => ({
         type: "tool_result",
         tool_use_id: b.id,
         content: "tool execution was interrupted",
         is_error: true,
       }));
-      await write({ op: "appendMessage", role: "user", content: repairs });
-      history.push({ role: "user", content: repairs });
-    }
   }
-
-  await write({ op: "appendMessage", role: "user", content: args.input });
-  history.push({ role: "user", content: args.input });
+  // Plain string when there is nothing to repair — the common case
+  // stays a simple transcript row.
+  const opening: string | LlmContentBlock[] =
+    repairs.length > 0
+      ? [...repairs, { type: "text", text: input }]
+      : input;
+  await write({ op: "appendMessage", role: "user", content: opening });
+  history.push({ role: "user", content: opening });
 
   // Tool declarations for the model.
   const tools: LlmTool[] = Object.entries(def.tools ?? {}).map(
@@ -328,6 +437,13 @@ async function runAgentLoop(
   const usage = { input_tokens: 0, output_tokens: 0 };
   let finalText = "";
   let steps = 0;
+  let cancelled = false;
+  let settled = false;
+
+  const drain = (extra: Record<string, unknown>) =>
+    write({ op: "drainInput", steps: priorSteps + steps, ...extra }) as Promise<
+      unknown
+    > as Promise<DrainResult>;
 
   try {
     for (;;) {
@@ -364,16 +480,137 @@ async function runAgentLoop(
         .map((b) => b.text)
         .join("");
 
-      if (res.stop_reason !== "tool_use") break;
+      if (res.stop_reason !== "tool_use") {
+        // Terminal boundary. Settling and draining in one transaction
+        // is what stops a message that lands right now from being
+        // stranded on a completed run.
+        const pending = await drain({ completeIfEmpty: true });
+        // Whatever was queued has already left the row, so persist it
+        // either way — cancelling must not silently swallow words the
+        // user had typed and can still see queued in the UI.
+        const text = pending.input.join("\n\n");
+        if (text !== "") {
+          await write({ op: "appendMessage", role: "user", content: text });
+          history.push({ role: "user", content: text });
+        }
+        if (pending.cancelRequested) {
+          cancelled = true;
+          break;
+        }
+        if (pending.completed) {
+          settled = true;
+          break;
+        }
+        // Steered after the model had stopped: the queued text became
+        // the next user turn and the same invocation keeps going.
+        continue;
+      }
 
       // 3. Execute every requested tool; failures become is_error
       // results the model can react to rather than run-fatal throws.
-      const results: LlmContentBlock[] = [];
-      for (const block of res.content) {
-        if (block.type !== "tool_use") continue;
+      const batch = await runToolBatch(def, ctx, runId, res.content);
+
+      // Tool boundary. Every tool_use needs its tool_result even when
+      // the batch stopped early, or the transcript can't be replayed.
+      const pending = await drain({});
+      const stopping = pending.cancelRequested || batch.cancelled;
+      const blocks: LlmContentBlock[] = [...batch.results];
+      for (const text of pending.input) {
+        blocks.push({ type: "text", text });
+      }
+      await write({ op: "appendMessage", role: "user", content: blocks });
+      history.push({ role: "user", content: blocks });
+      if (stopping) {
+        cancelled = true;
+        break;
+      }
+    }
+  } catch (err) {
+    const message = err instanceof Error ? err.message : String(err);
+    // Best-effort — the failure we surface is the loop's, not the
+    // bookkeeping write's.
+    await write({
+      op: "setStatus",
+      status: "failed",
+      error: message,
+      steps: priorSteps + steps,
+    }).catch(() => {});
+    throw err;
+  }
+
+  if (cancelled) {
+    await write({
+      op: "setStatus",
+      status: "cancelled",
+      steps: priorSteps + steps,
+    });
+    return { runId, text: finalText, steps, usage, cancelled: true };
+  }
+  // `settled` means drainInput already wrote the terminal status in
+  // the same transaction that proved nothing was queued.
+  if (!settled) {
+    await write({
+      op: "setStatus",
+      status: "completed",
+      steps: priorSteps + steps,
+    });
+  }
+  return { runId, text: finalText, steps, usage };
+}
+
+/** Run one turn's tool calls, watching for a cancel while they run.
+ *
+ *  The watch is a poll rather than a push because a cancel can be
+ *  requested on a different machine than the loop runs on — the run
+ *  row is the only thing both sides share. It runs only for the
+ *  duration of the batch: during `ctx.llm.stream` the host blocks its
+ *  per-call read loop, so an RPC issued then would not be answered. */
+async function runToolBatch(
+  def: AgentDefinition,
+  ctx: ActionCtx,
+  runId: string,
+  turn: LlmContentBlock[],
+): Promise<{ results: LlmContentBlock[]; cancelled: boolean }> {
+  const calls = turn.filter(
+    (b): b is Extract<LlmContentBlock, { type: "tool_use" }> =>
+      b.type === "tool_use",
+  );
+  const results: LlmContentBlock[] = [];
+  if (calls.length === 0) return { results, cancelled: false };
+
+  const controller = new AbortController();
+  const toolCtx = ctxWithSignal(ctx, controller.signal);
+  let cancelled = false;
+  let polling = false;
+  const timer = setInterval(() => {
+    // Skip rather than stack: a slow poll must not queue more.
+    if (polling || cancelled) return;
+    polling = true;
+    void ctx
+      .runQuery<{ cancelRequested: boolean }>("__pylon_agent_poll", { runId })
+      .then((s) => {
+        if (s.cancelRequested && !cancelled) {
+          cancelled = true;
+          controller.abort(new Error("agent run cancelled"));
+        }
+      })
+      .catch(() => {})
+      .finally(() => {
+        polling = false;
+      });
+  }, CANCEL_POLL_MS);
+
+  try {
+    for (const block of calls) {
+      let content: string;
+      let isError = false;
+      if (cancelled) {
+        // Stop starting new work, but still answer the call so the
+        // model sees why it has no result.
+        content = "cancelled by user";
+        isError = true;
+      } else {
         const tool = def.tools?.[block.name];
-        let content: string;
-        let isError = false;
         if (!tool) {
           content = `Unknown tool "${block.name}"`;
           isError = true;
@@ -385,7 +622,7 @@ async function runAgentLoop(
                 throw new Error(`Invalid tool input: ${check.errors.join("; ")}`);
               }
             }
-            const value = await tool.handler(ctx, block.input);
+            const value = await tool.handler(toolCtx, block.input);
             content =
               typeof value === "string" ? value : JSON.stringify(value ?? null);
           } catch (err) {
@@ -393,35 +630,25 @@ async function runAgentLoop(
             isError = true;
           }
         }
-        content = truncateToolResult(content);
-        // Announce the tool call on the stream so live UIs can render
-        // "using searchDocs…" without polling the message rows.
-        ctx.stream.writeEvent(
-          "tool",
-          JSON.stringify({ name: block.name, input: block.input, isError }),
-        );
-        results.push({
-          type: "tool_result",
-          tool_use_id: block.id,
-          content,
-          ...(isError ? { is_error: true } : {}),
-        });
       }
-      await write({ op: "appendMessage", role: "user", content: results });
-      history.push({ role: "user", content: results });
+      content = truncateToolResult(content);
+      // Announce the tool call on the stream so live UIs can render
+      // "using searchDocs…" without polling the message rows.
+      ctx.stream.writeEvent(
+        "tool",
+        JSON.stringify({ name: block.name, input: block.input, isError }),
+      );
+      results.push({
+        type: "tool_result",
+        tool_use_id: block.id,
+        content,
+        ...(isError ? { is_error: true } : {}),
+      });
     }
-  } catch (err) {
-    const message = err instanceof Error ? err.message : String(err);
-    // Best-effort — the failure we surface is the loop's, not the
-    // bookkeeping write's.
-    await write({ op: "setStatus", status: "failed", error: message }).catch(
-      () => {},
-    );
-    throw err;
+  } finally {
+    clearInterval(timer);
   }
-
-  await write({ op: "setStatus", status: "completed" });
-  return { runId, text: finalText, steps, usage };
+  return { results, cancelled };
 }
 
 function storedToLlmMessage(m: StoredMessage): LlmMessage {