@deepseek-ai/dsh-agent-loop-testkit 0.1.3-alpha.2 → 0.1.5-alpha.2

package/README.i18n.yaml

@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write packages/test-support/agent-loop-testkit/README.md
-README.md: 7b935594636e265bf4f808f692bba2fae0f83ddf
-README.zh.md: fc9dc688a1e7d4303f7744ed47c7da2d0fbbf67f
+README.md: abcd5966399998fbbeea5ac7573a9ee4085e05ca
+README.zh.md: 76a6a43b07acd65aa135536d41a5c9c1ec122e16

package/README.md

@@ -1,5 +1,5 @@
 ---
-description: "Shared service mounting for tests that exercise the concrete AgentLoop, for test authors wiring real loop prerequisites."
+description: "Prerequisite mounting, production AgentLoop drivers, and explicit Inbox stubs for agent-loop tests."
 kind: "package-library"
 ---
 
@@ -9,7 +9,7 @@ English | [中文](README.zh.md)
 
 ## Summary
 
-`dsh-agent-loop-testkit` mounts the standard prerequisite services a test needs before loading the concrete `AgentLoop` — the LLM runtime, session store, system-prompt registry, tool registry, and agent registry — in dependency order, with one call. The loop itself, adapters, optional plugins, agents, and teardown stay in the test's hands, so each scenario keeps its own load order and topology. Use it when a test's subject is loop behavior rather than service wiring; tests that probe injection failures or partial topologies mount their dependencies directly. It registers no model-facing behavior of its own.
+Use `dsh-agent-loop-testkit` to give AgentLoop tests the standard prerequisites and a production loop driver without repeating setup. The harness creates real Agents and exposes Inbox input claiming for tests of durable events, recovery, notifications, and claim behavior. For consumer tests that need only queue editing, choose the process-local Inbox stub; choose the fail-fast Inbox when pending input must never be touched. Tests still own adapters, optional plugins, load order, and context disposal, and the package adds no model-visible behavior.
 
 ## Table of Contents
 
@@ -25,31 +25,54 @@ English | [中文](README.zh.md)
 <a id="use-this-package"></a>
 ## Use this package
 
-This package gives an AgentLoop test a working service topology before the loop is mounted: call the helper on your test context, then mount `AgentLoop` with the configuration under test and register your adapter and optional plugins.
+This package gives an AgentLoop test a working service topology and keeps the choice between production Inbox behavior and a structural stub explicit.
 
-### Minimal example
+### Drive a production Agent
+
+Use `mountAgentLoopTestHarness()` when the test covers durable Inbox events, projection recovery or validation, live Inbox notifications, or loop-driver claims. Mount any load-order-sensitive consumers after the prerequisites and before creating the Agent. The context owns the loop and every Agent returned by the harness.
 
 ```ts
 import { Context } from '@deepseek-ai/cordis'
-import AgentLoop from '@deepseek-ai/dsh-agent-loop'
-import { mountAgentLoopTestDependencies } from '@deepseek-ai/dsh-agent-loop-testkit'
+import { SessionId, type UserMessage } from '@deepseek-ai/dsh-session'
+import {
+  mountAgentLoopTestDependencies,
+  mountAgentLoopTestHarness,
+} from '@deepseek-ai/dsh-agent-loop-testkit'
 
 const ctx = new Context()
 
 await mountAgentLoopTestDependencies(ctx)
-// Register the test adapter and any optional plugins here.
-await ctx.plugin(AgentLoop, { agents: [] })
+// Register the test adapter and any load-order-sensitive plugins here.
+const harness = await mountAgentLoopTestHarness(ctx)
+const agent = await harness.create(SessionId('test-agent'))
+declare const message: UserMessage
+
+agent.inbox.append('next-turn', message)
+const admitted = harness.claim(agent, 'next-turn', 1)
 ```
 
