@argszero/cordis-plugin-steer-preempt 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 argszero
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,104 @@
+# @argszero/cordis-plugin-steer-preempt
+
+Steer preemption for the DeepSeek Harness (`dsh`). When the agent blocks in a
+**`job_output(wait: true)`** read, a new user message — a *steer* that is queued
+as a next-step input — is normally ignored until the wait expires. The tool-jobs
+wait cap is **600,000 ms**, so a user's "stop, switch tasks" can sit unread for
+ten minutes. This plugin makes a pending steer **interrupt the blocking wait
+immediately** so the loop reaches its step boundary and honors the steer. The
+background job is **never killed**.
+
+## The gap it closes
+
+`Agent.steer()` (and the session-controller's insert path) sends the input to
+`inbox.nextStep`. The running step never looks at that queue — it is consumed
+only at the **next step boundary** (`preStep` claim in the agent loop). A
+blocking job read holds the step for up to the wait cap, so the steer is not
+processed until the wait expires on its own. See
+[deepseek-ai/deepseek-harness discussion #6030](https://github.com/deepseek-ai/deepseek-harness/discussions/6030).
+
+| Mechanism | Behavior |
+|---|---|
+| `Agent.steer()` / next-step input | only *queues* into `inbox.nextStep`; consumed at the next step boundary |
+| `job_output(wait: true)` | blocks up to the configured cap (max 600,000 ms), honoring `exec.signal` |
+| `Agent.cancel()` | aborts the phase the same tick (too heavy: kills the turn) |
+| **this plugin** | aborts **only the tool-visible derived signal** when a steer is pending → wait returns early → step boundary arrives → steer is honored |
+
+## How it works
+
+This plugin is a **community-side fix** that needs no harness patch. It registers
+a `tools/execute` around-wrapper (the same seam the in-tree
+`guard/timeout-policy` uses):
+
+1. Only **blocking** reads (`job_output` with `wait: true`) are wrapped; every
+   other tool call delegates with zero overhead.
+2. For a blocking read, the wrapper swaps in a **derived `AbortSignal`** for the
+   duration of the dispatch (the registry fuses it with the caller's signal, so
+   a real turn cancel keeps its semantics — the caller signal is never touched).
+3. A monitor polls the agent's public `inbox.nextStep` queue (read-only — it
+   **never consumes**; the loop's `preStep` claim owns consumption). When a
+   steer has been pending for a short **settle grace** (default 1 s), it aborts
+   the derived signal.
+4. The abort makes `jobs.wait` reject (`'wait aborted'`); the wait logic
+   **uncounts the waiter but leaves the job running**. The registry converts the
+   tool throw into an error result.
+5. The wrapper then replaces that error result with a structured
+   `STEER_PREEMPTED` result telling the model the job is still running in the
+   background and a user message is queued — so it finishes its turn and the
+   steer is consumed at the step boundary.
+
+A job that settles inside the grace window still returns its **real result**
+through the normal path — only an actual abort is ever replaced.
+
+Verified against `packages/core/tools/src/index.ts`,
+`packages/jobs/jobs-local/src/index.ts`, `packages/jobs/tool-jobs/src/index.ts`
+and `packages/core/agent/src/runtime-types.ts` on **dsh 0.1.5-alpha.1**.
+
+## Install
+
+Mount the plugin in your profile's bundle (see the dsh bundle/preset docs), or
+drop it into your plugins directory:
+
+```sh
+npm install @argszero/cordis-plugin-steer-preempt
+```
+
+```yaml
+# cordis.patch.yml overlay
+- insert:
+    - id: steer-preempt
+      name: '@argszero/cordis-plugin-steer-preempt'
+```
+
+Or use the shipped patch by adding the package to your `bundle` dependencies.
+
+## Configuration
+
+No config is required. Optional tuning (via a `set` layer):
+
+| Field | Default | Meaning |
+|---|---|---|
+| `pollMs` | `200` | Poll interval for the pending next-step queue while a blocking read is active |
+| `graceMs` | `1000` | Settle grace: after a steer is observed, how long to let a nearly-done job finish before aborting |
+
+## What it does not do
+
+- It does **not** kill or cancel the background job — the job keeps running and
+  a later `job_output` read returns its state.
+- It does **not** consume the steer — the loop's step boundary still owns that.
+- It does **not** replace a successful wait result — only an abort-shaped error
+  that this plugin's own trigger caused.
+- v0.1 targets `job_output(wait: true)` only (the reported gap). Other tools
+  that honor `exec.signal` can be added later.
+
+## Relationship to in-tree guards
+
+| Guard | Hook | Catches |
+|---|---|---|
+| `guard/timeout-policy` | `tools/execute` | a tool call exceeding a declared `timeoutMs` |
+| `guard/repeat-tool-reminder` | `tools/post-execute` | the model repeating the same tool-call chain |
+| **this plugin** | `tools/execute` | a **blocking wait** that a user steer should preempt |
+
+## License
+
+MIT

package/cordis.patch.yml

@@ -0,0 +1,14 @@
+# The @argszero/cordis-plugin-steer-preempt bundle patch: no deployment-specific
+# config is needed to mount (defaults poll the pending next-step queue every
+# 200ms and preempt a blocking job wait after a 1s settle grace once a steer is
+# observed). Tune via a profile layer if desired:
+#
+#   - set:
+#       - id: steer-preempt
+#         config:
+#           pollMs: 200
+#           graceMs: 1000
+
+- insert:
+    - id: steer-preempt
+      name: '@argszero/cordis-plugin-steer-preempt'

package/lib/index.js

@@ -0,0 +1,163 @@
+/**
+ * Steer preemption for the dsh harness.
+ *
+ * Closes an agent-loop latency gap that #6030 describes: while the agent blocks
+ * in a `job_output(wait: true)` read (which waits up to the tool-jobs configured
+ * cap — the tool-jobs maximum is 600,000 ms), a user steer
+ * (`Agent.send(input, 'next-step')`, i.e. the session-controller's insert path)
+ * only *queues* into `Agent.inbox.nextStep`; the running step never looks at it,
+ * and the queue is consumed only at the next step boundary (`preStep` claim in
+ * the agent loop). So a mid-wait steer is ignored until the wait expires — up to
+ * ten minutes of the user's message sitting unread.
+ *
+ * This plugin is the community-side fix. It wraps `tools/execute` (the same
+ * around-dispatch seam the in-tree `guard/timeout-policy` uses). When the called
+ * tool is a **blocking** `job_output` read, it swaps in a derived `AbortSignal`
+ * for the duration of the dispatch, polls the agent's public
+ * `inbox.nextStep` queue (read-only — it never consumes anything; the loop's
+ * `preStep` claim owns consumption), and aborts the derived signal once a
+ * pending steer has survived a short settle grace. The abort makes the tool
+ * wait return early — the background job is **not** killed (the wait logic
+ * uncounts the waiter and rejects; the job keeps running) — so the step ends,
+ * the loop reaches its step boundary, and the queued steer is honored promptly.
+ *
+ * Mechanism notes (verified against packages/core/tools/src/index.ts,
+ * packages/jobs/jobs-local/src/index.ts, packages/jobs/tool-jobs/src/index.ts
+ * and packages/core/agent/src/runtime-types.ts on dsh 0.1.5-alpha.1):
+ *  - `tools/execute` is a Cordis waterfall; a wrapper may replace `exec.signal`
+ *    for its delegated lifetime and the registry fuses every replacement with
+ *    the captured caller signal (`ToolDispatchExecution` doc). The caller/turn
+ *    signal is never touched, so a real cancel keeps its semantics.
+ *  - `job_output(wait: true)` calls `jobs.wait(id, timeout, exec.agent,
+ *    exec.signal)`; `jobs-local` honors the signal: a pre-aborted signal throws
+ *    `'wait aborted'` immediately, and a mid-wait abort rejects with the same
+ *    error after uncounting the waiter. Settlement releases waiters before any
+ *    abort can fire, so a job that finishes during the settle grace returns its
+ *    real result through the normal path.
+ *  - A rejected wait makes the tool `execute` throw; the registry converts tool
+ *    throws into `isError` results (`toolErrorResult`), so the wrapper sees a
+ *    resolved error result — never a thrown one.
+ *  - `Agent.inbox.nextStep` is a public readonly view of the pending steering
+ *    queue (`runtime-types.ts`); this plugin only reads `.length` per poll.
+ *
+ * Replacement semantics: when the wrapper's own trigger fired AND the tool
+ * result is an error (i.e. the wait was aborted, not completed), the error
+ * result is replaced with a structured `STEER_PREEMPTED` result that tells the
+ * model the job is still running and a user message is queued. A genuine
+ * success (the job settled inside the grace window) always passes through
+ * untouched.
+ *
+ * @module @argszero/cordis-plugin-steer-preempt
+ */
+import { Context } from '@deepseek-ai/cordis';
+import z from '@deepseek-ai/schemastery';
+/** Structured error code of the replacement result (mirrors `TOOL_TIMEOUT`). */
+export const STEER_PREEMPTED = 'STEER_PREEMPTED';
+/** Cordis plugin name used by loader diagnostics. */
+export const name = 'steer-preempt';
+/** The tool registry service this plugin wraps (`tools/execute`). */
+export const inject = ['tools'];
+export const Config = z.object({
+    pollMs: z.number().min(20).max(5000).default(200),
+    graceMs: z.number().min(0).max(30000).default(1000),
+});
+/** The only tool this plugin preempts in v0.1: a blocking background-job read. */
+const BLOCKING_TOOL = 'job_output';
+function jobIdOf(args) {
+    if (args === null || typeof args !== 'object')
+        return '';
+    const id = args.job_id;
+    return typeof id === 'string' ? id : '';
+}
+function isBlockingWait(args) {
+    return args !== null && typeof args === 'object' && args.wait === true;
+}
+/** The structured result substituted when this wrapper's abort wins the race. */
+function preemptedResult(jobId) {
+    const id = jobId.length > 0 ? ` ${jobId}` : '';
+    const message = `Blocking wait for job${id} was interrupted because a new user message arrived. `
+        + `The job keeps running in the background — a non-blocking job_output read returns its current state. `
+        + `The user message is queued and will be processed when this turn ends; do not start another `
+        + `blocking job_output wait.`;
+    return {
+        content: [{ type: 'text', text: `Error: ${message}` }],
+        isError: true,
+        error: { message, info: { name: 'SteerPreemptedError', code: STEER_PREEMPTED } },
+    };
+}
+function sleep(ms) {
+    return new Promise(resolve => setTimeout(resolve, ms));
+}
+/**
+ * Watch the agent's pending next-step queue and abort `controller` once a
+ * steer has been pending for `graceMs` (polling every `pollMs`). `isDone`
+ * returns true as soon as the delegated dispatch settled, which stops the
+ * monitor without aborting — a finished wait keeps its real result.
+ */
+async function monitorSteers(hasPendingSteer, controller, pollMs, graceMs, isDone) {
+    // Phase 1: wait for a steer to appear (or the dispatch to settle).
+    while (!isDone() && !hasPendingSteer()) {
+        await sleep(pollMs);
+    }
+    if (isDone())
+        return;
+    // Phase 2: steer pending — let a nearly-settled job finish within graceMs.
+    const deadline = Date.now() + graceMs;
+    while (!isDone()) {
+        if (Date.now() >= deadline) {
+            controller.abort();
+            return;
+        }
+        await sleep(pollMs);
+    }
+}
+/**
+ * The pure around-dispatch logic, exported separately from {@link apply} so it
+ * is testable without a live Cordis context. Returns the dispatch result to
+ * pass on (either the tool's own result or the structured replacement).
+ */
+export async function runWrapper(config, exec, next) {
+    // Only a blocking job read holds the step for up to the wait cap. Everything
+    // else (and every agent-less execution) delegates unchanged.
+    if (exec.name !== BLOCKING_TOOL || exec.agent === undefined)
+        return next();
+    const nextStep = exec.agent.inbox?.nextStep;
+    if (nextStep === undefined)
+        return next();
+    const args = exec.arguments;
+    if (!isBlockingWait(args))
+        return next();
+    const jobId = jobIdOf(args);
+    // Derived signal: aborting it interrupts the tool's wait without touching the
+    // caller/turn signal (the registry fuses replacements with the caller signal).
+    const controller = new AbortController();
+    let done = false;
+    const isDone = () => done;
+    const hasPendingSteer = () => nextStep.length > 0;
+    void monitorSteers(hasPendingSteer, controller, config.pollMs, config.graceMs, isDone);
+    const upstream = exec.signal;
+    exec.signal = controller.signal;
+    try {
+        const result = await next();
+        // Stop the monitor BEFORE reading controller state so a success that raced
+        // the abort is never replaced.
+        done = true;
+        if (controller.signal.aborted && result.isError) {
+            return preemptedResult(jobId);
+        }
+        return result;
+    }
+    finally {
+        done = true;
+        controller.abort();
+        exec.signal = upstream;
+    }
+}
+/**
+ * Register the wrapper. {@link runWrapper}'s structural {@link WrapperExec} is a
+ * subset of the registry's own `ToolDispatchExecution`, so the registration is
+ * a plain delegate with no casts.
+ */
+export function apply(ctx, config) {
+    ctx.on('tools/execute', (exec, next) => runWrapper(config, exec, next));
+}

package/lib/types/index.d.ts

@@ -0,0 +1,102 @@
+/**
+ * Steer preemption for the dsh harness.
+ *
+ * Closes an agent-loop latency gap that #6030 describes: while the agent blocks
+ * in a `job_output(wait: true)` read (which waits up to the tool-jobs configured
+ * cap — the tool-jobs maximum is 600,000 ms), a user steer
+ * (`Agent.send(input, 'next-step')`, i.e. the session-controller's insert path)
+ * only *queues* into `Agent.inbox.nextStep`; the running step never looks at it,
+ * and the queue is consumed only at the next step boundary (`preStep` claim in
+ * the agent loop). So a mid-wait steer is ignored until the wait expires — up to
+ * ten minutes of the user's message sitting unread.
+ *
+ * This plugin is the community-side fix. It wraps `tools/execute` (the same
+ * around-dispatch seam the in-tree `guard/timeout-policy` uses). When the called
+ * tool is a **blocking** `job_output` read, it swaps in a derived `AbortSignal`
+ * for the duration of the dispatch, polls the agent's public
+ * `inbox.nextStep` queue (read-only — it never consumes anything; the loop's
+ * `preStep` claim owns consumption), and aborts the derived signal once a
+ * pending steer has survived a short settle grace. The abort makes the tool
+ * wait return early — the background job is **not** killed (the wait logic
+ * uncounts the waiter and rejects; the job keeps running) — so the step ends,
+ * the loop reaches its step boundary, and the queued steer is honored promptly.
+ *
+ * Mechanism notes (verified against packages/core/tools/src/index.ts,
+ * packages/jobs/jobs-local/src/index.ts, packages/jobs/tool-jobs/src/index.ts
+ * and packages/core/agent/src/runtime-types.ts on dsh 0.1.5-alpha.1):
+ *  - `tools/execute` is a Cordis waterfall; a wrapper may replace `exec.signal`
+ *    for its delegated lifetime and the registry fuses every replacement with
+ *    the captured caller signal (`ToolDispatchExecution` doc). The caller/turn
+ *    signal is never touched, so a real cancel keeps its semantics.
+ *  - `job_output(wait: true)` calls `jobs.wait(id, timeout, exec.agent,
+ *    exec.signal)`; `jobs-local` honors the signal: a pre-aborted signal throws
+ *    `'wait aborted'` immediately, and a mid-wait abort rejects with the same
+ *    error after uncounting the waiter. Settlement releases waiters before any
+ *    abort can fire, so a job that finishes during the settle grace returns its
+ *    real result through the normal path.
+ *  - A rejected wait makes the tool `execute` throw; the registry converts tool
+ *    throws into `isError` results (`toolErrorResult`), so the wrapper sees a
+ *    resolved error result — never a thrown one.
+ *  - `Agent.inbox.nextStep` is a public readonly view of the pending steering
+ *    queue (`runtime-types.ts`); this plugin only reads `.length` per poll.
+ *
+ * Replacement semantics: when the wrapper's own trigger fired AND the tool
+ * result is an error (i.e. the wait was aborted, not completed), the error
+ * result is replaced with a structured `STEER_PREEMPTED` result that tells the
+ * model the job is still running and a user message is queued. A genuine
+ * success (the job settled inside the grace window) always passes through
+ * untouched.
+ *
+ * @module @argszero/cordis-plugin-steer-preempt
+ */
+import { Context } from '@deepseek-ai/cordis';
+import z from '@deepseek-ai/schemastery';
+import type { ToolExecutionResult } from '@deepseek-ai/dsh-tools';
+/** Structured error code of the replacement result (mirrors `TOOL_TIMEOUT`). */
+export declare const STEER_PREEMPTED = "STEER_PREEMPTED";
+/** Cordis plugin name used by loader diagnostics. */
+export declare const name = "steer-preempt";
+/** The tool registry service this plugin wraps (`tools/execute`). */
+export declare const inject: string[];
+/** Plugin configuration. */
+export interface Config {
+    /**
+     * Poll interval for the agent's pending next-step queue while a blocking
+     * job read is active. Default `200` ms.
+     */
+    pollMs?: number;
+    /**
+     * Settle grace: once a pending steer is observed, how long to keep waiting
+     * before aborting the read, so a job that finishes right about then still
+     * returns its real result. Default `1000` ms.
+     */
+    graceMs?: number;
+}
+/** Resolved config: every field carries its validated default. */
+export type ResolvedConfig = Required<Config>;
+export declare const Config: z<Config>;
+/** Structural view of the exec object this wrapper needs. */
+export interface WrapperExec {
+    readonly name: string;
+    readonly arguments: unknown;
+    readonly agent?: {
+        readonly inbox?: {
+            readonly nextStep?: readonly unknown[];
+        };
+    };
+    signal: AbortSignal;
+}
+/** Structural view of the delegated dispatch (`next()`). */
+export type WrapperNext = () => Promise<ToolExecutionResult>;
+/**
+ * The pure around-dispatch logic, exported separately from {@link apply} so it
+ * is testable without a live Cordis context. Returns the dispatch result to
+ * pass on (either the tool's own result or the structured replacement).
+ */
+export declare function runWrapper(config: ResolvedConfig, exec: WrapperExec, next: WrapperNext): Promise<ToolExecutionResult>;
+/**
+ * Register the wrapper. {@link runWrapper}'s structural {@link WrapperExec} is a
+ * subset of the registry's own `ToolDispatchExecution`, so the registration is
+ * a plain delegate with no casts.
+ */
+export declare function apply(ctx: Context, config: ResolvedConfig): void;

package/package.json

@@ -0,0 +1,58 @@
+{
+  "name": "@argszero/cordis-plugin-steer-preempt",
+  "description": "Steer preemption for dsh: a new user input (next-step steer) interrupts a blocking job_output(wait: true) read immediately instead of letting it block up to the job-wait cap, so the agent loop reaches its step boundary and honors the steer. The background job is never killed. Compatible with dsh 0.1.5-alpha.1 (job_output wait + Agent.inbox.nextStep).",
+  "version": "0.1.0",
+  "type": "module",
+  "main": "lib/index.js",
+  "types": "lib/types/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./lib/types/index.d.ts",
+      "default": "./lib/index.js"
+    },
+    "./src/*": "./src/*",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "lib/index.js",
+    "lib/types/**/*.d.ts",
+    "cordis.patch.yml",
+    "README.md",
+    "LICENSE"
+  ],
+  "license": "MIT",
+  "keywords": [
+    "cordis",
+    "deepseek-harness",
+    "dsh",
+    "plugin",
+    "steer",
+    "preempt",
+    "jobs",
+    "wait"
+  ],
+  "dsh": {
+    "bundle": {
+      "patch": "./cordis.patch.yml"
+    }
+  },
+  "peerDependencies": {
+    "@deepseek-ai/cordis": "^4.0.2",
+    "@deepseek-ai/dsh-tools": ">=0.1.2"
+  },
+  "dependencies": {
+    "@deepseek-ai/schemastery": "^3.18.1"
+  },
+  "devDependencies": {
+    "@deepseek-ai/cordis": "^4.0.2",
+    "@deepseek-ai/dsh-agent": "0.1.5-alpha.1",
+    "@deepseek-ai/dsh-tools": "0.1.5-alpha.1",
+    "@types/node": "^26.5.0",
+    "typescript": "^5.5.0"
+  },
+  "scripts": {
+    "build": "tsc",
+    "test": "tsc && node --test \"test/*.test.js\"",
+    "prepublishOnly": "tsc"
+  }
+}