@argszero/cordis-plugin-steer-preempt 0.1.0 → 0.1.2

package/README.md

@@ -37,8 +37,13 @@ a `tools/execute` around-wrapper (the same seam the in-tree
    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.
+   **user** steer has been pending for a short **settle grace** (default 1 s), it
+   aborts the derived signal. The trigger is a per-message
+   `message.source.kind === 'user'` test, **not** a bare queue-length check: the
+   `nextStep` queue also carries plugin-injected notifications (`agent.inject`,
+   e.g. a job-B completion notice while the model waits on job A, with
+   `source.kind === 'plugin'`). A plugin notice is not user input, so it must
+   not fire a user-steer preemption.
 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.
@@ -81,6 +86,17 @@ No config is required. Optional tuning (via a `set` layer):
 | `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 |
 
+## Changelog
+
+- **v0.1.1**: preemption trigger narrowed from `nextStep.length > 0` to a
+  per-message `message.source.kind === 'user'` test. Fixes a false preemption
+  when a plugin-injected notification (`agent.inject`, e.g. a job-B completion
+  notice with `source.kind === 'plugin'`) sits in the same `nextStep` queue as a
+  real user steer. Regression tests added. (Community feedback, discussion
+  #6030.)
+- **v0.1.0**: initial release — preempt a blocking `job_output(wait: true)` read
+  when a user steer is queued.
+
 ## What it does not do
 
 - It does **not** kill or cancel the background job — the job keeps running and

package/lib/index.js

@@ -16,11 +16,21 @@
  * 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
+ * pending **user** 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.
  *
+ * Refinement (v0.1.1, #6030 feedback): the `nextStep` queue is shared by two
+ * producers — `agent.steer(input)` (user-initiated, `send('next-step', true)`)
+ * and `agent.inject(input)` (plugin-initiated notification, e.g. a job-B
+ * completion notice while the model waits on job A; `send('next-step', false)`).
+ * `Agent.inbox.nextStep` cannot distinguish them, so the plugin must filter by
+ * `message.source.kind === 'user'`. Counting `nextStep.length` alone would
+ * falsely preempt a job-A wait when a job-B completion notice is injected into
+ * the same queue — but that notice is not user input, so no user-steer abort
+ * should fire. The trigger is now a per-message `source.kind === 'user'` test.
+ *
  * 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):
@@ -88,6 +98,16 @@ function preemptedResult(jobId) {
 function sleep(ms) {
     return new Promise(resolve => setTimeout(resolve, ms));
 }
+/**
+ * True when the pending next-step queue contains a *user-initiated* steer
+ * (`message.source.kind === 'user'`). Plugin-injected notifications (job
+ * completion notices, `source.kind === 'plugin'`) share the same queue but must
+ * NOT trigger a user-steer preemption — a second job finishing while the model
+ * waits on first job is not user input.
+ */
+function hasUserSteer(queue) {
+    return queue.some(message => message.source?.kind === 'user');
+}
 /**
  * Watch the agent's pending next-step queue and abort `controller` once a
  * steer has been pending for `graceMs` (polling every `pollMs`). `isDone`
@@ -133,7 +153,7 @@ export async function runWrapper(config, exec, next) {
     const controller = new AbortController();
     let done = false;
     const isDone = () => done;
-    const hasPendingSteer = () => nextStep.length > 0;
+    const hasPendingSteer = () => hasUserSteer(nextStep);
     void monitorSteers(hasPendingSteer, controller, config.pollMs, config.graceMs, isDone);
     const upstream = exec.signal;
     exec.signal = controller.signal;

package/lib/types/index.d.ts

@@ -16,11 +16,21 @@
  * 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
+ * pending **user** 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.
  *
+ * Refinement (v0.1.1, #6030 feedback): the `nextStep` queue is shared by two
+ * producers — `agent.steer(input)` (user-initiated, `send('next-step', true)`)
+ * and `agent.inject(input)` (plugin-initiated notification, e.g. a job-B
+ * completion notice while the model waits on job A; `send('next-step', false)`).
+ * `Agent.inbox.nextStep` cannot distinguish them, so the plugin must filter by
+ * `message.source.kind === 'user'`. Counting `nextStep.length` alone would
+ * falsely preempt a job-A wait when a job-B completion notice is injected into
+ * the same queue — but that notice is not user input, so no user-steer abort
+ * should fire. The trigger is now a per-message `source.kind === 'user'` test.
+ *
  * 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):
@@ -81,11 +91,23 @@ export interface WrapperExec {
     readonly arguments: unknown;
     readonly agent?: {
         readonly inbox?: {
-            readonly nextStep?: readonly unknown[];
+            readonly nextStep?: readonly UserMessageLike[];
         };
     };
     signal: AbortSignal;
 }
+/**
+ * Minimal structural view of a queued next-step entry. Only `source.kind` is
+ * inspected: a user-initiated steer carries `source.kind === 'user'`; a
+ * plugin-injected notification (e.g. a job completion notice) carries
+ * `source.kind === 'plugin'`. This is how the plugin distinguishes a real user
+ * steer from an injected context artifact sharing the same queue.
+ */
+export interface UserMessageLike {
+    readonly source?: {
+        readonly kind?: string;
+    };
+}
 /** Structural view of the delegated dispatch (`next()`). */
 export type WrapperNext = () => Promise<ToolExecutionResult>;
 /**

package/package.json

@@ -1,7 +1,7 @@
 {
   "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",
+  "version": "0.1.2",
   "type": "module",
   "main": "lib/index.js",
   "types": "lib/types/index.d.ts",
@@ -38,7 +38,7 @@
   },
   "peerDependencies": {
     "@deepseek-ai/cordis": "^4.0.2",
-    "@deepseek-ai/dsh-tools": ">=0.1.2"
+    "@deepseek-ai/dsh-tools": ">=0.1.2-rc.1 <0.2.0 || >=0.1.5-alpha.1 <0.2.0"
   },
   "dependencies": {
     "@deepseek-ai/schemastery": "^3.18.1"