-The helper activates the LLM, session, system-prompt, tool, and agent services in dependency order and returns before the loop is mounted. System-prompt and tool-registry configuration can be forwarded through `options`; the helper provides no test defaults beyond those the services own.
+The dependency helper forwards system-prompt and tool-registry configuration through `options` and provides no test defaults beyond those services' own defaults. A plugin-load failure rejects the helper call; services activated earlier in the sequence remain context-owned and unwind when the context is disposed.
+
+### Build a structural Agent stub
+
+Use `createInboxStub()` when the test subject needs mutable pending lists but does not exercise durability, projection validation, live Inbox notifications, or the driver's claim policy. The stub implements the public queue operations with two process-local arrays and never writes to a Session. Use `unsupportedInbox()` when the test subject must not touch pending input; every mutation throws at the first unexpected dependency.
+
+```ts
+import { createInboxStub } from '@deepseek-ai/dsh-agent-loop-testkit'
+
+const agent = {
+  // ...
+  inbox: createInboxStub(),
+}
+```
 
 ### When to use it
 
-Use the helper for tests whose subject is the loop: load order, retries, tool execution, or session behavior on a real prerequisite stack. Mount dependencies directly when a test probes service load order, injection failures, partial topologies, or teardown — the helper hides exactly the wiring such tests must control.
+Use the dependency and loop helpers for tests whose subject is production loop or durable Inbox behavior. Use the structural stub for consumer-domain tests that only need queue editing. Mount dependencies directly when a test probes service injection failures or partial topologies, because the helper hides exactly the wiring those tests must control.
 
 ### What can go wrong
 
-A plugin-load failure rejects the helper call; services activated earlier in the sequence remain owned by your context and unwind with it. The context owns every mounted service, so dispose it after the test.
+The harness mounts no LLM adapter. Register an adapter before sending work that would start a model request. Dispose the owning context after every test so Agents reach quiescence and their scoped registrations unwind.
 
 -----
 
@@ -59,11 +82,11 @@ A plugin-load failure rejects the helper call; services activated earlier in the
 <details>
 <summary>Implementation internals — click to expand</summary>
 
