290 lines
14 KiB
Markdown
290 lines
14 KiB
Markdown
<!-- Generated by scripts/gen-website-api.ts — do not edit by hand. Run `pnpm run gen-website-api` to regenerate. -->
|
|
|
|
# ctx.agents
|
|
|
|
`AgentRegistry` — provided by `@deepseek-ai/dsh-agent`.
|
|
|
|
Agent service (`ctx.agents`): tracks live agents and carries the initiating Agent through one process-local asynchronous driver chain. Agent *creation* is provided by whichever plugin implements the AgentFactory (`@deepseek-ai/dsh-agent-loop`), registered via setFactory.
|
|
|
|
[Source](https://github.com/deepseek-harness/deepseek-harness/blob/master/packages/core/agent/src/index.ts#L211)
|
|
|
|
### ctx.agents.currentInitiator()
|
|
|
|
```ts website-api
|
|
currentInitiator(): Agent | undefined
|
|
```
|
|
|
|
Read the Agent that initiated the inherited asynchronous driver chain.
|
|
|
|
**Returns** the inherited Agent, or `undefined` outside a driver and inside an explicit clearing boundary.
|
|
|
|
[Source](https://github.com/deepseek-harness/deepseek-harness/blob/master/packages/core/agent/src/index.ts#L246)
|
|
|
|
### ctx.agents.requireInitiator()
|
|
|
|
```ts website-api
|
|
requireInitiator(): Agent
|
|
```
|
|
|
|
Read the initiating Agent and fail when no driver boundary is active.
|
|
|
|
**Returns** the inherited Agent.
|
|
|
|
[Source](https://github.com/deepseek-harness/deepseek-harness/blob/master/packages/core/agent/src/index.ts#L256)
|
|
|
|
### ctx.agents.withInitiator(agent, operation)
|
|
|
|
```ts website-api
|
|
withInitiator<T>(agent: Agent, operation: () => T): T
|
|
```
|
|
|
|
Run an operation with one exact Agent as its process-local initiator. The exact synchronous value or Promise returned by the operation is preserved. If its inherited async chain starts an owning-fiber unload, the nested boundary lineage is excluded from the drain so teardown cannot wait on itself.
|
|
|
|
- `agent` — initiating Agent to inherit; presence is neither liveness proof nor authorization.
|
|
- `operation` — synchronous or asynchronous operation to invoke.
|
|
|
|
**Returns** the exact value returned by `operation`.
|
|
|
|
[Source](https://github.com/deepseek-harness/deepseek-harness/blob/master/packages/core/agent/src/index.ts#L272)
|
|
|
|
### ctx.agents.withoutInitiator(operation)
|
|
|
|
```ts website-api
|
|
withoutInitiator<T>(operation: () => T): T
|
|
```
|
|
|
|
Run an operation inside a boundary that hides any inherited initiating Agent. The exact synchronous value or Promise is preserved. If its inherited async chain starts an owning-fiber unload, the nested boundary lineage is excluded from the drain so teardown cannot wait on itself.
|
|
|
|
- `operation` — synchronous or asynchronous operation to invoke without an initiator.
|
|
|
|
**Returns** the exact value returned by `operation`.
|
|
|
|
[Source](https://github.com/deepseek-harness/deepseek-harness/blob/master/packages/core/agent/src/index.ts#L285)
|
|
|
|
### ctx.agents.setFactory(factory)
|
|
|
|
```ts website-api
|
|
/**
|
|
* Register the agent-creation factory (the loop calls this on construction,
|
|
* effect-scoped). A traced Cordis service is canonicalized to its concrete
|
|
* target; each create/resume call is then traced through that caller's
|
|
* context so ownership follows the caller without stacking proxy layers.
|
|
* Throws if a factory is already registered. Returns the disposer; on
|
|
* dispose the factory slot is cleared.
|
|
* @param factory - the loop-owned factory {@link create}/{@link resume} delegate to.
|
|
* @returns the disposer that clears the factory slot. The exact
|
|
* Cordis effect disposer (single-shot): composite (generator) effects may
|
|
* yield it directly — exact identity nests the teardown in order.
|
|
*/
|
|
setFactory(factory: AgentFactory): () => void
|
|
```
|
|
|
|
Register the agent-creation factory (the loop calls this on construction, effect-scoped). A traced Cordis service is canonicalized to its concrete target; each create/resume call is then traced through that caller's context so ownership follows the caller without stacking proxy layers. Throws if a factory is already registered. Returns the disposer; on dispose the factory slot is cleared.
|
|
|
|
- `factory` — the loop-owned factory `create`/`resume` delegate to.
|
|
|
|
**Returns** the disposer that clears the factory slot. The exact Cordis effect disposer (single-shot): composite (generator) effects may yield it directly — exact identity nests the teardown in order.
|
|
|
|
[Source](https://github.com/deepseek-harness/deepseek-harness/blob/master/packages/core/agent/src/index.ts#L301)
|
|
|
|
### ctx.agents.create(options)
|
|
|
|
```ts website-api
|
|
/**
|
|
* Create and publish a new agent through the registered factory.
|
|
* Distinct from {@link register} (which records an already-constructed
|
|
* agent): this constructs the agent and its session. Rejects if no factory is
|
|
* registered or creation/setup fails. The resolved {@link AgentHandle} lets
|
|
* the owner tear down exactly this agent.
|
|
* @param options - shared identity, session seed/metadata, and agent options.
|
|
* @returns the handle after setup, rollback-covered publication, and loop start complete.
|
|
*/
|
|
async create(options: CreateAgentOptions): Promise<AgentHandle>
|
|
```
|
|
|
|
Create and publish a new agent through the registered factory. Distinct from register (which records an already-constructed agent): this constructs the agent and its session. Rejects if no factory is registered or creation/setup fails. The resolved AgentHandle lets the owner tear down exactly this agent.
|
|
|
|
- `options` — shared identity, session seed/metadata, and agent options.
|
|
|
|
**Returns** the handle after setup, rollback-covered publication, and loop start complete.
|
|
|
|
[Source](https://github.com/deepseek-harness/deepseek-harness/blob/master/packages/core/agent/src/index.ts#L334)
|
|
|
|
### ctx.agents.resume(options)
|
|
|
|
```ts website-api
|
|
/**
|
|
* Load a persisted session and resume an agent on it through the registered
|
|
* factory. Rejects if no factory is registered; the factory rejects if
|
|
* session persistence is not configured or persistence/setup fails.
|
|
* @param options - persisted identity, configuration, and optional setup.
|
|
* @returns the handle after setup, rollback-covered publication, and loop start complete.
|
|
*/
|
|
async resume(options: ResumeAgentOptions): Promise<AgentHandle>
|
|
```
|
|
|
|
Load a persisted session and resume an agent on it through the registered factory. Rejects if no factory is registered; the factory rejects if session persistence is not configured or persistence/setup fails.
|
|
|
|
- `options` — persisted identity, configuration, and optional setup.
|
|
|
|
**Returns** the handle after setup, rollback-covered publication, and loop start complete.
|
|
|
|
[Source](https://github.com/deepseek-harness/deepseek-harness/blob/master/packages/core/agent/src/index.ts#L353)
|
|
|
|
### ctx.agents.register(agent)
|
|
|
|
```ts website-api
|
|
/**
|
|
* Register a live agent. Throws if an agent with the same id is already
|
|
* registered. Emits `agent/created` on registration and `agent/disposed`
|
|
* when the calling fiber is disposed — both with the agent's scope carrier
|
|
* (`scopeTarget(agent, agent)`): the subject is the agent in hand, so the
|
|
* emits are scope-filtered regardless of which context invoked `register`
|
|
* (calling through `agent.ctx` scopes EFFECTS; dispatch scoping always
|
|
* requires passing the carrier). Returns the disposer.
|
|
* @param agent - the already-constructed agent to record in the store.
|
|
* @returns the EXACT Cordis effect disposer (single-shot; a repeat call
|
|
* returns undefined without awaiting an in-flight teardown). Exact
|
|
* identity is load-bearing: a composite (generator) effect that owns a
|
|
* teardown ORDER — the agent factory's lifecycle chain — must yield THIS
|
|
* function so Cordis nests the unregistration at that yield position;
|
|
* yielding a wrapper would leave it disposing as a concurrent sibling on
|
|
* owner unload, unregistering the agent (and emitting `agent/disposed`)
|
|
* while its final turn is still draining.
|
|
*/
|
|
register(agent: Agent): () => void
|
|
```
|
|
|
|
Register a live agent. Throws if an agent with the same id is already registered. Emits `agent/created` on registration and `agent/disposed` when the calling fiber is disposed — both with the agent's scope carrier (`scopeTarget(agent, agent)`): the subject is the agent in hand, so the emits are scope-filtered regardless of which context invoked `register` (calling through `agent.ctx` scopes EFFECTS; dispatch scoping always requires passing the carrier). Returns the disposer.
|
|
|
|
- `agent` — the already-constructed agent to record in the store.
|
|
|
|
**Returns** the EXACT Cordis effect disposer (single-shot; a repeat call returns undefined without awaiting an in-flight teardown). Exact identity is load-bearing: a composite (generator) effect that owns a teardown ORDER — the agent factory's lifecycle chain — must yield THIS function so Cordis nests the unregistration at that yield position; yielding a wrapper would leave it disposing as a concurrent sibling on owner unload, unregistering the agent (and emitting `agent/disposed`) while its final turn is still draining.
|
|
|
|
[Source](https://github.com/deepseek-harness/deepseek-harness/blob/master/packages/core/agent/src/index.ts#L379)
|
|
|
|
### ctx.agents.enter(agent, owner)
|
|
|
|
```ts website-api
|
|
/**
|
|
* Insert an already-constructed agent without announcing it. This is the
|
|
* advanced ordered-lifecycle primitive used by the async agent factory: it
|
|
* first completes setup while the agent is unpublished, then assigns the
|
|
* returned detach closure into its pre-installed composite teardown before
|
|
* calling {@link announce}. Ordinary callers use {@link register}.
|
|
* @param agent - the prepared, unpublished agent.
|
|
* @param owner - live agent whose scoped context created this agent, or
|
|
* undefined for a top-level runtime root. This is runtime ownership, not
|
|
* the resumed session's durable parent lineage.
|
|
* @returns an idempotent closure that removes this exact entry and emits
|
|
* `agent/disposed` with listener failures contained. When called from a
|
|
* synchronous `agent/created` listener, removal and disposal wait until
|
|
* that creation dispatch unwinds.
|
|
*/
|
|
enter(agent: Agent, owner: Agent | undefined): () => void
|
|
```
|
|
|
|
Insert an already-constructed agent without announcing it. This is the advanced ordered-lifecycle primitive used by the async agent factory: it first completes setup while the agent is unpublished, then assigns the returned detach closure into its pre-installed composite teardown before calling announce. Ordinary callers use register.
|
|
|
|
- `agent` — the prepared, unpublished agent.
|
|
- `owner` — live agent whose scoped context created this agent, or undefined for a top-level runtime root. This is runtime ownership, not the resumed session's durable parent lineage.
|
|
|
|
**Returns** an idempotent closure that removes this exact entry and emits `agent/disposed` with listener failures contained. When called from a synchronous `agent/created` listener, removal and disposal wait until that creation dispatch unwinds.
|
|
|
|
[Source](https://github.com/deepseek-harness/deepseek-harness/blob/master/packages/core/agent/src/index.ts#L403)
|
|
|
|
### ctx.agents.announce(agent)
|
|
|
|
```ts website-api
|
|
/**
|
|
* Announce an agent previously inserted with {@link enter}.
|
|
* @param agent - the live inserted agent to announce.
|
|
* @throws if `agent` is not the exact live registry entry for its id, or its
|
|
* creation announcement already began (including a reentrant call from a
|
|
* creation listener).
|
|
*/
|
|
announce(agent: Agent): void
|
|
```
|
|
|
|
Announce an agent previously inserted with enter.
|
|
|
|
- `agent` — the live inserted agent to announce.
|
|
|
|
[Source](https://github.com/deepseek-harness/deepseek-harness/blob/master/packages/core/agent/src/index.ts#L478)
|
|
|
|
### ctx.agents.get(id)
|
|
|
|
```ts website-api
|
|
/**
|
|
* Look up a live agent.
|
|
* @param id - the shared agent/session id to look up.
|
|
* @returns the agent, or undefined when no live agent has that id.
|
|
*/
|
|
get(id: SessionId): Agent | undefined
|
|
```
|
|
|
|
Look up a live agent.
|
|
|
|
- `id` — the shared agent/session id to look up.
|
|
|
|
**Returns** the agent, or undefined when no live agent has that id.
|
|
|
|
[Source](https://github.com/deepseek-harness/deepseek-harness/blob/master/packages/core/agent/src/index.ts#L512)
|
|
|
|
### ctx.agents.isOwnedBy(id, owner)
|
|
|
|
```ts website-api
|
|
/**
|
|
* Test whether a live agent was created through one exact parent agent's
|
|
* scoped context. Runtime ownership is independent of durable session
|
|
* lineage and remains unambiguous when unrelated providers reuse an id.
|
|
* @param id - the candidate child agent's shared agent/session id.
|
|
* @param owner - the expected runtime creator agent.
|
|
* @returns true only while the exact child entry is live under that owner.
|
|
*/
|
|
isOwnedBy(id: SessionId, owner: Agent): boolean
|
|
```
|
|
|
|
Test whether a live agent was created through one exact parent agent's scoped context. Runtime ownership is independent of durable session lineage and remains unambiguous when unrelated providers reuse an id.
|
|
|
|
- `id` — the candidate child agent's shared agent/session id.
|
|
- `owner` — the expected runtime creator agent.
|
|
|
|
**Returns** true only while the exact child entry is live under that owner.
|
|
|
|
[Source](https://github.com/deepseek-harness/deepseek-harness/blob/master/packages/core/agent/src/index.ts#L524)
|
|
|
|
### ctx.agents.list()
|
|
|
|
```ts website-api
|
|
/**
|
|
* All live agents, in registration order.
|
|
* @returns a fresh array; mutating it does not affect the registry.
|
|
*/
|
|
list(): Agent[]
|
|
```
|
|
|
|
All live agents, in registration order.
|
|
|
|
**Returns** a fresh array; mutating it does not affect the registry.
|
|
|
|
[Source](https://github.com/deepseek-harness/deepseek-harness/blob/master/packages/core/agent/src/index.ts#L532)
|
|
|
|
### ctx.agents.roots()
|
|
|
|
```ts website-api
|
|
/**
|
|
* All live top-level agents in registration order. A top-level agent was
|
|
* created without an owning agent context; durable session lineage does not
|
|
* affect this runtime relation, so a resumed fork may still be a root.
|
|
* @returns a fresh array; mutating it does not affect the registry.
|
|
*/
|
|
roots(): Agent[]
|
|
```
|
|
|
|
All live top-level agents in registration order. A top-level agent was created without an owning agent context; durable session lineage does not affect this runtime relation, so a resumed fork may still be a root.
|
|
|
|
**Returns** a fresh array; mutating it does not affect the registry.
|
|
|
|
[Source](https://github.com/deepseek-harness/deepseek-harness/blob/master/packages/core/agent/src/index.ts#L542)
|