From 7d5cc498d35755ce4a6a3154060007bd421cd726 Mon Sep 17 00:00:00 2001 From: _Kerman Date: Mon, 27 Jul 2026 17:24:20 +0800 Subject: [PATCH] docs(agent): call agent step an extension point --- docs/cordis-catalog/events.md | 6 +++--- packages/cordis/tool-cordis/src/api-catalog.ts | 2 +- packages/core/agent-loop/src/agent.ts | 8 ++++---- .../core/agent-loop/tests/contract-regressions.spec.ts | 10 +++++----- packages/core/agent/src/types.ts | 4 ++-- 5 files changed, 15 insertions(+), 15 deletions(-) diff --git a/docs/cordis-catalog/events.md b/docs/cordis-catalog/events.md index 34fde32127..b89a22be83 100644 --- a/docs/cordis-catalog/events.md +++ b/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. diff --git a/packages/cordis/tool-cordis/src/api-catalog.ts b/packages/cordis/tool-cordis/src/api-catalog.ts index 683cc09531..3ea9e87579 100644 --- a/packages/cordis/tool-cordis/src/api-catalog.ts +++ b/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, turn: number, step: number, signal: AbortSignal): Promise | 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).', }, { diff --git a/packages/core/agent-loop/src/agent.ts b/packages/core/agent-loop/src/agent.ts index 255fc6ddc2..32bb940d03 100644 --- a/packages/core/agent-loop/src/agent.ts +++ b/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 { 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() diff --git a/packages/core/agent-loop/tests/contract-regressions.spec.ts b/packages/core/agent-loop/tests/contract-regressions.spec.ts index fa432b80c0..a43d08170a 100644 --- a/packages/core/agent-loop/tests/contract-regressions.spec.ts +++ b/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(r => void (releasePreStep = r)) diff --git a/packages/core/agent/src/types.ts b/packages/core/agent/src/types.ts index a20151686d..dcef6c57ed 100644 --- a/packages/core/agent/src/types.ts +++ b/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.