-This section explains the design of the helper; the observable behavior is fully covered in [Use this package](#use-this-package).
+This section explains the design of the test utilities; the observable behavior is fully covered in [Use this package](#use-this-package).
 
 ### Design
 
-**Runtime invariant:** No companion is published. This test-support package owns no production event stream or mutable data; consuming test suites exercise its behavior.
+`mountAgentLoopTestDependencies` mounts six service plugins in a fixed dependency order — LLM, session, session-projection registry, system-prompt registry, tool registry, then agent registry — and stops before `AgentLoop`, so the caller controls loop load order. `mountAgentLoopTestHarness` mounts the public production plugin, creates Agents through its service, and exposes the production driver's claim operation without exporting the loop's concrete Inbox class or projection definition. [`src/inbox.ts`](src/inbox.ts) contains only the process-local mutable stub and the fail-fast unsupported placeholder; it owns no projection or durable event implementation. The mounting and driver implementation lives in [`src/index.ts`](src/index.ts). No invariant companion is published because the package owns only test helpers and has no independent production observations that can diverge.
 
 </details>
 
@@ -72,11 +95,11 @@ This section explains the design of the helper; the observable behavior is fully
 <a id="further-exploration"></a>
 ## Further Exploration
 
-Read these pages when the package-level contract is not enough. They move from the loop to the services the helper mounts and the tests that use it.
+Read these pages when the package-level behavior is not enough. They move from the loop to the services the helper mounts and the tests that use it.
 
-- [Agent loop package](../../core/agent-loop/README.md) — the concrete loop this helper prepares tests for.
-- [Session package](../../core/session/README.md) — the session store the helper mounts.
-- [LLM package](../../llm/llm/README.md) — the LLM runtime and adapter contract the helper mounts.
+- [Agent loop package](../../core/agent-loop/README.md) — the concrete loop this helper mounts for production behavior.
+- [Session package](../../core/session/README.md) — the durable event log used by production Inbox behavior.
+- [LLM package](../../llm/llm/README.md) — the LLM runtime and adapter interface the helper prepares.
 - [Testing policy](../../../docs/testing.md) — the coverage tiers these tests serve.
 - [Test-support group map](../README.md) — sibling harnesses and support packages.
 
@@ -85,20 +108,22 @@ Read these pages when the package-level contract is not enough. They move from t
 <a id="model-experience"></a>
 ## Model Experience
 
-None, as this test-only composition helper neither drives nor modifies model requests.
+None, as these test-only utilities neither assemble nor modify model requests.
 
 #### KV Cache effect
 
-None; this package neither assembles nor sends a provider request.
+None; the package itself sends no provider request.
 
 ## Known Limitations and Deferred Work
 
 <a id="known-limitations-and-deferred-work"></a>
 
+These limits define what the utilities do not share. They are current package constraints, not a task backlog.
 
-These limits define what the helper does not share. They are current package constraints, not a task backlog.
-
-- **Only the mandatory prerequisite spine is shared** — adapters, optional plugins, `AgentLoop`, agents, and context teardown remain caller-owned so scenario-specific ordering stays visible.
+- **Only the mandatory prerequisite spine is shared** — adapters, optional plugins, scenario-specific load order, and context teardown remain caller-owned.
+- **The production harness has no adapter default** — tests that start the loop must register the route they exercise.
+- **The mutable Inbox stub is process-local only** — use a harness-created Agent whenever durable events, projection recovery or validation, live notifications, or claim policy matter.
+- **The unsupported Inbox accepts no mutations** — use the mutable stub or a harness-created Agent whenever pending input is part of the test subject.
 
 <a id="dev-note"></a>
 ### Dev Note

package/README.zh.md

@@ -1,5 +1,5 @@
 ---
-description: "为运行具体 AgentLoop 的测试挂载共享服务先决依赖，面向接线真实循环前置依赖的测试作者。"
+description: "为 agent-loop 测试提供先决依赖挂载、生产 AgentLoop 驱动与职责明确的 Inbox 桩。"
 kind: "package-library"
 ---
 
@@ -9,7 +9,7 @@ kind: "package-library"
 
 ## 概述
 
-`dsh-agent-loop-testkit` 为测试在加载具体 `AgentLoop` 之前所需的全部标准先决服务——LLM（大语言模型）运行时、会话存储、系统提示词注册表、工具注册表与 agent（智能体）注册表——按依赖顺序一键挂载。loop 本身、适配器、可选插件、agent 与清理仍由测试掌控，因此每个场景都保持自己的加载顺序与拓扑。当测试对象是 loop 行为而非服务接线时使用它；针对注入失败或部分拓扑的测试会直接挂载其依赖。它自身不注册任何模型可见行为。
+使用 `dsh-agent-loop-testkit` 可以为 AgentLoop 测试准备标准先决条件和生产 loop 驱动，避免重复设置。Harness 可以创建真实 Agent，并公开 Inbox 输入认领能力，以测试持久事件、恢复、通知和认领行为。只需编辑队列的消费方测试应选择进程内 Inbox 桩；待处理输入绝不应被访问时，应选择快速失败的 Inbox。测试仍然负责适配器、可选插件、加载顺序和上下文释放，本包不会添加模型可见行为。
 
 ## 目录
 
@@ -25,31 +25,54 @@ kind: "package-library"
 <a id="use-this-package"></a>
 ## 使用本包
 
-本包在 loop 挂载前为 AgentLoop 测试提供可用的服务拓扑：在测试上下文上调用此辅助函数，然后用待测配置挂载 `AgentLoop`，并注册你的适配器与可选插件。
+本包为 AgentLoop 测试提供可用的服务拓扑，并要求测试明确选择生产 Inbox 行为或结构化桩。
 
-### 最小示例
+### 驱动生产 Agent
+
+当测试覆盖持久 Inbox 事件、投影恢复或校验、实时 Inbox 通知，或 loop 驱动的认领策略时，使用 `mountAgentLoopTestHarness()`。应在挂载先决依赖后、创建 Agent 前挂载所有对加载顺序敏感的消费方。上下文拥有 loop 以及该 harness 返回的每个 Agent。
 
 ```ts
 import { Context } from '@deepseek-ai/cordis'
-import AgentLoop from '@deepseek-ai/dsh-agent-loop'
-import { mountAgentLoopTestDependencies } from '@deepseek-ai/dsh-agent-loop-testkit'
+import { SessionId, type UserMessage } from '@deepseek-ai/dsh-session'
+import {
+  mountAgentLoopTestDependencies,
+  mountAgentLoopTestHarness,
+} from '@deepseek-ai/dsh-agent-loop-testkit'
 
 const ctx = new Context()
 
 await mountAgentLoopTestDependencies(ctx)
-// Register the test adapter and any optional plugins here.
-await ctx.plugin(AgentLoop, { agents: [] })
+// Register the test adapter and any load-order-sensitive plugins here.
+const harness = await mountAgentLoopTestHarness(ctx)
+const agent = await harness.create(SessionId('test-agent'))
+declare const message: UserMessage
+
+agent.inbox.append('next-turn', message)
+const admitted = harness.claim(agent, 'next-turn', 1)
 ```
 
-该辅助函数按依赖顺序激活 LLM、会话、系统提示词、工具与 agent 服务，并在 loop 挂载前返回。系统提示词与工具注册表配置可通过 `options` 转发；除服务自有的默认值外，本辅助函数不提供测试默认值。
+依赖辅助函数通过 `options` 转发系统提示词与工具注册表配置，除这些服务自有的默认值外不提供测试默认值。插件加载失败会使辅助函数调用被拒绝；顺序中较早激活的服务仍归上下文所有，并在上下文释放时一并解除。
+
+### 构造结构化 Agent 桩
+
+当测试对象需要可变的待处理列表，但不测试持久性、投影校验、实时 Inbox 通知或驱动的认领策略时，使用 `createInboxStub()`。该桩通过两个进程内数组实现公开队列操作，且绝不会写入 Session。当测试对象不应访问待处理输入时，使用 `unsupportedInbox()`；每次变更都会在首个意外依赖处抛错。
+
+```ts
+import { createInboxStub } from '@deepseek-ai/dsh-agent-loop-testkit'
+
+const agent = {
+  // ...
+  inbox: createInboxStub(),
+}
+```
 
 ### 何时使用
 
-当测试对象是 loop 本身——在真实先决依赖栈上的加载顺序、重试、工具执行或会话行为——时使用此辅助函数。当测试要探测服务加载顺序、注入失败、部分拓扑或清理时，请直接挂载依赖——辅助函数隐藏的正是这类测试必须控制的接线。
+当测试对象是生产 loop 或持久 Inbox 行为时，使用依赖与 loop 辅助函数。只需要编辑队列的消费方领域测试使用结构化桩。当测试探测服务注入失败或部分拓扑时，请直接挂载依赖，因为辅助函数隐藏的正是这类测试必须控制的接线。
 
 ### 可能出什么问题
 
-插件加载失败会使辅助函数调用被拒绝；顺序中较早激活的服务仍归你的上下文所有，并随上下文一起解除。上下文拥有所有已挂载服务，因此测试结束后请 dispose（资源释放）它。
+harness 不会挂载任何 LLM 适配器。若测试发送的任务会启动模型请求，请先注册被测路由的适配器。每个测试结束后都应释放所属上下文，使 Agent 达到静止状态并解除其作用域注册。
 
 -----
 
@@ -59,11 +82,11 @@ await ctx.plugin(AgentLoop, { agents: [] })
 <details>
 <summary>实现细节——点击展开</summary>
 
-本节解释辅助函数的设计；可观察行为已在[使用本包](#use-this-package)中完整说明。
+本节解释测试辅助工具的设计；可观察行为已在[使用本包](#use-this-package)中完整说明。
 
 ### 设计
 
-**运行时不变式：** 不发布伴生入口。本包不持有生产事件流或可变数据；消费它的测试套件会直接检验 harness 行为。
+`mountAgentLoopTestDependencies` 按固定依赖顺序——LLM、会话、会话投影注册表、系统提示词注册表、工具注册表、agent 注册表——挂载六个服务插件，并在 `AgentLoop` 之前停下，使调用方控制 loop 加载顺序。`mountAgentLoopTestHarness` 挂载公开的生产插件，通过其服务创建 Agent，并公开生产驱动的认领操作，而不导出 loop 的具体 Inbox 类或投影定义。[`src/inbox.ts`](src/inbox.ts) 仅包含进程内可变桩和快速失败且不支持操作的占位值；它不持有投影或持久事件实现。挂载与驱动实现位于 [`src/index.ts`](src/index.ts)。本包不发布 invariant companion，因为它只持有测试辅助工具，不存在可能相互偏离的独立生产观测。
 
 </details>
 
@@ -72,11 +95,11 @@ await ctx.plugin(AgentLoop, { agents: [] })
 <a id="further-exploration"></a>
 ## 进一步探索
 
-当包级约定不够用时阅读以下页面。它们从 loop 逐步进入辅助函数挂载的服务以及使用它的测试。
+当包级行为不够用时阅读以下页面。它们从 loop 逐步进入辅助函数挂载的服务以及使用它的测试。
 
-- [Agent loop 包](../../core/agent-loop/README.zh.md)——本辅助函数为之准备测试的具体 loop。
-- [会话包](../../core/session/README.zh.md)——辅助函数挂载的会话存储。
-- [LLM 包](../../llm/llm/README.zh.md)——辅助函数挂载的 LLM 运行时与适配器约定。
+- [Agent loop 包](../../core/agent-loop/README.zh.md)——本辅助函数为生产行为挂载的具体 loop。
+- [会话包](../../core/session/README.zh.md)——生产 Inbox 行为使用的持久事件日志。
+- [LLM 包](../../llm/llm/README.zh.md)——本辅助函数准备的 LLM 运行时与适配器接口。
 - [测试策略](../../../docs/testing.zh.md)——这些测试所服务的覆盖层级。
 - [test-support 组地图](../README.zh.md)——兄弟 harness 与支持包。
 
@@ -85,20 +108,22 @@ await ctx.plugin(AgentLoop, { agents: [] })
 <a id="model-experience"></a>
 ## 模型体验
 
-无。该测试专用组合辅助函数既不驱动也不修改模型请求。
+无。这些测试专用辅助工具既不组装也不修改模型请求。
 
 #### KV Cache 影响
 
-无；本包既不组装也不发送提供方请求。
+无；本包自身不发送提供方请求。
 
 ## 已知限制与延期工作
 
 <a id="known-limitations-and-deferred-work"></a>
 
+这些限制说明辅助工具不共享什么。它们是当前包约束，不是任务积压。
 
-这些限制说明辅助函数不共享什么。它们是当前包约束，不是任务积压。
-
-- **只共享必需的先决主干**——适配器、可选插件、`AgentLoop`、agent 与上下文清理仍由调用方负责，以使特定场景的挂载顺序清晰可见。
+- **只共享必需的先决主干**——适配器、可选插件、场景特定的加载顺序与上下文清理仍由调用方负责。
+- **生产 harness 没有适配器默认值**——启动 loop 的测试必须注册其实际使用的路由。
+- **可变 Inbox 桩仅存在于进程内**——只要持久事件、投影恢复或校验、实时通知或认领策略属于测试对象，就应使用 harness 创建的 Agent。
+- **不支持操作的 Inbox 不接受变更**——只要待处理输入属于测试对象，就应使用可变桩或 harness 创建的 Agent。
 
 <a id="dev-note"></a>
 ### 开发备注

package/lib/index.js

@@ -1,13 +1,90 @@
 import AgentRegistry from "@deepseek-ai/dsh-agent";
+import AgentLoop from "@deepseek-ai/dsh-agent-loop";
 import LlmRuntime from "@deepseek-ai/dsh-llm";
 import SessionStore from "@deepseek-ai/dsh-session";
+import SessionProjectionRegistry from "@deepseek-ai/dsh-session-projection";
 import SystemPrompt from "@deepseek-ai/dsh-system-prompt";
 import ToolRuntime from "@deepseek-ai/dsh-tools";
+//#region lib/types/inbox.js
+/**
+* Create a mutable in-memory Inbox stub for tests that exercise only the public
+* queue operations. Durable events, projection validation, and live Inbox
+* notifications require a real Agent created by the AgentLoop test harness.
+* @returns an Inbox backed by two process-local arrays.
+*/
+function createInboxStub() {
+	const pending = {
+		"next-turn": [],
+		"next-step": []
+	};
+	const locate = (messageId) => {
+		for (const target of ["next-turn", "next-step"]) {
+			const index = pending[target].findIndex((message) => message.id === messageId);
+			if (index >= 0) return {
+				target,
+				index
+			};
+		}
+	};
+	return {
+		get nextTurn() {
+			return pending["next-turn"];
+		},
+		get nextStep() {
+			return pending["next-step"];
+		},
+		clear() {
+			pending["next-step"].splice(0);
+			pending["next-turn"].splice(0);
+		},
+		append(target, message) {
+			pending[target].push(message);
+		},
+		prepend(target, message) {
+			pending[target].unshift(message);
+		},
+		replace(messageId, message) {
+			const location = locate(messageId);
+			if (location === void 0) return false;
+			pending[location.target].splice(location.index, 1, message);
+			return true;
+		},
+		remove(messageId) {
+			const location = locate(messageId);
+			if (location === void 0) return false;
+			pending[location.target].splice(location.index, 1);
+			return true;
+		},
+		splice(target, start, deleteCount, inserted) {
+			return pending[target].splice(start, deleteCount, ...inserted);
+		}
+	};
+}
+/**
+* Create an unsupported Inbox placeholder for Agent stubs whose tests do not exercise Inbox behavior.
+* @returns an Inbox whose pending lists are empty and whose mutation methods throw.
+*/
+function unsupportedInbox() {
+	const rejectMutation = () => {
+		throw new Error("this test Agent does not support Inbox mutations");
+	};
+	return {
+		nextTurn: [],
+		nextStep: [],
+		clear: rejectMutation,
+		append: rejectMutation,
+		prepend: rejectMutation,
+		replace: rejectMutation,
+		remove: rejectMutation,
+		splice: rejectMutation
+	};
+}
+//#endregion
 //#region lib/types/index.js
 /**
-* Shared mounting for the services required before tests load the concrete
-* agent loop. The caller retains ownership of the context, loop, adapters,
-* optional plugins, and teardown.
+* Shared service mounting, real AgentLoop drivers, and structural Inbox stubs
+* for agent-loop tests. Callers retain ownership of their contexts, adapters,
+* optional plugins, agents, and teardown.
 * @module @deepseek-ai/dsh-agent-loop-testkit
 */
 /**
@@ -25,9 +102,25 @@ import ToolRuntime from "@deepseek-ai/dsh-tools";
 async function mountAgentLoopTestDependencies(ctx, options = {}) {
 	await ctx.plugin(LlmRuntime);
 	await ctx.plugin(SessionStore);
+	await ctx.plugin(SessionProjectionRegistry);
 	await ctx.plugin(SystemPrompt, options.systemPrompt ?? {});
 	await ctx.plugin(ToolRuntime, options.tools ?? {});
 	await ctx.plugin(AgentRegistry);
 }
+/**
+* Mount the production AgentLoop and expose its narrow test-driver operations.
+* Mount {@link mountAgentLoopTestDependencies} and any load-order-sensitive
+* consumers before calling this helper. The context owns the loop and every
+* Agent returned by the harness.
+* @param ctx - test context with the AgentLoop prerequisite services active.
+* @returns a driver that creates production Agents and claims their real Inbox.
+*/
+async function mountAgentLoopTestHarness(ctx) {
+	await ctx.plugin(AgentLoop, { agents: [] });
+	return {
+		create: async (id, options = {}, meta = {}) => ctx.agentLoop.create(id, options, meta),
+		claim: (agent, target, turn) => agent.inbox.claim(target, turn)
+	};
+}
 //#endregion
-export { mountAgentLoopTestDependencies };
+export { createInboxStub, mountAgentLoopTestDependencies, mountAgentLoopTestHarness, unsupportedInbox };

package/lib/types/inbox.d.ts

@@ -0,0 +1,14 @@
+import type { Inbox } from '@deepseek-ai/dsh-agent';
+/**
+ * Create a mutable in-memory Inbox stub for tests that exercise only the public
+ * queue operations. Durable events, projection validation, and live Inbox
+ * notifications require a real Agent created by the AgentLoop test harness.
+ * @returns an Inbox backed by two process-local arrays.
+ */
+export declare function createInboxStub(): Inbox;
+/**
+ * Create an unsupported Inbox placeholder for Agent stubs whose tests do not exercise Inbox behavior.
+ * @returns an Inbox whose pending lists are empty and whose mutation methods throw.
+ */
+export declare function unsupportedInbox(): Inbox;
+//# sourceMappingURL=inbox.d.ts.map

package/lib/types/index.d.ts

@@ -1,12 +1,34 @@
 /**
- * Shared mounting for the services required before tests load the concrete
- * agent loop. The caller retains ownership of the context, loop, adapters,
- * optional plugins, and teardown.
+ * Shared service mounting, real AgentLoop drivers, and structural Inbox stubs
+ * for agent-loop tests. Callers retain ownership of their contexts, adapters,
+ * optional plugins, agents, and teardown.
  * @module @deepseek-ai/dsh-agent-loop-testkit
  */
 import type { Context } from '@deepseek-ai/cordis';
+import type { Agent, AgentOptions, InboxTarget } from '@deepseek-ai/dsh-agent';
+import type { SessionHeader, SessionId, UserMessage } from '@deepseek-ai/dsh-session';
 import type { Config as SystemPromptConfig } from '@deepseek-ai/dsh-system-prompt';
 import type { Config as ToolRuntimeConfig } from '@deepseek-ai/dsh-tools';
+export { createInboxStub, unsupportedInbox } from './inbox.ts';
+/** Test driver for production Agents created by a mounted AgentLoop. */
+export interface AgentLoopTestHarness {
+    /**
+     * Create a production Agent and fresh Session owned by the harness context.
+     * @param id - shared Agent and Session identity.
+     * @param options - concrete loop options.
+     * @param meta - optional fresh-session workspace metadata.
+     * @returns the published production Agent after creation completes.
+     */
+    create(id: SessionId, options?: AgentOptions, meta?: Pick<SessionHeader, 'cwd'>): Promise<Agent>;
+    /**
+     * Admit pending messages through the production loop driver's claim operation.
+     * @param agent - Agent returned by this harness's `create` method.
+     * @param target - boundary whose pending input is admitted.
+     * @param turn - turn that owns the admitted messages.
+     * @returns next-step messages followed by one next-turn message when requested.
+     */
+    claim(agent: Agent, target: InboxTarget, turn: number): UserMessage[];
+}
 /** Configuration forwarded to the prerequisite service plugins. */
 export interface AgentLoopTestDependenciesOptions {
     /** Configuration for the system-prompt registry. */
@@ -27,4 +49,13 @@ export interface AgentLoopTestDependenciesOptions {
  * @returns after every prerequisite service has activated.
  */
 export declare function mountAgentLoopTestDependencies(ctx: Context, options?: AgentLoopTestDependenciesOptions): Promise<void>;
+/**
+ * Mount the production AgentLoop and expose its narrow test-driver operations.
+ * Mount {@link mountAgentLoopTestDependencies} and any load-order-sensitive
+ * consumers before calling this helper. The context owns the loop and every
+ * Agent returned by the harness.
+ * @param ctx - test context with the AgentLoop prerequisite services active.
+ * @returns a driver that creates production Agents and claims their real Inbox.
+ */
+export declare function mountAgentLoopTestHarness(ctx: Context): Promise<AgentLoopTestHarness>;
 //# sourceMappingURL=index.d.ts.map

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@deepseek-ai/dsh-agent-loop-testkit",
-  "description": "Shared prerequisite mounting for tests that exercise the concrete agent loop",
-  "version": "0.1.3-alpha.2",
+  "description": "Prerequisite mounting, production AgentLoop drivers, and Inbox stubs for tests",
+  "version": "0.1.5-alpha.2",
   "publishConfig": {
     "access": "public"
   },
@@ -27,20 +27,24 @@
   ],
   "license": "MIT",
   "peerDependencies": {
-    "@deepseek-ai/dsh-agent": "^0.1.3-alpha.2",
-    "@deepseek-ai/dsh-llm": "^0.1.3-alpha.2",
-    "@deepseek-ai/dsh-session": "^0.1.3-alpha.2",
-    "@deepseek-ai/dsh-system-prompt": "^0.1.3-alpha.2",
-    "@deepseek-ai/dsh-tools": "^0.1.3-alpha.2",
+    "@deepseek-ai/dsh-agent": "^0.1.5-alpha.2",
+    "@deepseek-ai/dsh-agent-loop": "^0.1.5-alpha.2",
+    "@deepseek-ai/dsh-session": "^0.1.5-alpha.2",
+    "@deepseek-ai/dsh-llm": "^0.1.5-alpha.2",
+    "@deepseek-ai/dsh-session-projection": "^0.1.5-alpha.2",
+    "@deepseek-ai/dsh-system-prompt": "^0.1.5-alpha.2",
+    "@deepseek-ai/dsh-tools": "^0.1.5-alpha.2",
     "@deepseek-ai/cordis": "^4.0.2"
   },
+  "dependencies": {},
   "devDependencies": {
-    "@deepseek-ai/dsh-agent": "^0.1.3-alpha.2",
-    "@deepseek-ai/dsh-llm": "^0.1.3-alpha.2",
-    "@deepseek-ai/dsh-session": "^0.1.3-alpha.2",
-    "@deepseek-ai/dsh-system-prompt": "^0.1.3-alpha.2",
-    "@deepseek-ai/dsh-agent-loop": "^0.1.3-alpha.2",
-    "@deepseek-ai/dsh-tools": "^0.1.3-alpha.2",
-    "@deepseek-ai/cordis": "^4.0.2"
+    "@deepseek-ai/dsh-agent": "^0.1.5-alpha.2",
+    "@deepseek-ai/dsh-agent-loop": "^0.1.5-alpha.2",
+    "@deepseek-ai/dsh-llm": "^0.1.5-alpha.2",
+    "@deepseek-ai/dsh-session": "^0.1.5-alpha.2",
+    "@deepseek-ai/dsh-session-projection": "^0.1.5-alpha.2",
+    "@deepseek-ai/dsh-tools": "^0.1.5-alpha.2",
+    "@deepseek-ai/cordis": "^4.0.2",
+    "@deepseek-ai/dsh-system-prompt": "^0.1.5-alpha.2"
   }
 }