Coder/deepseek-harness
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs(agent): call agent step an extension point

Browse Source
This commit is contained in:
_Kerman
2026-07-27 17:24:20 +08:00
parent e3a7836e4b
commit 7d5cc498d3
5 changed files with 15 additions and 15 deletions
Download Patch File Download Diff File Expand all files Collapse all files

6
docs/cordis-catalog/events.md
View File

@@ -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.

2
packages/cordis/tool-cordis/src/api-catalog.ts
View File

@@ -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).',
},
{

8
packages/core/agent-loop/src/agent.ts
View File

@@ -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()

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

@@ -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))

4
packages/core/agent/src/types.ts
View File

@@ -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.