@deepseek-ai/dsh-tool-ralph 0.0.1-rc.1

package/LICENSE

@@ -0,0 +1,28 @@
+BSD 3-Clause License
+
+Copyright (c) 2026, DeepSeek
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+1. Redistributions of source code must retain the above copyright notice, this
+   list of conditions and the following disclaimer.
+
+2. Redistributions in binary form must reproduce the above copyright notice,
+   this list of conditions and the following disclaimer in the documentation
+   and/or other materials provided with the distribution.
+
+3. Neither the name of the copyright holder nor the names of its
+   contributors may be used to endorse or promote products derived from
+   this software without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

package/README.i18n.yaml

@@ -0,0 +1,6 @@
+# Bilingual-pair consistency record (docs/i18n/README.md): the git blob hash of each
+# 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/workflow/tool-ralph/README.md
+README.md: daf242364d1093cff30cd1dc95823e1ecb89a9c7
+README.zh.md: 92c3256188d9b4c38a292ba7697f702dc46db737

package/README.md

@@ -0,0 +1,93 @@
+# @deepseek-ai/dsh-tool-ralph
+
+English | [中文](README.zh.md)
+
+The model-facing `ralph` tool runs a fixed foreground workflow that gives one immutable objective to a sequence of fresh child agents. It demonstrates a specialized orchestration policy as an ordinary plugin over [`ctx.workflows`](../workflow/README.md) and [`ctx.subagents`](../../subagent/subagent/README.md): no Ralph mode or fresh-agent loop is added to `agent-loop`, and the same-session [goal domain](../../goal/goal/README.md) remains independent. The [Ralph Agent Note](../../../.agents/notes/implemented/feature/2026-07-19-fresh-agent-ralph-workflow-tool.md) owns the policy and deferred work.
+
+## Contract
+
+`ralph({ objective, maxRounds? })` waits for the entire run. The deployment config's `maxRounds` is both the default and a ceiling on a call override. Every Ralph round starts one child through `subagentProvider`; that provider must exist, support structured output, and report `inheritsParentContext: false`. The configured provider is carried as `WorkflowStartRequest.subagentProvider`, so the fixed script cannot inspect or change routing and the ordinary model-written `workflow` tool gains no provider selector. The resolved round cap is also carried as `WorkflowStartRequest.maxTotalAgents`, coordinating the fixed loop with the engine's total-child backstop; the engine rejects a Ralph cap above its deployment ceiling before publishing a run.
+
+Each child receives only the immutable objective, its current Ralph round and cap, a shared-workspace-as-authority instruction, and the previous structured handoff. The workspace is long-term memory; parent conversation and prior child sessions are not seeded. Reports have `status: continue | complete | blocked`, a non-empty summary, evidence, next steps, and blocker text. Status-specific semantics and the serialized `maxHandoffChars` ceiling are validated inside the fixed workflow and again at the consumer boundary. Invalid, missing, or oversized reports fail the workflow instead of being truncated or mistaken for cap exhaustion.
+
+The successful terminal tool result is `complete`, `blocked`, or `budget-limited`, with the last bounded report and number of rounds started. The canonical envelope is `{ runId, agentsStarted, result }`; completion and blocker labels in its Native renderer explicitly say that a worker reported the outcome, not independent certification. `maxResultChars` bounds only that rendered text including its truncation marker, without altering the validated report in the canonical value or the cross-round handoff.
+
+An ordinary child failure produces an error naming the failed round and retaining the last successful handoff when one exists. Ralph does not retry that round. Fatal provider-start, transport, worker, or workflow failures remain workflow errors and may settle before the fixed script can return a handoff. Cancellation is also an error; partial output is never success.
+
+## Lifecycle and cancellation
+
+The caller's agent is the parent of every fresh child, preserving cwd and lineage without copying its conversation. `exec.signal` enters the workflow engine and is also bridged to `run.cancel()` for implementation independence. The tool awaits `run.result` and calls `run.dispose()` in `finally`, so a cancelled parent step waits for the engine's bounded termination and child quiescence before returning.
+
+## Render intent
+
+The pending call is a `generic` card titled `ralph`; the immutable objective is its `rawInput`. The result keeps the generic card. Both presentation functions depend only on tool arguments and the settled tool envelope.
+
+## Config
+
+| Key | Default | Meaning |
+|---|---|---|
+| `subagentProvider` | `spawn` | Fresh structured-output provider used for every round. |
+| `maxRounds` | `256` | Default and deployment ceiling for one Ralph run. |
+| `maxHandoffChars` | `16384` | Maximum serialized characters in one round report. |
+| `maxResultChars` | `16384` | Maximum characters in the complete successful parent result. |
+
+All config values are normalized and validated when the plugin applies, including direct application outside Loader schema normalization. Provider capabilities are resolved immediately before each call because provider registration can change under plugin lifecycle and HMR.
+
+## Model Experience
+
+### System prompt
+
+#### What the model sees
+
+Every parent request in this plugin's registration scope receives the fixed routing guidance below.
+
+##### Ralph guidance
+
+```markdown
+Use the ralph tool ONLY when the direct human explicitly asks for a Ralph loop or fresh-agent iterative execution. Each Ralph round starts a fresh child with no conversation seed and uses the shared workspace as durable memory. Completion and blockers are worker reports, not independent evaluation. Use same-session goal tools for ordinary long-running objectives, and plain subagents or workflows for bounded delegation and fan-out.
+```
+
+#### Token effect
+
+Small fixed guidance cost per request while the plugin is active.
+
+#### KV Cache effect
+
+Prefix-stable while the plugin scope and guidance text are unchanged. Activation or disposal may invalidate reuse from this prompt section.
+
+### Tool schema
+
+#### What the model sees
+
+The generated [`ralph` schema](../../../docs/tool-catalog.md#deepseek-aidsh-tool-ralph) exposes one required `objective` string and one optional `maxRounds` number. Provider choice, handoff size, report schema, workflow script, and orchestration behavior are deployment-owned and absent from the call surface.
+
+#### Token effect
+
+Small fixed schema cost on each request where the tool is visible.
+
+#### KV Cache effect
+
+Prefix-stable while the definition and visibility are unchanged.
+
+### Child requests and parent result
+
+#### What the model sees
+
+Each child sees the standalone fixed round prompt plus the structured-output capture contract. The parent sees only the original call and one terminal result containing a worker-reported status, round count, and pretty-printed final report; intermediate child messages and reports do not enter the parent conversation. A failed ordinary child instead yields an error with its round number and, after round one, the last successful handoff.
+
+#### Token effect
+
+Every round pays for a fresh child context. `maxHandoffChars` bounds cross-round state and `maxResultChars` independently bounds the complete successful parent text; child work remains outside the parent context.
+
+#### KV Cache effect
+
+Each fresh child has an independent request cache. The parent result appends after the reusable request prefix.
+
+## Known Limitations and Deferred Work
+
+- **Completion is worker self-declaration** — there is no independent evaluator or verifier deciding whether the objective is actually complete; evaluator policy and evaluator-driven continuation are deferred.
+- **Foreground only** — there is no task id, background collection, process-resume checkpoint, scheduler, or wall-clock start policy.
+- **The workspace is the only cross-round long-term memory** — one bounded report is the explicit handoff, and uncommitted conversational reasoning disappears with each child.
+- **One round is one fresh child** — there is no within-round fan-out, model/provider switching, fork context, or model-call-selected provider.
+- **Ordinary child failure is terminal for the run** — the fixed script reports the failed round and last successful handoff but does not retry; fatal workflow infrastructure failures can end before that state is returned.
+- **Only round count bounds aggregate effort** — token, price, and elapsed-time budgets are deferred.

package/README.zh.md

@@ -0,0 +1,93 @@
+# @deepseek-ai/dsh-tool-ralph
+
+[English](README.md) | 中文
+
+面向模型的 `ralph` 工具运行固定的前台工作流，把一个不可变目标依次交给多个全新子 agent（智能体）。它展示如何把专用编排策略实现为基于 [`ctx.workflows`](../workflow/README.md) 和 [`ctx.subagents`](../../subagent/subagent/README.md) 的普通插件：不会向 `agent-loop` 添加 Ralph 模式或全新 agent loop（智能体循环），同会话的[目标领域](../../goal/goal/README.md)也保持独立。策略和暂缓事项由 [Ralph Agent Note](../../../.agents/notes/implemented/feature/2026-07-19-fresh-agent-ralph-workflow-tool.md)负责。
+
+## 约定
+
+`ralph({ objective, maxRounds? })` 会等待整个运行完成。部署配置中的 `maxRounds` 既是默认值，也是调用覆盖值的上限。每个 Ralph Round 通过 `subagentProvider` 启动一个子 agent；该提供方必须存在、支持结构化输出，并报告 `inheritsParentContext: false`。已配置的提供方以 `WorkflowStartRequest.subagentProvider` 传递，使固定脚本无法检查或更改路由，普通的模型编写 `workflow` 工具也不会因此获得提供方选择器。解析后的 Round 上限还会作为 `WorkflowStartRequest.maxTotalAgents` 传递，使固定循环与引擎的子 agent 总数后备上限协同；Ralph 上限超过引擎部署上限时，引擎会在发布运行前拒绝。
+
+每个子 agent 只接收不可变目标、当前 Ralph Round 及其上限、一条「共享工作区是权威状态」指令，以及上一个结构化交接内容。工作区是长期记忆；不会把父级对话或先前子 agent 会话作为初始内容。报告包含 `status: continue | complete | blocked`、非空摘要、证据、后续步骤和阻塞文本。固定工作流内部及消费方边界都会校验特定状态的语义和序列化后的 `maxHandoffChars` 上限。无效、缺失或过大的报告会使工作流失败，而不会被截断或误认为上限耗尽。
+
+成功的终态工具结果为 `complete`、`blocked` 或 `budget-limited`，并包含最后一份有界报告和已启动的 Round 数量。规范包络为 `{ runId, agentsStarted, result }`；Native 渲染器中的完成与阻塞标签会明确说明结果由 worker 报告，而非独立认证。`maxResultChars` 只限制包含截断标记的渲染文本，不会改变规范值中经过校验的报告或跨 Round 交接内容。
+
+普通子 agent 失败会产生错误，其中标明失败的 Round；如果已有上一次成功交接，也会保留它。Ralph 不会重试该 Round。致命的提供方启动、传输、worker 或工作流失败仍是工作流错误，并可能在固定脚本返回交接内容前结算。取消同样属于错误；局部输出绝不会视为成功。
+
+## 生命周期与取消
+
+调用方 agent 是每个全新子 agent 的父级，因此会保留 cwd 和谱系，但不会复制其对话。`exec.signal` 进入工作流引擎，同时也桥接到 `run.cancel()`，以便不依赖具体实现。工具等待 `run.result` 并调用 `run.dispose()`，后一个调用位于 `finally` 中，因此取消的父级步骤会等到引擎完成有界终止且子 agent 完全停稳后才返回。
+
+## 渲染意图
+
+待处理调用使用 `generic` 卡片，标题为 `ralph`；不可变目标作为其 `rawInput`。结果继续使用 generic 卡片。两个呈现函数都只依赖工具参数和已结算的工具包络。
+
+## 配置
+
+| 键 | 默认值 | 含义 |
+|---|---|---|
+| `subagentProvider` | `spawn` | 每个 Round 使用的全新结构化输出提供方。 |
+| `maxRounds` | `256` | 一次 Ralph 运行的默认值和部署上限。 |
+| `maxHandoffChars` | `16384` | 一份 Round 报告序列化后的最大字符数。 |
+| `maxResultChars` | `16384` | 返回给父级的完整成功结果最大字符数。 |
+
+插件应用时会规范化并校验所有配置值，也包括绕过 Loader schema 规范化而直接应用的情况。每次调用前都会立即解析提供方能力，因为提供方注册可能随插件生命周期和热模块替换（HMR）变化。
+
+## 模型体验
+
+### 系统提示词
+
+#### 模型看到的内容
+
+在该插件的注册作用域内，每个父级请求都会收到下方的固定路由指导。
+
+##### Ralph 指导
+
+```markdown
+Use the ralph tool ONLY when the direct human explicitly asks for a Ralph loop or fresh-agent iterative execution. Each Ralph round starts a fresh child with no conversation seed and uses the shared workspace as durable memory. Completion and blockers are worker reports, not independent evaluation. Use same-session goal tools for ordinary long-running objectives, and plain subagents or workflows for bounded delegation and fan-out.
+```
+
+#### Token 影响
+
+插件启用期间，每个请求都会产生少量固定的指导 token 开销。
+
+#### KV Cache 影响
+
+只要插件作用域和指导文本不变，前缀就保持稳定。启用或 dispose（资源释放）可能会使从该提示词段起的缓存复用失效。
+
+### 工具 schema
+
+#### 模型看到的内容
+
+已生成的 [`ralph` schema](../../../docs/tool-catalog.md#deepseek-aidsh-tool-ralph)公开一个必填 `objective` 字符串和一个可选 `maxRounds` 数字。提供方选择、交接大小、报告 schema、工作流脚本和编排行为均由部署侧控制，不在调用接口中。
+
+#### Token 影响
+
+工具可见时，每个请求都会产生少量固定的 schema token 开销。
+
+#### KV Cache 影响
+
+只要定义和可见性不变，前缀就保持稳定。
+
+### 子 agent 请求与父级结果
+
+#### 模型看到的内容
+
+每个子 agent 都会看到独立的固定 Round 提示词和结构化输出捕获约定。父级只看到原始调用和一个终态结果，其中包含 worker 报告的状态、Round 数量及经过美化打印的最终报告；中间子 agent 消息和报告不会进入父级对话。普通子 agent 失败时会改为产生错误，其中包含对应 Round 编号；从第二个 Round 起，还会包含上一次成功交接。
+
+#### Token 影响
+
+每个 Round 都会支付全新子 agent 上下文的成本。`maxHandoffChars` 限制跨 Round 状态，`maxResultChars` 独立限制完整的父级成功文本；子 agent 工作留在父级上下文之外。
+
+#### KV Cache 影响
+
+每个全新子 agent 都有独立的请求缓存。父级结果追加在可复用请求前缀之后。
+
+## 已知限制与暂缓事项
+
+- **完成由 worker 自行声明**：没有独立的评估器或验证器判断目标是否实际完成；评估器策略及评估器驱动的延续均暂缓处理。
+- **仅支持前台**：没有 task id、后台收集、进程恢复检查点、调度器或基于挂钟时间的启动策略。
+- **工作区是唯一的跨 Round 长期记忆**：一份有界报告作为显式交接内容，每个子 agent 结束后，未提交的对话推理都会消失。
+- **一个 Round 对应一个全新子 agent**：Round 内没有扇出、模型/提供方切换、fork 上下文或由模型调用选择的提供方。
+- **普通子 agent 失败会终止运行**：固定脚本报告失败的 Round 和上一次成功交接，但不会重试；致命的工作流基础设施失败可能在该状态返回前结束。
+- **聚合工作量仅受 Round 数量限制**：token、价格和耗时预算均暂缓处理。

package/lib/index.js

@@ -0,0 +1,371 @@
+import z from "@deepseek-ai/schemastery";
+import { defineTool } from "@deepseek-ai/dsh-tools";
+//#region lib/types/index.js
+/**
+* Model-facing foreground Ralph loop over the workflow and subagent seams. A
+* fixed script starts one fresh structured-output child per round, carrying
+* only the immutable objective and the previous bounded handoff between them.
+* @module @deepseek-ai/dsh-tool-ralph
+*/
+const name = "tool-ralph";
+const inject = [
+	"tools",
+	"workflows",
+	"subagents",
+	"systemPrompt"
+];
+/** Schemastery configuration for the Ralph tool. */
+const Config = z.object({
+	subagentProvider: z.string().default("spawn"),
+	maxRounds: z.number().step(1).min(1).max(Number.MAX_SAFE_INTEGER).default(256),
+	maxHandoffChars: z.number().step(1).min(1).max(Number.MAX_SAFE_INTEGER).default(16384),
+	maxResultChars: z.number().step(1).min(1).max(Number.MAX_SAFE_INTEGER).default(16384)
+});
+const RALPH_META = {
+	name: "ralph-loop",
+	description: "Iterate toward one objective with a fresh child and bounded structured handoff per round.",
+	phases: [{
+		title: "Fresh-agent rounds",
+		detail: "One clean child context per Ralph round."
+	}]
+};
+/**
+* Fixed, deployment-owned orchestration. The model supplies data only; it
+* cannot alter the loop, provider route, schema, or handoff validation.
+*/
+const RALPH_SCRIPT = String.raw`
+const reportSchema = {
+  type: 'object',
+  properties: {
+    status: { type: 'string', enum: ['continue', 'complete', 'blocked'] },
+    summary: { type: 'string' },
+    evidence: { type: 'array', items: { type: 'string' } },
+    nextSteps: { type: 'array', items: { type: 'string' } },
+    blocker: { type: 'string' },
+  },
+  required: ['status', 'summary', 'evidence', 'nextSteps', 'blocker'],
+  additionalProperties: false,
+}
+
+function normalizedText(value) {
+  return typeof value === 'string' && value.length > 0 && value === value.trim()
+}
+
+function normalizedList(value) {
+  return Array.isArray(value) && value.every(normalizedText)
+}
+
+function validateReport(report) {
+  if (report === null || typeof report !== 'object' || Array.isArray(report)) {
+    throw new Error('Ralph child returned no structured round report')
+  }
+  if (!normalizedText(report.summary)) {
+    throw new Error('Ralph round report summary must be non-empty and normalized')
+  }
+  if (!normalizedList(report.evidence) || !normalizedList(report.nextSteps)) {
+    throw new Error('Ralph round report evidence and nextSteps must contain only non-empty normalized strings')
+  }
+  if (typeof report.blocker !== 'string' || report.blocker !== report.blocker.trim()) {
+    throw new Error('Ralph round report blocker must be a normalized string')
+  }
+  switch (report.status) {
+    case 'continue':
+      if (report.nextSteps.length === 0 || report.blocker !== '') {
+        throw new Error('a continuing Ralph report needs nextSteps and an empty blocker')
+      }
+      break
+    case 'complete':
+      if (report.evidence.length === 0 || report.nextSteps.length !== 0 || report.blocker !== '') {
+        throw new Error('a complete Ralph report needs evidence, no nextSteps, and an empty blocker')
+      }
+      break
+    case 'blocked':
+      if (!normalizedText(report.blocker)) {
+        throw new Error('a blocked Ralph report needs a concrete blocker')
+      }
+      break
+    default:
+      throw new Error('Ralph round report status is invalid')
+  }
+  const serialized = JSON.stringify(report)
+  if (serialized.length > args.maxHandoffChars) {
+    throw new Error('Ralph round report exceeds maxHandoffChars (' + serialized.length + ' > ' + args.maxHandoffChars + ')')
+  }
+  return report
+}
+
+let previous
+phase('Fresh-agent rounds')
+for (let round = 1; round <= args.maxRounds; round += 1) {
+  const prior = previous === undefined ? '(none — this is the first round)' : JSON.stringify(previous)
+  const prompt = [
+    'You are one fresh worker in a foreground Ralph loop. You receive no parent conversation and no prior child session. Do not call the ralph tool: this round already is its worker.',
+    'Immutable objective:\n' + args.objective,
+    'Ralph round: ' + round + ' of ' + args.maxRounds + '.',
+    'The shared workspace and its current working tree are the long-term memory and source of truth. Inspect them before acting, preserve existing work, perform concrete in-scope work, and verify what you change. Treat the previous report only as a bounded handoff; confirm it against the workspace.',
+    'Previous structured handoff:\n' + prior,
+    'Return one report with exact normalized strings. Use status continue with at least one nextSteps entry while useful work remains; complete only with concrete evidence and no nextSteps; blocked only when no meaningful progress is possible without human input or an external-state change. blocker must be empty unless blocked.',
+  ].join('\n\n')
+  const rawReport = await agent(prompt, {
+    label: 'Ralph round ' + round,
+    phase: 'Fresh-agent rounds',
+    schema: reportSchema,
+  })
+  if (rawReport === null) {
+    return { status: 'round-failed', roundsStarted: round, lastReport: previous ?? null }
+  }
+  const report = validateReport(rawReport)
+  if (report.status === 'complete') return { status: 'complete', roundsStarted: round, report }
+  if (report.status === 'blocked') return { status: 'blocked', roundsStarted: round, report }
+  previous = report
+}
+return { status: 'budget-limited', roundsStarted: args.maxRounds, report: previous }
+`;
+const DESCRIPTION = "Run a foreground fresh-agent Ralph loop toward one immutable objective. Use only when the direct human explicitly asks for Ralph or fresh-agent iteration. Each round opens a new child with no parent conversation or prior child session; the shared workspace is long-term memory, and only a bounded structured report crosses rounds. The call returns when a worker reports completion or a concrete blocker, or at the round limit. Ordinary long-running same-session work belongs to goal tools.";
+/** Validate defaults even when a caller invokes apply() without Loader normalization. */
+function resolveConfig(config) {
+	const subagentProvider = config.subagentProvider ?? "spawn";
+	const maxRounds = config.maxRounds ?? 256;
+	const maxHandoffChars = config.maxHandoffChars ?? 16384;
+	const maxResultChars = config.maxResultChars ?? 16384;
+	if (subagentProvider.length === 0 || subagentProvider !== subagentProvider.trim()) throw new TypeError("subagentProvider must be a non-empty normalized string");
+	if (!Number.isSafeInteger(maxRounds) || maxRounds < 1) throw new TypeError("maxRounds must be a positive safe integer");
+	if (!Number.isSafeInteger(maxHandoffChars) || maxHandoffChars < 1) throw new TypeError("maxHandoffChars must be a positive safe integer");
+	if (!Number.isSafeInteger(maxResultChars) || maxResultChars < 1) throw new TypeError("maxResultChars must be a positive safe integer");
+	return {
+		subagentProvider,
+		maxRounds,
+		maxHandoffChars,
+		maxResultChars
+	};
+}
+/** Resolve one model-selected cap against the deployment ceiling. */
+function resolveMaxRounds(requested, ceiling) {
+	const value = requested ?? ceiling;
+	if (!Number.isSafeInteger(value) || value < 1) throw new TypeError("Ralph maxRounds must be a positive safe integer");
+	if (value > ceiling) throw new TypeError(`Ralph maxRounds ${value} exceeds the deployment ceiling ${ceiling}`);
+	return value;
+}
+/** Require the configured route to mean a genuinely fresh structured child. */
+function requireFreshProvider(ctx, name) {
+	const provider = ctx.subagents.getProvider(name);
+	if (provider === void 0) throw new Error(`Ralph subagent provider "${name}" is not registered`);
+	if (!provider.capabilities.outputSchema) throw new Error(`Ralph subagent provider "${name}" does not support structured output`);
+	if (provider.inheritsParentContext) throw new Error(`Ralph subagent provider "${name}" inherits parent context; Ralph requires a fresh provider`);
+	return provider;
+}
+function isRecord(value) {
+	return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function normalizedText(value) {
+	return typeof value === "string" && value.length > 0 && value === value.trim();
+}
+function normalizedList(value) {
+	return Array.isArray(value) && value.every(normalizedText);
+}
+/** Defensively decode the fixed script's report across a provider boundary. */
+function readReport(value, expectedStatus, maxChars) {
+	if (!isRecord(value) || Object.keys(value).sort().join(",") !== "blocker,evidence,nextSteps,status,summary" || value["status"] !== expectedStatus || !normalizedText(value["summary"]) || !normalizedList(value["evidence"]) || !normalizedList(value["nextSteps"]) || typeof value["blocker"] !== "string" || value["blocker"] !== value["blocker"].trim()) throw new Error("Ralph workflow returned a malformed round report");
+	const report = {
+		status: expectedStatus,
+		summary: value["summary"],
+		evidence: value["evidence"],
+		nextSteps: value["nextSteps"],
+		blocker: value["blocker"]
+	};
+	if (expectedStatus === "continue" && (report.nextSteps.length === 0 || report.blocker !== "")) throw new Error("Ralph workflow returned an invalid continuing report");
+	if (expectedStatus === "complete" && (report.evidence.length === 0 || report.nextSteps.length !== 0 || report.blocker !== "")) throw new Error("Ralph workflow returned an invalid completion report");
+	if (expectedStatus === "blocked" && !normalizedText(report.blocker)) throw new Error("Ralph workflow returned an invalid blocked report");
+	const chars = JSON.stringify(report).length;
+	if (chars > maxChars) throw new Error(`Ralph workflow returned an oversized handoff (${chars} > ${maxChars})`);
+	return report;
+}
+/** Defensively decode the fixed script's terminal value. */
+function readRunResult(value, maxRounds, maxHandoffChars) {
+	if (!isRecord(value) || typeof value["roundsStarted"] !== "number" || !Number.isSafeInteger(value["roundsStarted"]) || value["roundsStarted"] < 1 || value["roundsStarted"] > maxRounds) throw new Error("Ralph workflow returned a malformed terminal result");
+	const roundsStarted = value["roundsStarted"];
+	switch (value["status"]) {
+		case "complete":
+			if (Object.keys(value).sort().join(",") !== "report,roundsStarted,status") throw new Error("Ralph workflow returned a malformed terminal result");
+			return {
+				status: "complete",
+				roundsStarted,
+				report: readReport(value["report"], "complete", maxHandoffChars)
+			};
+		case "blocked":
+			if (Object.keys(value).sort().join(",") !== "report,roundsStarted,status") throw new Error("Ralph workflow returned a malformed terminal result");
+			return {
+				status: "blocked",
+				roundsStarted,
+				report: readReport(value["report"], "blocked", maxHandoffChars)
+			};
+		case "budget-limited":
+			if (Object.keys(value).sort().join(",") !== "report,roundsStarted,status") throw new Error("Ralph workflow returned a malformed terminal result");
+			if (roundsStarted !== maxRounds) throw new Error("Ralph workflow returned budget-limited before the round limit");
+			return {
+				status: "budget-limited",
+				roundsStarted,
+				report: readReport(value["report"], "continue", maxHandoffChars)
+			};
+		case "round-failed":
+			if (Object.keys(value).sort().join(",") !== "lastReport,roundsStarted,status") throw new Error("Ralph workflow returned a malformed terminal result");
+			if (roundsStarted === 1) {
+				if (value["lastReport"] !== null) throw new Error("Ralph workflow returned an invalid first-round failure");
+				return {
+					status: "round-failed",
+					roundsStarted
+				};
+			}
+			if (value["lastReport"] === null) throw new Error("Ralph workflow returned a round failure without its last handoff");
+			return {
+				status: "round-failed",
+				roundsStarted,
+				lastReport: readReport(value["lastReport"], "continue", maxHandoffChars)
+			};
+		default: throw new Error("Ralph workflow returned an unknown terminal status");
+	}
+}
+/** A non-clean workflow finish is an error, never a partial Ralph success. */
+function stopReasonError(result) {
+	switch (result.stopReason) {
+		case "completed": return;
+		case "cancelled": return `Ralph workflow was cancelled${result.error === void 0 ? "" : ` (${result.error})`}`;
+		case "error": return `Ralph workflow failed: ${result.error ?? "unknown error"}`;
+		/* v8 ignore start -- WorkflowStopReason is closed; a future variant must fail loud here. */
+		default: return `Ralph workflow ended abnormally (${String(result.stopReason)})`;
+	}
+}
+const TRUNCATION_NOTICE = "\n… [truncated]";
+/** Bound complete parent-facing text, including its envelope and truncation marker. */
+function boundResult(text, maxChars) {
+	if (text.length <= maxChars) return text;
+	if (maxChars <= 14) return TRUNCATION_NOTICE.slice(0, maxChars);
+	return `${text.slice(0, maxChars - 14)}${TRUNCATION_NOTICE}`;
+}
+/** Render the fixed terminal envelope without presenting self-report as certification. */
+function renderResult(result, maxChars) {
+	const rounds = `${result.roundsStarted} round${result.roundsStarted === 1 ? "" : "s"}`;
+	let text;
+	switch (result.status) {
+		case "complete":
+			text = `Ralph worker reported completion after ${rounds}.\nFinal report:\n${JSON.stringify(result.report, null, 2)}`;
+			break;
+		case "blocked":
+			text = `Ralph worker reported a blocker after ${rounds}.\nFinal report:\n${JSON.stringify(result.report, null, 2)}`;
+			break;
+		case "budget-limited":
+			text = `Ralph reached its ${rounds} limit; the worker reported work remaining.\nFinal report:\n${JSON.stringify(result.report, null, 2)}`;
+			break;
+	}
+	return boundResult(text, maxChars);
+}
+/** Canonical Ralph result fields shared by schema inference and rendering. */
+const RALPH_OUTPUT_PROPERTIES = {
+	runId: {
+		type: "string",
+		required: true
+	},
+	agentsStarted: {
+		type: "integer",
+		required: true
+	},
+	result: {
+		type: "json",
+		required: true
+	}
+};
+/** Render an ordinary child failure with the most recent durable handoff. */
+function renderRoundFailure(result, maxChars) {
+	const header = `Ralph round ${result.roundsStarted} child failed before producing a structured report.`;
+	return boundResult(result.lastReport === void 0 ? `${header}\nNo previous handoff was available.` : `${header}\nLast successful handoff:\n${JSON.stringify(result.lastReport, null, 2)}`, maxChars);
+}
+function presentCall(args) {
+	return {
+		card: "generic",
+		title: "ralph",
+		rawInput: args.objective
+	};
+}
+function presentResult(args, result) {
+	return { card: "generic" };
+}
+/** Register the fixed Ralph tool and its explicit-ask usage policy. */
+function apply(ctx, config) {
+	const resolved = resolveConfig(config);
+	ctx.systemPrompt.section({
+		name: "tool:ralph",
+		order: 116,
+		text: "Use the ralph tool ONLY when the direct human explicitly asks for a Ralph loop or fresh-agent iterative execution. Each Ralph round starts a fresh child with no conversation seed and uses the shared workspace as durable memory. Completion and blockers are worker reports, not independent evaluation. Use same-session goal tools for ordinary long-running objectives, and plain subagents or workflows for bounded delegation and fan-out."
+	});
+	ctx.tools.register(defineTool({
+		name: "ralph",
+		description: DESCRIPTION,
+		parameters: {
+			objective: {
+				type: "string",
+				required: true,
+				description: "The immutable completion objective for every fresh Ralph round."
+			},
+			maxRounds: {
+				type: "number",
+				description: "Optional positive safe-integer round cap, bounded by the deployment ceiling."
+			}
+		},
+		output: {
+			schema: {
+				type: "object",
+				additionalProperties: false,
+				properties: RALPH_OUTPUT_PROPERTIES
+			},
+			render: (_args, value) => [{
+				type: "text",
+				text: renderResult(value.result, resolved.maxResultChars)
+			}]
+		},
+		async execute(args, exec) {
+			const parent = exec.agent;
+			if (parent === void 0) throw new Error("Ralph tool requires a calling agent (exec.agent was undefined)");
+			const objective = args.objective.trim();
+			if (objective.length === 0) throw new Error("Ralph objective must be a non-empty string");
+			const maxRounds = resolveMaxRounds(args.maxRounds, resolved.maxRounds);
+			requireFreshProvider(ctx, resolved.subagentProvider);
+			const run = ctx.workflows.start({
+				script: RALPH_SCRIPT,
+				meta: RALPH_META,
+				args: {
+					objective,
+					maxRounds,
+					maxHandoffChars: resolved.maxHandoffChars
+				},
+				subagentProvider: resolved.subagentProvider,
+				maxTotalAgents: maxRounds,
+				parent,
+				signal: exec.signal
+			});
+			const onAbort = () => {
+				run.cancel("parent step aborted");
+			};
+			exec.signal.addEventListener("abort", onAbort, { once: true });
+			if (exec.signal.aborted) run.cancel("parent step aborted");
+			try {
+				const settled = await run.result;
+				const error = stopReasonError(settled);
+				if (error !== void 0) throw new Error(error);
+				const value = readRunResult(settled.value, maxRounds, resolved.maxHandoffChars);
+				if (value.status === "round-failed") throw new Error(renderRoundFailure(value, resolved.maxResultChars));
+				return {
+					runId: run.id,
+					agentsStarted: settled.agentsStarted,
+					result: value
+				};
+			} finally {
+				exec.signal.removeEventListener("abort", onAbort);
+				await run.dispose();
+			}
+		},
+		presentCall,
+		presentResult
+	}));
+}
+//#endregion
+export { Config, apply, inject, name };

package/lib/invariant.js

@@ -0,0 +1,23 @@
+//#region lib/types/invariant.js
+/**
+* Package-owned invariant companion for `@deepseek-ai/dsh-tool-ralph`.
+* @module @deepseek-ai/dsh-tool-ralph/invariant
+*/
+const PACKAGE_NAME = "@deepseek-ai/dsh-tool-ralph";
+/** Cordis companion plugin name. */
+const name = "tool-ralph-invariant";
+/** Service required before the companion can reserve package ownership. */
+const inject = ["invariants"];
+/**
+* No runtime invariant: this model-facing orchestration adapter owns no independent event stream;
+* workflow and subagent owners validate the runs and child lifecycles it starts.
+*/
+const install = () => {};
+/**
+* Register this package's invariant companion.
+* @param ctx - Cordis context carrying the invariant service.
+* @returns the installed registration's disposer after setup succeeds.
+*/
+const apply = (ctx) => Promise.resolve(ctx.invariants.register(PACKAGE_NAME, install));
+//#endregion
+export { apply, inject, name };

package/lib/types/index.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Model-facing foreground Ralph loop over the workflow and subagent seams. A
+ * fixed script starts one fresh structured-output child per round, carrying
+ * only the immutable objective and the previous bounded handoff between them.
+ * @module @deepseek-ai/dsh-tool-ralph
+ */
+import type { Context } from '@deepseek-ai/cordis';
+import z from '@deepseek-ai/schemastery';
+export declare const name = "tool-ralph";
+export declare const inject: string[];
+/** Deployment policy for the fixed Ralph workflow. */
+export interface Config {
+    /** Fresh structured-output provider used for every round (default `spawn`). */
+    subagentProvider?: string;
+    /** Default and deployment ceiling for one call's round count (default 256). */
+    maxRounds?: number;
+    /** Maximum serialized characters in one structured handoff (default 16384). */
+    maxHandoffChars?: number;
+    /** Maximum characters in a successful parent-facing terminal text (default 16384). */
+    maxResultChars?: number;
+}
+/** Schemastery configuration for the Ralph tool. */
+export declare const Config: z<Config>;
+/** Register the fixed Ralph tool and its explicit-ask usage policy. */
+export declare function apply(ctx: Context, config: Config): void;
+//# sourceMappingURL=index.d.ts.map

package/lib/types/invariant.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Package-owned invariant companion for `@deepseek-ai/dsh-tool-ralph`.
+ * @module @deepseek-ai/dsh-tool-ralph/invariant
+ */
+import type { Context } from '@deepseek-ai/cordis';
+/** Cordis companion plugin name. */
+export declare const name = "tool-ralph-invariant";
+/** Service required before the companion can reserve package ownership. */
+export declare const inject: string[];
+/**
+ * Register this package's invariant companion.
+ * @param ctx - Cordis context carrying the invariant service.
+ * @returns the installed registration's disposer after setup succeeds.
+ */
+export declare const apply: (ctx: Context) => Promise<() => void>;
+//# sourceMappingURL=invariant.d.ts.map

package/package.json

@@ -0,0 +1,64 @@
+{
+  "name": "@deepseek-ai/dsh-tool-ralph",
+  "description": "Model-facing fresh-agent Ralph loop over the workflow and subagent seams",
+  "version": "0.0.1-rc.1",
+  "publishConfig": {
+    "access": "restricted"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/deepseek-ai/deepseek-harness.git",
+    "directory": "packages/workflow/tool-ralph"
+  },
+  "type": "module",
+  "main": "lib/index.js",
+  "types": "lib/types/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./lib/types/index.d.ts",
+      "default": "./lib/index.js"
+    },
+    "./invariant": {
+      "types": "./lib/types/invariant.d.ts",
+      "default": "./lib/invariant.js"
+    },
+    "./src/*": "./src/*",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "lib/index.js",
+    "lib/invariant.js",
+    "lib/types/**/*.d.ts"
+  ],
+  "license": "BSD-3-Clause",
+  "peerDependencies": {
+    "@deepseek-ai/dsh-invariants": "^0.0.1-rc.1",
+    "@deepseek-ai/dsh-subagent": "^0.0.1-rc.1",
+    "@deepseek-ai/dsh-tools": "^0.0.1-rc.1",
+    "@deepseek-ai/dsh-llm": "^0.0.1-rc.1",
+    "@deepseek-ai/dsh-workflow": "^0.0.1-rc.1",
+    "@deepseek-ai/cordis": "^4.0.1-rc.1",
+    "@deepseek-ai/dsh-system-prompt": "^0.0.1-rc.1",
+    "@deepseek-ai/dsh-agent": "^0.0.1-rc.1"
+  },
+  "dependencies": {
+    "@deepseek-ai/schemastery": "^3.18.1-rc.1"
+  },
+  "devDependencies": {
+    "@deepseek-ai/cordis-plugin-loader": "^1.0.1-rc.1",
+    "@deepseek-ai/dsh-agent": "^0.0.1-rc.1",
+    "@deepseek-ai/dsh-agent-loop": "^0.0.1-rc.1",
+    "@deepseek-ai/dsh-agent-loop-testkit": "^0.0.1-rc.1",
+    "@deepseek-ai/dsh-invariants": "^0.0.1-rc.1",
+    "@deepseek-ai/dsh-llm": "^0.0.1-rc.1",
+    "@deepseek-ai/dsh-session": "^0.0.1-rc.1",
+    "@deepseek-ai/dsh-subagent": "^0.0.1-rc.1",
+    "@deepseek-ai/dsh-subagent-inprocess": "^0.0.1-rc.1",
+    "@deepseek-ai/dsh-subagent-spawn": "^0.0.1-rc.1",
+    "@deepseek-ai/dsh-system-prompt": "^0.0.1-rc.1",
+    "@deepseek-ai/dsh-tools": "^0.0.1-rc.1",
+    "@deepseek-ai/dsh-workflow": "^0.0.1-rc.1",
+    "@deepseek-ai/dsh-workflow-workerthread": "^0.0.1-rc.1",
+    "@deepseek-ai/cordis": "^4.0.1-rc.1"
+  }
+}