docs(agent): call agent step an extension point

docs/cordis-catalog/events.md

@@ -304,14 +304,14 @@ Source: [`packages/core/agent/src/types.ts:254`](../../packages/core/agent/src/t
 
 ### `agent/step` — serial
 
-Awaited serial checkpoint before EVERY request of a turn is built (the first as well as each post-tools continuation). The single "between steps" seam: inject context, steer, or edit the session log here — the request's history derives from the log right after this settles.
+Awaited serial checkpoint before EVERY request of a turn is built (the first as well as each post-tools continuation). The single "between steps" extension point: inject context, steer, or edit the session log here — the request's history derives from the log right after this settles.
 
 ```ts cordis-catalog
 /**
  * Awaited serial checkpoint before EVERY request of a turn is built (the
  * first as well as each post-tools continuation). The single "between
- * steps" seam: inject context, steer, or edit the session log here — the
- * request's history derives from the log right after this settles.
+ * steps" extension point: inject context, steer, or edit the session log
+ * here — the request's history derives from the log right after this settles.
  * @param agent - the agent about to send a request.
  * @param turn - the open turn number.
  * @param step - the step number about to open.

packages/cordis/tool-cordis/src/api-catalog.ts

@@ -1066,7 +1066,7 @@ export const EVENT_API: readonly EventApiEntry[] = [
     name: 'agent/step',
     mode: 'serial',
     signature: '\'agent/step\'(this: Scoped<Agent>, agent: Agent, turn: number, step: number, signal: AbortSignal): Promise<void> | void',
-    jsDoc: '/**\n * Awaited serial checkpoint before EVERY request of a turn is built (the\n * first as well as each post-tools continuation). The single "between\n * steps" seam: inject context, steer, or edit the session log here — the\n * request\'s history derives from the log right after this settles.\n * @param agent - the agent about to send a request.\n * @param turn - the open turn number.\n * @param step - the step number about to open.\n * @param signal - the turn abort signal.\n * Scope-filtered dispatch (`@deepseek-ai/dsh-scope`): agent-scoped listeners receive only that agent.\n * @mode serial\n */',
+    jsDoc: '/**\n * Awaited serial checkpoint before EVERY request of a turn is built (the\n * first as well as each post-tools continuation). The single "between\n * steps" extension point: inject context, steer, or edit the session log\n * here — the request\'s history derives from the log right after this settles.\n * @param agent - the agent about to send a request.\n * @param turn - the open turn number.\n * @param step - the step number about to open.\n * @param signal - the turn abort signal.\n * Scope-filtered dispatch (`@deepseek-ai/dsh-scope`): agent-scoped listeners receive only that agent.\n * @mode serial\n */',
     summary: 'Awaited serial checkpoint before EVERY request of a turn is built (the first as well as each post-tools continuation).',
   },
   {

packages/core/agent-loop/src/agent.ts

@@ -415,8 +415,8 @@ export class ReactLoopAgent implements Agent {
   }
 
   /**
-   * Run the `agent/step` seam, commit pending input, derive one request, and
-   * execute its tool calls inside one durable step boundary.
+   * Run the `agent/step` extension point, commit pending input, derive one
+   * request, and execute its tool calls inside one durable step boundary.
    */
   private async step(
     turn: number,
@@ -425,8 +425,8 @@ export class ReactLoopAgent implements Agent {
   ): Promise<StepOutcome> {
     const { session } = this
 
-    // The single between-steps seam: listeners inject, steer, or edit the log
-    // here; the request derives from the log after this settles.
+    // The single between-steps extension point: listeners inject, steer, or
+    // edit the log here; the request derives from the log after this settles.
     await this.loopCtx.serial(agentCarrier(this), 'agent/step', this, turn, step, signal)
     signal.throwIfAborted()
 

packages/core/agent-loop/tests/contract-regressions.spec.ts

@@ -1221,7 +1221,7 @@ describe('disposal and cancellation during pre-step assembly', () => {
     expect(reasons).toEqual([{ kind: 'aborted' }])
   })
 
-  it('disposal during agent/step seam ends the turn disposed', { timeout: 15000 }, async () => {
+  it('disposal during agent/step listeners ends the turn disposed', { timeout: 15000 }, async () => {
     // Start disposal, then release pre-step; awaiting disposal first would
     // deadlock on the blocked driver.
     const adapter = new MockAdapter(['hang'])
@@ -1258,13 +1258,13 @@ describe('disposal and cancellation during pre-step assembly', () => {
     await disposalDone
     await driverDone(agent)
 
-    // After the pre-step seam finishes, the post-seam cancel/dispose check
+    // After the agent/step listeners finish, the post-listener cancel/dispose check
     // catches disposal. The step was never opened, no LLM call was made.
     const e = [...agent.session.events]
     expect(e.filter(x => x.type === 'turn/start')).toHaveLength(1)
     expect(e.filter(x => x.type === 'turn/end')).toHaveLength(1)
     const turnEnd = e.findLast(x => x.type === 'turn/end')
-    // Disposal wins the post-seam check — reason is `disposed`.
+    // Disposal wins the post-listener check — reason is `disposed`.
     expect(turnEnd?.type === 'turn/end' && turnEnd.data.reason).toEqual({ kind: 'disposed' })
     expect(e.some(x => x.type === 'step/start')).toBe(false)
     expect(e.some(x => x.type === 'assistant/chunk')).toBe(false)
@@ -1272,8 +1272,8 @@ describe('disposal and cancellation during pre-step assembly', () => {
     // (turn boundaries have no agent/* mirror).
   })
 
-  it('cancel during agent/step seam ends the turn aborted', { timeout: 15000 }, async () => {
-    // Release pre-step after cancellation to exercise the post-seam check.
+  it('cancel during agent/step listeners ends the turn aborted', { timeout: 15000 }, async () => {
+    // Release agent/step after cancellation to exercise the post-listener check.
     const adapter = new MockAdapter(['hang'])
     let releasePreStep!: () => void
     const blocker = new Promise<void>(r => void (releasePreStep = r))

packages/core/agent/src/types.ts

@@ -323,8 +323,8 @@ declare module 'cordis' {
     /**
      * Awaited serial checkpoint before EVERY request of a turn is built (the
      * first as well as each post-tools continuation). The single "between
-     * steps" seam: inject context, steer, or edit the session log here — the
-     * request's history derives from the log right after this settles.
+     * steps" extension point: inject context, steer, or edit the session log
+     * here — the request's history derives from the log right after this settles.
      * @param agent - the agent about to send a request.
      * @param turn - the open turn number.
      * @param step - the step number about to open.