|
|
@@ -2,11 +2,11 @@
|
|
|
|
|
|
English | [中文](core.zh.md)
|
|
|
|
|
|
-The **core** subsystem is [`packages/core`](../../packages/core/README.md) — the control spine every composition boots: the event-sourced session log, system-prompt assembly, the tool registry, the agent vocabulary, and the concrete loop that drives them. This page owns the spine's shared vocabulary — the `Agent` handle, its delivery and interception contracts, and the repo-wide type patterns — and orients to the group's dedicated pages; the folder is indexed in the [subsystems README](README.md).
|
|
|
+The **core** subsystem is [`packages/core`](../../packages/core/README.md) — the control spine every composition boots: the event-sourced session log, system-prompt assembly, the tool registry, the agent vocabulary, and the concrete loop that drives them. This page owns what the `agent`/`agent-loop` pair declares — how an agent is created and owned, and the `Agent` handle with its delivery, cancellation, and interception contracts — plus the two type patterns every subsystem follows; the group's dedicated pages and the rest of the folder are indexed in the [subsystems README](README.md).
|
|
|
|
|
|
## The spine, package by package
|
|
|
|
|
|
-A turn flows through the six packages in one loop: the driver in [`agent-loop`](../../packages/core/agent-loop) claims a queued prompt, opens a turn on the [session log](session.md) (`ctx.sessions`), assembles the request prefix through [system-prompt](system-prompt.md) (`ctx.systemPrompt`) and derives history from the log, streams the model response through the [LLM seam](llm-streaming.md), dispatches tool calls through the [tool registry](tools.md) (`ctx.tools`), and appends every model-visible fact back onto the log before the next step derives from it.
|
|
|
+A turn flows through the six packages in one loop: the driver in [`agent-loop`](../../packages/core/agent-loop) claims a queued prompt, opens a turn on the [session log](session.md) (`ctx.sessions`), assembles the request prefix through [system-prompt](system-prompt.md) (`ctx.systemPrompt`) and derives history from the log, streams the model response through the [LLM seam](llm-streaming.md), dispatches tool calls through the [tool registry](tools.md) (`ctx.tools`), and appends every model-visible fact back onto the log before the next step derives from it. The conversation vocabulary the loop moves — `Message`, `ContentBlock`, `StreamChunk`, the model request — is declared by [`packages/llm`](../../packages/llm/README.md) and documented on [llm-streaming.md](llm-streaming.md).
|
|
|
|
|
|
| Package | Owns | Page |
|
|
|
|---|---|---|
|
|
|
@@ -19,208 +19,45 @@ A turn flows through the six packages in one loop: the driver in [`agent-loop`](
|
|
|
|
|
|
`scope/` is the one non-service package: a dependency-free library (`createScope`/`scopeOf`/`scopeTarget`) that sits below `session/` and `system-prompt/` in the module graph precisely so they can consume it without a cycle. `agent-loop` is the one concrete implementation of the `agent` seam and lives here because it is the harness's default product loop; it runs each driver inside `ctx.agents.withInitiator()`. Extension plugins depend on `agent` — including when they need the initiating Agent — and never on `agent-loop` directly, so the loop stays swappable. The default composition that wires this spine into a runnable agent is [`examples/agent-spine-demo`](../../packages/examples/agent-spine-demo/README.md).
|
|
|
|
|
|
-<a id="what-counts-as-core"></a>
|
|
|
+## Creation and ownership
|
|
|
|
|
|
-## What this page owns
|
|
|
+Consumers create agents through `ctx.agents` — `create()` builds a fresh session and agent under one caller-supplied `SessionId`, `resume()` loads a persisted session first — or declaratively through the loop's config entries. Programmatic creation returns the owner's handle:
|
|
|
|
|
|
-The conversation vocabulary the loop moves — `Message`, `ContentBlock`, `StreamChunk`, the model request — is declared by [`packages/llm`](../../packages/llm/README.md) and documented on [llm-streaming.md](llm-streaming.md); the session-event, prompt-assembly, and tool vocabularies live on this group's dedicated pages above. What remains here is the vocabulary shared by everything: the `Agent` handle and its delivery, cancellation, and interception contracts (declared by `packages/core/agent`), the `SessionEvent` envelope, and the two type patterns every subsystem follows. The scoping rule is recorded in the [subsystems-catalog Agent Note](../../.agents/notes/implemented/process/2026-06-20-core-data-structures-catalog.md): the type you write, hold, or receive is documented where its declaring subsystem is; the machinery that types, renders, or persists it stays on that machinery's page.
|
|
|
-
|
|
|
-## The `…Map → derived-union` pattern
|
|
|
-
|
|
|
-Almost every extensible sum type in the harness follows one shape: an interface keyed by a discriminant tag (the `…Map`), from which the union is derived with `keyof`. Plugins add variants by **declaration merging** — no edit to the owning package.
|
|
|
-
|
|
|
-```ts ignore-check
|
|
|
-// The pattern, schematically:
|
|
|
-interface ThingMap {
|
|
|
- 'a': { kind: 'a'; /* … */ }
|
|
|
- 'b': { kind: 'b'; /* … */ }
|
|
|
-}
|
|
|
-type ThingKind = keyof ThingMap // 'a' | 'b'
|
|
|
-type Thing = ThingMap[keyof ThingMap] // the discriminated union
|
|
|
-
|
|
|
-// A plugin extends it without touching the source package:
|
|
|
-declare module '@deepseek-ai/dsh-llm' {
|
|
|
- interface ThingMap {
|
|
|
- 'c': { kind: 'c'; /* … */ }
|
|
|
- }
|
|
|
-}
|
|
|
-```
|
|
|
-
|
|
|
-Six canonical maps use this pattern; a plugin author extends these:
|
|
|
-
|
|
|
-| Map | Package | Derives | Catalog |
|
|
|
-|---|---|---|---|
|
|
|
-| `ContentBlockMap` | dsh-llm | `ContentBlock` | [llm-streaming.md](llm-streaming.md#content-blocks-and-messages) |
|
|
|
-| `MessageSourceMap` | dsh-llm | `MessageSource` | [llm-streaming.md](llm-streaming.md#content-blocks-and-messages) |
|
|
|
-| `FinishReasonMap` | dsh-llm | `FinishReason` | [llm-streaming.md](llm-streaming.md#the-model-request-and-result) |
|
|
|
-| `TurnTriggerMap` | dsh-session | `TurnTrigger` | [session.md](session.md) |
|
|
|
-| `TurnEndReasonMap` | dsh-session | `TurnEndReason` | [session.md](session.md) |
|
|
|
-| `SessionEventMap` | dsh-session | `SessionEvent` | [session.md](session.md) |
|
|
|
-
|
|
|
-Two large discriminated unions are the ones consumers `switch` over most: **`StreamChunk`** (the streaming protocol) and **`SessionEvent`** (the log entry). Per the repo convention, `switch` on the tag — don't chain `if`s — so each arm narrows and a typo'd tag fails to compile.
|
|
|
-
|
|
|
-## Branded IDs
|
|
|
-
|
|
|
-IDs that cross package boundaries are **branded** — structurally strings, but non-interchangeable at the type level (a `SessionId` cannot be passed where a `CallId` is expected). Construction goes through a per-type factory; comparison, logging, and JSON behave as ordinary strings.
|
|
|
-
|
|
|
-The `Branded<B>` primitive lives in its own type-only package, [dsh-brand](../../packages/util/brand) (no runtime code, no harness-package dependency), so any package can brand the ids it owns without depending on an unrelated capability package.
|
|
|
-
|
|
|
-Source: [`packages/util/brand/src/index.ts`](../../packages/util/brand/src/index.ts)
|
|
|
-
|
|
|
-```ts type-equiv
|
|
|
-/** A string carrying a compile-time-only brand `B`. */
|
|
|
-type Branded<B extends string> = string & { readonly [BRAND]: B }
|
|
|
-```
|
|
|
-
|
|
|
-The two core IDs are `CallId` (correlates a tool call with its result; dsh-llm) and `SessionId` (the shared live agent and durable session identity; dsh-session). Capability packages brand their own ids too, such as `TaskId` in [tasks.md](tasks.md).
|
|
|
-
|
|
|
-## Sessions
|
|
|
-
|
|
|
-A `Session` is an **append-only log** of typed `SessionEvent`s — the single source of truth. The LLM message history is *derived* from the log (`deriveMessages()`), not stored separately. The event vocabulary derives from `SessionEventMap`:
|
|
|
-
|
|
|
-Source: [`packages/core/session/src/types.ts`](../../packages/core/session/src/types.ts)
|
|
|
-
|
|
|
-```ts type-equiv
|
|
|
-/**
|
|
|
- * One immutable entry in the session log.
|
|
|
- *
|
|
|
- * A proper discriminated union over `type` (not independent `type`/`data`
|
|
|
- * unions), so `switch (event.type)` narrows `event.data` without casts.
|
|
|
- *
|
|
|
- * The {@link sourceEventSeqs} and {@link surfaceOp} fields are conditional:
|
|
|
- * they only exist on {@link SurfaceEventType} variants (`user/message`,
|
|
|
- * `assistant/message`, `tool/result`, `steering/message`).
|
|
|
- * Non-surface events (boundary markers, chunks, usage, errors) never carry
|
|
|
- * surface metadata — the compiler enforces this at `Session.append()`
|
|
|
- * call sites.
|
|
|
- */
|
|
|
-type SessionEvent<T extends SessionEventType = SessionEventType> = {
|
|
|
- [K in SessionEventType]: {
|
|
|
- type: K
|
|
|
- /** Monotonic sequence number within the session. */
|
|
|
- seq: number
|
|
|
- /** Unix epoch milliseconds. */
|
|
|
- time: number
|
|
|
- data: SessionEventMap[K]
|
|
|
- } & (K extends SurfaceEventType ? {
|
|
|
- /**
|
|
|
- * Seq numbers of events that are provenance sources of this event
|
|
|
- * (e.g. the `assistant/chunk` seqs that built an `assistant/message`,
|
|
|
- * or the surface nodes shadowed by a compaction replace node). An
|
|
|
- * `assistant/message` may carry a present empty array for a known empty
|
|
|
- * provider stream; omission means unrecorded provenance.
|
|
|
- */
|
|
|
- sourceEventSeqs?: number[]
|
|
|
- /** How this event entered the surface; absent for non-surface events. */
|
|
|
- surfaceOp?: SurfaceOp
|
|
|
- } : object)
|
|
|
-}[T]
|
|
|
-```
|
|
|
-
|
|
|
-The twelve event variants (`turn/start`, `turn/end`, `step/start`, `step/end`, `user/message`, `assistant/chunk`, `assistant/message`, `tool/call`, `tool/result`, `steering/message`, `todo/write`, `request/header`), the `deriveMessages()` projection rules, the `TurnTrigger`/`TurnEndReason` reasons, and the execution-enclosure and standalone-event rules are on **[session.md](session.md)**. How the log is made durable — the `SessionPersistence` seam, JSONL/SQLite backends, the `session/flush` checkpoint, crash recovery, and `SessionHeader` — is on **[persistence.md](persistence.md)**.
|
|
|
-
|
|
|
-## The agent handle
|
|
|
-
|
|
|
-`Agent` is the surface every plugin (UI, hooks, orchestrators) programs against. The concrete implementation is package-internal to dsh-agent-loop; nothing outside the loop depends on it.
|
|
|
-
|
|
|
-Source: [`packages/core/agent/src/types.ts`](../../packages/core/agent/src/types.ts)
|
|
|
-
|
|
|
-```ts type-equiv
|
|
|
-/**
|
|
|
- * Which inbox queue a {@link Agent.send} item joins:
|
|
|
- * - `next-turn` — the item becomes its own turn, claimed at a turn boundary.
|
|
|
- * - `next-step` — during prompt admission or an open turn, the item stages for
|
|
|
- * the next safe step boundary; otherwise it is promoted per its `wakeup`
|
|
|
- * flag.
|
|
|
- */
|
|
|
-type SendTarget = 'next-turn' | 'next-step'
|
|
|
-```
|
|
|
-
|
|
|
-```ts type-equiv
|
|
|
-/** Resolved inbox placement reported when an accepted message is enqueued. */
|
|
|
-type InboxPlacement = 'queued' | 'steering'
|
|
|
-```
|
|
|
-
|
|
|
-`InboxItemId` is a process-local branded string minted for each accepted FIFO occurrence. It is intentionally distinct from `MessageId`: sending the same immutable message twice creates two independently addressable pending items.
|
|
|
-
|
|
|
-```ts type-equiv
|
|
|
-/** One independently addressable accepted occurrence in an agent inbox. */
|
|
|
-interface InboxItem {
|
|
|
- /** Agent-loop-minted occurrence identity. */
|
|
|
- readonly id: InboxItemId
|
|
|
- /** Identified message delivered by the caller. */
|
|
|
- readonly message: UserMessage
|
|
|
- /** Acceptance-time FIFO classification. */
|
|
|
- readonly placement: InboxPlacement
|
|
|
-}
|
|
|
-```
|
|
|
-
|
|
|
-```ts type-equiv
|
|
|
-/** A user-requested mutation of one still-pending queued occurrence. */
|
|
|
-type InboxAction =
|
|
|
- | { readonly kind: 'edit'; readonly content: ContentBlock[] }
|
|
|
- | { readonly kind: 'remove' }
|
|
|
- | { readonly kind: 'steer' }
|
|
|
-```
|
|
|
-
|
|
|
-```ts type-equiv
|
|
|
-/** Result of applying an inbox action at the synchronous ownership boundary. */
|
|
|
-type InboxActionResult = 'applied' | 'not-found' | 'steer-unavailable'
|
|
|
-```
|
|
|
+Source: [`packages/core/agent/src/index.ts`](../../packages/core/agent/src/index.ts)
|
|
|
|
|
|
```ts type-equiv
|
|
|
/**
|
|
|
- * Options for the unified {@link Agent.send} primitive over the
|
|
|
- * (`target` × `wakeup`) matrix. Named presets: {@link Agent.followup}
|
|
|
- * (`next-turn`/wakeup), {@link Agent.steer} (`next-step`/wakeup), and
|
|
|
- * {@link Agent.inject} (`next-step`/no-wakeup).
|
|
|
+ * An owned agent plus its disposer, returned by {@link AgentRegistry.create} /
|
|
|
+ * {@link AgentRegistry.resume}. The disposer is a CAPABILITY: among consumers,
|
|
|
+ * only the holder can tear this agent down. The registered factory provider is
|
|
|
+ * also a structural owner because the scoped agent depends on that provider's
|
|
|
+ * service surface; provider unload stops and drains every live handle it made.
|
|
|
+ * `dispose()` stops the loop, awaits its exit, unregisters the agent, removes
|
|
|
+ * its session from the store, and finally unwinds its scoped world.
|
|
|
*
|
|
|
- * The object is complete so routing policy is explicit.
|
|
|
- */
|
|
|
-interface SendOptions {
|
|
|
- /** Queue the item joins. */
|
|
|
- target: SendTarget
|
|
|
- /**
|
|
|
- * Whether this item makes the model run: wake a parked driver (`next-turn`)
|
|
|
- * or force a continuation step (`next-step` while running). A `false`
|
|
|
- * `next-turn` item queues without waking; a `false`
|
|
|
- * `next-step` item attaches durable context without forcing another step
|
|
|
- * (the injection preset).
|
|
|
- */
|
|
|
- wakeup: boolean
|
|
|
+ * `ctx.agents.get(id)` still returns a bare {@link Agent} — the handle is
|
|
|
+ * exposed only to the consumer owner that created it; the structural provider
|
|
|
+ * reaches the same teardown internally. Config-created agents (the loop's own
|
|
|
+ * startup) are owned by the loop fiber and never need a handle.
|
|
|
+ */
|
|
|
+interface AgentHandle {
|
|
|
+ agent: Agent
|
|
|
+ dispose(): Promise<void>
|
|
|
}
|
|
|
```
|
|
|
|
|
|
-The fixed-preset aliases own `target` and `wakeup`; their already identified `UserMessage` carries role, content, and provenance. Its `MessageId` remains stable when an edit replaces content or strict steer transfers the immutable message. The original queued occurrence ends and strict steer accepts a new steering occurrence with a distinct `InboxItemId`. Injection bypasses the FIFOs and never appears on inbox lifecycle events.
|
|
|
+`CreateAgentOptions` carries the shared identity and everything a fresh agent needs before publication: session metadata (`meta` — validated `cwd`, fork lineage, seed boundary, origin classification, delegation depth), an optional `seed` replay prefix for forks, per-agent `AgentOptions`, a creation-only cancellation `signal`, and `setup`. `ResumeAgentOptions` is the persisted-identity counterpart: `resumeSessionId`, `agentOptions`, `signal`, and `setup`. The `setup` callback (`AgentSetup`) composes the agent's scoped world while both ids are still unpublished — everything registered through `agentCtx` exists before `agent/created` and the first prompt assembly — and may return a synchronous commit invoked immediately before publication; a setup rejection, commit throw, or owner disposal rolls the transaction back without publishing either id.
|
|
|
|
|
|
-```ts type-equiv
|
|
|
-/** Options for {@link Agent.cancel}. */
|
|
|
-interface CancelOptions {
|
|
|
- /**
|
|
|
- * Preserve queued and steering inbox items instead of discarding them. The
|
|
|
- * active turn is still aborted, but un-started and pending work survives for a
|
|
|
- * later turn and no `agent/inbox/discard` fires.
|
|
|
- */
|
|
|
- keepInbox?: boolean
|
|
|
-}
|
|
|
-```
|
|
|
+`AgentFactory` is the creation seam behind the registry: the loop registers its factory via `ctx.agents.setFactory()`, so consumers program against `ctx.agents` without depending on the concrete loop package. The exact `create`/`resume` signatures and their rollback contracts are in the [generated section](#ctxagents--agentregistry) below.
|
|
|
|
|
|
-`SteeringReceipt.outcome` always resolves. `admitted` identifies the turn and step whose immutable request history contains that exact message; `rejected` means lifecycle or terminal policy discarded it first. Synchronous input validation still throws from `steer()`.
|
|
|
+## The agent handle
|
|
|
|
|
|
-```ts type-equiv
|
|
|
-/** Stable runtime cause accepted by {@link Agent.cancel}. */
|
|
|
-type AgentCancelCause =
|
|
|
- | { readonly kind: 'user' }
|
|
|
- | { readonly kind: 'parent' }
|
|
|
-```
|
|
|
+`Agent` is the surface every plugin (UI, hooks, orchestrators) programs against; `ctx.agents.get(id)` returns it, and the [initiator scope](#initiating-agent) carries it. The concrete implementation is package-internal to dsh-agent-loop; nothing outside the loop depends on it. The unified `send` method exposes target and wakeup routing directly; `followup`, `steer`, and `inject` are fixed-preset aliases.
|
|
|
|
|
|
-`Agent` is an interface over the public live-agent contract. Concrete drivers own the `followup`/`steer`/`inject` aliases and route them through `send`'s (`target` × `wakeup`) matrix.
|
|
|
+Source: [`packages/core/agent/src/types.ts`](../../packages/core/agent/src/types.ts)
|
|
|
|
|
|
```ts type-equiv
|
|
|
-/**
|
|
|
- * Public live-agent handle with aliases over the unified delivery primitive.
|
|
|
- * @typert object
|
|
|
- */
|
|
|
+/** Public live-agent handle. */
|
|
|
interface Agent {
|
|
|
/** The single identity shared with {@link session}. */
|
|
|
readonly id: SessionId
|
|
|
@@ -228,78 +65,28 @@ interface Agent {
|
|
|
readonly options: AgentOptions
|
|
|
/** The live session this agent drives; its log is the durable source of truth. */
|
|
|
readonly session: Session
|
|
|
+ /** The agent-owned projection of durable pending work. */
|
|
|
+ readonly inbox: Inbox
|
|
|
/** The current lifecycle state, mirrored on every `agent/status` transition. */
|
|
|
readonly status: AgentStatus
|
|
|
- /**
|
|
|
- * Whether a `next-step` send currently stages for prompt admission or the
|
|
|
- * open turn. Unlike {@link status}, this excludes admission exit and turn
|
|
|
- * settlement, when a waking `next-step` send becomes a queued follow-up.
|
|
|
- */
|
|
|
- readonly acceptsNextStep: boolean
|
|
|
/** Agent-scoped context; its contributions are agent-local, unwind on disposal, and reject registration afterward. */
|
|
|
readonly ctx: Context
|
|
|
|
|
|
- /**
|
|
|
- * The unified delivery primitive over the (`target` × `wakeup`) matrix.
|
|
|
- * It routes the caller's typed content and source as follows:
|
|
|
- *
|
|
|
- * - `next-turn` queues an item that becomes the sole ordinary message of its
|
|
|
- * own FIFO-ordered turn; `wakeup:true` wakes a
|
|
|
- * parked driver, while `wakeup:false` queues without waking.
|
|
|
- * - `next-step` with `wakeup:true` stages steering during prompt admission
|
|
|
- * or an open turn; outside that window it falls back to a woken
|
|
|
- * `next-turn`.
|
|
|
- * - `next-step` with `wakeup:false` injects durable model-facing context
|
|
|
- * without running the model: admission or an open turn stages it for the
|
|
|
- * next safe log position, while an injection outside that window appends
|
|
|
- * immediately without opening a turn. If admission closes without a turn,
|
|
|
- * a context-only boundary appends immediately; context staged beside
|
|
|
- * steering remains pending with it.
|
|
|
- * The agent publishes or queues the identified frozen message as-is.
|
|
|
- * @param message - identified model-facing content and its producer provenance.
|
|
|
- * @param options - target queue and wakeup decision.
|
|
|
- */
|
|
|
- send(message: UserMessage, options: SendOptions): void
|
|
|
-
|
|
|
- /**
|
|
|
- * Reserve admission of the next ordinary turn while this agent is idle, so an
|
|
|
- * operation can mutate durable history before any queued prompt derives a
|
|
|
- * request from it. Already-accepted waking work has right of way, including a
|
|
|
- * send whose wake is still a pending microtask. Later sends keep their
|
|
|
- * ordinary placement, FIFO order, and `wakeup` facts, and
|
|
|
- * {@link acceptsNextStep} stays `false`, so a waking `next-step` send becomes
|
|
|
- * a queued follow-up rather than steering; cancellation and disposal may
|
|
|
- * still discard them. {@link inject} is not withheld. {@link whenIdle} treats
|
|
|
- * a live reservation as activity, while lifecycle teardown does not await it.
|
|
|
- * @returns the idempotent release, or `undefined` when the agent is running, already reserved, or already committed to waking work.
|
|
|
- */
|
|
|
- reserveTurnAdmission(): (() => void) | undefined
|
|
|
-
|
|
|
- /**
|
|
|
- * Mutate one still-pending queued occurrence synchronously. Editing preserves
|
|
|
- * the message identity and queue position; removal publishes its terminal
|
|
|
- * discard. Steer strictly transfers the message into the current next-step
|
|
|
- * window, or returns `steer-unavailable` without changing the queued
|
|
|
- * occurrence. Steering occurrences and driver-claimed items return
|
|
|
- * `not-found`.
|
|
|
- * @param id - independently addressable queued occurrence.
|
|
|
- * @param action - edit, remove, or strict steer operation.
|
|
|
- * @returns the applied outcome or the reason no mutation occurred.
|
|
|
- */
|
|
|
- updateInbox(id: InboxItemId, action: InboxAction): InboxActionResult
|
|
|
-
|
|
|
/**
|
|
|
* Clear queued and steering work — unless `keepInbox` — and abort the active
|
|
|
- * turn. An effective call first emits `agent/cancel-requested` with the
|
|
|
- * resolved typed cause. The first cause wins for the active turn, and
|
|
|
- * `whenIdle()` resolves after cancellation reaches quiescence. Idle
|
|
|
- * cancellation is a no-op and does not arm later work.
|
|
|
- * @param cause - the stable caller intent carried by the current turn signal.
|
|
|
+ * turn or between-turn task. The first cause wins for that activity. With no
|
|
|
+ * active activity, cancellation is a no-op and does not arm later work.
|
|
|
+ * @param cause - the stable caller intent carried by the active operation signal.
|
|
|
* @param options - cancellation options; `keepInbox` preserves pending work.
|
|
|
*/
|
|
|
cancel(cause: AgentCancelCause, options?: CancelOptions): void
|
|
|
|
|
|
- /** Resolve at idle quiescence; disposal waits for driver exit rather than only the status transition. */
|
|
|
+ /**
|
|
|
+ * Resolve after the current whole-agent activity reaches quiescence. This
|
|
|
+ * follows replacement work started before the observed driver retires,
|
|
|
+ * but does not identify the settlement of any particular message.
|
|
|
+ * @returns fulfillment after no active driver or maintenance task remains.
|
|
|
+ */
|
|
|
whenIdle(): Promise<void>
|
|
|
|
|
|
/**
|
|
|
@@ -334,35 +121,86 @@ interface Agent {
|
|
|
followup(message: UserMessage): void
|
|
|
|
|
|
/**
|
|
|
- * Submit steering with a message-owned admission receipt — the
|
|
|
- * `next-step`/wakeup preset of {@link send}. During prompt admission or an
|
|
|
- * open turn, the message waits in the steering FIFO until a committed step
|
|
|
- * snapshots it; outside that window it enters the ordinary queued FIFO. The
|
|
|
- * receipt resolves `admitted` only after the message joins that step's
|
|
|
- * immutable request history, or `rejected` when terminal policy,
|
|
|
- * cancellation, or disposal discards it first. A non-terminal turn close may
|
|
|
- * leave it staged for a later admitted prompt without settling the receipt.
|
|
|
+ * Submit steering for the nearest step. An idle driver starts a turn;
|
|
|
+ * a running driver consumes it at its next step boundary.
|
|
|
+ * A rejected step leaves steering parked in the inbox until the next
|
|
|
+ * wake; cancellation or disposal may discard pending steering.
|
|
|
* @param message - identified steering content and its producer provenance.
|
|
|
- * @returns the receipt for this exact message's eventual admission outcome.
|
|
|
*/
|
|
|
- steer(message: UserMessage): SteeringReceipt
|
|
|
+ steer(message: UserMessage): void
|
|
|
|
|
|
/**
|
|
|
- * Append model-facing context without running the model — the
|
|
|
- * `next-step`/no-wakeup preset of {@link send}. Admission or an open turn
|
|
|
- * stages it at the next safe log position; outside that window it appends
|
|
|
- * immediately without opening a turn. If admission closes without a turn,
|
|
|
- * a context-only boundary appends immediately; context staged beside
|
|
|
- * steering remains pending with it.
|
|
|
+ * Queue model-facing context for the next pre-step without waking the
|
|
|
+ * driver. A running driver claims it at the nearest later step boundary;
|
|
|
+ * idle drivers leave it pending until follow-up or steering
|
|
|
+ * wakes them. It may miss a request whose pre-step already claimed its
|
|
|
+ * batch. Cancellation or disposal may discard pending context.
|
|
|
* @param message - identified injected context and its producer provenance.
|
|
|
*/
|
|
|
inject(message: UserMessage): void
|
|
|
}
|
|
|
```
|
|
|
|
|
|
-`AgentStatus` is `'idle' | 'running'`, and `SessionId` is branded. Disposal removes the agent from the registry and emits `agent/disposed`; it is not a terminal status value. `running` describes the driver-wide drain interval and may span consecutive queued turns; it does not prove a turn is still open. `acceptsNextStep` is the narrower routing predicate for callers that must choose between steering the current admission/turn and submitting a fresh admitted prompt. A live turn-admission reservation is quiescence-relevant without changing `status` or turning later queue entries into steering; its only authority is to defer the next driver claim until release. `AgentOptions` is merge-extensible: core declares `provider?`, `model?`, and `maxTokens?` (dispatch requires provider and model after `agent/request`). When present, `maxTokens` must be a positive safe integer and caps every conversation-model request; omission allows the exact-model adapter default to materialize before the request header, or otherwise leaves provider behavior unchanged. Persona belongs to `dsh-system-prompt`: an agent-scoped `deployment:persona` may shadow the global default.
|
|
|
+```ts type-equiv
|
|
|
+/**
|
|
|
+ * An agent's lifecycle state, emitted on every transition as `agent/status`:
|
|
|
+ * `idle` means no driver is active; `running` begins when waking input starts
|
|
|
+ * cancellable pre-step processing and lasts while the driver drains,
|
|
|
+ * closes, or checkpoints turns. Disposal removes the agent from its registry;
|
|
|
+ * it is not a third observable status.
|
|
|
+ */
|
|
|
+type AgentStatus = 'idle' | 'running'
|
|
|
+```
|
|
|
+
|
|
|
+`running` describes the driver-wide drain interval and may span consecutive queued turns; it does not prove a turn is still open. Disposal removes the agent from the registry and emits `agent/disposed`; it is not a terminal status value. `followup()` returns no handle: its `MessageId` identifies durable inbox insertion, claim, and discard facts, not a later assistant output or turn ending. `whenIdle()` observes the whole agent, so callers may call a receipt-to-idle interval a run only when they explicitly own that interval ([decision](../../.agents/notes/implemented/architecture/2026-07-30-followup-enqueue-and-owned-runs.md)).
|
|
|
+
|
|
|
+```ts type-equiv
|
|
|
+/** Merge-extensible agent creation options. Persona belongs to system-prompt sections. */
|
|
|
+interface AgentOptions {
|
|
|
+ /** Provider route (must have a registered adapter at call time). */
|
|
|
+ provider?: string
|
|
|
+ /** Model id interpreted by the selected provider adapter. */
|
|
|
+ model?: string
|
|
|
+ /** Maximum output tokens for each conversation-model request. */
|
|
|
+ maxTokens?: number
|
|
|
+}
|
|
|
+```
|
|
|
+
|
|
|
+Dispatch requires `provider` and `model` after `agent/request`. When present, `maxTokens` must be a positive safe integer and caps every conversation-model request; omission allows the exact-model adapter default to materialize before the request header, or otherwise leaves provider behavior unchanged. An agent-scoped `deployment:persona` prompt section may shadow the global default persona.
|
|
|
+
|
|
|
+The inbox is the delivery vocabulary — two ordered pending-message lists the agent owns as a durable projection:
|
|
|
+
|
|
|
+```ts type-equiv
|
|
|
+/** One of the two ordered pending-message lists owned by an agent. */
|
|
|
+type InboxTarget = 'next-turn' | 'next-step'
|
|
|
+```
|
|
|
+
|
|
|
+Every pending occurrence is its `UserMessage`; `MessageId` is the sole identity. `Inbox.append`, `prepend`, `replace`, `remove`, `clear`, `splice`, and `claim` record normalized durable `agent/inbox/spliced` mutations and reject duplicate pending ids. `replace(messageId, newMessage)` and `remove(messageId)` locate the pending message across both lists; replacement may change identity and emits the old message as discarded followed by the new message as inserted. Ordinary removals and `clear()` are cancellations. `claim(target)` removes the proposed step batch — all `next-step` input plus, at a turn boundary, one `next-turn` message — through pure deletion splices without emitting discarded notifications, and the loop separately emits per-message claimed notifications. Whole-queue consumers such as UI projections reconstruct `nextTurn` and `nextStep` from the durable splices, while consumers following one message use the exact `agent/inbox/inserted`, `claimed`, and `discarded` notifications.
|
|
|
+
|
|
|
+Cancellation:
|
|
|
+
|
|
|
+```ts type-equiv
|
|
|
+/** Options for {@link Agent.cancel}. */
|
|
|
+interface CancelOptions {
|
|
|
+ /**
|
|
|
+ * Preserve queued and steering inbox items instead of discarding them. The
|
|
|
+ * active turn is still aborted, but un-started and pending work survives for a
|
|
|
+ * later turn and no canceled inbox splice is logged.
|
|
|
+ */
|
|
|
+ keepInbox?: boolean | undefined
|
|
|
+}
|
|
|
+```
|
|
|
+
|
|
|
+```ts type-equiv
|
|
|
+/** Why an active agent driver was cancelled. */
|
|
|
+type AgentCancelCause =
|
|
|
+ | { readonly kind: 'user' }
|
|
|
+ | { readonly kind: 'parent' }
|
|
|
+ | { readonly kind: 'hook'; readonly reason: string }
|
|
|
+ | { readonly kind: 'disposed' }
|
|
|
+```
|
|
|
|
|
|
-The cause is a TypeScript-enforced same-process input. An active `TurnCancellation` holder copies its discriminant into the runtime-only `AbortSignal.reason` and is retired before `turn/end` publication; the frozen `AbortSignal.reason` remains readable after that retirement. Only the loop reads the cause (`user`, `parent`, or lifecycle-only `disposed`) back off its own machine-private signal at settlement — there is no public reader, and a signal grants cooperating listeners no classification authority. Durable `turn/end` retains the coarse `{ kind: 'aborted' }` outcome; request provenance would require a separate durable event rather than overloading the terminal result.
|
|
|
+The cause is a TypeScript-enforced same-process input. An active cancellation holder copies it into the runtime-only `AbortSignal.reason`; a signal grants cooperating listeners no classification authority. Durable `turn/end` retains the coarse `{ kind: 'aborted' }` outcome; request provenance would require a separate durable event rather than overloading the terminal result.
|
|
|
|
|
|
The [event taxonomy](../architecture.md#event) owns the `agent/*` lifecycle, checkpoint, and waterfall contracts. Turn and step boundaries are durable session events rather than agent emits.
|
|
|
|
|
|
@@ -372,22 +210,19 @@ The process-local initiator carried by `ctx.agents` is the exact `Agent` above,
|
|
|
|
|
|
## Interception decisions
|
|
|
|
|
|
-Prompt and post-tool decisions use the same identified `UserMessage` shape as durable user-role input. Each `additionalContexts` entry becomes a separate `user/message`, preserving its identity and provenance. Hook bridges map their native decision fields onto these typed results.
|
|
|
+Pre-step decisions use the same identified `UserMessage` shape as durable user-role input. The entered batch is authoritative and preserves every message's identity and provenance. Hook bridges map their native decision fields onto this typed result.
|
|
|
|
|
|
Source: [`packages/core/agent/src/types.ts`](../../packages/core/agent/src/types.ts)
|
|
|
|
|
|
-`agent/prompt-submit` returns a `PromptDecision` before a turn opens. Allow may rewrite the claimed prompt or attach `additionalContexts`; block rejects admission without creating turn events:
|
|
|
+`agent/pre-step` receives one payload carrying the exclusive claimed batch (`messages`), the proposed step's coordinates (`turn`, `step`), and the current turn's cancellation `signal`. The initial proposal runs inside an open turn before any step; a tool continuation may submit an empty claimed batch between steps:
|
|
|
+
|
|
|
+It returns a `PreStepDecision`. Reject opens no step. Enter supplies the complete message batch appended after `step/start`; claimed messages omitted by the final decision remain removed, while input inserted after the claim stays pending:
|
|
|
|
|
|
```ts type-equiv
|
|
|
-/**
|
|
|
- * Prompt interception result. `allow.content` replaces the prompt, while
|
|
|
- * `additionalContexts` appends model-facing context before the turn starts.
|
|
|
- * An `allow` returned by a listener is authoritative: a listener wrapping
|
|
|
- * `next()` preserves both fields unless it intentionally replaces them.
|
|
|
- */
|
|
|
-type PromptDecision =
|
|
|
- | { kind: 'allow'; content?: ContentBlock[]; additionalContexts?: UserMessage[] }
|
|
|
- | { kind: 'block'; reason: string }
|
|
|
+/** Whether and with which messages the loop enters a proposed step. */
|
|
|
+type PreStepDecision =
|
|
|
+ | { kind: 'reject' }
|
|
|
+ | { kind: 'enter'; messages: UserMessage[] }
|
|
|
```
|
|
|
|
|
|
`agent/request-error` runs after a failed model step closes and before its turn closes. Listeners can repair durable state or await policy work while the failed turn's signal is still live. A handling listener returns `{ kind: 'retry' }` without calling `next()`; the default `undefined` leaves the failure terminal.
|
|
|
@@ -397,12 +232,7 @@ type PromptDecision =
|
|
|
type RequestErrorAction = { kind: 'retry' } | undefined
|
|
|
```
|
|
|
|
|
|
-```ts type-equiv
|
|
|
-/** Model-request failure with an optional machine-routable provider code. */
|
|
|
-type RequestError = Error & { code?: string }
|
|
|
-```
|
|
|
-
|
|
|
-`agent/step` is the single serial boundary before request derivation. `agent/turn-stopping` runs when a turn has no tool or steering continuation, before one final steering drain.
|
|
|
+`agent/pre-step` is the single serial boundary before request derivation. `agent/turn-stopping` runs when a turn has no tool or steering continuation, before one final steering drain.
|
|
|
|
|
|
`agent/session-start` carries a `SessionStartSource` (why the session lifecycle began; a bridge keys its SessionStart matcher on it):
|
|
|
|
|
|
@@ -411,12 +241,71 @@ type RequestError = Error & { code?: string }
|
|
|
type SessionStartSource = 'startup' | 'resume' | 'clear' | 'compact'
|
|
|
```
|
|
|
|
|
|
+## Sessions
|
|
|
+
|
|
|
+A `Session` is an **append-only log** of typed `SessionEvent`s — the single source of truth. The LLM message history is *derived* from the log (`deriveMessages()`), not stored separately. Every entry carries a monotonic `seq`, a `time`, and a `type`-discriminated `data` payload; surface variants additionally carry `sourceEventSeqs` provenance and a `surfaceOp`.
|
|
|
+
|
|
|
+The `SessionEvent` envelope's exact conditional shape, the twelve event variants (`turn/start`, `turn/end`, `step/start`, `step/end`, `user/message`, `assistant/chunk`, `assistant/message`, `tool/call`, `tool/result`, `steering/message`, `todo/write`, `request/header`), the `deriveMessages()` projection rules, the `TurnTrigger`/`TurnEndReason` reasons, and the execution-enclosure and standalone-event rules are on **[session.md](session.md)**. How the log is made durable — the `SessionPersistence` seam, JSONL/SQLite backends, the `session/flush` checkpoint, crash recovery, and `SessionHeader` — is on **[persistence.md](persistence.md)**.
|
|
|
+
|
|
|
## `ToolDefinition`
|
|
|
|
|
|
The one pipeline-authoring type that is core: what every registered tool *is* — a model-facing `ToolSchema` plus an `execute` function and optional final-content and UI callbacks. A tool author rarely constructs it by hand (the `defineTool` DSL builds it with typed args), but it is the contract the registry holds and the loop dispatches through.
|
|
|
|
|
|
Its full fields, the `defineTool`/`ValueSchemaSpec`/`ParameterSchemaSpec` typed schema DSL, the `ToolExecution`/`ToolExecutionResult` waterfall shapes, and the tool-presentation UI vocabulary are on **[tools.md](tools.md)**.
|
|
|
|
|
|
+## Repo-wide type patterns
|
|
|
+
|
|
|
+Two patterns recur across every subsystem and are documented once, here.
|
|
|
+
|
|
|
+### The `…Map → derived-union` pattern
|
|
|
+
|
|
|
+Almost every extensible sum type in the harness follows one shape: an interface keyed by a discriminant tag (the `…Map`), from which the union is derived with `keyof`. Plugins add variants by **declaration merging** — no edit to the owning package.
|
|
|
+
|
|
|
+```ts ignore-check
|
|
|
+// The pattern, schematically:
|
|
|
+interface ThingMap {
|
|
|
+ 'a': { kind: 'a'; /* … */ }
|
|
|
+ 'b': { kind: 'b'; /* … */ }
|
|
|
+}
|
|
|
+type ThingKind = keyof ThingMap // 'a' | 'b'
|
|
|
+type Thing = ThingMap[keyof ThingMap] // the discriminated union
|
|
|
+
|
|
|
+// A plugin extends it without touching the source package:
|
|
|
+declare module '@deepseek-ai/dsh-llm' {
|
|
|
+ interface ThingMap {
|
|
|
+ 'c': { kind: 'c'; /* … */ }
|
|
|
+ }
|
|
|
+}
|
|
|
+```
|
|
|
+
|
|
|
+Six canonical maps use this pattern; a plugin author extends these:
|
|
|
+
|
|
|
+| Map | Package | Derives | Catalog |
|
|
|
+|---|---|---|---|
|
|
|
+| `ContentBlockMap` | dsh-llm | `ContentBlock` | [llm-streaming.md](llm-streaming.md#content-blocks-and-messages) |
|
|
|
+| `MessageSourceMap` | dsh-llm | `MessageSource` | [llm-streaming.md](llm-streaming.md#content-blocks-and-messages) |
|
|
|
+| `FinishReasonMap` | dsh-llm | `FinishReason` | [llm-streaming.md](llm-streaming.md#the-model-request-and-result) |
|
|
|
+| `TurnTriggerMap` | dsh-session | `TurnTrigger` | [session.md](session.md) |
|
|
|
+| `TurnEndReasonMap` | dsh-session | `TurnEndReason` | [session.md](session.md) |
|
|
|
+| `SessionEventMap` | dsh-session | `SessionEvent` | [session.md](session.md) |
|
|
|
+
|
|
|
+Two large discriminated unions are the ones consumers `switch` over most: **`StreamChunk`** (the streaming protocol) and **`SessionEvent`** (the log entry). Per the repo convention, `switch` on the tag — don't chain `if`s — so each arm narrows and a typo'd tag fails to compile.
|
|
|
+
|
|
|
+### Branded IDs
|
|
|
+
|
|
|
+IDs that cross package boundaries are **branded** — structurally strings, but non-interchangeable at the type level (a `SessionId` cannot be passed where a `CallId` is expected). Construction goes through a per-type factory; comparison, logging, and JSON behave as ordinary strings.
|
|
|
+
|
|
|
+The `Branded<B>` primitive lives in its own type-only package, [dsh-brand](../../packages/util/brand) (no runtime code, no harness-package dependency), so any package can brand the ids it owns without depending on an unrelated capability package.
|
|
|
+
|
|
|
+Source: [`packages/util/brand/src/index.ts`](../../packages/util/brand/src/index.ts)
|
|
|
+
|
|
|
+```ts type-equiv
|
|
|
+/** A string carrying a compile-time-only brand `B`. */
|
|
|
+type Branded<B extends string> = string & { readonly [BRAND]: B }
|
|
|
+```
|
|
|
+
|
|
|
+The two core IDs are `CallId` (correlates a tool call with its result; dsh-llm) and `SessionId` (the shared live agent and durable session identity; dsh-session). Capability packages brand their own ids too, such as `TaskId` in [tasks.md](tasks.md).
|
|
|
+
|
|
|
<!-- BEGIN GENERATED cordis-surface (gen-cordis-catalog.ts) — do not edit between markers -->
|
|
|
|
|
|
<a id="cordis-surface"></a>
|
|
|
@@ -462,7 +351,7 @@ async resume(ownerCtx: Context, options: ResumeAgentOptions): Promise<AgentHandl
|
|
|
|
|
|
Types: [SessionHeader](persistence.md)
|
|
|
|
|
|
-Source: [`packages/core/agent-loop/src/index.ts:252`](../../packages/core/agent-loop/src/index.ts)
|
|
|
+Source: [`packages/core/agent-loop/src/index.ts:277`](../../packages/core/agent-loop/src/index.ts)
|
|
|
|
|
|
<a id="ctxagents--agentregistry"></a>
|
|
|
|
|
|
@@ -634,35 +523,12 @@ list(): Agent[]
|
|
|
roots(): Agent[]
|
|
|
```
|
|
|
|
|
|
-Source: [`packages/core/agent/src/index.ts:242`](../../packages/core/agent/src/index.ts)
|
|
|
+Source: [`packages/core/agent/src/index.ts:253`](../../packages/core/agent/src/index.ts)
|
|
|
|
|
|
<a id="agent-events"></a>
|
|
|
|
|
|
### `agent/*` events
|
|
|
|
|
|
-<a id="agentcancel-requested--emit"></a>
|
|
|
-
|
|
|
-#### `agent/cancel-requested` — emit
|
|
|
-
|
|
|
-Effective broad cancellation was requested, before queued/outbox work is cleared or the active turn is aborted. This observe-only notification cannot veto cancellation; listener failures are contained.
|
|
|
-
|
|
|
-```ts cordis-catalog
|
|
|
-/**
|
|
|
- * Effective broad cancellation was requested, before queued/outbox work
|
|
|
- * is cleared or the active turn is aborted. This observe-only notification
|
|
|
- * cannot veto cancellation; listener failures are contained.
|
|
|
- * @param agent - the agent whose current work is being cancelled.
|
|
|
- * @param cause - the explicit typed cancellation cause.
|
|
|
- * Scope-filtered dispatch (`@deepseek-ai/dsh-scope`): agent-scoped listeners receive only that agent.
|
|
|
- * @mode emit
|
|
|
- */
|
|
|
-'agent/cancel-requested'(this: Scoped<Agent>, agent: Agent, cause: AgentCancelCause): void
|
|
|
-```
|
|
|
-
|
|
|
-Types: [Scoped](scope.md)
|
|
|
-
|
|
|
-Source: [`packages/core/agent/src/types.ts:353`](../../packages/core/agent/src/types.ts)
|
|
|
-
|
|
|
<a id="agentcreated--emit"></a>
|
|
|
|
|
|
#### `agent/created` — emit
|
|
|
@@ -676,11 +542,11 @@ A fully configured agent and live session were published. Setup is composition-o
|
|
|
* Synchronous listener failure vetoes publication, while returned-promise
|
|
|
* rejection is reported. Detach requested during dispatch waits until every
|
|
|
* creation listener has observed the stable entry.
|
|
|
- * @param agent - the newly registered agent with its live session and completed setup.
|
|
|
+ * @param payload.agent - the newly registered agent with its live session and completed setup.
|
|
|
* Scope-filtered dispatch (`@deepseek-ai/dsh-scope`): agent-scoped listeners receive only that agent.
|
|
|
* @mode emit
|
|
|
*/
|
|
|
-'agent/created'(this: Scoped<Agent>, agent: Agent): void
|
|
|
+'agent/created'(this: Scoped<Agent>, payload: { agent: Agent }): void
|
|
|
```
|
|
|
|
|
|
Types: [Scoped](scope.md)
|
|
|
@@ -698,11 +564,11 @@ An agent left the registry; AgentLoop emits this after driver quiescence and sco
|
|
|
* An agent left the registry; AgentLoop emits this after driver quiescence
|
|
|
* and scoped-registration unwind, but before session detachment. Custom
|
|
|
* registry users own their driver-ordering contract.
|
|
|
- * @param agent - the exact agent removed from the registry.
|
|
|
+ * @param payload.agent - the exact agent removed from the registry.
|
|
|
* Scope-filtered dispatch (`@deepseek-ai/dsh-scope`): agent-scoped listeners receive only that agent.
|
|
|
* @mode emit
|
|
|
*/
|
|
|
-'agent/disposed'(this: Scoped<Agent>, agent: Agent): void
|
|
|
+'agent/disposed'(this: Scoped<Agent>, payload: { agent: Agent }): void
|
|
|
```
|
|
|
|
|
|
Types: [Scoped](scope.md)
|
|
|
@@ -713,138 +579,111 @@ Source: [`packages/core/agent/src/types.ts:167`](../../packages/core/agent/src/t
|
|
|
|
|
|
#### `agent/error` — emit
|
|
|
|
|
|
-A step or turn errored. The machine reports a failure here (plus the logger) even when the error has no in-turn position for a durable record.
|
|
|
+A step or turn errored. The machine reports a failure here even when the error has no in-turn position for a durable record.
|
|
|
|
|
|
```ts cordis-catalog
|
|
|
/**
|
|
|
- * A step or turn errored. The machine reports a failure here (plus the
|
|
|
- * logger) even when the error has no in-turn position for a durable record.
|
|
|
- * @param agent - the agent whose turn errored.
|
|
|
- * @param turn - the turn in which the failure surfaced.
|
|
|
- * @param step - the step at which the failure surfaced.
|
|
|
- * @param error - the failure, verbatim.
|
|
|
+ * A step or turn errored. The machine reports a failure here even when
|
|
|
+ * the error has no in-turn position for a durable record.
|
|
|
+ * @param payload.agent - the agent whose turn errored.
|
|
|
+ * @param payload.turn - the turn in which the failure surfaced.
|
|
|
+ * @param payload.step - the step at which the failure surfaced.
|
|
|
+ * @param payload.error - the failure, verbatim.
|
|
|
* Scope-filtered dispatch (`@deepseek-ai/dsh-scope`): agent-scoped listeners receive only that agent.
|
|
|
* @mode emit
|
|
|
*/
|
|
|
-'agent/error'(this: Scoped<Agent>, agent: Agent, turn: number, step: number, error: unknown): void
|
|
|
+'agent/error'(this: Scoped<Agent>, payload: { agent: Agent; turn: number; step: number; error: unknown }): void
|
|
|
```
|
|
|
|
|
|
Types: [Scoped](scope.md)
|
|
|
|
|
|
Source: [`packages/core/agent/src/types.ts:289`](../../packages/core/agent/src/types.ts)
|
|
|
|
|
|
-<a id="agentinboxdequeue--emit"></a>
|
|
|
+<a id="agentinboxclaimed--emit"></a>
|
|
|
|
|
|
-#### `agent/inbox/dequeue` — emit
|
|
|
+#### `agent/inbox/claimed` — emit
|
|
|
|
|
|
-The driver claimed one item out of the inbox: a queued item at a turn boundary, or steering drained between steps. Fires after the item leaves its FIFO and before it becomes a durable message.
|
|
|
+One message left the inbox inside its open turn. If the proposed step is rejected, the claimed message ends here: it is neither discarded nor re-emitted as a user/message, and the turn closes without a step.
|
|
|
|
|
|
```ts cordis-catalog
|
|
|
/**
|
|
|
- * The driver claimed one item out of the inbox: a queued item at a turn
|
|
|
- * boundary, or steering drained between steps. Fires after the item leaves
|
|
|
- * its FIFO and before it becomes a durable message.
|
|
|
- * @param agent - the agent whose inbox item was claimed.
|
|
|
- * @param item - the exact claimed occurrence.
|
|
|
+ * One message left the inbox inside its open turn. If the proposed step
|
|
|
+ * is rejected, the claimed message ends here: it is neither discarded nor
|
|
|
+ * re-emitted as a user/message, and the turn closes without a step.
|
|
|
+ * @param payload.agent - the agent whose inbox changed.
|
|
|
+ * @param payload.message - the claimed message.
|
|
|
+ * @param payload.turn - the owning turn.
|
|
|
* Scope-filtered dispatch (`@deepseek-ai/dsh-scope`): agent-scoped listeners receive only that agent.
|
|
|
* @mode emit
|
|
|
*/
|
|
|
-'agent/inbox/dequeue'(this: Scoped<Agent>, agent: Agent, item: InboxItem): void
|
|
|
+'agent/inbox/claimed'(this: Scoped<Agent>, payload: { agent: Agent; message: UserMessage; turn: number }): void
|
|
|
```
|
|
|
|
|
|
-Types: [Scoped](scope.md)
|
|
|
+Types: [Scoped](scope.md) · [UserMessage](session.md)
|
|
|
|
|
|
Source: [`packages/core/agent/src/types.ts:196`](../../packages/core/agent/src/types.ts)
|
|
|
|
|
|
-<a id="agentinboxdiscard--emit"></a>
|
|
|
+<a id="agentinboxdiscarded--emit"></a>
|
|
|
|
|
|
-#### `agent/inbox/discard` — emit
|
|
|
+#### `agent/inbox/discarded` — emit
|
|
|
|
|
|
-Pending inbox items were dropped without delivering them, so every enqueue occurrence receives exactly one terminal `agent/inbox/dequeue` OR `agent/inbox/discard`. `cancel()` without `keepInbox`, including disposal, emits this after `agent/cancel-requested` when applicable and before aborting the active work. Fires once per drop with every dropped item.
|
|
|
+One message was discarded from the live inbox.
|
|
|
|
|
|
```ts cordis-catalog
|
|
|
/**
|
|
|
- * Pending inbox items were dropped without delivering them, so every
|
|
|
- * enqueue occurrence receives exactly one terminal `agent/inbox/dequeue` OR
|
|
|
- * `agent/inbox/discard`. `cancel()` without `keepInbox`, including disposal,
|
|
|
- * emits this after `agent/cancel-requested` when applicable and before
|
|
|
- * aborting the active work. Fires once per drop with every dropped item.
|
|
|
- * @param agent - the agent whose inbox items were dropped.
|
|
|
- * @param items - the discarded occurrences in FIFO order (queued then steering); never empty.
|
|
|
+ * One message was discarded from the live inbox.
|
|
|
+ * @param payload.agent - the agent whose inbox changed.
|
|
|
+ * @param payload.message - the discarded message.
|
|
|
* Scope-filtered dispatch (`@deepseek-ai/dsh-scope`): agent-scoped listeners receive only that agent.
|
|
|
* @mode emit
|
|
|
*/
|
|
|
-'agent/inbox/discard'(this: Scoped<Agent>, agent: Agent, items: InboxItem[]): void
|
|
|
+'agent/inbox/discarded'(this: Scoped<Agent>, payload: { agent: Agent; message: UserMessage }): void
|
|
|
```
|
|
|
|
|
|
-Types: [Scoped](scope.md)
|
|
|
+Types: [Scoped](scope.md) · [UserMessage](session.md)
|
|
|
|
|
|
Source: [`packages/core/agent/src/types.ts:204`](../../packages/core/agent/src/types.ts)
|
|
|
|
|
|
-<a id="agentinboxenqueue--emit"></a>
|
|
|
+<a id="agentinboxinserted--emit"></a>
|
|
|
|
|
|
-#### `agent/inbox/enqueue` — emit
|
|
|
+#### `agent/inbox/inserted` — emit
|
|
|
|
|
|
-An item entered the queued or steering inbox. `placement` is the acceptance-time routing result; listeners must not reconstruct it from later agent or session state.
|
|
|
+One message entered the live inbox.
|
|
|
|
|
|
```ts cordis-catalog
|
|
|
/**
|
|
|
- * An item entered the queued or steering inbox. `placement` is the
|
|
|
- * acceptance-time routing result; listeners must not reconstruct it from
|
|
|
- * later agent or session state.
|
|
|
- * @param agent - the owning agent.
|
|
|
- * @param item - accepted occurrence, message, and resolved placement.
|
|
|
+ * One message entered the live inbox.
|
|
|
+ * @param payload.agent - the agent whose inbox changed.
|
|
|
+ * @param payload.message - the inserted message.
|
|
|
* Scope-filtered dispatch (`@deepseek-ai/dsh-scope`): agent-scoped listeners receive only that agent.
|
|
|
* @mode emit
|
|
|
*/
|
|
|
-'agent/inbox/enqueue'(this: Scoped<Agent>, agent: Agent, item: InboxItem): void
|
|
|
+'agent/inbox/inserted'(this: Scoped<Agent>, payload: { agent: Agent; message: UserMessage }): void
|
|
|
```
|
|
|
|
|
|
-Types: [Scoped](scope.md)
|
|
|
+Types: [Scoped](scope.md) · [UserMessage](session.md)
|
|
|
|
|
|
Source: [`packages/core/agent/src/types.ts:185`](../../packages/core/agent/src/types.ts)
|
|
|
|
|
|
-<a id="agentinboxupdate--emit"></a>
|
|
|
-
|
|
|
-#### `agent/inbox/update` — emit
|
|
|
-
|
|
|
-A still-pending queued item changed content. The item id, placement, and position remain stable while the event carries the replacement message.
|
|
|
-
|
|
|
-```ts cordis-catalog
|
|
|
-/**
|
|
|
- * A still-pending queued item changed content. The item id, placement, and
|
|
|
- * position remain stable while the event carries the replacement message.
|
|
|
- * @param agent - the owning agent.
|
|
|
- * @param item - the complete post-update occurrence.
|
|
|
- * Scope-filtered dispatch (`@deepseek-ai/dsh-scope`): agent-scoped listeners receive only that agent.
|
|
|
- * @mode emit
|
|
|
- */
|
|
|
-'agent/inbox/update'(this: Scoped<Agent>, agent: Agent, item: InboxItem): void
|
|
|
-```
|
|
|
-
|
|
|
-Types: [Scoped](scope.md)
|
|
|
-
|
|
|
-Source: [`packages/core/agent/src/types.ts:321`](../../packages/core/agent/src/types.ts)
|
|
|
-
|
|
|
-<a id="agentprompt-submit--waterfall"></a>
|
|
|
+<a id="agentpre-step--waterfall"></a>
|
|
|
|
|
|
-#### `agent/prompt-submit` — waterfall
|
|
|
+#### `agent/pre-step` — waterfall
|
|
|
|
|
|
-Allow, rewrite, or block one claimed prompt before it becomes a user message or opens a turn. Call `next()` for the unchanged default. The signal controls only this admission attempt; listeners may cooperate with it but must not retain it for a later attempt or turn.
|
|
|
+Reject a proposed step or replace the messages that enter it. Calling `next()` preserves the current messages.
|
|
|
|
|
|
```ts cordis-catalog
|
|
|
/**
|
|
|
- * Allow, rewrite, or block one claimed prompt before it becomes a user
|
|
|
- * message or opens a turn. Call `next()` for the unchanged default. The
|
|
|
- * signal controls only this admission attempt; listeners may cooperate with
|
|
|
- * it but must not retain it for a later attempt or turn.
|
|
|
- * @param agent - the agent whose turn claimed the message.
|
|
|
- * @param message - the frozen claimed message, including identity and source.
|
|
|
- * @param signal - the current turn's explicit abort signal.
|
|
|
+ * Reject a proposed step or replace the messages that enter it. Calling
|
|
|
+ * `next()` preserves the current messages.
|
|
|
+ * @param payload.agent - the agent proposing the step.
|
|
|
+ * @param payload.messages - messages removed from the inbox for this step.
|
|
|
+ * @param payload.turn - the turn that will own the step.
|
|
|
+ * @param payload.step - the step proposed by the loop.
|
|
|
+ * @param payload.signal - the current turn's cancellation signal.
|
|
|
* Scope-filtered dispatch (`@deepseek-ai/dsh-scope`): agent-scoped listeners receive only that agent.
|
|
|
* @mode waterfall
|
|
|
*/
|
|
|
-'agent/prompt-submit'(this: Scoped<Agent>, agent: Agent, message: UserMessage, signal: AbortSignal, next: () => Promise<PromptDecision>): Promise<PromptDecision>
|
|
|
+'agent/pre-step'(this: Scoped<Agent>, payload: { agent: Agent; messages: UserMessage[]; turn: number; step: number; signal: AbortSignal }, next: () => Promise<PreStepDecision>): Promise<PreStepDecision>
|
|
|
```
|
|
|
|
|
|
Types: [Scoped](scope.md) · [UserMessage](session.md)
|
|
|
@@ -863,14 +702,14 @@ Replace the frozen call configuration. `await next()` yields the config the mach
|
|
|
* the machine would use (agent options on the first request, the logged
|
|
|
* header afterwards); return a replacement to switch. Model-visible
|
|
|
* content must use logged channels; this seam cannot mutate messages.
|
|
|
- * @param agent - the agent making the model call.
|
|
|
- * @param turn - the open turn number.
|
|
|
- * @param step - the step whose request this is.
|
|
|
- * @param signal - the current turn's explicit abort signal.
|
|
|
+ * @param payload.agent - the agent making the model call.
|
|
|
+ * @param payload.turn - the open turn number.
|
|
|
+ * @param payload.step - the step whose request this is.
|
|
|
+ * @param payload.signal - the current turn's explicit abort signal.
|
|
|
* Scope-filtered dispatch (`@deepseek-ai/dsh-scope`): agent-scoped listeners receive only that agent.
|
|
|
* @mode waterfall
|
|
|
*/
|
|
|
-'agent/request'(this: Scoped<Agent>, agent: Agent, turn: number, step: number, signal: AbortSignal, next: () => Promise<LlmCallConfig>): Promise<LlmCallConfig>
|
|
|
+'agent/request'(this: Scoped<Agent>, payload: { agent: Agent; turn: number; step: number; signal: AbortSignal }, next: () => Promise<LlmCallConfig>): Promise<LlmCallConfig>
|
|
|
```
|
|
|
|
|
|
Types: [LlmCallConfig](llm-streaming.md) · [Scoped](scope.md)
|
|
|
@@ -881,28 +720,25 @@ Source: [`packages/core/agent/src/types.ts:243`](../../packages/core/agent/src/t
|
|
|
|
|
|
#### `agent/request-error` — waterfall
|
|
|
|
|
|
-Handle a model-request failure after its failed step has closed but before the failed turn closes. A listener returns `{ kind: 'retry' }` without calling `next()` when it owns the error, or calls `next()` to delegate. The default `undefined` leaves the failure terminal.
|
|
|
+Handle one failed model-request attempt before the loop retries or closes its step. A listener returns `{ kind: 'retry' }` without calling `next()` when it owns recovery, or calls `next()` to delegate. The default `undefined` leaves the failure terminal.
|
|
|
|
|
|
```ts cordis-catalog
|
|
|
/**
|
|
|
- * Handle a model-request failure after its failed step has closed but
|
|
|
- * before the failed turn closes. A listener returns `{ kind: 'retry' }`
|
|
|
- * without calling `next()` when it owns the error, or calls `next()` to
|
|
|
- * delegate. The default `undefined` leaves the failure terminal.
|
|
|
- * @param agent - the agent whose request failed.
|
|
|
- * @param turn - the open turn number.
|
|
|
- * @param step - the failed step number.
|
|
|
- * @param error - the original model-request failure.
|
|
|
- * @param failure - serializable facts normalized at the final adapter boundary.
|
|
|
- * @param priorFailures - immutable failures that already authorized another
|
|
|
- * retry turn in this consecutive sequence.
|
|
|
- * @param retryPolicy - immutable policy of the adapter registration that served
|
|
|
- * the failed request, or `undefined` if no final adapter served it.
|
|
|
- * @param signal - the turn abort signal.
|
|
|
+ * Handle one failed model-request attempt before the loop retries or closes
|
|
|
+ * its step. A listener returns `{ kind: 'retry' }` without calling `next()`
|
|
|
+ * when it owns recovery, or calls `next()` to delegate. The default
|
|
|
+ * `undefined` leaves the failure terminal.
|
|
|
+ * @param payload.agent - the agent whose request failed.
|
|
|
+ * @param payload.turn - the turn containing the failed request.
|
|
|
+ * @param payload.step - the step containing the failed request attempt.
|
|
|
+ * @param payload.provider - the provider selected for the failed request.
|
|
|
+ * @param payload.failure - serializable facts normalized at the final adapter boundary.
|
|
|
+ * @param payload.retryPolicy - the policy of the adapter registration that served the failed request.
|
|
|
+ * @param payload.signal - the turn abort signal.
|
|
|
* Scope-filtered dispatch (`@deepseek-ai/dsh-scope`): agent-scoped listeners receive only that agent.
|
|
|
* @mode waterfall
|
|
|
*/
|
|
|
-'agent/request-error'(this: Scoped<Agent>, agent: Agent, turn: number, step: number, error: RequestError, failure: LlmFailure, priorFailures: readonly LlmFailure[], retryPolicy: ResolvedRetryPolicy | undefined, signal: AbortSignal, next: () => Promise<RequestErrorAction>): Promise<RequestErrorAction>
|
|
|
+'agent/request-error'(this: Scoped<Agent>, payload: { agent: Agent; turn: number; step: number; provider: string; failure: LlmFailure; retryPolicy: ResolvedRetryPolicy | undefined; signal: AbortSignal }, next: () => Promise<RequestErrorAction>): Promise<RequestErrorAction>
|
|
|
```
|
|
|
|
|
|
Types: [LlmFailure](llm-streaming.md) · [ResolvedRetryPolicy](llm-streaming.md) · [Scoped](scope.md)
|
|
|
@@ -921,12 +757,12 @@ The session lifecycle began, once before the first turn. Use `agent.inject()` to
|
|
|
* `agent.inject()` to seed model-facing context. This is a notification, not
|
|
|
* a veto; disposal requested by a lifecycle owner is rechecked before the
|
|
|
* driver starts.
|
|
|
- * @param agent - the agent whose session lifecycle began.
|
|
|
- * @param source - why the session started (fresh startup, resume, …).
|
|
|
+ * @param payload.agent - the agent whose session lifecycle began.
|
|
|
+ * @param payload.source - why the session started (fresh startup, resume, …).
|
|
|
* Scope-filtered dispatch (`@deepseek-ai/dsh-scope`): agent-scoped listeners receive only that agent.
|
|
|
* @mode emit
|
|
|
*/
|
|
|
-'agent/session-start'(this: Scoped<Agent>, agent: Agent, source: SessionStartSource): void
|
|
|
+'agent/session-start'(this: Scoped<Agent>, payload: { agent: Agent; source: SessionStartSource }): void
|
|
|
```
|
|
|
|
|
|
Types: [Scoped](scope.md)
|
|
|
@@ -937,18 +773,19 @@ Source: [`packages/core/agent/src/types.ts:216`](../../packages/core/agent/src/t
|
|
|
|
|
|
#### `agent/status` — emit
|
|
|
|
|
|
-Agent status changed (`idle` ⇄ `running`). `send()` does not enter `running` synchronously; drive lifecycle from this event.
|
|
|
+Agent status changed (`idle` ⇄ `running`). A waking delivery enters `running` synchronously after reserving cancellation; `idle` means no driver remains scheduled or active.
|
|
|
|
|
|
```ts cordis-catalog
|
|
|
/**
|
|
|
- * Agent status changed (`idle` ⇄ `running`). `send()` does not enter
|
|
|
- * `running` synchronously; drive lifecycle from this event.
|
|
|
- * @param agent - the agent whose status flipped.
|
|
|
- * @param status - the status just entered (the transition's destination).
|
|
|
+ * Agent status changed (`idle` ⇄ `running`). A waking delivery enters
|
|
|
+ * `running` synchronously after reserving cancellation; `idle` means no
|
|
|
+ * driver remains scheduled or active.
|
|
|
+ * @param payload.agent - the agent whose status flipped.
|
|
|
+ * @param payload.status - the status just entered (the transition's destination).
|
|
|
* Scope-filtered dispatch (`@deepseek-ai/dsh-scope`): agent-scoped listeners receive only that agent.
|
|
|
* @mode emit
|
|
|
*/
|
|
|
-'agent/status'(this: Scoped<Agent>, agent: Agent, status: AgentStatus): void
|
|
|
+'agent/status'(this: Scoped<Agent>, payload: { agent: Agent; status: AgentStatus }): void
|
|
|
```
|
|
|
|
|
|
Types: [Scoped](scope.md)
|
|
|
@@ -959,7 +796,7 @@ Source: [`packages/core/agent/src/types.ts:177`](../../packages/core/agent/src/t
|
|
|
|
|
|
#### `agent/turn-stopping` — serial
|
|
|
|
|
|
-The turn is about to close: the model owes no response (no live tool calls, no fresh steering). Awaited before the boundary commits — a listener that objects steers (`agent.steer(...)`) and the machine re-reads its inbox: fresh steering runs another step, none closes the turn. Data decides, so listener order cannot change the outcome. The inverse control (stop a tool loop early) is data too: a tool result carrying `concludesTurn` ends the turn at its step.
|
|
|
+The turn is about to close: the model owes no response (no live tool calls, no fresh steering). Awaited before the boundary commits — a listener that objects steers (`agent.steer(...)`) and the machine re-reads its inbox: fresh steering runs another step, none closes the turn. Data decides, so listener order cannot change the outcome. The inverse control (stop a tool loop early) is data too: a tool result carrying `concludesTurn` ends the turn at its step. The conclusion never short-circuits already-submitted next-step work: same-step `additionalContexts` or racing steering still runs, and the turn closes only when that inbox drains.
|
|
|
|
|
|
```ts cordis-catalog
|
|
|
/**
|
|
|
@@ -969,14 +806,17 @@ The turn is about to close: the model owes no response (no live tool calls, no f
|
|
|
* re-reads its inbox: fresh steering runs another step, none closes the
|
|
|
* turn. Data decides, so listener order cannot change the outcome. The
|
|
|
* inverse control (stop a tool loop early) is data too: a tool result
|
|
|
- * carrying `concludesTurn` ends the turn at its step.
|
|
|
- * @param agent - the agent whose turn is at its stop boundary.
|
|
|
- * @param turn - the turn about to close.
|
|
|
- * @param signal - the current turn's explicit abort signal.
|
|
|
+ * carrying `concludesTurn` ends the turn at its step. The conclusion
|
|
|
+ * never short-circuits already-submitted next-step work: same-step
|
|
|
+ * `additionalContexts` or racing steering still runs, and the turn
|
|
|
+ * closes only when that inbox drains.
|
|
|
+ * @param payload.agent - the agent whose turn is at its stop boundary.
|
|
|
+ * @param payload.turn - the turn about to close.
|
|
|
+ * @param payload.signal - the current turn's explicit abort signal.
|
|
|
* Scope-filtered dispatch (`@deepseek-ai/dsh-scope`): agent-scoped listeners receive only that agent.
|
|
|
* @mode serial
|
|
|
*/
|
|
|
-'agent/turn-stopping'(this: Scoped<Agent>, agent: Agent, turn: number, signal: AbortSignal): Promise<void> | void
|
|
|
+'agent/turn-stopping'(this: Scoped<Agent>, payload: { agent: Agent; turn: number; signal: AbortSignal }): Promise<void> | void
|
|
|
```
|
|
|
|
|
|
Types: [Scoped](scope.md)
|
|
|
@@ -999,12 +839,12 @@ A declarative agent entry failed before it could publish a live agent. Consumers
|
|
|
* Consumers that buffer work for the configured identity use this
|
|
|
* transient signal to reject that work instead of waiting forever. Normal
|
|
|
* factory teardown suppresses failures from the cancelled startup attempt.
|
|
|
- * @param sessionId - exact shared agent/session identity that failed startup.
|
|
|
- * @param error - persistence, setup, or publication failure.
|
|
|
+ * @param payload.sessionId - exact shared agent/session identity that failed startup.
|
|
|
+ * @param payload.error - persistence, setup, or publication failure.
|
|
|
* @mode emit
|
|
|
*/
|
|
|
-'agent-loop/config-start-failed'(sessionId: SessionId, error: unknown): void
|
|
|
+'agent-loop/config-start-failed'(payload: { sessionId: SessionId; error: unknown }): void
|
|
|
```
|
|
|
|
|
|
-Source: [`packages/core/agent-loop/src/index.ts:157`](../../packages/core/agent-loop/src/index.ts)
|
|
|
+Source: [`packages/core/agent-loop/src/index.ts:182`](../../packages/core/agent-loop/src/index.ts)
|
|
|
<!-- END GENERATED cordis-surface -->
|
Tianyi Cui