From fc6db791f18a008db44345101e47d095e8e4270b Mon Sep 17 00:00:00 2001 From: Ziya <199893125+ZiyaZhang@users.noreply.github.com> Date: Wed, 8 Jul 2026 20:45:05 -0700 Subject: [PATCH 01/15] refactor(compact): extract the shared transcript renderer into dsh-compact Move compact-basic's private _extractText/_blocksToText into the interface package as renderTranscript/renderContentBlocks, so the summarize path and a future recall read path render one span identically. Byte-identical output vs the private helpers it replaces; compact-basic delegates. --- docs/cordis-catalog/services.md | 2 +- packages/compact/compact-basic/src/index.ts | 99 +------------ .../compact-basic/tests/compact-basic.spec.ts | 2 +- packages/compact/compact/README.md | 2 +- packages/compact/compact/src/index.ts | 1 + packages/compact/compact/src/render.ts | 118 +++++++++++++++ packages/compact/compact/tests/render.spec.ts | 138 ++++++++++++++++++ 7 files changed, 262 insertions(+), 100 deletions(-) create mode 100644 packages/compact/compact/src/render.ts create mode 100644 packages/compact/compact/tests/render.spec.ts diff --git a/docs/cordis-catalog/services.md b/docs/cordis-catalog/services.md index 26126c4481..53251518b4 100644 --- a/docs/cordis-catalog/services.md +++ b/docs/cordis-catalog/services.md @@ -102,7 +102,7 @@ abstract compactIfNeeded( agent: CompactAgentContext, fullSystemPrompt: string, abstract compactRegion( session: Session, start: number, end: number, agent: CompactAgentContext, signal?: AbortSignal, ): Promise ``` -Source: [`packages/compact/compact/src/index.ts:63`](../../packages/compact/compact/src/index.ts) +Source: [`packages/compact/compact/src/index.ts:64`](../../packages/compact/compact/src/index.ts) ## `ctx.fs` — `FileSystem` (abstract seam) diff --git a/packages/compact/compact-basic/src/index.ts b/packages/compact/compact-basic/src/index.ts index 03f7c9ab4b..3916441402 100644 --- a/packages/compact/compact-basic/src/index.ts +++ b/packages/compact/compact-basic/src/index.ts @@ -30,7 +30,7 @@ */ import { Context } from 'cordis' -import { CompactService } from '@deepseek-ai/dsh-compact' +import { CompactService, renderTranscript } from '@deepseek-ai/dsh-compact' import type { CompactionResult } from '@deepseek-ai/dsh-compact' import { BlockAssembler } from '@deepseek-ai/dsh-llm' import type { ContentBlock, FinishReason, GenerateOptions, Message } from '@deepseek-ai/dsh-llm' @@ -483,7 +483,7 @@ export class BasicCompactService extends CompactService { try { // --- Extract text and summarize --- - const text = this._extractText(session, shadowedSeqs) + const text = renderTranscript(session.events, shadowedSeqs) const { summary, model, maxTokens } = await this.summarize(text, agent, signal) // Estimate token count of the shadowed content for provenance. @@ -679,101 +679,6 @@ export class BasicCompactService extends CompactService { } return null } - - /** - * Extract plain-text conversation from a set of surface node seqs, for - * feeding into the summarization model. Walks the seqs in the order given - * (surface order, as `compactRegion` slices the surface-node list) so the - * summary follows the conversation as the model sees it — which, after a - * `replace`, is NOT ascending log-seq order (a high-seq summary node heads the - * surface before older retained lower-seq nodes). - */ - private _extractText(session: Session, seqs: number[]): string { - const lines: string[] = [] - - // Walk seqs in the order given (surface order, as compactRegion slices the - // surface-node list) — NOT ascending log-seq order. After a replace the - // summary node carries a fresh high seq while sitting at the head of the - // surface before older retained lower-seq nodes, so a log-order scan would - // feed the transcript out of order and break the checkpoint-merge prompt. - for (const seq of seqs) { - const event = session.events[seq] - /* v8 ignore next -- seq is a surface-node seq, always a valid log index by construction */ - if (!event) continue - - switch (event.type) { - case 'user/message': { - const text = this._blocksToText(event.data.content) - if (text) lines.push(`User: ${text}`) - break - } - case 'assistant/message': { - const text = this._blocksToText(event.data.content) - if (text) lines.push(`Assistant: ${text}`) - break - } - case 'tool/result': { - const text = this._blocksToText(event.data.content) - const label = event.data.isError ? 'Tool error' : 'Tool result' - if (text) lines.push(`${label} (call ${event.data.callId}): ${text}`) - break - } - case 'context/message': { - const text = this._blocksToText(event.data.content) - if (text) lines.push(`[Context: ${text}]`) - break - } - case 'steering/message': { - const text = this._blocksToText(event.data.content) - if (text) lines.push(`[Steering: ${text}]`) - break - } - // SessionEventMap is merge-extensible — unknown types are - // non-message events that carry no extractable text. - /* v8 ignore next 2 -- seqs only name surface nodes, always one of the 5 handled SurfaceEventTypes; unreachable */ - default: - break - } - } - - return lines.join('\n\n') - } - - /** - * Render content blocks to a single plain-text string for the summarization - * prompt. Text and reasoning contribute their text; every other block type - * contributes a type-tagged placeholder (`[tool-call: name(args)]`, - * `[tool-result: …]`, …) so the summarizer is told what non-text content - * existed in the region rather than silently losing it. Blocks join with - * newlines; empty-text blocks contribute nothing. - */ - private _blocksToText(blocks: readonly ContentBlock[]): string { - const parts: string[] = [] - for (const block of blocks) { - switch (block.type) { - case 'text': - if (block.text) parts.push(block.text) - break - case 'reasoning': - if (block.text) parts.push(`[reasoning: ${block.text}]`) - break - case 'tool-call': - parts.push(`[tool-call: ${block.name}(${block.arguments})]`) - break - case 'tool-result': { - const inner = this._blocksToText(block.content) - parts.push(inner ? `[tool-result: ${inner}]` : '[tool-result]') - break - } - // ContentBlockMap is merge-extensible — render an unknown block as a - // bare type-tagged placeholder so a plugin-added block type is still - // signalled to the summarizer rather than dropped. - default: - parts.push(`[${(block as ContentBlock).type}]`) - } - } - return parts.join('\n') - } } export default BasicCompactService diff --git a/packages/compact/compact-basic/tests/compact-basic.spec.ts b/packages/compact/compact-basic/tests/compact-basic.spec.ts index 990d60190a..9cd61a95be 100644 --- a/packages/compact/compact-basic/tests/compact-basic.spec.ts +++ b/packages/compact/compact-basic/tests/compact-basic.spec.ts @@ -1278,7 +1278,7 @@ describe('BasicCompactService auto-compaction (agent/pre-step listener)', () => }) }) -describe('BasicCompactService._extractText branches', () => { +describe('BasicCompactService transcript rendering (delegated to dsh-compact)', () => { it('renders reasoning, context, and steering messages', async () => { const svc = createTestService() const s = new Session(SessionId('rich')) diff --git a/packages/compact/compact/README.md b/packages/compact/compact/README.md index 54bdcc7f4e..e908412d16 100644 --- a/packages/compact/compact/README.md +++ b/packages/compact/compact/README.md @@ -6,7 +6,7 @@ This package is the interface tier of the compaction capability, split so each c | Package | Role | |---|---| -| `@deepseek-ai/dsh-compact` (this) | the interface: abstract service + `compact/*` events + `CompactionResult` | +| `@deepseek-ai/dsh-compact` (this) | the interface: abstract service + `compact/*` events + `CompactionResult` + the shared transcript renderer (`renderTranscript`/`renderContentBlocks`) | | `@deepseek-ai/dsh-compact-basic` (deferred) | a backend: chars-per-token estimation (`charsPerToken`, default 4) + token-budget retention + `llm.stream()` summarization | | `@deepseek-ai/dsh-tool-compact` (deferred) | the model-facing `/compact` tool over `ctx.compact` | diff --git a/packages/compact/compact/src/index.ts b/packages/compact/compact/src/index.ts index cc190ccd87..931e8274cf 100644 --- a/packages/compact/compact/src/index.ts +++ b/packages/compact/compact/src/index.ts @@ -26,6 +26,7 @@ import type { Session } from '@deepseek-ai/dsh-session' import type { CompactionResult } from './types.ts' export type { CompactionResult } from './types.ts' +export { renderContentBlocks, renderTranscript } from './render.ts' /** Minimal agent context compaction needs without depending on the agent package. */ export interface CompactAgentContext { diff --git a/packages/compact/compact/src/render.ts b/packages/compact/compact/src/render.ts new file mode 100644 index 0000000000..6e977df007 --- /dev/null +++ b/packages/compact/compact/src/render.ts @@ -0,0 +1,118 @@ +/** + * Plain-text transcript rendering over session events: the shared projection + * used wherever a compaction-class consumer needs "what a model once saw" as + * readable text — a summarizer's input, or a recall tool's output. + * + * Extracted from the basic backend's private helpers so the summarize path and + * the recall read path render one span identically (two renderers would drift, + * and a recall reader would then see a different transcript than the one the + * summary was written from). Both functions are pure over their arguments: no + * session access beyond the provided events, no clock, no randomness — a + * rendered span is a pure function of the log, so replay reproduces it + * byte-identically. + * + * @module @deepseek-ai/dsh-compact/render + */ + +import type { ContentBlock } from '@deepseek-ai/dsh-llm' +import type { SessionEvent } from '@deepseek-ai/dsh-session' + +/** + * Render content blocks to a single plain-text string. Text and reasoning + * contribute their text (reasoning wrapped as `[reasoning: …]`); every other + * block type contributes a type-tagged placeholder (`[tool-call: name(args)]`, + * `[tool-result: …]`, …) so the reader is told what non-text content existed + * rather than silently losing it. A `tool-result` block recurses into its + * nested content (`[tool-result: ]`), falling back to a bare + * `[tool-result]` when the nested content renders to nothing. Blocks join + * with newlines; empty-text blocks contribute nothing. + * + * @param blocks - the content blocks to render. + * @returns the newline-joined plain-text rendering; empty string when nothing renders. + */ +export function renderContentBlocks(blocks: readonly ContentBlock[]): string { + const parts: string[] = [] + for (const block of blocks) { + switch (block.type) { + case 'text': + if (block.text) parts.push(block.text) + break + case 'reasoning': + if (block.text) parts.push(`[reasoning: ${block.text}]`) + break + case 'tool-call': + parts.push(`[tool-call: ${block.name}(${block.arguments})]`) + break + case 'tool-result': { + const inner = renderContentBlocks(block.content) + parts.push(inner ? `[tool-result: ${inner}]` : '[tool-result]') + break + } + // ContentBlockMap is merge-extensible — render an unknown block as a + // bare type-tagged placeholder so a plugin-added block type is still + // signalled to the reader rather than dropped. + default: + parts.push(`[${(block as ContentBlock).type}]`) + } + } + return parts.join('\n') +} + +/** + * Render a set of surface-node seqs as a `User:`/`Assistant:`/`Tool result:` + * transcript. Walks `seqs` in the order given — callers pass surface order + * (e.g. a `compactRegion` slice of the surface-node list), which after a + * `replace` is NOT ascending log-seq order (a high-seq summary node can sit at + * the head of the surface before older retained lower-seq nodes); a log-order + * scan would render the transcript out of order. + * + * Only the five surface (message-producing) event types render; a seq naming + * any other event type contributes nothing. `SessionEventMap` is + * merge-extensible, so unknown types are simply non-message events with no + * renderable text. + * + * @param events - the session log the seqs index into (`session.events`). + * @param seqs - the surface-node seqs to render, in surface order. + * @returns the transcript, entries joined by blank lines; empty string when nothing renders. + */ +export function renderTranscript(events: readonly SessionEvent[], seqs: readonly number[]): string { + const lines: string[] = [] + + for (const seq of seqs) { + const event = events[seq] + if (!event) continue + + switch (event.type) { + case 'user/message': { + const text = renderContentBlocks(event.data.content) + if (text) lines.push(`User: ${text}`) + break + } + case 'assistant/message': { + const text = renderContentBlocks(event.data.content) + if (text) lines.push(`Assistant: ${text}`) + break + } + case 'tool/result': { + const text = renderContentBlocks(event.data.content) + const label = event.data.isError ? 'Tool error' : 'Tool result' + if (text) lines.push(`${label} (call ${event.data.callId}): ${text}`) + break + } + case 'context/message': { + const text = renderContentBlocks(event.data.content) + if (text) lines.push(`[Context: ${text}]`) + break + } + case 'steering/message': { + const text = renderContentBlocks(event.data.content) + if (text) lines.push(`[Steering: ${text}]`) + break + } + default: + break + } + } + + return lines.join('\n\n') +} diff --git a/packages/compact/compact/tests/render.spec.ts b/packages/compact/compact/tests/render.spec.ts new file mode 100644 index 0000000000..1a22296565 --- /dev/null +++ b/packages/compact/compact/tests/render.spec.ts @@ -0,0 +1,138 @@ +import { describe, expect, it } from 'vitest' +import { renderContentBlocks, renderTranscript } from '@deepseek-ai/dsh-compact' +import { Session, SessionId } from '@deepseek-ai/dsh-session' +import type { ContentBlock } from '@deepseek-ai/dsh-llm' +import { CallId } from '@deepseek-ai/dsh-llm' + +function session(): Session { + return new Session(SessionId('render-spec')) +} + +describe('renderContentBlocks', () => { + it('renders text blocks verbatim and skips empty ones', () => { + expect(renderContentBlocks([ + { type: 'text', text: 'hello' }, + { type: 'text', text: '' }, + { type: 'text', text: 'world' }, + ])).toBe('hello\nworld') + }) + + it('wraps reasoning, skipping empty reasoning', () => { + expect(renderContentBlocks([ + { type: 'reasoning', text: 'think' }, + { type: 'reasoning', text: '' }, + ])).toBe('[reasoning: think]') + }) + + it('renders tool-call as a name(args) placeholder', () => { + expect(renderContentBlocks([ + { type: 'tool-call', id: CallId('c1'), name: 'read', arguments: '{"filePath":"a"}' }, + ])).toBe('[tool-call: read({"filePath":"a"})]') + }) + + it('renders tool-result with nested content, and bare when empty', () => { + expect(renderContentBlocks([ + { type: 'tool-result', toolCallId: CallId('c1'), content: [{ type: 'text', text: 'ok' }] }, + { type: 'tool-result', toolCallId: CallId('c2'), content: [] }, + ])).toBe('[tool-result: ok]\n[tool-result]') + }) + + it('renders an unknown (merge-extended) block type as a bare type tag', () => { + const unknown = { type: 'image', data: 'zzz' } as unknown as ContentBlock + expect(renderContentBlocks([unknown])).toBe('[image]') + }) + + it('returns the empty string for no blocks', () => { + expect(renderContentBlocks([])).toBe('') + }) +}) + +describe('renderTranscript', () => { + it('renders each surface event type with its label, in the seq order given', () => { + const s = session() + const user = s.append('user/message', { + content: [{ type: 'text', text: 'fix the bug' }], + source: { kind: 'user' }, + }, { surfaceOp: 'append' }) + const assistant = s.append('assistant/message', { + turn: 0, step: 0, + content: [{ type: 'text', text: 'looking' }], + }, { surfaceOp: 'append' }) + const result = s.append('tool/result', { + turn: 0, step: 0, callId: CallId('c1'), + content: [{ type: 'text', text: 'exit 0' }], + isError: false, + }, { surfaceOp: 'append' }) + const context = s.append('context/message', { + content: [{ type: 'text', text: 'file changed' }], + source: { kind: 'plugin', plugin: 'fs' }, + }, { surfaceOp: 'append' }) + const steering = s.append('steering/message', { + turn: 0, + content: [{ type: 'text', text: 'stop that' }], + source: { kind: 'user' }, + }, { surfaceOp: 'append' }) + + expect(renderTranscript(s.events, [user.seq, assistant.seq, result.seq, context.seq, steering.seq])).toBe([ + 'User: fix the bug', + 'Assistant: looking', + 'Tool result (call c1): exit 0', + '[Context: file changed]', + '[Steering: stop that]', + ].join('\n\n')) + }) + + it('labels an error tool result "Tool error"', () => { + const s = session() + const result = s.append('tool/result', { + turn: 0, step: 0, callId: CallId('c9'), + content: [{ type: 'text', text: 'boom' }], + isError: true, + }, { surfaceOp: 'append' }) + expect(renderTranscript(s.events, [result.seq])).toBe('Tool error (call c9): boom') + }) + + it('renders NON-log-order seqs in the order given (surface order after a replace)', () => { + const s = session() + const first = s.append('user/message', { + content: [{ type: 'text', text: 'first' }], + source: { kind: 'user' }, + }, { surfaceOp: 'append' }) + const second = s.append('user/message', { + content: [{ type: 'text', text: 'second' }], + source: { kind: 'user' }, + }, { surfaceOp: 'append' }) + expect(renderTranscript(s.events, [second.seq, first.seq])).toBe('User: second\n\nUser: first') + }) + + it('skips events that render to nothing, non-message events, and seqs with no event', () => { + const s = session() + const empty = s.append('user/message', { + content: [{ type: 'text', text: '' }], + source: { kind: 'user' }, + }, { surfaceOp: 'append' }) + const emptyAssistant = s.append('assistant/message', { + turn: 0, step: 0, + content: [{ type: 'text', text: '' }], + }, { surfaceOp: 'append' }) + const emptyResult = s.append('tool/result', { + turn: 0, step: 0, callId: CallId('c3'), + content: [{ type: 'text', text: '' }], + isError: false, + }, { surfaceOp: 'append' }) + const emptyContext = s.append('context/message', { + content: [{ type: 'text', text: '' }], + source: { kind: 'plugin', plugin: 'fs' }, + }, { surfaceOp: 'append' }) + const emptySteering = s.append('steering/message', { + turn: 0, + content: [{ type: 'text', text: '' }], + source: { kind: 'user' }, + }, { surfaceOp: 'append' }) + // A log-only (non-surface) event type: contributes nothing to a transcript. + const lock = s.append('compact/start', { turn: 0 }) + expect(renderTranscript(s.events, [ + empty.seq, emptyAssistant.seq, emptyResult.seq, emptyContext.seq, emptySteering.seq, lock.seq, 9999, + ])).toBe('') + }) +}) From 68ebc76af7a20e53744d1ca569e59014031ebe35 Mon Sep 17 00:00:00 2001 From: imccyu <276526105+imccyu@users.noreply.github.com> Date: Wed, 8 Jul 2026 11:45:01 +0800 Subject: [PATCH 02/15] docs(rfc): the self-referential cordis toolset The design record for tool-cordis: the three-tool contract, the vm sandbox trust stance and boundary mechanisms, the dynamic-group lifecycle, cross-mount provide/inject composition, the generated runtime API catalog, and the alternatives weighed (per-capability registration tools, hand-maintained API tables, a mount provenance event, a hardened sandbox). --- docs/rfc/INDEX.md | 1 + ...6-07-08-self-referential-cordis-toolset.md | 84 +++++++++++++++++++ 2 files changed, 85 insertions(+) create mode 100644 docs/rfc/implemented/feature/2026-07-08-self-referential-cordis-toolset.md diff --git a/docs/rfc/INDEX.md b/docs/rfc/INDEX.md index e70e81877c..09f8caedb4 100644 --- a/docs/rfc/INDEX.md +++ b/docs/rfc/INDEX.md @@ -63,6 +63,7 @@ Generated by `pnpm run gen-rfc-index` from the RFC tree — never edit by hand; | [Subagent lifecycle enrichment — lastAssistantMessage (observe-only)](implemented/feature/2026-06-30-subagent-observe-enrich.md) | 2026-06-30 | | [Explicit model-facing tool order](implemented/feature/2026-07-06-explicit-tool-order.md) | 2026-07-06 | | [Repeat-tool-call guard plugin](implemented/feature/2026-07-08-repeat-tool-guard.md) | 2026-07-08 | +| [The self-referential cordis toolset](implemented/feature/2026-07-08-self-referential-cordis-toolset.md) | 2026-07-08 | ### Simplification diff --git a/docs/rfc/implemented/feature/2026-07-08-self-referential-cordis-toolset.md b/docs/rfc/implemented/feature/2026-07-08-self-referential-cordis-toolset.md new file mode 100644 index 0000000000..95cb12b571 --- /dev/null +++ b/docs/rfc/implemented/feature/2026-07-08-self-referential-cordis-toolset.md @@ -0,0 +1,84 @@ +# RFC: The self-referential cordis toolset + +Status: implemented + +## Problem + +Everything in this harness is a cordis plugin, but the agent running inside that plugin runtime cannot see or touch it: it cannot enumerate the services and events around it, cannot extend itself with a new tool mid-session, and cannot compose capabilities it invents. Handing the model that power is worth exploring — a self-referential agent that inspects and modifies its own runtime — but it raises three correctness problems at once, and the design is about answering them rather than the raw "let the model run code" mechanic. + +First, model-written registration must be validated where it happens: a malformed tool schema has to fail at registration, not when a later request tries to assemble it into a prompt. Second, model-written code has to call service APIs whose source it has never seen — guessed method signatures and, worse, guessed return-value shapes cost many steps of blind probing. Third, everything the model mounts must be fully disposable, by the model on demand and by the ordinary plugin lifecycle when the host plugin reloads, or a long session accretes orphaned listeners and tools. + +## Decision + +The toolset ships as [`@deepseek-ai/dsh-tool-cordis`](../../../../packages/cordis/tool-cordis/README.md) — a new top-level `packages/cordis/` group — and is demoed by [`examples/cordis-agent`](../../../../examples/cordis-agent/README.md). It gives the model three tools over the live cordis runtime it is running inside: inspect it, mount model-written plugins into it, dispose them again. + +The trust stance, stated once and threaded through the rest: the `node:vm` sandbox isolates the global context only — it prevents accidental global pollution, not malice. The `ctx` handed to a mounted plugin's `apply` is the real, fully privileged runtime handle; handing the model that handle is the point of the toolset. A deployment loads this plugin exactly as deliberately as it grants a bash tool — an opt-in capability in the app's `cordis.yml`, never a product default. + +### The three tools + +| Tool | Contract | +|---|---| +| `cordis_inspect` | Read-only report over the live runtime, one Markdown section per `what` value (omit `what` for all sections). Never mutates. | +| `cordis_mount` | Evaluates `code` (the body of an async JavaScript function) in a `node:vm` sandbox; the code must `return` a cordis plugin, which is mounted as a child of the `cordis-dynamic` group fiber and tracked under a fresh id (`dyn-1`, `dyn-2`, …). | +| `cordis_unmount` | Disposes one dynamic mount by id and returns only after disposal reaches quiescence — every registration the plugin made is unwound, not merely requested to stop. | + +`cordis_inspect` sections: `services` (every provided ctx service and the owning fiber, non-active owners flagged), `plugins` (the whole plugin fiber tree rebuilt from `ctx.registry`, ASCII, dynamic mounts annotated with their ids), `tools` (what the model can call), `dynamic` (the mount table: id, name, state, provided services, awaited services), `api` (live service signatures + the type shapes they reference, from the generated catalog), and `events` (harness events with dispatch mode and signature). The model-facing tool descriptions carry the operational rules the model needs at call time; [the generated tool catalog](../../../tool-catalog.md) is their exhaustive rendering. + +### Sandbox semantics + +Mount code runs via `vm.createContext` + `runInContext`, wrapped as the body of an async function under a per-mount filename (`cordis-mount-.js`). The vm gives the code a fresh realm: writes to `globalThis` stay inside the sandbox, and no Node API is provided — capability access is routed through the cordis services (`ctx.fs` for files, `ctx.web` for HTTP, `ctx.bash` for processes, the `ctx.timer` helpers for timing), never Node built-ins, so everything a mounted plugin does stays inspectable through the fiber tree and disposable with it. The `vmTimeoutMs` config bounds only the synchronous portion of evaluation; an async body escapes the bound (acceptable under the trust stance above). + +Sandbox globals are deliberately small: a tagged write-through `console` (`[cordis:] …` on the host stdout/stderr, so a listener that fires long after the mount call still lands somewhere the user sees), the `harness.defineTool` / `harness.registerTool` registration pair, the encoding primitives fresh vm contexts lack (`btoa`/`atob` as host closures over `Buffer` — a sanctioned exception, `Buffer` itself is never exposed — plus `TextEncoder`/`TextDecoder`), and callable traps over the withheld Node APIs (`require`, `setTimeout`/`setInterval`/`setImmediate`/`clearTimeout`/`clearInterval`, `fetch`) that throw a redirect naming the cordis alternative. Only function-shaped globals are trapped; `process` and `Buffer` stay `undefined` so a `typeof` feature probe stays inert rather than detonating a throwing accessor. + +Three boundary mechanisms make model-written code behave correctly across the realm seam. **Dual-realm `instanceof`**: most objects sandbox code touches are host-realm (tool `args`, event payloads, service returns), so a plain `x instanceof Array` in the vm would silently be false — a per-sandbox prelude gives the vm realm's own constructors a `Symbol.hasInstance` that checks both the vm constructor and its host counterpart, patching only vm-realm globals. **Realm normalization of tool results**: objects built inside the vm carry the vm realm's `Object.prototype`, which the session log's append-time plainness check (`isJsonValue` in `dsh-session`, a prototype-identity comparison) rejects, so the sandbox's `harness.defineTool` JSON round-trips every `execute` return into the host realm — which also projects it onto exactly what the log durably stores. **Guarded registration**: the `ctx` a mounted plugin receives is a proxy whose `tools.register` accepts only definitions returned by `harness.defineTool` (a marker symbol), so every dynamic tool passes SchemaSpec validation and realm normalization; everything else on `ctx` passes through with correct `this` binding, which is what keeps cross-mount `provide`/`inject` working. + +Boundary errors are written around the mistakes models actually make (see [Consequences](#consequences) for how each was found): JSON Schema where the SchemaSpec DSL is expected gets a ✗/✓ example pair; an unbalanced `});` closing gets the vm's offending source line plus a "code is a function body" reminder; TypeScript syntax gets the remove-annotations fix (detected on the failing line only, so an ` as ` inside a description string does not misfire); a forgotten `return` gets the two valid plugin forms; a Node built-in call gets the redirect to its cordis service; a tool-name collision on re-mount gets the unmount-first-then-remount recipe. + +### The dynamic group and mount lifecycle + +Every dynamic mount is a child of a single `cordis-dynamic` group fiber, itself a child of the `tool-cordis` plugin's fiber. The group exists so the mounts form one subtree: they read as a unit in the inspect tree, and disposing `tool-cordis` (HMR reload, config unload) cascades over every mount through the ordinary parent→child fiber lifecycle — no bespoke cleanup. Mounting settles before it reports: the returned fiber is `await()`ed, and a startup error (a throwing `apply`, a duplicate tool name, a duplicate service) disposes the fiber and surfaces as the tool error, so a failed mount never lingers. A settled fiber that is not active is a legal pending mount — cordis semantics for unsatisfied `inject` — kept mounted and reported with what it waits for. Everything the plugin registers is an effect on its fiber, so `cordis_unmount` is nothing but an awaited `fiber.dispose()`. + +### Cross-mount composition via provide/inject + +Mounts relate to each other through ordinary cordis service semantics, with their ids as the lifecycle handles: mount A calls `ctx.provide('foo', value)`, mount B declares `inject: ['foo']` and activates the moment `foo` exists; mounted first, B stays pending and names the missing service; unmounting A sends B back to pending (its registrations unwound) and a later re-provide re-runs B's `apply` through the same guarded context; a duplicate provide fails loud with the owning fiber named. One realm caveat: a service value provided by a mount is a vm-realm object — method calls on it work from anywhere, but consumers must not assume host prototypes on it. + +### The generated API catalog + +`cordis_inspect what:"api"` and `what:"events"` answer from a machine-readable catalog generated at build time, never a hand-maintained table that would drift from the JSDoc it paraphrases. [`scripts/gen-cordis-api.ts`](../../../../scripts/gen-cordis-api.ts) reuses `collectServices` / `collectEvents` from [`scripts/gen-cordis-catalog.ts`](../../../../scripts/gen-cordis-catalog.ts) — the same AST walk that generates [the cordis service catalog](../../../cordis-catalog/services.md) and [events catalog](../../../cordis-catalog/events.md) — and emits `packages/cordis/tool-cordis/src/api-catalog.ts`, a committed, banner-commented data module. The artifact carries, per service, its key + one-line summary + raw method signatures; per event, name + `@mode` + signature + summary; the comment-stripped declarations of every exported type the service signatures reference (transitive closure — so a consumer sees that a bash run's `stdout` is `{ text, truncated }`, not a string); plus the curated inherited `ctx` surface shared with the cordis catalog generator. A type name declared in more than one package (each plugin's `Config`) is dropped as ambiguous, and an oversized declaration is truncated with a marker. + +Freshness is gated like every generated artifact: `pnpm run verify-cordis-api` (in `doc-sync`) regenerates in memory and fails on any diff, so a JSDoc edit that changes a public signature cannot ship without regenerating the catalog the model reads. At runtime the inspect tool intersects the catalog with the live runtime rather than dumping it: live catalogued services render summary + signatures, live services without a catalog entry (mount-provided ones) render name + owning fiber, catalogued services with no live provider are listed tersely, and the referenced type shapes follow. + +### Configuration, rendering, and observability + +The plugin exposes one config field, validated by schemastery and documented in [the config catalog](../../../config-catalog.md): `vmTimeoutMs` (default 5000), the millisecond bound on the synchronous portion of mount-code evaluation. Tool names, the `cordis-dynamic` group name, and the `dyn-` id prefix are structural vocabulary and stay fixed. All three tools render as `generic` cards per [the tool cookbook](../../../cookbook/adding-a-tool.md) (`cordis_inspect` a `read`, `cordis_mount` an `execute` carrying the code as `rawInput`, `cordis_unmount` a `delete`), with no `presentResult` overrides. + +Model-visible ⟺ logged holds with no new session event type: a mount or unmount is visible only through its own `tool/call` / `tool/result` pair, which the loop logs, and the changed tool set a mount induces is logged by the request-header delta the loop already emits when schemas change between steps. There is deliberately no `cordis/mount` provenance event — it would duplicate what the tool-call pair records. Dynamic mounts are process-lifetime, not session state: resuming a persisted session rehydrates the conversation but does not re-mount plugins. + +## Alternatives considered + +**A structured per-capability registration tool instead of `cordis_mount`.** The most tempting alternative is a `cordis_register_tool` with explicit `name` / `description` / `parameters` / `code` fields (and siblings `cordis_register_listener`, `cordis_register_service`, …) rather than a single "mount a plugin" primitive. It was rejected because its one real win — no plugin boilerplate for the single commonest case — does not pay for its costs, while a single mount primitive answers every capability at once. + +| Dimension | Structured per-capability tools | Single `cordis_mount` | +|---|---|---| +| Schema correctness | `parameters` is still a model-written JSON object needing SchemaSpec validation, merely one step earlier | The same validation runs at the sandbox boundary, with the same instructive errors | +| The code field | An `execute` body is still model-written JS in a vm; the realm and service-call correctness problems are unchanged | One sandbox, one normalization path, one guarded registration | +| Capability coverage | Tools only; listeners, services, `inject` relations each need another structured tool — a surface that grows without bound | One vocabulary (a cordis plugin) covers every effect, present and future | +| Cross-mount composition | Not expressible in a tool-registration payload | Native `provide`/`inject`, ordinary cordis semantics | +| Inspectability | Registers something the plugin tree cannot show as a plugin | What the model mounts is exactly what `cordis_inspect` renders | +| Model ergonomics | Wins for the single most common case (no plugin boilerplate) | Mitigated by the canonical recipe in the mount description plus boundary errors that teach the fix | + +The correctness investment therefore goes where it pays for every capability at once: the generated API catalog surfaced through `cordis_inspect`, and sandbox-boundary validation whose error messages teach the correct call. A structured registration tool remains addable later as sugar that synthesizes mount code; nothing here forecloses it. + +**A hand-maintained service/event reference in the tool.** The first cut of the inspect tool carried a hand-written table of service method signatures. It was replaced by the generated `api-catalog.ts` because a hand table drifts from the JSDoc the moment a signature changes and nothing gates the drift, whereas the generated artifact is freshness-checked against the same AST the docs use. + +**A new `cordis/mount` session event.** A durable provenance event recording each mount (source, name) has clear precedent (`hook/invoked`, `compact/start`). It was declined for v1: mount and unmount are already visible as `tool/call` / `tool/result` pairs and the tool-set change is already logged as a request-header delta, so a dedicated event would only duplicate the record. It remains addable if an audit use case needs mount provenance separable from the tool call. + +**A hardened / capability-restricted sandbox.** Trapping Node built-ins might suggest an intent to sandbox for safety. It is explicitly not that: the traps redirect the model toward cordis services (and away from leak-prone Node timers) for correctness and inspectability, but `ctx` is fully privileged and the vm is not a security boundary. A real security boundary (separate process, permission prompts) was out of scope for a dev/opt-in toolset and would fight the entire point — handing the model the live runtime. + +## Consequences + +The toolset is a deliberate opt-in with a fully-privileged `ctx`, so a deployment adopts it as consciously as a bash tool. Several facts follow that the tool descriptions warn the model about directly: a waterfall listener (e.g. `tools/pre-execute`) that returns without calling `next()` vetoes the chain, so a mounted listener can lobotomize the agent's own tool dispatch ([waterfall semantics](../../../cordis-primer.md#cordis-waterfall-semantics)); mount code runs inside a tool call of the current turn, so awaiting anything that resolves only after the turn deadlocks; `vmTimeoutMs` bounds synchronous evaluation only; and mounts do not survive session resume. + +The instructive boundary errors were not guessed — they were written against a live self-design session in which a real model was asked to build itself coding tools. That session surfaced the failure modes now mitigated: the model closed a returned plugin object with `});` and got only a bare `Unexpected token ')'` it retried blind; it hit a false-positive "this is TypeScript" hint because a description string contained the word "as"; and, most costly, it guessed a bash run's `stdout` was a string and burned six steps building throwaway debug tools to discover it is `{ text, truncated }`. The fixes — source-line-plus-caret parse errors, line-scoped TypeScript detection, the type-shape closure in the API catalog, and the redirect traps — cut a second session from dozens of tool calls with repeated errors to a first-try success on every capability, including a model that hit a Node-`setTimeout` trap and self-corrected to `inject: ['timer']` in one step. + +Coverage is named per tier: package unit specs drive the three tools through a real `ToolRegistry` on a real fiber tree (the mount success/failure family, vm isolation, dual-realm `instanceof`, realm normalization against the real `isJsonValue`, the SchemaSpec and raw-registration rejections, the Node-API traps, the cross-mount provide/inject matrix, catalog-backed `api`/`events` rendering, config validation, presenters, quiescent unmount, and the HMR cascade), a `MockAdapter` loop test proves a tool mounted in one step is dispatchable in the next, and the example carries a keyless Loader smoke plus a with-key smoke that world-verifies a live model mounting a listener, building its own tool, and composing two mounts. No snapshot scenario is added: the toolset ships in no ACP-served app, so it changes no editor-facing transcript, and its presenters are unit-tested pure functions — adding it to the ACP example solely for a golden would rewrite the pinned request-header tool set of every recorded scenario. From ee1da1ce5be9dbee1c97080687355b471a1b4dad Mon Sep 17 00:00:00 2001 From: imccyu <276526105+imccyu@users.noreply.github.com> Date: Wed, 8 Jul 2026 11:45:46 +0800 Subject: [PATCH 03/15] =?UTF-8?q?feat(cordis):=20@deepseek-ai/dsh-tool-cor?= =?UTF-8?q?dis=20=E2=80=94=20inspect/mount/unmount=20over=20the=20live=20r?= =?UTF-8?q?untime?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit New top-level packages/cordis/ group with the self-referential toolset: cordis_inspect (services / plugin tree / tools / dynamic mounts / api / events, the api section intersecting the generated catalog with the live service store), cordis_mount (model-written code evaluated in a node:vm sandbox, mounted under one cordis-dynamic group fiber as dyn-), cordis_unmount (awaited disposal to quiescence). Boundary mechanisms: dual-realm instanceof, JSON realm normalization of dynamic tool results, marker-guarded registration, SchemaSpec teaching errors, parse failures surfaced with the offending line + caret and a line-scoped TypeScript hint, and the unmount-first recipe on tool-name collisions. Config: vmTimeoutMs (schemastery, default 5000). Design record: docs/rfc/implemented/feature/2026-07-08-self-referential-cordis-toolset.md. The tool-catalog boot manifest, its regenerated output, and the pinned tool-name list land here rather than with the other repo registration: the completeness guard globs packages/*/tool-* and fails the generator (and the core/tools spec) the moment the package directory exists. --- docs/tool-catalog.md | 73 ++ packages/cordis/README.md | 7 + packages/cordis/tool-cordis/README.md | 33 + packages/cordis/tool-cordis/package.json | 42 + .../cordis/tool-cordis/src/api-catalog.ts | 786 ++++++++++++++++++ .../cordis/tool-cordis/src/fiber-state.ts | 39 + packages/cordis/tool-cordis/src/guard.ts | 199 +++++ packages/cordis/tool-cordis/src/index.ts | 228 +++++ packages/cordis/tool-cordis/src/inspect.ts | 225 +++++ packages/cordis/tool-cordis/src/mount.ts | 64 ++ packages/cordis/tool-cordis/src/present.ts | 51 ++ packages/cordis/tool-cordis/src/sandbox.ts | 153 ++++ .../tool-cordis/tests/cross-mount.spec.ts | 105 +++ packages/cordis/tool-cordis/tests/helpers.ts | 104 +++ .../cordis/tool-cordis/tests/inspect.spec.ts | 123 +++ .../tool-cordis/tests/integration.spec.ts | 74 ++ .../cordis/tool-cordis/tests/mount.spec.ts | 409 +++++++++ .../cordis/tool-cordis/tests/present.spec.ts | 41 + .../tool-cordis/tests/tool-cordis.spec.ts | 49 ++ .../tool-cordis/tests/unmount-hmr.spec.ts | 82 ++ packages/cordis/tool-cordis/tsconfig.json | 27 + .../core/tools/tests/gen-tool-catalog.spec.ts | 2 +- pnpm-lock.yaml | 34 + scripts/gen-tool-catalog.ts | 13 + tsconfig.base.json | 1 + tsconfig.build.json | 1 + tsconfig.json | 1 + 27 files changed, 2965 insertions(+), 1 deletion(-) create mode 100644 packages/cordis/README.md create mode 100644 packages/cordis/tool-cordis/README.md create mode 100644 packages/cordis/tool-cordis/package.json create mode 100644 packages/cordis/tool-cordis/src/api-catalog.ts create mode 100644 packages/cordis/tool-cordis/src/fiber-state.ts create mode 100644 packages/cordis/tool-cordis/src/guard.ts create mode 100644 packages/cordis/tool-cordis/src/index.ts create mode 100644 packages/cordis/tool-cordis/src/inspect.ts create mode 100644 packages/cordis/tool-cordis/src/mount.ts create mode 100644 packages/cordis/tool-cordis/src/present.ts create mode 100644 packages/cordis/tool-cordis/src/sandbox.ts create mode 100644 packages/cordis/tool-cordis/tests/cross-mount.spec.ts create mode 100644 packages/cordis/tool-cordis/tests/helpers.ts create mode 100644 packages/cordis/tool-cordis/tests/inspect.spec.ts create mode 100644 packages/cordis/tool-cordis/tests/integration.spec.ts create mode 100644 packages/cordis/tool-cordis/tests/mount.spec.ts create mode 100644 packages/cordis/tool-cordis/tests/present.spec.ts create mode 100644 packages/cordis/tool-cordis/tests/tool-cordis.spec.ts create mode 100644 packages/cordis/tool-cordis/tests/unmount-hmr.spec.ts create mode 100644 packages/cordis/tool-cordis/tsconfig.json diff --git a/docs/tool-catalog.md b/docs/tool-catalog.md index 3645ff40e9..e77716f736 100644 --- a/docs/tool-catalog.md +++ b/docs/tool-catalog.md @@ -16,6 +16,7 @@ This table connects model-visible tool names to the plugin package and service s | Tool package | Model-visible names | Requires | Writes / affects | Shipped aliases | Deployment note | | --- | --- | --- | --- | --- | --- | | `@deepseek-ai/dsh-tool-bash` | `bash`, `bash_kill`, `bash_output` | `ctx.tools`, `ctx.bash` | `tool/call`, `tool/result`, `context/message via agent.inject() for background completion notices` | - | The bash/bash_output/bash_kill tools are model-facing consumers of the bash executor seam. | +| `@deepseek-ai/dsh-tool-cordis` | `cordis_inspect`, `cordis_mount`, `cordis_unmount` | `ctx.tools` | `tool/call`, `tool/result`, `live plugin-tree mutations (mount/unmount)` | - | Ships in examples/cordis-agent only (a deliberate opt-in — mounted code gets the real ctx, see docs/rfc/implemented/feature/2026-07-08-self-referential-cordis-toolset.md). Plugins the model mounts may register ADDITIONAL model-visible tools at runtime; the request-header ToolsDelta logs those tool-set changes. | | `@deepseek-ai/dsh-tool-fs` | `edit`, `read`, `write` | `ctx.tools`, `ctx.fs`, `ctx.systemPrompt` | `tool/call`, `fs/write-intent or fs/edit-intent for mutations`, `fs/observed after successful file operations`, `tool/result` | - | The read-before-write/edit policy is added by `@deepseek-ai/dsh-fs-policy` (an `fs/*` event-gate plugin, no schema change); a deployment that loads these tools is expected to also load it. The tool schemas above are identical with or without the policy plugin. | | `@deepseek-ai/dsh-tool-subagent` | `subagent` | `ctx.tools`, `ctx.subagents` | `tool/call`, `tool/result`, `child session events through the chosen provider` | `subagent`, `subagent_fork` | The registered tool name is the load-time `toolName` config (default `subagent`); the schema above is that default. The shipped example agents load this package once per subagent backend, so the model additionally sees `subagent_fork` (bound to the fork backend) with an identical schema — see `examples/coding-agent/cordis.yml` and `examples/acp-agent/cordis.yml`. | | `@deepseek-ai/dsh-tool-todo` | `todo_write` | `ctx.tools`, `owning Agent session` | `tool/call`, `todo/write`, `tool/result` | - | todo_write is session-owned state; UIs render the latest todo/write event as a checklist or ACP plan. | @@ -105,6 +106,78 @@ Source: [`packages/bash/tool-bash/src/index.ts`](../packages/bash/tool-bash/src/ The bash/bash_output/bash_kill tools are model-facing consumers of the bash executor seam. +## `@deepseek-ai/dsh-tool-cordis` + +### `cordis_inspect` + +Inspect the live cordis runtime that is running THIS agent. Read-only. Sections: `services` (every provided ctx service and the plugin fiber that owns it), `plugins` (the whole plugin fiber tree with lifecycle states, as an ASCII tree — dynamic mounts appear under the `cordis-dynamic` group with their ids), `tools` (the model-facing tools currently registered, i.e. what you can call), `dynamic` (plugins you mounted via cordis_mount: id, name, state, provided services, awaited services), `api` (method signatures AND argument/return type shapes for every LIVE service — read this before writing plugin code that calls a service), `events` (every harness event with its dispatch mode and exact signature — pick listener targets here). Omit `what` to get all six sections. + +```json +{ + "type": "object", + "properties": { + "what": { + "type": "string", + "description": "Limit the report to one section. Omit for all sections.", + "enum": [ + "services", + "plugins", + "tools", + "dynamic", + "api", + "events" + ] + } + } +} +``` + +Source: [`packages/cordis/tool-cordis/src/index.ts`](../packages/cordis/tool-cordis/src/index.ts) + +### `cordis_mount` + +Mount a NEW cordis plugin into the live runtime that is running THIS agent (self-modification). `code` runs as the body of an async JavaScript function in an isolated sandbox and MUST `return` a plugin. Two forms: FUNCTION form `return (ctx) => { … }` — cannot declare inject, uses whatever services are on the parent context, and accessing a service without inject (e.g. ctx.bash) throws; use it only when you need no injected services. OBJECT form `return { name?, inject: ['bash', 'llm', …], apply(ctx) { … } }` — declares dependencies, and cordis activates the plugin only after the services exist; PREFER this form for any plugin that needs bash, llm, sessions, etc. BEFORE calling a service from your code, read cordis_inspect what:"api" — it lists method signatures AND the type shapes of their arguments/returns (do not guess a field's type; e.g. a bash run's stdout is an object, not a string). Inside `apply`, use the standard cordis API: `ctx.on(event, listener)` to observe events (see cordis_inspect what:"events"), or call `harness.registerTool(ctx, harness.defineTool({ name, description, parameters: { text: { type: 'string', required: true } }, async execute(args) { … } }))` to give yourself a new tool — it becomes callable on your NEXT step. A tool's `execute` MUST return an ARRAY of content blocks, e.g. `return [{ type: 'text', text: someString }]` — never a bare string. Mounts can COMPOSE: one plugin may `ctx.provide('name', value)` a service and another may declare `inject: ['name']` to consume it — the consumer stays pending until the provider exists and returns to pending when the provider is unmounted. Everything registered inside `apply` is cleaned up automatically on unmount. Sandbox globals: `console` (tagged `[cordis:]`, writes through to the harness terminal), `harness.defineTool`, `harness.registerTool`, `btoa`, `atob`, `TextEncoder`, `TextDecoder`; there is no `require`, `process`, `Buffer`, or network. Write PLAIN JavaScript, not TypeScript (no `as`, no type annotations). Cautions: (1) waterfall events (e.g. tools/pre-execute) hand the listener a trailing `next` callback which MUST be called — returning without `next()` VETOES the call; prefer plain notification events unless you intend to intercept. (2) Never await something that only resolves after the current turn (your code runs INSIDE a tool call of that turn — it would deadlock). (3) The sandbox prevents accidental global pollution, not malice: `ctx` is the real, fully privileged runtime handle. + +```json +{ + "type": "object", + "properties": { + "code": { + "type": "string", + "description": "Body of an async JS function; must `return` the plugin to mount." + } + }, + "required": [ + "code" + ] +} +``` + +Source: [`packages/cordis/tool-cordis/src/index.ts`](../packages/cordis/tool-cordis/src/index.ts) + +### `cordis_unmount` + +Dispose a plugin previously mounted with cordis_mount, by id. All its registrations (event listeners, tools, services) are cleaned up through the cordis effect lifecycle. Returns only after disposal has fully completed (quiescence, not just a request to stop). + +```json +{ + "type": "object", + "properties": { + "id": { + "type": "string", + "description": "The dynamic mount id returned by cordis_mount (e.g. \"dyn-1\")." + } + }, + "required": [ + "id" + ] +} +``` + +Source: [`packages/cordis/tool-cordis/src/index.ts`](../packages/cordis/tool-cordis/src/index.ts) + +Ships in examples/cordis-agent only (a deliberate opt-in — mounted code gets the real ctx, see docs/rfc/implemented/feature/2026-07-08-self-referential-cordis-toolset.md). Plugins the model mounts may register ADDITIONAL model-visible tools at runtime; the request-header ToolsDelta logs those tool-set changes. + ## `@deepseek-ai/dsh-tool-fs` ### `edit` diff --git a/packages/cordis/README.md b/packages/cordis/README.md new file mode 100644 index 0000000000..2eb33006e5 --- /dev/null +++ b/packages/cordis/README.md @@ -0,0 +1,7 @@ +# packages/cordis — the self-referential runtime toolset + +Model-facing tools over the live cordis runtime the agent itself runs inside: inspect the plugin tree and service surface, mount model-written plugins, and dispose them again. Design home: [the toolset RFC](../../docs/rfc/implemented/feature/2026-07-08-self-referential-cordis-toolset.md). + +| Package | Role | ctx key | +|---|---|---| +| [`tool-cordis/`](tool-cordis/README.md) | The `cordis_inspect` / `cordis_mount` / `cordis_unmount` tools: read the runtime, evaluate model-written plugin code in a `node:vm` sandbox, and manage the dynamic mounts under one group fiber | registers on `ctx.tools` | diff --git a/packages/cordis/tool-cordis/README.md b/packages/cordis/tool-cordis/README.md new file mode 100644 index 0000000000..71b79fecad --- /dev/null +++ b/packages/cordis/tool-cordis/README.md @@ -0,0 +1,33 @@ +# @deepseek-ai/dsh-tool-cordis + +The self-referential cordis toolset: three model-facing tools over the live runtime the agent runs inside. Design home — sandbox semantics, mount lifecycle, cross-mount composition, the generated API catalog, standing decisions: [the toolset RFC](../../../docs/rfc/implemented/feature/2026-07-08-self-referential-cordis-toolset.md). + +## What it does + +- `cordis_inspect` — read-only report over the runtime: services, the plugin fiber tree (ASCII), registered tools, the dynamic-mount table, and the catalog-backed `api` / `events` references. +- `cordis_mount` — evaluates model-written JavaScript (the body of an async function) in a `node:vm` sandbox; the code must `return` a cordis plugin, which is mounted under the `cordis-dynamic` group fiber and tracked as `dyn-`. +- `cordis_unmount` — disposes one mount by id, returning only after quiescence. + +Exact model-facing schemas: [the generated tool catalog](../../../docs/tool-catalog.md). + +## Trust stance + +The sandbox isolates the global context only — it is not a security boundary. No Node API is provided: `require`, the timers, and `fetch` are callable traps that throw a redirect to the cordis alternative (`ctx.fs` / `ctx.web` / `ctx.bash` / `inject: ['timer']` + `ctx.setTimeout`); `process` and `Buffer` are `undefined`; `globalThis` writes stay inside. The `ctx` a mounted plugin's `apply` receives is the real, fully privileged runtime handle; load this plugin as deliberately as you would grant a bash tool. + +## Config + +| Field | Default | Meaning | +|---|---|---| +| `vmTimeoutMs` | `5000` | Bound on the SYNCHRONOUS portion of mount-code evaluation; an async body escapes it | + +## The generated API catalog + +`src/api-catalog.ts` is generated by `scripts/gen-cordis-api.ts` from the same AST walk as [docs/cordis-catalog](../../../docs/cordis-catalog/services.md) and freshness-gated by `pnpm run verify-cordis-api` (in `doc-sync`) — never edit it by hand. `cordis_inspect` intersects it with the live service store at call time. + +## Rendering + +All three tools render `generic` cards (`read` / `execute` / `delete`); `cordis_mount` carries the mount code as `rawInput`. Presenters are pure functions of the args; results keep the default text rendering. + +## Export shape + +Namespace plugin: named exports `name` / `inject` / `Config` / `apply`, no default export ([docs/postmortem/0001](../../../docs/postmortem/0001-acp-default-export-drops-inject.md)). diff --git a/packages/cordis/tool-cordis/package.json b/packages/cordis/tool-cordis/package.json new file mode 100644 index 0000000000..657013f1c4 --- /dev/null +++ b/packages/cordis/tool-cordis/package.json @@ -0,0 +1,42 @@ +{ + "name": "@deepseek-ai/dsh-tool-cordis", + "description": "Self-referential cordis toolset: inspect the live runtime, mount and dispose model-written plugins", + "version": "0.0.1", + "private": true, + "type": "module", + "main": "lib/index.js", + "types": "lib/types/index.d.ts", + "exports": { + ".": { + "types": "./lib/types/index.d.ts", + "default": "./lib/index.js" + }, + "./src/*": "./src/*", + "./package.json": "./package.json" + }, + "files": [ + "lib/index.js", + "lib/types/**/*.d.ts", + "lib/types/**/*.d.ts.map", + "src" + ], + "license": "BSD-3-Clause", + "peerDependencies": { + "@deepseek-ai/dsh-tools": "^0.0.1", + "cordis": "^4.0.0-rc.6" + }, + "dependencies": { + "schemastery": "^3.18.0" + }, + "devDependencies": { + "@deepseek-ai/dsh-agent": "workspace:^", + "@deepseek-ai/dsh-agent-loop": "workspace:^", + "@deepseek-ai/dsh-llm": "workspace:^", + "@deepseek-ai/dsh-session": "workspace:^", + "@deepseek-ai/dsh-system-prompt": "workspace:^", + "@deepseek-ai/dsh-tools": "workspace:^", + "@cordisjs/plugin-loader": "^1.0.0-rc.4", + "cordis": "^4.0.0-rc.6", + "@cordisjs/plugin-timer": "workspace:^" + } +} diff --git a/packages/cordis/tool-cordis/src/api-catalog.ts b/packages/cordis/tool-cordis/src/api-catalog.ts new file mode 100644 index 0000000000..39f1a12f47 --- /dev/null +++ b/packages/cordis/tool-cordis/src/api-catalog.ts @@ -0,0 +1,786 @@ +/** + * Generated by scripts/gen-cordis-api.ts — do not edit by hand; run + * `pnpm run gen-cordis-api` to regenerate (freshness-gated by + * `pnpm run verify-cordis-api` in doc-sync). + * + * The machine-readable cordis API catalog `cordis_inspect` serves to the + * model: harness services (summary + public method signatures), harness + * events (mode + signature), and the inherited `ctx` surface. Produced by + * the same AST walk as docs/cordis-catalog, so this data and the rendered + * docs cannot diverge. + * + * @module @deepseek-ai/dsh-tool-cordis/api-catalog + */ + +/** One harness `ctx.` service: its one-line summary and public method signatures. */ +export interface ServiceApiEntry { + /** The `ctx.` name, e.g. `tools`. */ + key: string + /** First sentence of the service class JSDoc. */ + summary: string + /** Public method signatures, bodies stripped, in source order. */ + methods: readonly string[] +} + +/** One harness event: its dispatch mode, exact signature, and one-line summary. */ +export interface EventApiEntry { + /** The scoped event name, e.g. `agent/status`. */ + name: string + /** The dispatch mode from the declaration's `@mode` tag. */ + mode: string + /** The exact listener signature, whitespace-normalized. */ + signature: string + /** First sentence of the event JSDoc. */ + summary: string +} + +/** One inherited (cordis core + loader/hmr/timer) `ctx` member group with its summary. */ +export interface InheritedApiEntry { + /** The `ctx` member name(s), e.g. `ctx.on / ctx.once`. */ + name: string + /** One-line summary of what the member does. */ + summary: string +} + +/** One named type shape the service signatures reference. */ +export interface TypeApiEntry { + /** The exported type/interface name, e.g. `BashRunResult`. */ + name: string + /** The full declaration text, comments stripped. */ + declaration: string +} + +/** Every harness `ctx.` service, sorted by key. */ +export const SERVICE_API: readonly ServiceApiEntry[] = [ + { + key: 'agentLoop', + summary: 'The agent-loop plugin (`ctx.agentLoop`): creates ReactLoopAgents, runs their loops, and registers them in `ctx.agents`.', + methods: [ + 'create(id: AgentId, options: AgentOptions = {}): ReactLoopAgent', + 'createAgent(options: CreateAgentOptions): AgentHandle', + 'async resume(options: ResumeAgentOptions): Promise', + ], + }, + { + key: 'agents', + summary: 'Agent registry (`ctx.agents`): tracks live agents so UI, hook, and orchestrator plugins can find them without depending on the concrete loop package.', + methods: [ + 'setFactory(factory: AgentFactory): () => void', + 'create(options: CreateAgentOptions): AgentHandle', + 'async resume(options: ResumeAgentOptions): Promise', + 'register(agent: Agent): () => void', + 'get(id: AgentId): Agent | undefined', + 'list(): Agent[]', + ], + }, + { + key: 'bash', + summary: 'Abstract bash execution service.', + methods: [ + 'abstract resolve(request: BashExecRequest): BashExecSpec', + 'abstract run(spec: BashExecSpec): Promise', + 'abstract start(spec: BashExecSpec): BashTask', + 'abstract get(id: BashTaskId): BashTask | undefined', + 'abstract ownerOf(id: BashTaskId): OwnerToken | undefined', + 'abstract list(): BashTask[]', + 'abstract readOutput(id: BashTaskId): BashTaskRead', + 'abstract kill(id: BashTaskId): boolean', + 'onTaskDone(listener: BashTaskListener): () => void', + ], + }, + { + key: 'compact', + summary: 'Abstract compaction service.', + methods: [ + 'abstract compactIfNeeded( agent: CompactAgentContext, fullSystemPrompt: string, signal: AbortSignal, ): Promise', + 'abstract compactRegion( session: Session, start: number, end: number, agent: CompactAgentContext, signal?: AbortSignal, ): Promise', + ], + }, + { + key: 'fs', + summary: 'Abstract filesystem provider service.', + methods: [ + 'abstract resolve(path: string, opts?: { cwd?: string }): Promise', + 'abstract stat(target: FsTarget, signal?: AbortSignal): Promise', + 'abstract readText(target: FsTarget, signal?: AbortSignal): Promise', + 'abstract streamText(target: FsTarget, signal?: AbortSignal): Promise>', + 'abstract listDir(target: FsTarget, signal?: AbortSignal): Promise', + 'abstract writeText(target: FsTarget, content: string, expected?: FsWriteIntent, signal?: AbortSignal): Promise', + 'abstract editText(target: FsTarget, edit: FsEditRequest, expected?: { version: FsVersion }, signal?: AbortSignal): Promise', + ], + }, + { + key: 'llm', + summary: 'The abstract `llm` service: an adapter registry plus a streaming model-call surface, interceptable via the `llm/stream` waterfall.', + methods: [ + 'registerAdapter(models: string[], adapter: LlmAdapter): () => void', + 'models(): string[]', + 'stream(options: GenerateOptions): AsyncIterable', + ], + }, + { + key: 'sessionPersistence', + summary: 'Abstract durable session-persistence service.', + methods: [ + 'abstract create(meta: SessionHeader): Promise', + 'abstract append(id: SessionId, events: readonly SessionEvent[]): Promise', + 'abstract load(id: SessionId): Promise<{ meta: SessionHeader; events: SessionEvent[] }>', + 'abstract list(): Promise', + ], + }, + { + key: 'sessions', + summary: 'In-memory session store (`ctx.sessions`).', + methods: [ + 'create(id?: SessionId, options?: CreateSessionOptions): Session', + 'prepare(id?: SessionId, options?: CreateSessionOptions): Session', + 'enter(session: Session): () => void', + 'announce(session: Session): void', + 'get(id: SessionId): Session | undefined', + 'list(): Session[]', + 'fork(source: SessionForkSource, boundary?: number, childSessionId?: SessionId): Session', + ], + }, + { + key: 'subagents', + summary: 'The `subagents` service: a registry of named SubagentProviders and a capability-checked start surface.', + methods: [ + 'registerProvider(provider: SubagentProvider): () => void', + 'getProvider(name: string): SubagentProvider | undefined', + 'list(): string[]', + 'start(name: string, request: SubagentStartRequest): SubagentRun', + ], + }, + { + key: 'systemPrompt', + summary: 'Registry service (`ctx.systemPrompt`): plugins contribute ordered text sections, tool-schema providers, and named prompt variables; the agent loop calls `assemble(context)` once per step.', + methods: [ + 'section(section: PromptSection): () => void', + 'tools(provider: () => ToolSchema[]): () => void', + 'variable(name: string, provider: (context: AssembleContext) => string | undefined): () => void', + 'async assemble(context: AssembleContext = {}): Promise', + ], + }, + { + key: 'tools', + summary: 'Tool registry (`ctx.tools`): tool plugins register definitions; the agent loop executes calls through the `tools/pre-execute` → `tools/execute` → `tools/post-execute` pipeline.', + methods: [ + 'register(definition: ToolDefinition): () => void', + 'get(name: string): ToolDefinition | undefined', + 'schemas(): ToolSchema[]', + 'async execute(exec: ToolExecution): Promise', + ], + }, + { + key: 'web', + summary: 'The web access service.', + methods: [ + 'registerSearchProvider(provider: WebSearchProvider): () => void', + 'registerFetchProvider(provider: WebFetchProvider): () => void', + 'async search(request: WebSearchRequest, exec?: WebExecContext): Promise', + 'async fetch(request: WebFetchRequest, exec?: WebExecContext): Promise', + ], + }, +] + +/** Every harness event, sorted by name. */ +export const EVENT_API: readonly EventApiEntry[] = [ + { + name: 'agent/created', + mode: 'emit', + signature: '\'agent/created\'(agent: Agent): void', + summary: 'An agent was registered in the AgentRegistry and is ready to receive messages.', + }, + { + name: 'agent/disposed', + mode: 'emit', + signature: '\'agent/disposed\'(agent: Agent): void', + summary: 'An agent was disposed and removed from the registry; its fiber and any in-flight turn have been torn down.', + }, + { + name: 'agent/error', + mode: 'emit', + signature: '\'agent/error\'(agent: Agent, turn: number, step: number, error: Error): void', + summary: 'A step or turn errored.', + }, + { + name: 'agent/pre-step', + mode: 'serial', + signature: '\'agent/pre-step\'(agent: Agent, turn: number, step: number, fullSystemPrompt: string, signal: AbortSignal): Promise | void', + summary: 'Awaited pre-step surface-mutation checkpoint, fired once per step AFTER `turn/start` (and after the prior step closed) but BEFORE this step\'s `step/start` — so anything a listener appends lands OUTSIDE the step, between `turn/start`/`step/end` and the upcoming `step/start`.', + }, + { + name: 'agent/prompt-submit', + mode: 'waterfall', + signature: '\'agent/prompt-submit\'(agent: Agent, content: ContentBlock[], source: MessageSource, next: () => Promise): Promise', + summary: 'Waterfall: decide what happens to ONE drained queued message before it becomes a `user/message` — allow (optionally rewriting the prompt bytes or attaching `additionalContext`) or block it.', + }, + { + name: 'agent/queued', + mode: 'emit', + signature: '\'agent/queued\'(agent: Agent, content: ContentBlock[], info: { source: MessageSource; steering: boolean }): void', + summary: 'A message entered the agent\'s inbox (queued or steering).', + }, + { + name: 'agent/request', + mode: 'waterfall', + signature: '\'agent/request\'(agent: Agent, turn: number, step: number, config: LlmCallConfig, next: () => Promise): Promise', + summary: 'Waterfall: shape the step\'s call configuration — model switching, sampling overrides — by returning a replacement LlmCallConfig (the frozen seed is the config the loop would otherwise use).', + }, + { + name: 'agent/session-start', + mode: 'emit', + signature: '\'agent/session-start\'(agent: Agent, source: SessionStartSource): void', + summary: 'The agent\'s session lifecycle began, fired once before its first turn.', + }, + { + name: 'agent/status', + mode: 'emit', + signature: '\'agent/status\'(agent: Agent, status: AgentStatus): void', + summary: 'Agent status changed (`idle` ⇄ `running`, or → `disposed`).', + }, + { + name: 'agent/step-result', + mode: 'waterfall', + signature: '\'agent/step-result\'(agent: Agent, turn: number, step: number, message: Message, next: () => Promise): Promise', + summary: 'Waterfall: post-process the assembled assistant Message before tool dispatch (validation, content rewriting, …).', + }, + { + name: 'agent/turn-continuation', + mode: 'waterfall', + signature: '\'agent/turn-continuation\'(agent: Agent, turn: number, defaultDecision: ContinuationDecision, next: () => Promise): Promise', + summary: 'Waterfall: override the turn-continuation decision via a typed ContinuationDecision.', + }, + { + name: 'fs/edit-intent', + mode: 'waterfall', + signature: '\'fs/edit-intent\'(target: FsTarget, actor: object | undefined, next: () => { version: FsVersion } | undefined | Promise<{ version: FsVersion } | undefined>): Promise<{ version: FsVersion } | undefined>', + summary: 'Single-slot decision: produce the optional version guard for the next FileSystem.editText.', + }, + { + name: 'fs/observed', + mode: 'emit', + signature: '\'fs/observed\'(target: FsTarget, version: FsVersion, actor: object | undefined): void', + summary: 'Record that an actor observed a target at a version, after a successful read/write/edit.', + }, + { + name: 'fs/write-intent', + mode: 'waterfall', + signature: '\'fs/write-intent\'(target: FsTarget, actor: object | undefined, next: () => FsWriteIntent | undefined | Promise): Promise', + summary: 'Single-slot decision: produce the write intent for the next FileSystem.writeText.', + }, + { + name: 'llm/stream', + mode: 'waterfall', + signature: '\'llm/stream\'(this: LlmService, options: GenerateOptions, next: () => AsyncIterable): AsyncIterable', + summary: 'Waterfall around every streaming model call (retry, replay, routing).', + }, + { + name: 'session/created', + mode: 'emit', + signature: '\'session/created\'(session: Session): void', + summary: 'A session was created in the store.', + }, + { + name: 'session/event', + mode: 'emit', + signature: '\'session/event\'(session: Session, event: SessionEvent): void', + summary: 'An event was appended to a session log (sync, fire-and-forget).', + }, + { + name: 'session/flush', + mode: 'parallel', + signature: '\'session/flush\'(session: Session): Promise | void', + summary: 'Awaited durability checkpoint.', + }, + { + name: 'subagent/end', + mode: 'emit', + signature: '\'subagent/end\'(info: SubagentRunEndInfo): void', + summary: 'A subagent run settled — emitted when SubagentRun.result resolves (any stop reason).', + }, + { + name: 'subagent/provider-added', + mode: 'emit', + signature: '\'subagent/provider-added\'(provider: SubagentProvider): void', + summary: 'A provider became resolvable in the SubagentService registry.', + }, + { + name: 'subagent/provider-removed', + mode: 'emit', + signature: '\'subagent/provider-removed\'(name: string): void', + summary: 'A provider left the registry (its plugin\'s fiber was disposed — an unload or an HMR reload).', + }, + { + name: 'subagent/start', + mode: 'emit', + signature: '\'subagent/start\'(info: SubagentRunInfo): void', + summary: 'A subagent run started — emitted after the provider is resolved and its capabilities validated, as the child run begins.', + }, + { + name: 'system-prompt/assemble', + mode: 'waterfall', + signature: '\'system-prompt/assemble\'(this: SystemPrompt, assembly: PromptAssembly, context: AssembleContext, next: () => Promise): Promise', + summary: 'Waterfall around prompt assembly — mutate or extend the PromptAssembly (sections + tools + variables) before it is rendered.', + }, + { + name: 'system-prompt/change', + mode: 'emit', + signature: '\'system-prompt/change\'(): void', + summary: 'A section, tool provider, or variable provider was registered or unregistered (the assembly inputs changed).', + }, + { + name: 'tools/change', + mode: 'emit', + signature: '\'tools/change\'(): void', + summary: 'A tool was registered or unregistered (the available tool set changed).', + }, + { + name: 'tools/execute', + mode: 'waterfall', + signature: '\'tools/execute\'(this: ToolRegistry, exec: ToolExecution, next: () => Promise): Promise', + summary: 'Around-dispatch waterfall wrapping the registry\'s core tool dispatch, between the `tools/pre-execute` gate and the `tools/post-execute` seam.', + }, + { + name: 'tools/post-execute', + mode: 'waterfall', + signature: '\'tools/post-execute\'(this: ToolRegistry, exec: ToolExecution, result: ToolExecutionResult, next: () => Promise): Promise', + summary: 'Waterfall AFTER a tool runs — where hook plugins inspect the result and accept it (optionally REPLACING the model-facing content, and/or attaching `additionalContext` for the next request) or block it with corrective `feedback` (Claude Code\'s `PostToolUse`).', + }, + { + name: 'tools/pre-execute', + mode: 'waterfall', + signature: '\'tools/pre-execute\'(this: ToolRegistry, exec: ToolExecution, next: () => Promise): Promise', + summary: 'Waterfall BEFORE a tool runs — the gate where sandbox, permission, and hook plugins allow or deny a call (Claude Code\'s `PreToolUse`).', + }, +] + +/** Shapes of every exported type the SERVICE_API signatures reference (transitively), sorted by name. */ +export const TYPE_API: readonly TypeApiEntry[] = [ + { + name: 'Agent', + declaration: 'export interface Agent {\n readonly id: AgentId;\n readonly options: AgentOptions;\n readonly session: Session;\n readonly status: AgentStatus;\n send(content: ContentBlock[], options?: SendOptions): void;\n steer(content: ContentBlock[], options?: SendOptions): void;\n inject(content: ContentBlock[], options?: SendOptions): void;\n cancel(reason?: string): void;\n whenIdle(): Promise;\n}', + }, + { + name: 'AgentFactory', + declaration: 'export interface AgentFactory {\n createAgent(options: CreateAgentOptions): AgentHandle;\n resume(options: ResumeAgentOptions): Promise;\n}', + }, + { + name: 'AgentHandle', + declaration: 'export interface AgentHandle {\n agent: Agent;\n dispose(): Promise;\n}', + }, + { + name: 'AgentId', + declaration: 'export type AgentId = Branded<\'AgentId\'>;', + }, + { + name: 'AgentOptions', + declaration: 'export interface AgentOptions {\n model?: string;\n}', + }, + { + name: 'AgentStatus', + declaration: 'export type AgentStatus = \'idle\' | \'running\' | \'disposed\';', + }, + { + name: 'AssembleContext', + declaration: 'export interface AssembleContext {\n}', + }, + { + name: 'AssembledSection', + declaration: 'export interface AssembledSection {\n name: string;\n order: number;\n text: string;\n}', + }, + { + name: 'BashExecRequest', + declaration: 'export interface BashExecRequest {\n command: string;\n workdir?: string | undefined;\n timeoutMs?: number | undefined;\n signal?: AbortSignal | undefined;\n stdin?: string | undefined;\n env?: Record | undefined;\n owner?: OwnerToken | undefined;\n}', + }, + { + name: 'BashExecSpec', + declaration: 'export interface BashExecSpec {\n command: string;\n workdir: string;\n timeoutMs: number;\n signal?: AbortSignal | undefined;\n stdin?: string | undefined;\n env?: Record | undefined;\n owner: OwnerToken | undefined;\n}', + }, + { + name: 'BashRunResult', + declaration: 'export interface BashRunResult {\n exitCode: number | null;\n signal: NodeJS.Signals | null;\n timedOut: boolean;\n aborted: boolean;\n timeoutMs: number;\n stdout: CollectedOutput;\n stderr: CollectedOutput;\n}', + }, + { + name: 'BashTask', + declaration: 'export interface BashTask {\n readonly id: BashTaskId;\n readonly command: string;\n status: BashTaskStatus;\n exitCode: number | null;\n signal: NodeJS.Signals | null;\n readonly done: Promise;\n}', + }, + { + name: 'BashTaskId', + declaration: 'export type BashTaskId = Branded<\'BashTaskId\'>;', + }, + { + name: 'BashTaskListener', + declaration: 'export type BashTaskListener = (task: BashTask) => void;', + }, + { + name: 'BashTaskRead', + declaration: 'export interface BashTaskRead {\n task: BashTask;\n delta: string;\n lossy: boolean;\n stdoutSpillPath?: string;\n stderrSpillPath?: string;\n}', + }, + { + name: 'BashTaskStatus', + declaration: 'export type BashTaskStatus = \'running\' | \'completed\' | \'killed\';', + }, + { + name: 'Branded', + declaration: 'export type Branded = string & {\n readonly [BRAND]: B;\n};', + }, + { + name: 'CallId', + declaration: 'export type CallId = Branded<\'CallId\'>;', + }, + { + name: 'CollectedOutput', + declaration: 'export interface CollectedOutput {\n text: string;\n truncated: boolean;\n spillPath?: string;\n}', + }, + { + name: 'CompactAgentContext', + declaration: 'export interface CompactAgentContext {\n session: Session;\n options: {\n model?: string;\n };\n}', + }, + { + name: 'CompactionResult', + declaration: 'export interface CompactionResult {\n startSeq: number;\n summarySeq: number;\n endSeq: number;\n summary: ContentBlock[];\n shadowedRange: {\n start: number;\n end: number;\n };\n shadowedSeqs: number[];\n shadowedTokenCount: number;\n}', + }, + { + name: 'ContentBlockMap', + declaration: 'export interface ContentBlockMap {\n \'text\': TextBlock;\n \'reasoning\': ReasoningBlock;\n \'tool-call\': ToolCallBlock;\n \'tool-result\': ToolResultBlock;\n}', + }, + { + name: 'ContentBlockType', + declaration: 'export type ContentBlockType = keyof ContentBlockMap;', + }, + { + name: 'CreateAgentOptions', + declaration: 'export interface CreateAgentOptions {\n agentId: AgentId;\n sessionId: SessionId;\n meta?: {\n cwd?: string;\n parentSession?: SessionId;\n seedLength?: number;\n };\n seed?: SessionEvent[];\n agentOptions?: AgentOptions;\n}', + }, + { + name: 'CreateSessionOptions', + declaration: 'export interface CreateSessionOptions {\n seed?: SessionEvent[];\n meta?: {\n cwd?: string;\n parentSession?: SessionId;\n createdAt?: number;\n seedLength?: number;\n };\n}', + }, + { + name: 'DiffCallView', + declaration: 'export interface DiffCallView {\n card: \'diff\';\n title: string;\n diffs: FileDiff[];\n locations?: FileLocation[];\n}', + }, + { + name: 'DiffResultView', + declaration: 'export interface DiffResultView {\n card: \'diff\';\n title?: string;\n diffs: FileDiff[];\n}', + }, + { + name: 'FileDiff', + declaration: 'export interface FileDiff {\n path: string;\n oldText: string | null;\n newText: string;\n}', + }, + { + name: 'FileLocation', + declaration: 'export interface FileLocation {\n path: string;\n line?: number;\n}', + }, + { + name: 'FinishReason', + declaration: 'export type FinishReason = FinishReasonMap[keyof FinishReasonMap];', + }, + { + name: 'FinishReasonMap', + declaration: 'export interface FinishReasonMap {\n \'stop\': {\n kind: \'stop\';\n };\n \'tool-calls\': {\n kind: \'tool-calls\';\n };\n \'max-tokens\': {\n kind: \'max-tokens\';\n };\n \'aborted\': {\n kind: \'aborted\';\n };\n \'error\': {\n kind: \'error\';\n message: string;\n code?: string;\n };\n}', + }, + { + name: 'FsDirEntry', + declaration: 'export interface FsDirEntry {\n name: string;\n type: \'file\' | \'directory\' | \'other\';\n target: FsTarget;\n version?: FsVersion;\n size?: number;\n}', + }, + { + name: 'FsEditOutcome', + declaration: 'export interface FsEditOutcome {\n version: FsVersion;\n before: string;\n after: string;\n}', + }, + { + name: 'FsEditRequest', + declaration: 'export interface FsEditRequest {\n oldString: string;\n newString: string;\n replaceAll: boolean;\n}', + }, + { + name: 'FsInfo', + declaration: 'export interface FsInfo {\n version: FsVersion;\n type: \'file\' | \'directory\' | \'other\';\n size?: number;\n}', + }, + { + name: 'FsTarget', + declaration: 'export interface FsTarget {\n targetKey: FsTargetKey;\n displayPath: string;\n}', + }, + { + name: 'FsTargetKey', + declaration: 'export type FsTargetKey = Branded<\'FsTargetKey\'>;', + }, + { + name: 'FsVersion', + declaration: 'export type FsVersion = Branded<\'FsVersion\'>;', + }, + { + name: 'FsWriteIntent', + declaration: 'export type FsWriteIntent = {\n kind: \'createIfAbsent\';\n} | {\n kind: \'replaceIfVersion\';\n version: FsVersion;\n};', + }, + { + name: 'FsWriteOutcome', + declaration: 'export interface FsWriteOutcome {\n operation: \'create\' | \'update\';\n version: FsVersion;\n before: string | null;\n after: string;\n}', + }, + { + name: 'GenerateOptions', + declaration: 'export interface GenerateOptions {\n model: string;\n messages: Message[];\n system?: string;\n tools?: ToolSchema[];\n temperature?: number;\n maxTokens?: number;\n stop?: string[];\n signal?: AbortSignal;\n sessionId?: Branded<\'SessionId\'>;\n}', + }, + { + name: 'GenericCallView', + declaration: 'export interface GenericCallView {\n card: \'generic\';\n title: string;\n kind?: ToolCallKind;\n rawInput?: unknown;\n content?: ContentBlock[];\n locations?: FileLocation[];\n}', + }, + { + name: 'GenericResultView', + declaration: 'export interface GenericResultView {\n card: \'generic\';\n title?: string;\n content?: ContentBlock[];\n}', + }, + { + name: 'HookContext', + declaration: 'export interface HookContext {\n content: ContentBlock[];\n source: MessageSource;\n}', + }, + { + name: 'Message', + declaration: 'export interface Message {\n role: \'system\' | \'user\' | \'assistant\';\n content: ContentBlock[];\n}', + }, + { + name: 'MessageSource', + declaration: 'export type MessageSource = MessageSourceMap[keyof MessageSourceMap];', + }, + { + name: 'MessageSourceMap', + declaration: 'export interface MessageSourceMap {\n user: {\n kind: \'user\';\n };\n plugin: {\n kind: \'plugin\';\n plugin: string;\n };\n}', + }, + { + name: 'OwnerToken', + declaration: 'export type OwnerToken = Branded<\'OwnerToken\'>;', + }, + { + name: 'PromptAssembly', + declaration: 'export interface PromptAssembly {\n sections: AssembledSection[];\n tools: ToolSchema[];\n variables: Record;\n}', + }, + { + name: 'PromptSection', + declaration: 'export interface PromptSection {\n name: string;\n order: number;\n text: string | ((context: AssembleContext) => string);\n}', + }, + { + name: 'ReasoningBlock', + declaration: 'export interface ReasoningBlock {\n type: \'reasoning\';\n text: string;\n}', + }, + { + name: 'ResumeAgentOptions', + declaration: 'export interface ResumeAgentOptions {\n agentId: AgentId;\n resumeSessionId: SessionId;\n agentOptions?: AgentOptions;\n}', + }, + { + name: 'SendOptions', + declaration: 'export interface SendOptions {\n source?: MessageSource;\n}', + }, + { + name: 'SessionEvent', + declaration: 'export type SessionEvent = {\n [K in SessionEventType]: {\n type: K;\n seq: number;\n time: number;\n data: SessionEventMap[K];\n } & (K extends SurfaceEventType ? {\n sourceEventSeqs?: number[];\n surfaceOp?: SurfaceOp;\n } : object);\n}[T];', + }, + { + name: 'SessionEventMap', + declaration: 'export interface SessionEventMap {\n \'turn/start\': {\n turn: number;\n trigger: TurnTrigger;\n };\n \'turn/end\': {\n turn: number;\n reason: TurnEndReason;\n };\n \'step/start\': {\n turn: number;\n step: number;\n };\n \'step/end\': {\n turn: number;\n step: number;\n };\n \'user/message\': {\n content: ContentBlock[];\n source: MessageSource;\n };\n \'prompt/blocked\': {\n content: ContentBlock[];\n source: MessageSource;\n reason: string;\n };\n \'context/message\': {\n content: ContentBlock[];\n source: MessageSource;\n };\n \'assistant/chunk\': {\n turn: number;\n step: number;\n chunk: StreamChunk;\n };\n \'assistant/message\': {\n turn: number;\n step: number;\n content: ContentBlock[];\n usage?: TokenUsage;\n };\n \'tool/call\': {\n turn: number;\n step: number;\n callId: CallId;\n name: string;\n arguments: string;\n };\n \'tool/result\': {\n turn: number;\n step: number;\n callId: CallId;\n content: ContentBlock[];\n isError: boolean;\n error?: {\n name: string;\n code: string;\n };\n meta?: unknown;\n };\n \'steering/message\': {\n turn: number;\n content: ContentBlock[];\n source: MessageSource;\n };\n \'todo/write\': {\n todos: TodoItem[];\n };\n \'request/header\': {\n header: E /* …truncated — full shape in source */', + }, + { + name: 'SessionEventType', + declaration: 'export type SessionEventType = keyof SessionEventMap;', + }, + { + name: 'SessionForkSource', + declaration: 'export type SessionForkSource = Session | SessionId;', + }, + { + name: 'SessionHeader', + declaration: 'export interface SessionHeader {\n version: number;\n id: SessionId;\n createdAt: number;\n cwd?: string;\n parentSession?: SessionId;\n seedLength?: number;\n}', + }, + { + name: 'SessionId', + declaration: 'export type SessionId = Branded<\'SessionId\'>;', + }, + { + name: 'StreamChunk', + declaration: 'export type StreamChunk = {\n type: \'block-start\';\n index: number;\n blockType: ContentBlockType;\n} | {\n type: \'text-delta\';\n index: number;\n text: string;\n} | {\n type: \'reasoning-delta\';\n index: number;\n text: string;\n} | {\n type: \'tool-call-delta\';\n index: number;\n id: CallId;\n name?: string;\n argumentsDelta: string;\n} | {\n type: \'block-end\';\n index: number;\n block: ContentBlock;\n} | {\n type: \'usage\';\n usage: TokenUsage;\n} | {\n type: \'finish\';\n reason: FinishReason;\n};', + }, + { + name: 'StructuredOutputSchema', + declaration: 'export type StructuredOutputSchema = StructuredSchemaNode & {\n type: \'object\';\n};', + }, + { + name: 'StructuredScalar', + declaration: 'export type StructuredScalar = string | number | boolean | null;', + }, + { + name: 'StructuredSchemaNode', + declaration: 'export interface StructuredSchemaNode {\n type: StructuredSchemaType;\n properties?: Record;\n required?: string[];\n additionalProperties?: boolean;\n items?: StructuredSchemaNode;\n enum?: StructuredScalar[];\n const?: StructuredScalar;\n description?: string;\n title?: string;\n default?: unknown;\n examples?: unknown;\n}', + }, + { + name: 'StructuredSchemaType', + declaration: 'export type StructuredSchemaType = \'object\' | \'array\' | \'string\' | \'number\' | \'integer\' | \'boolean\' | \'null\';', + }, + { + name: 'SubagentCapabilities', + declaration: 'export interface SubagentCapabilities {\n outputSchema: boolean;\n depthLimit: boolean;\n toolFilter: boolean;\n}', + }, + { + name: 'SubagentProvider', + declaration: 'export interface SubagentProvider {\n readonly name: string;\n readonly capabilities: SubagentCapabilities;\n readonly inheritsParentContext: boolean;\n start(request: SubagentStartRequest): SubagentRun;\n}', + }, + { + name: 'SubagentResult', + declaration: 'export interface SubagentResult {\n output: ContentBlock[];\n structured?: unknown;\n stopReason: SubagentStopReason;\n}', + }, + { + name: 'SubagentRun', + declaration: 'export interface SubagentRun {\n readonly id: AgentId;\n readonly result: Promise;\n cancel(reason?: string): void;\n dispose(): Promise;\n sendMessage?(content: ContentBlock[]): void;\n resume?(content: ContentBlock[]): SubagentRun;\n}', + }, + { + name: 'SubagentStartRequest', + declaration: 'export interface SubagentStartRequest {\n prompt: ContentBlock[];\n parent: Agent;\n signal?: AbortSignal;\n agentOptions?: AgentOptions;\n outputSchema?: StructuredOutputSchema;\n maxDepth?: number;\n toolFilter?: {\n allow?: string[];\n deny?: string[];\n };\n}', + }, + { + name: 'SubagentStopReason', + declaration: 'export type SubagentStopReason = SubagentStopReasonMap[keyof SubagentStopReasonMap];', + }, + { + name: 'SubagentStopReasonMap', + declaration: 'export interface SubagentStopReasonMap {\n completed: \'completed\';\n aborted: \'aborted\';\n error: \'error\';\n \'max-tokens\': \'max-tokens\';\n refusal: \'refusal\';\n}', + }, + { + name: 'SurfaceEventType', + declaration: 'export type SurfaceEventType = \'user/message\' | \'assistant/message\' | \'tool/result\' | \'context/message\' | \'steering/message\';', + }, + { + name: 'SurfaceOp', + declaration: 'export type SurfaceOp = \'append\' | {\n op: \'replace\';\n start: number;\n end: number;\n};', + }, + { + name: 'TerminalCallView', + declaration: 'export interface TerminalCallView {\n card: \'terminal\';\n title: string;\n description?: string;\n cwd?: string;\n}', + }, + { + name: 'TerminalResultView', + declaration: 'export interface TerminalResultView {\n card: \'terminal\';\n title?: string;\n output?: string;\n exitCode?: number;\n signal?: string;\n}', + }, + { + name: 'TodoItem', + declaration: 'export interface TodoItem {\n content: string;\n status: \'pending\' | \'in_progress\' | \'completed\';\n}', + }, + { + name: 'TokenUsage', + declaration: 'export interface TokenUsage {\n inputTokens: number;\n outputTokens: number;\n cacheReadTokens?: number;\n cacheWriteTokens?: number;\n reasoningTokens?: number;\n}', + }, + { + name: 'ToolCallBlock', + declaration: 'export interface ToolCallBlock {\n type: \'tool-call\';\n id: CallId;\n name: string;\n arguments: string;\n}', + }, + { + name: 'ToolCallKind', + declaration: 'export type ToolCallKind = \'read\' | \'edit\' | \'delete\' | \'move\' | \'search\' | \'execute\' | \'fetch\' | \'other\';', + }, + { + name: 'ToolCallView', + declaration: 'export type ToolCallView = GenericCallView | TerminalCallView | DiffCallView;', + }, + { + name: 'ToolDefinition', + declaration: 'export interface ToolDefinition extends ToolSchema {\n execute(args: unknown, exec: ToolExecution): Promise;\n timeoutMs?: number;\n presentCall?(args: unknown): ToolCallView | undefined;\n presentResult?(args: unknown, result: ToolResult): ToolResultView | undefined;\n}', + }, + { + name: 'ToolErrorInfo', + declaration: 'export interface ToolErrorInfo {\n name: string;\n code: string;\n}', + }, + { + name: 'ToolExecuteReturn', + declaration: 'export type ToolExecuteReturn = ContentBlock[] | {\n content: ContentBlock[];\n meta?: unknown;\n};', + }, + { + name: 'ToolExecution', + declaration: 'export interface ToolExecution {\n callId: CallId;\n name: string;\n arguments: unknown;\n agent?: Agent;\n signal?: AbortSignal;\n}', + }, + { + name: 'ToolExecutionResult', + declaration: 'export interface ToolExecutionResult {\n callId: CallId;\n content: ContentBlock[];\n isError: boolean;\n error?: ToolErrorInfo;\n additionalContext?: HookContext;\n meta?: unknown;\n}', + }, + { + name: 'ToolResult', + declaration: 'export interface ToolResult {\n content: ContentBlock[];\n isError: boolean;\n meta?: unknown;\n}', + }, + { + name: 'ToolResultBlock', + declaration: 'export interface ToolResultBlock {\n type: \'tool-result\';\n toolCallId: CallId;\n content: ContentBlock[];\n isError?: boolean;\n}', + }, + { + name: 'ToolResultView', + declaration: 'export type ToolResultView = GenericResultView | TerminalResultView | DiffResultView;', + }, + { + name: 'ToolSchema', + declaration: 'export interface ToolSchema {\n name: string;\n description: string;\n parameters: Record;\n}', + }, + { + name: 'TurnEndReason', + declaration: 'export type TurnEndReason = TurnEndReasonMap[keyof TurnEndReasonMap];', + }, + { + name: 'TurnEndReasonMap', + declaration: 'export interface TurnEndReasonMap {\n completed: {\n kind: \'completed\';\n };\n aborted: {\n kind: \'aborted\';\n reason?: string;\n };\n error: {\n kind: \'error\';\n step: number;\n message: string;\n code?: string;\n };\n disposed: {\n kind: \'disposed\';\n };\n \'max-tokens\': {\n kind: \'max-tokens\';\n };\n rejected: {\n kind: \'rejected\';\n reason: string;\n };\n interrupted: {\n kind: \'interrupted\';\n };\n}', + }, + { + name: 'TurnTrigger', + declaration: 'export type TurnTrigger = TurnTriggerMap[keyof TurnTriggerMap];', + }, + { + name: 'TurnTriggerMap', + declaration: 'export interface TurnTriggerMap {\n message: {\n kind: \'message\';\n source: MessageSource;\n };\n injection: {\n kind: \'injection\';\n source: MessageSource;\n };\n}', + }, + { + name: 'WebExecContext', + declaration: 'export interface WebExecContext {\n readonly signal?: AbortSignal;\n}', + }, + { + name: 'WebFetchBody', + declaration: 'export type WebFetchBody = {\n readonly kind: \'html\';\n readonly content: string;\n} | {\n readonly kind: \'text\';\n readonly content: string;\n};', + }, + { + name: 'WebFetchProvider', + declaration: 'export interface WebFetchProvider {\n readonly id: string;\n status(): WebProviderStatus;\n fetch(request: WebFetchRequest, exec?: WebExecContext): Promise;\n}', + }, + { + name: 'WebFetchRequest', + declaration: 'export interface WebFetchRequest {\n readonly url: string;\n readonly timeoutMs?: number;\n}', + }, + { + name: 'WebFetchResult', + declaration: 'export interface WebFetchResult {\n readonly providerId: string;\n readonly url: string;\n readonly statusCode: number;\n readonly body: WebFetchBody;\n readonly truncated: boolean;\n}', + }, + { + name: 'WebProviderStatus', + declaration: 'export type WebProviderStatus = {\n readonly available: true;\n} | {\n readonly available: false;\n readonly reason: \'missing-credential\' | \'misconfigured\';\n};', + }, + { + name: 'WebSearchProvider', + declaration: 'export interface WebSearchProvider {\n readonly id: string;\n status(): WebProviderStatus;\n search(request: WebSearchRequest, exec?: WebExecContext): Promise;\n}', + }, + { + name: 'WebSearchRequest', + declaration: 'export interface WebSearchRequest {\n readonly query: string;\n readonly maxResults?: number;\n}', + }, + { + name: 'WebSearchResult', + declaration: 'export interface WebSearchResult {\n readonly providerId: string;\n readonly query: string;\n readonly content?: string;\n readonly sources: readonly WebSearchSource[];\n readonly truncated: boolean;\n}', + }, + { + name: 'WebSearchSource', + declaration: 'export interface WebSearchSource {\n readonly url: string;\n readonly title?: string;\n readonly snippet?: string;\n readonly publishedAt?: string;\n}', + }, +] + +/** The inherited `ctx` surface (cordis core + loader/hmr/timer), in curated order. */ +export const INHERITED_CTX_API: readonly InheritedApiEntry[] = [ + { name: 'ctx.on / ctx.once', summary: 'Register an event listener (disposable).' }, + { name: 'ctx.emit / ctx.parallel / ctx.serial / ctx.bail / ctx.waterfall', summary: 'Dispatch an event (sync / awaited / first-bail / veto-chain).' }, + { name: 'ctx.plugin / ctx.inject', summary: 'Load a plugin / declare required services.' }, + { name: 'ctx.effect', summary: 'Register a disposable side effect tied to the fiber.' }, + { name: 'ctx.get / ctx.set / ctx.provide / ctx.accessor / ctx.mixin', summary: 'Low-level service-store access and binding.' }, + { name: 'ctx.extend / ctx.isolate / ctx.intercept', summary: 'Derive a child context (scoped services / isolation / interception).' }, + { name: 'ctx.root / ctx.scope / ctx.fiber / ctx.registry / ctx.reflect / ctx.events / ctx.logger', summary: 'Ambient handles onto the running context graph.' }, + { name: 'ctx.timer (+ interval / timeout / throttle / debounce / setTimeout / setInterval)', summary: 'Disposable timer helpers. The `timer` key is provided at runtime; the six helpers are mixed onto ctx directly (declared via Pick).' }, + { name: 'ctx.loader', summary: 'The config Loader that booted the app (present under the loader).' }, + { name: 'ctx.hmr', summary: 'The hot-module-reload watcher (present under the hmr plugin).' }, +] diff --git a/packages/cordis/tool-cordis/src/fiber-state.ts b/packages/cordis/tool-cordis/src/fiber-state.ts new file mode 100644 index 0000000000..e46700c387 --- /dev/null +++ b/packages/cordis/tool-cordis/src/fiber-state.ts @@ -0,0 +1,39 @@ +/** + * Runtime mirror of the cordis `FiberState` const enum plus human-readable + * labels, shared by the mount lifecycle (state reporting) and the inspect + * renderers (tree and mount-table labels). + * + * Cordis exposes `FiberState` as a `const enum`: there is no runtime object for + * Node's type-stripping runner to import, so the members are mirrored here as + * values — each typed (via the type-only import) as the cordis enum member it + * mirrors, so enum-typed reads like `fiber.state` compare against them under a + * shared enum type. Source of truth: vendor/cordis/src/fiber.ts (pinned; drift + * only happens through a deliberate vendor sync). + * + * @module @deepseek-ai/dsh-tool-cordis/fiber-state + */ + +import type { FiberState as FiberStateEnum } from 'cordis' + +/** Value mirror of the cordis `FiberState` const enum (see the module doc for why a mirror exists). */ +export const FiberState = { + PENDING: 0 as FiberStateEnum.PENDING, + LOADING: 1 as FiberStateEnum.LOADING, + ACTIVE: 2 as FiberStateEnum.ACTIVE, + FAILED: 3 as FiberStateEnum.FAILED, + DISPOSED: 4 as FiberStateEnum.DISPOSED, + UNLOADING: 5 as FiberStateEnum.UNLOADING, +} as const + +/** The cordis `FiberState` enum type, re-exported so mirror consumers need one import. */ +export type FiberState = FiberStateEnum + +/** Human-readable label for each {@link FiberState}, keyed by member (inlining-safe — no reverse mapping). */ +export const STATE_LABELS: Record = { + [FiberState.PENDING]: 'pending', + [FiberState.LOADING]: 'loading', + [FiberState.ACTIVE]: 'active', + [FiberState.FAILED]: 'failed', + [FiberState.DISPOSED]: 'disposed', + [FiberState.UNLOADING]: 'unloading', +} diff --git a/packages/cordis/tool-cordis/src/guard.ts b/packages/cordis/tool-cordis/src/guard.ts new file mode 100644 index 0000000000..09d804771f --- /dev/null +++ b/packages/cordis/tool-cordis/src/guard.ts @@ -0,0 +1,199 @@ +/** + * The registration boundary between sandboxed mount code and the real runtime: + * SchemaSpec validation with teaching errors, the marker-guarded + * `harness.defineTool` / `harness.registerTool` pair, the guarded `ctx` proxy a + * mounted plugin receives, and the plugin-shape helpers the mount lifecycle + * narrows sandbox return values with. + * + * Two realm facts drive the design. Objects built inside the vm carry the vm + * realm's `Object.prototype`, and the session log's append-time plainness check + * (`dsh-session`'s `isJsonValue`, a prototype-identity comparison) rejects + * foreign-realm data — so every dynamic tool's `execute` return is JSON + * round-tripped into the host realm before it reaches the registry. And a + * malformed tool schema must fail at REGISTRATION, not when a later request + * assembles it — so dynamic `ctx.tools.register` calls accept only definitions + * produced by the sandbox's `harness.defineTool`, which asserts the SchemaSpec + * DSL up front. + * + * @module @deepseek-ai/dsh-tool-cordis/guard + */ + +import type { Context, Plugin } from 'cordis' +import { defineTool } from '@deepseek-ai/dsh-tools' +import type { ToolDefinition, ToolExecuteReturn } from '@deepseek-ai/dsh-tools' + +const DYNAMIC_TOOL = Symbol('tool-cordis.dynamic-tool') +const SCHEMA_TYPES = new Set(['string', 'number', 'boolean', 'object', 'array']) + +type DynamicToolDefinition = ToolDefinition & { [DYNAMIC_TOOL]: true } +type DynamicToolMarker = { [DYNAMIC_TOOL]?: unknown } + +function isPlainRecord(value: unknown): value is Record { + return Object.prototype.toString.call(value) === '[object Object]' +} + +/** Assert a sandbox-provided `parameters` value is a SchemaSpec object, with a teaching error for the common JSON-Schema mistake. */ +function assertSchemaSpec(value: unknown): void { + if (!isPlainRecord(value)) { + throw new Error('harness.defineTool parameters must be a SchemaSpec object') + } + if (value.type === 'object' && isPlainRecord(value.properties)) { + throw new Error( + 'harness.defineTool parameters use the SchemaSpec DSL (NOT JSON Schema).\n' + + ' ✗ { type: \'object\', properties: { name: { type: \'string\' } }, required: [\'name\'] }\n' + + ' ✓ { name: { type: \'string\', required: true } }\n' + + 'Remove the outer { type: \'object\', properties, required } wrapper; ' + + 'each key IS a property directly on the parameters object.', + ) + } + for (const [key, prop] of Object.entries(value)) { + assertSchemaProp(prop, `parameters.${key}`) + } +} + +function assertSchemaProp(value: unknown, path: string): void { + if (!isPlainRecord(value)) { + throw new Error(`harness.defineTool ${path} must be a SchemaSpec property object`) + } + if (!SCHEMA_TYPES.has(value.type)) { + throw new Error(`harness.defineTool ${path} must declare a valid type`) + } + if (value.required !== undefined && value.required !== true) { + throw new Error(`harness.defineTool ${path}.required must be true when present`) + } + if (value.properties !== undefined) { + if (value.type !== 'object') { + throw new Error(`harness.defineTool ${path}.properties is only valid for type "object"`) + } + assertSchemaSpec(value.properties) + } + if (value.items !== undefined) { + if (value.type !== 'array') { + throw new Error(`harness.defineTool ${path}.items is only valid for type "array"`) + } + assertSchemaProp(value.items, `${path}.items`) + } +} + +function markDynamicTool(tool: ToolDefinition): DynamicToolDefinition { + Object.defineProperty(tool, DYNAMIC_TOOL, { value: true }) + return tool as DynamicToolDefinition +} + +function assertDynamicTool(tool: unknown): asserts tool is DynamicToolDefinition { + if (!isPlainRecord(tool) || (tool as DynamicToolMarker)[DYNAMIC_TOOL] !== true) { + throw new Error('dynamic tool registration must use a tool returned by harness.defineTool(...)') + } +} + +/** + * The `harness.defineTool` handed into the sandbox: the real DSL, with the + * tool's `execute` return normalized into the host realm via a JSON round-trip + * (see the module doc). The round-trip also projects the return onto exactly + * what the log would durably store, so a non-JSON-serializable return surfaces + * as that one call's error instead of poisoning the turn. + * @param options - the standard `defineTool` options, with `parameters` asserted against the SchemaSpec DSL before the DSL sees them. + * @returns the marker-tagged definition `harness.registerTool` (and the guarded `ctx.tools.register`) accepts. + */ +export function sandboxDefineTool(options: Parameters[0]): ToolDefinition { + assertSchemaSpec((options as { parameters?: unknown }).parameters) + const tool = defineTool(options) + const execute = tool.execute.bind(tool) + return markDynamicTool({ + ...tool, + async execute(args, exec) { + return JSON.parse(JSON.stringify(await execute(args, exec))) as ToolExecuteReturn + }, + }) +} + +/** + * The `harness.registerTool` handed into the sandbox: registers a + * marker-verified dynamic tool on the given context's registry. + * @param ctx - the (guarded) context whose `tools` service receives the tool. + * @param tool - a definition produced by {@link sandboxDefineTool}; anything else is rejected. + * @returns the registry disposer for the registration. + */ +export function sandboxRegisterTool(ctx: Context, tool: unknown): () => void { + assertDynamicTool(tool) + return ctx.tools.register(tool) +} + +function bindMethod(value: unknown, target: object): unknown { + if (typeof value !== 'function') return value + return (...args: unknown[]): unknown => Reflect.apply(value, target, args) as unknown +} + +function guardedContext(ctx: Context): Context { + const tools = new Proxy(ctx.tools, { + get(target, prop) { + if (prop === 'register') { + return (tool: unknown): () => void => sandboxRegisterTool(ctx, tool) + } + const value = Reflect.get(target, prop, target) as unknown + return bindMethod(value, target) + }, + }) + return new Proxy(ctx, { + get(target, prop) { + if (prop === 'tools') return tools + if (prop === 'get') { + return (service: string): unknown => service === 'tools' ? tools : target.get(service) + } + const value = Reflect.get(target, prop, target) as unknown + return bindMethod(value, target) + }, + }) +} + +/** + * Narrow an arbitrary sandbox return value to a mountable cordis plugin: a + * function, or an object with an `apply` function. (A bare function passes the + * first arm, so the object arm never sees `Function.prototype.apply`.) + * @param value - whatever the mount code returned. + * @returns whether the value is mountable via `ctx.plugin`. + */ +export function isPlugin(value: unknown): value is Plugin { + if (typeof value === 'function') return true + return typeof value === 'object' && value !== null + && typeof (value as { apply?: unknown }).apply === 'function' +} + +/** + * Wrap a plugin so its `apply` receives a guarded context (`tools.register` + * only accepts tools from `harness.defineTool`). Both function-form and + * object-form plugins go through the same guard; everything else on the + * context — `on`, `provide`, `inject` resolution — passes through with correct + * `this` binding, so cross-mount provide/inject works unmodified. + * @param plugin - the plugin the mount code returned. + * @returns an equivalent plugin whose `apply` sees the guarded context. + */ +export function guardedPlugin(plugin: Plugin): Plugin { + if (typeof plugin === 'function') { + const functionPlugin = plugin as (ctx: Context, config?: unknown) => unknown + return { + name: pluginName(plugin), + apply(ctx: Context, config?: unknown) { + return functionPlugin(guardedContext(ctx), config) + }, + } + } + const objectPlugin = plugin as { apply(ctx: Context, config?: unknown): unknown } + return { + ...plugin, + apply(ctx: Context, config?: unknown) { + return objectPlugin.apply(guardedContext(ctx), config) + }, + } +} + +/** + * Display name for a mounted plugin: its `name` property, else anonymous. + * @param plugin - the plugin the mount code returned. + * @returns the human-readable name used in mount results and inspect output. + */ +export function pluginName(plugin: Plugin): string { + const named = (plugin as { name?: unknown }).name + if (typeof named === 'string' && named.length > 0) return named + return '' +} diff --git a/packages/cordis/tool-cordis/src/index.ts b/packages/cordis/tool-cordis/src/index.ts new file mode 100644 index 0000000000..d4492b4768 --- /dev/null +++ b/packages/cordis/tool-cordis/src/index.ts @@ -0,0 +1,228 @@ +/** + * The self-referential cordis toolset: three model-facing tools that let the + * agent inspect and MODIFY the live cordis runtime it is running inside. + * + * - `cordis_inspect` — read-only: provided services, the plugin fiber tree + * (rendered as an ASCII tree), registered tools, the dynamic mounts, and the + * catalog-backed `api` / `events` references. + * - `cordis_mount` — evaluate model-written code in a `node:vm` sandbox; the + * code returns a cordis plugin, which is mounted as a child of a dedicated + * `cordis-dynamic` group fiber and tracked under an id (`dyn-1`, `dyn-2`, …). + * - `cordis_unmount` — dispose one dynamic mount by id, awaiting quiescence. + * + * Everything the model's plugin registers (listeners via `ctx.on`, tools via + * `harness.registerTool`, services via `ctx.provide`) is an effect on the + * dynamic fiber, so unmounting — or disposing this plugin itself (HMR) — cleans + * it all up through the ordinary cordis lifecycle. The group fiber exists + * exactly so the dynamic mounts form ONE subtree: visible as a unit in the + * inspect tree and disposed as a unit with this plugin. Design home: + * docs/rfc/implemented/feature/2026-07-08-self-referential-cordis-toolset.md. + * + * The vm sandbox guards against ACCIDENTAL global pollution only — it is not a + * security boundary. The `ctx` handed to the mounted plugin's `apply` is the + * real, fully privileged runtime handle; that is the point of the toolset, so + * a deployment loads this plugin as deliberately as it grants a bash tool. + * + * Plugin export shape: named exports, NO default. The cordis Loader's + * `unwrapExports` does `exports.default ?? exports`, so a stray default would + * collapse the module to the bare `apply` and drop `inject`, crashing at load + * (see docs/postmortem/0001). + * + * @module @deepseek-ai/dsh-tool-cordis + */ + +import type { Context, Fiber } from 'cordis' +import z from 'schemastery' +import { defineTool } from '@deepseek-ai/dsh-tools' +import { STATE_LABELS } from './fiber-state.ts' +import { isPlugin, pluginName } from './guard.ts' +import { describeApi, describeDynamic, describeEvents, describePluginTree, describeServices, describeTools } from './inspect.ts' +import { missingServices, mountDynamic } from './mount.ts' +import type { DynamicMount } from './mount.ts' +import { presentInspectCall, presentMountCall, presentUnmountCall } from './present.ts' +import { createSandbox, evaluateMountCode } from './sandbox.ts' + +export const name = 'tool-cordis' +export const inject = ['tools'] + +/** Config for the tool-cordis plugin: the sandbox evaluation bound. */ +export interface Config { + /** + * Milliseconds the SYNCHRONOUS portion of mount code may run in the vm + * before evaluation is aborted (default 5000). An async body escapes this + * bound — see docs/rfc/implemented/feature/2026-07-08-self-referential-cordis-toolset.md for the trust stance. + */ + vmTimeoutMs?: number +} + +/** Schemastery validator for {@link Config}: `vmTimeoutMs` must be at least 1 (defaults to 5000). */ +export const Config: z = z.object({ + vmTimeoutMs: z.number().min(1).default(5000), +}) + +/** {@link Config} with every defaulted field present, as schemastery resolves it at load. */ +type ResolvedConfig = Required + +/** + * Mount the three cordis tools on `ctx.tools` and create the `cordis-dynamic` + * group fiber every dynamic mount hangs under. + * @param ctx - the plugin context (`tools` injected). + * @param config - the schemastery-resolved {@link Config}. + */ +export function apply(ctx: Context, config: Config): void { + const { vmTimeoutMs } = config as ResolvedConfig + // The one group fiber every dynamic mount hangs under. Mounted here (a child + // of this plugin's fiber) so disposing tool-cordis cascades over the whole + // dynamic subtree — the ordinary parent→child fiber lifecycle, nothing extra. + const group = ctx.plugin({ name: 'cordis-dynamic', apply: () => {} }) + + const mounts = new Map() + let nextId = 1 + + /** The dynamic-mount id for a fiber, when that fiber is a tracked mount. */ + function mountIdOf(fiber: Fiber): string | undefined { + for (const [id, mount] of mounts) { + if (mount.fiber === fiber) return id + } + return undefined + } + + ctx.tools.register(defineTool({ + name: 'cordis_inspect', + description: + 'Inspect the live cordis runtime that is running THIS agent. Read-only. ' + + 'Sections: `services` (every provided ctx service and the plugin fiber that owns it), ' + + '`plugins` (the whole plugin fiber tree with lifecycle states, as an ASCII tree — ' + + 'dynamic mounts appear under the `cordis-dynamic` group with their ids), ' + + '`tools` (the model-facing tools currently registered, i.e. what you can call), ' + + '`dynamic` (plugins you mounted via cordis_mount: id, name, state, provided services, awaited services), ' + + '`api` (method signatures AND argument/return type shapes for every LIVE service — read this before writing plugin code that calls a service), ' + + '`events` (every harness event with its dispatch mode and exact signature — pick listener targets here). ' + + 'Omit `what` to get all six sections.', + parameters: { + what: { + type: 'string', + enum: ['services', 'plugins', 'tools', 'dynamic', 'api', 'events'], + description: 'Limit the report to one section. Omit for all sections.', + }, + }, + execute(args): Promise<{ type: 'text'; text: string }[]> { + const sections: [heading: string, body: () => string[]][] = [ + ['services', () => describeServices(ctx)], + ['plugins', () => describePluginTree(ctx, mountIdOf)], + ['tools', () => describeTools(ctx)], + ['dynamic', () => describeDynamic(ctx, mounts)], + ['api', () => describeApi(ctx)], + ['events', () => describeEvents()], + ] + const selected = sections.filter(([heading]) => args.what === undefined || args.what === heading) + const text = selected + .map(([heading, body]) => `## ${heading}\n${body().join('\n')}`) + .join('\n\n') + return Promise.resolve([{ type: 'text', text }]) + }, + presentCall: presentInspectCall, + })) + + ctx.tools.register(defineTool({ + name: 'cordis_mount', + description: + 'Mount a NEW cordis plugin into the live runtime that is running THIS agent ' + + '(self-modification). `code` runs as the body of an async JavaScript function ' + + 'in an isolated sandbox and MUST `return` a plugin. Two forms: ' + + 'FUNCTION form `return (ctx) => { … }` — cannot declare inject, uses whatever ' + + 'services are on the parent context, and accessing a service without inject ' + + '(e.g. ctx.bash) throws; use it only when you need no injected services. ' + + 'OBJECT form `return { name?, inject: [\'bash\', \'llm\', …], apply(ctx) { … } }` ' + + '— declares dependencies, and cordis activates the plugin only after the ' + + 'services exist; PREFER this form for any plugin that needs bash, llm, sessions, etc. ' + + 'BEFORE calling a service from your code, read cordis_inspect what:"api" — it lists ' + + 'method signatures AND the type shapes of their arguments/returns (do not guess a ' + + 'field\'s type; e.g. a bash run\'s stdout is an object, not a string). ' + + 'Inside `apply`, use the standard cordis API: `ctx.on(event, listener)` to observe ' + + 'events (see cordis_inspect what:"events"), or call ' + + '`harness.registerTool(ctx, harness.defineTool({ name, description, parameters: ' + + '{ text: { type: \'string\', required: true } }, async execute(args) { … } }))` ' + + 'to give yourself a new tool — it becomes callable on your NEXT step. A ' + + 'tool\'s `execute` MUST return an ARRAY of content blocks, e.g. `return ' + + '[{ type: \'text\', text: someString }]` — never a bare string. ' + + 'Mounts can COMPOSE: one plugin may `ctx.provide(\'name\', value)` a service and ' + + 'another may declare `inject: [\'name\']` to consume it — the consumer stays pending ' + + 'until the provider exists and returns to pending when the provider is unmounted. ' + + 'Everything registered inside `apply` is cleaned up automatically on unmount. ' + + 'Sandbox globals: `console` (tagged `[cordis:]`, writes through to the harness ' + + 'terminal), `harness.defineTool`, `harness.registerTool`, ' + + '`btoa`, `atob`, `TextEncoder`, `TextDecoder`; ' + + 'there is no `require`, `process`, `Buffer`, or network. ' + + 'Write PLAIN JavaScript, not TypeScript (no `as`, no type annotations). ' + + 'Cautions: (1) waterfall events (e.g. tools/pre-execute) hand the listener a ' + + 'trailing `next` callback which MUST be called — returning without `next()` ' + + 'VETOES the call; prefer plain notification events unless you intend to ' + + 'intercept. (2) Never await something that only resolves after the current ' + + 'turn (your code runs INSIDE a tool call of that turn — it would deadlock). ' + + '(3) The sandbox prevents accidental global pollution, not malice: `ctx` is ' + + 'the real, fully privileged runtime handle.', + parameters: { + code: { + type: 'string', + required: true, + description: 'Body of an async JS function; must `return` the plugin to mount.', + }, + }, + async execute(args) { + const id = `dyn-${nextId++}` + const sandbox = createSandbox(id) + const evaluated = await evaluateMountCode(sandbox, args.code, id, vmTimeoutMs) + if (!isPlugin(evaluated)) { + if (evaluated === undefined) { + throw new Error( + 'mount code returned `undefined` — did you forget `return`?\n' + + ' ✓ return (ctx) => { … }\n' + + ' ✓ return { name: \'…\', inject: […], apply(ctx) { … } }', + ) + } + throw new Error( + 'mount code must `return` a plugin: a function, or an object with an `apply(ctx)` method', + ) + } + const fiber = await mountDynamic(group, evaluated) + mounts.set(id, { fiber, pluginName: pluginName(evaluated) }) + // A settled fiber that is not ACTIVE is waiting on unsatisfied inject — + // legal cordis semantics (it activates when the service appears), so keep + // it mounted but tell the model what it is waiting for. + const missing = missingServices(ctx, fiber) + const state = STATE_LABELS[fiber.state] + const note = missing.length > 0 + ? ` — waiting for service(s): ${missing.join(', ')} (activates when provided)` + : '' + return [{ type: 'text', text: `mounted ${id} (plugin "${pluginName(evaluated)}", state: ${state}${note})` }] + }, + presentCall: presentMountCall, + })) + + ctx.tools.register(defineTool({ + name: 'cordis_unmount', + description: + 'Dispose a plugin previously mounted with cordis_mount, by id. All its ' + + 'registrations (event listeners, tools, services) are cleaned up through ' + + 'the cordis effect lifecycle. Returns only after disposal has fully ' + + 'completed (quiescence, not just a request to stop).', + parameters: { + id: { + type: 'string', + required: true, + description: 'The dynamic mount id returned by cordis_mount (e.g. "dyn-1").', + }, + }, + async execute(args) { + const mount = mounts.get(args.id) + if (!mount) { + throw new Error(`no dynamic plugin with id "${args.id}" (list mounts with cordis_inspect what:"dynamic")`) + } + await mount.fiber.dispose() + mounts.delete(args.id) + return [{ type: 'text', text: `unmounted ${args.id} (plugin "${mount.pluginName}")` }] + }, + presentCall: presentUnmountCall, + })) +} diff --git a/packages/cordis/tool-cordis/src/inspect.ts b/packages/cordis/tool-cordis/src/inspect.ts new file mode 100644 index 0000000000..dfcc9a0c6b --- /dev/null +++ b/packages/cordis/tool-cordis/src/inspect.ts @@ -0,0 +1,225 @@ +/** + * Read-only renderers over the live runtime for `cordis_inspect`: the service + * list, the plugin fiber tree (ASCII), the registered tools, the dynamic-mount + * table (with per-mount provides/waits), and the catalog-backed `api` / + * `events` sections. Every renderer is a pure function of the runtime handles + * it receives — no session state, no clock — so inspect output is exactly the + * runtime it describes. + * + * @module @deepseek-ai/dsh-tool-cordis/inspect + */ + +import type { Context, Fiber } from 'cordis' +import { EVENT_API, INHERITED_CTX_API, SERVICE_API, TYPE_API } from './api-catalog.ts' +import type { EventApiEntry, InheritedApiEntry, ServiceApiEntry, TypeApiEntry } from './api-catalog.ts' +import { FiberState, STATE_LABELS } from './fiber-state.ts' +import { missingServices } from './mount.ts' +import type { DynamicMount } from './mount.ts' + +/** The live service registrations from `ctx.reflect.store` (map + filter keeps the possibly-undefined index read branch-free). */ +function liveImpls(ctx: Context): { name: string; fiber: Fiber }[] { + const store = ctx.reflect.store + return Object.getOwnPropertySymbols(store) + .map(key => store[key]) + .filter((impl): impl is NonNullable => impl !== undefined) +} + +/** Whether `fiber` is `root` itself or mounted anywhere inside `root`'s subtree. */ +function withinFiber(fiber: Fiber, root: Fiber): boolean { + let current = fiber + while (true) { + if (current === root) return true + const parent = current.parent.fiber + if (parent === current) return false + current = parent + } +} + +/** The service names provided by a mount's fiber subtree, sorted. */ +function providedBy(ctx: Context, fiber: Fiber): string[] { + return liveImpls(ctx) + .filter(impl => withinFiber(impl.fiber, fiber)) + .map(impl => impl.name) + .sort() +} + +/** + * The `services` section: every provided ctx service with its owning fiber, + * annotating non-active owners with their lifecycle state. + * @param ctx - the runtime to enumerate. + * @returns one line per service, or a single placeholder line when none are provided. + */ +export function describeServices(ctx: Context): string[] { + const lines = liveImpls(ctx).map((impl) => { + const active = impl.fiber.state === FiberState.ACTIVE + return `- ${impl.name} (provided by ${impl.fiber.name}${active ? '' : `, ${STATE_LABELS[impl.fiber.state]}`})` + }) + return lines.length > 0 ? lines : ['(no services provided)'] +} + +/** The tree node shape {@link renderTree} draws: one line per fiber, children indented. */ +interface TreeNode { + label: string + children: TreeNode[] +} + +/** Render a node list as an ASCII tree (`├─`/`└─` box drawing). */ +function renderTree(nodes: TreeNode[], prefix = ''): string[] { + return nodes.flatMap((node, index) => { + const last = index === nodes.length - 1 + const line = `${prefix}${last ? '└─' : '├─'} ${node.label}` + const childPrefix = `${prefix}${last ? ' ' : '│ '}` + return [line, ...renderTree(node.children, childPrefix)] + }) +} + +/** + * The `plugins` section: every fiber the registry knows, rebuilt into the + * parent→child tree from each fiber's mounting context and rendered as an + * ASCII tree with lifecycle states. Fibers whose parent fiber is outside the + * registry (i.e. mounted on the root context) become roots. + * @param ctx - the runtime whose registry is walked. + * @param mountIdOf - resolves a fiber to its dynamic-mount id, so mounts render as `dyn-: name`. + * @returns the tree lines, starting at the synthetic `root` line. + */ +export function describePluginTree(ctx: Context, mountIdOf: (fiber: Fiber) => string | undefined): string[] { + const fibers = new Set() + for (const runtime of ctx.registry.values()) { + for (const fiber of runtime.fibers) fibers.add(fiber) + } + const childrenOf = new Map() + const roots: Fiber[] = [] + for (const fiber of fibers) { + const parent = fiber.parent.fiber + if (fibers.has(parent)) { + const siblings = childrenOf.get(parent) ?? [] + siblings.push(fiber) + childrenOf.set(parent, siblings) + } else { + roots.push(fiber) + } + } + const byUid = (a: Fiber, b: Fiber): number => (a.uid ?? Infinity) - (b.uid ?? Infinity) + const toNode = (fiber: Fiber): TreeNode => { + const id = mountIdOf(fiber) + const label = `${id ? `${id}: ` : ''}${fiber.name} [${STATE_LABELS[fiber.state]}]` + const children = (childrenOf.get(fiber) ?? []).sort(byUid).map(toNode) + return { label, children } + } + return ['root', ...renderTree(roots.sort(byUid).map(toNode))] +} + +/** + * The `tools` section: the model-facing tool names currently registered. + * @param ctx - the runtime whose tool registry is read. + * @returns one line per registered tool. + */ +export function describeTools(ctx: Context): string[] { + return ctx.tools.schemas().map(schema => `- ${schema.name}`) +} + +/** + * The `dynamic` section: one line per mount with id, plugin name, lifecycle + * state, the services its subtree provides, and — for a pending mount — the + * services it waits for. + * @param ctx - the runtime the mounts live in. + * @param mounts - the tracked mounts, in mount order. + * @returns one line per mount, or a single placeholder line when none exist. + */ +export function describeDynamic(ctx: Context, mounts: ReadonlyMap): string[] { + if (mounts.size === 0) return ['(no dynamic plugins mounted)'] + return [...mounts].map(([id, mount]) => { + const provides = providedBy(ctx, mount.fiber) + const waiting = missingServices(ctx, mount.fiber) + const providesNote = provides.length > 0 ? ` — provides: ${provides.join(', ')}` : '' + const waitingNote = waiting.length > 0 ? ` — waiting for: ${waiting.join(', ')}` : '' + return `- ${id}: ${mount.pluginName} [${STATE_LABELS[mount.fiber.state]}]${providesNote}${waitingNote}` + }) +} + +/** + * The transitive closure of catalogued type shapes referenced (word-bounded) + * by the seed texts — the runtime scoping that keeps the `api` section to the + * shapes the LIVE signatures actually mention. + */ +function typeClosure(seeds: string[], types: readonly TypeApiEntry[]): TypeApiEntry[] { + const included = new Map() + let frontier = seeds + while (frontier.length > 0) { + const next: string[] = [] + for (const entry of types) { + if (included.has(entry.name)) continue + const pattern = new RegExp(`\\b${entry.name}\\b`) + if (frontier.some(text => pattern.test(text))) { + included.set(entry.name, entry) + next.push(entry.declaration) + } + } + frontier = next + } + return [...included.values()].sort((a, b) => a.name.localeCompare(b.name)) +} + +/** + * The `api` section: the generated service catalog intersected with the LIVE + * runtime — catalogued live services render summary + method signatures, live + * services without a catalog entry (e.g. ones another mount provides) render + * name + owning fiber, catalog services that are not running are listed + * tersely, the type shapes the live signatures reference follow, and the + * inherited `ctx` surface closes the section. + * @param ctx - the runtime to intersect the catalog with. + * @param api - the service catalog (the generated one by default; injectable for tests). + * @param inherited - the inherited `ctx` surface lines (generated by default; injectable for tests). + * @param types - the type-shape catalog (generated by default; injectable for tests). + * @returns the section lines. + */ +export function describeApi( + ctx: Context, + api: readonly ServiceApiEntry[] = SERVICE_API, + inherited: readonly InheritedApiEntry[] = INHERITED_CTX_API, + types: readonly TypeApiEntry[] = TYPE_API, +): string[] { + const live = new Map() + for (const impl of liveImpls(ctx)) live.set(impl.name, impl.fiber.name) + const lines: string[] = [] + const liveMethodTexts: string[] = [] + for (const entry of api) { + if (!live.has(entry.key)) continue + lines.push(`- ${entry.key} — ${entry.summary}`) + for (const method of entry.methods) { + lines.push(` ${method}`) + liveMethodTexts.push(method) + } + } + const catalogued = new Set(api.map(entry => entry.key)) + for (const [name, fiber] of [...live].sort(([a], [b]) => a.localeCompare(b))) { + if (!catalogued.has(name)) lines.push(`- ${name} (provided by ${fiber}, no catalog entry)`) + } + const notRunning = api.filter(entry => !live.has(entry.key)).map(entry => entry.key) + if (notRunning.length > 0) lines.push(`not running (loadable services with no live provider): ${notRunning.join(', ')}`) + const shapes = typeClosure(liveMethodTexts, types) + if (shapes.length > 0) { + lines.push('type shapes (referenced by the signatures above — read these before assuming a field is a string):') + for (const shape of shapes) { + for (const declLine of shape.declaration.split('\n')) lines.push(` ${declLine}`) + } + } + lines.push('inherited ctx API:') + for (const entry of inherited) lines.push(`- ${entry.name} — ${entry.summary}`) + return lines +} + +/** + * The `events` section: every harness event with its dispatch mode, one-line + * summary, and exact signature, closed by the waterfall caution. + * @param events - the event catalog (the generated one by default; injectable for tests). + * @returns the section lines. + */ +export function describeEvents(events: readonly EventApiEntry[] = EVENT_API): string[] { + const lines = events.flatMap(event => [ + `- ${event.name} [${event.mode}] — ${event.summary}`, + ` ${event.signature}`, + ]) + lines.push('waterfall listeners receive a trailing next() and MUST call it to delegate — returning without next() vetoes the chain.') + return lines +} diff --git a/packages/cordis/tool-cordis/src/mount.ts b/packages/cordis/tool-cordis/src/mount.ts new file mode 100644 index 0000000000..a222e81da1 --- /dev/null +++ b/packages/cordis/tool-cordis/src/mount.ts @@ -0,0 +1,64 @@ +/** + * Dynamic-mount lifecycle over the `cordis-dynamic` group fiber: settle a + * sandbox-produced plugin as a child fiber (never leaving a failed fiber + * mounted), and report the services a settled-but-pending fiber still waits + * for. Disposal needs no helper — a mount unwinds through an ordinary awaited + * `fiber.dispose()`, because everything the plugin registered is an effect on + * its fiber. + * + * @module @deepseek-ai/dsh-tool-cordis/mount + */ + +import type { Context, Fiber, Plugin } from 'cordis' +import { guardedPlugin } from './guard.ts' + +/** One tracked dynamic mount: the fiber plus the display name captured at mount time. */ +export interface DynamicMount { + /** The child fiber under the `cordis-dynamic` group. */ + fiber: Fiber + /** The plugin's display name at mount time (its `name`, else ``). */ + pluginName: string +} + +/** + * Mount a plugin under the group fiber and settle it. The group fiber loads + * asynchronously right after the owning plugin's `apply`, so it is awaited + * before hanging a child off its context. The child fiber's `await()` settles + * its lifecycle work and rethrows a startup error (e.g. a throwing `apply`); + * on error the fiber is disposed first — a failed mount never lingers. + * @param group - the `cordis-dynamic` group fiber every mount hangs under. + * @param plugin - the plugin the sandbox returned; wrapped with the registration guard before mounting. + * @returns the settled child fiber (possibly pending on unsatisfied `inject`). + */ +export async function mountDynamic(group: Fiber, plugin: Plugin): Promise { + await group.await() + const fiber = group.ctx.plugin(guardedPlugin(plugin)) + try { + await fiber.await() + } catch (error) { + await fiber.dispose() + const message = error instanceof Error ? error.message : String(error) + // The commonest startup collision is remounting a NEW version of a tool + // while the old mount still holds the name — teach the replace recipe. + if (message.includes('already registered')) { + throw new Error( + `${message} — to REPLACE something an earlier mount registered, first cordis_unmount that mount's id ` + + '(find it with cordis_inspect what:"dynamic"), then mount the new version.', + ) + } + throw error instanceof Error ? error : new Error(message) + } + return fiber +} + +/** + * The services a fiber declared in `inject` that do not exist yet — a settled + * fiber that is not active is waiting on exactly these (legal cordis + * semantics: it activates when the service appears). + * @param ctx - the context to resolve service existence against. + * @param fiber - the mount fiber whose `inject` declarations are checked. + * @returns the missing service names, in declaration order. + */ +export function missingServices(ctx: Context, fiber: Fiber): string[] { + return Object.keys(fiber.inject).filter(service => ctx.get(service) === undefined) +} diff --git a/packages/cordis/tool-cordis/src/present.ts b/packages/cordis/tool-cordis/src/present.ts new file mode 100644 index 0000000000..614b070193 --- /dev/null +++ b/packages/cordis/tool-cordis/src/present.ts @@ -0,0 +1,51 @@ +/** + * ACP render intents for the three cordis tools — all `generic` cards, decided + * up front as part of the tool design. Presenters are pure functions of the + * call arguments (they run on replay too): no I/O, no session state, no clock. + * No `presentResult` overrides exist — the tools' text results are their + * correct completed rendering. + * + * @module @deepseek-ai/dsh-tool-cordis/present + */ + +import type { GenericCallView } from '@deepseek-ai/dsh-tools' + +/** + * The `cordis_inspect` call card: a read, titled with the requested section. + * @param args - the validated call arguments. + * @returns the generic card the ACP bridge renders. + */ +export function presentInspectCall(args: { what?: string }): GenericCallView { + return { + card: 'generic', + kind: 'read', + title: args.what === undefined ? 'Inspect cordis runtime' : `Inspect cordis runtime: ${args.what}`, + } +} + +/** + * The `cordis_mount` call card: an execute carrying the mount code as raw input. + * @param args - the validated call arguments. + * @returns the generic card the ACP bridge renders. + */ +export function presentMountCall(args: { code: string }): GenericCallView { + return { + card: 'generic', + kind: 'execute', + title: 'Mount plugin into live cordis runtime', + rawInput: { code: args.code }, + } +} + +/** + * The `cordis_unmount` call card: a delete, titled with the mount id. + * @param args - the validated call arguments. + * @returns the generic card the ACP bridge renders. + */ +export function presentUnmountCall(args: { id: string }): GenericCallView { + return { + card: 'generic', + kind: 'delete', + title: `Unmount ${args.id}`, + } +} diff --git a/packages/cordis/tool-cordis/src/sandbox.ts b/packages/cordis/tool-cordis/src/sandbox.ts new file mode 100644 index 0000000000..4d3eb16dfc --- /dev/null +++ b/packages/cordis/tool-cordis/src/sandbox.ts @@ -0,0 +1,153 @@ +/** + * The `node:vm` sandbox `cordis_mount` code evaluates in: a fresh realm whose + * globals are a tagged write-through console, the `harness` registration + * helpers, and the encoding primitives a bare vm context lacks. The sandbox + * guards against ACCIDENTAL global pollution only — it is not a security + * boundary; the `ctx` a mounted plugin's `apply` later receives is the real, + * fully privileged runtime handle, and that is the point of the toolset. + * + * @module @deepseek-ai/dsh-tool-cordis/sandbox + */ + +import { createContext, runInContext } from 'node:vm' +import { sandboxDefineTool, sandboxRegisterTool } from './guard.ts' + +/** + * A write-through console for one sandbox, tagging every line with the mount + * id. Write-through (host stdout/stderr), NOT buffered into the tool result: + * a mounted listener fires long after the mount call returned, and its output + * must land somewhere the user can see — for the stdio demo, the terminal. + */ +function taggedConsole(id: string): Record<'log' | 'info' | 'warn' | 'error' | 'debug', (...args: unknown[]) => void> { + const tag = `[cordis:${id}]` + const log = (...args: unknown[]): void => { console.log(tag, ...args) } + const error = (...args: unknown[]): void => { console.error(tag, ...args) } + return { log, info: log, warn: log, debug: log, error } +} + +/** + * Per-sandbox prelude: give the vm realm's own constructors a + * `Symbol.hasInstance` that checks BOTH realms. Model code runs against a + * fresh vm realm, but most objects it touches are HOST-realm (the `args` a + * tool's `execute` receives, event payloads a listener observes, service + * return values), so a plain `x instanceof Array` / `instanceof Object` in + * sandbox code would silently be false. The patch replaces each vm + * constructor's own `[Symbol.hasInstance]` with "ordinary check against the + * vm constructor OR the host counterpart" — the ordinary algorithm is a pure + * prototype-chain walk, so calling it with the host constructor as receiver + * needs no host-side change. ONLY vm-realm globals are modified; host + * intrinsics are passed in as values and never touched. + */ +const DUAL_REALM_INSTANCEOF_PRELUDE = ` +(hostIntrinsics) => { + 'use strict' + const ordinary = Function.prototype[Symbol.hasInstance] + for (const name of Object.keys(hostIntrinsics)) { + const VmCtor = globalThis[name] + const HostCtor = hostIntrinsics[name] + if (typeof VmCtor !== 'function' || typeof HostCtor !== 'function') continue + Object.defineProperty(VmCtor, Symbol.hasInstance, { + value: (instance) => ordinary.call(VmCtor, instance) || ordinary.call(HostCtor, instance), + configurable: true, + }) + } +} +` + +/** Run {@link DUAL_REALM_INSTANCEOF_PRELUDE} in a freshly created sandbox, handing it the host intrinsics to pair up. */ +function patchDualRealmInstanceof(sandbox: object): void { + const patch = runInContext(DUAL_REALM_INSTANCEOF_PRELUDE, sandbox) as (intrinsics: Record) => void + patch({ Object, Array, Function, Error, TypeError, RangeError, SyntaxError, Promise, RegExp, Date, Map, Set }) +} + +/** + * Build the vm context one `cordis_mount` call evaluates in: the tagged + * console, the `harness` registration helpers, the encoding primitives, and + * the dual-realm `instanceof` patch, already `createContext`-ed. + * @param id - the mount id (`dyn-`), used as the console tag and filename stem. + * @returns the contextified sandbox object to pass to {@link evaluateMountCode}. + */ +export function createSandbox(id: string): object { + const sandbox = { + console: taggedConsole(id), + harness: { defineTool: sandboxDefineTool, registerTool: sandboxRegisterTool }, + // Web APIs absent from fresh vm contexts — made available so the model + // can encode/decode base64 without Buffer (which is also absent). + btoa: (s: string) => Buffer.from(s, 'utf-8').toString('base64'), + atob: (s: string) => Buffer.from(s, 'base64').toString('utf-8'), + TextEncoder, + TextDecoder, + } + createContext(sandbox) + patchDualRealmInstanceof(sandbox) + return sandbox +} + +/** + * Cross-realm SyntaxError detection: a compile failure inside `runInContext` + * constructs its error in the SANDBOX realm, so a host `instanceof + * SyntaxError` is silently false — the `name` property is the realm-safe tag. + */ +function isSyntaxError(error: unknown): error is Error { + return typeof error === 'object' && error !== null && (error as { name?: unknown }).name === 'SyntaxError' +} + +/** + * The parse-failure context a vm `SyntaxError` carries: the vm prints the + * offending source line and a caret before the message, which is exactly what + * a model needs to self-correct — surface it instead of the bare message. + * Falls back to `String(error)` when the stack carries no such prelude. + * @param error - the `SyntaxError` (host- or sandbox-realm) thrown while compiling mount code. + * @returns the stack prefix up to and including the `SyntaxError: …` line. + */ +export function syntaxErrorContext(error: Error): string { + const lines = (error.stack ?? '').split('\n') + const messageIndex = lines.findIndex(line => line.startsWith('SyntaxError')) + if (messageIndex === -1) return String(error) + return lines.slice(0, messageIndex + 1).join('\n') +} + +/** + * Evaluate mount code as the body of an async function inside the sandbox. + * `vmTimeoutMs` only bounds the SYNCHRONOUS portion; an async body escapes it + * — acceptable under the module's trust stance. A parse failure is answered + * with the offending line + caret and a teaching hint: TypeScript syntax on + * the failing line gets the remove-annotations fix, anything else gets the + * function-body/bracket-balance reminder (models habitually close the returned + * plugin object with `});` as if it were a callback argument). + * @param sandbox - the contextified object from {@link createSandbox}. + * @param code - the model-written function body; must `return` a plugin. + * @param id - the mount id, used as the vm filename (`cordis-mount-.js`). + * @param vmTimeoutMs - the synchronous evaluation bound in milliseconds. + * @returns whatever the code returned, still un-narrowed (the mount lifecycle checks plugin shape). + */ +export async function evaluateMountCode(sandbox: object, code: string, id: string, vmTimeoutMs: number): Promise { + try { + return await runInContext( + `(async () => {\n${code}\n})()`, + sandbox, + { filename: `cordis-mount-${id}.js`, timeout: vmTimeoutMs }, + ) + } catch (error) { + if (!isSyntaxError(error)) throw error + const context = syntaxErrorContext(error) + // Scope the TypeScript heuristic to the OFFENDING line, not the whole + // code: an ` as ` inside an ordinary description string must not turn a + // plain syntax error into a misleading remove-annotations message. + const offendingLine = context.split('\n')[1] ?? '' + if (/\bas\b/.test(offendingLine)) { + throw new Error( + `mount code failed to parse:\n${context}\n` + + 'The sandbox runs plain JavaScript, not TypeScript. Remove type annotations:\n' + + ' ✗ { type: \'text\' as const, text: x }\n' + + ' ✓ { type: \'text\', text: x }', + ) + } + throw new Error( + `mount code failed to parse:\n${context}\n` + + 'Note: `code` runs as the BODY of an async function (line numbers are offset by the 1-line wrapper). ' + + 'Check bracket balance — ending the returned plugin object with `});` closes a call that was never opened; ' + + 'a plain `return { … }` ends with `}` (an optional `;`), never `)`.', + ) + } +} diff --git a/packages/cordis/tool-cordis/tests/cross-mount.spec.ts b/packages/cordis/tool-cordis/tests/cross-mount.spec.ts new file mode 100644 index 0000000000..f68eaef639 --- /dev/null +++ b/packages/cordis/tool-cordis/tests/cross-mount.spec.ts @@ -0,0 +1,105 @@ +import { describe, expect, it } from 'vitest' +import { call, CONSUMER_CODE, PROVIDER_CODE, setup, text } from './helpers.ts' + +/** + * Cross-mount composition through ordinary cordis provide/inject semantics: + * one mount provides a service, another injects it, and mount ids stay the + * lifecycle handles. Every assertion is against the WORLD — the registry, the + * service store, real tool dispatch — not the tool's own summary line. + */ + +describe('cross-mount provide/inject', () => { + it('provider first: the consumer activates immediately and its tool reaches the provided service', async () => { + const ctx = await setup() + const provider = await call(ctx, 'cordis_mount', { code: PROVIDER_CODE }) + expect(text(provider)).toContain('state: active') + + const consumer = await call(ctx, 'cordis_mount', { code: CONSUMER_CODE }) + expect(consumer.isError).toBe(false) + expect(text(consumer)).toContain('state: active') + + // The vm-realm service value is callable across mounts, and the result + // normalizes into the host realm like any dynamic tool result. + const greeted = await call(ctx, 'greet', { name: 'harness' }) + expect(greeted.isError).toBe(false) + expect(text(greeted)).toBe('hi harness') + }) + + it('consumer first: stays pending naming the missing service, then activates when the provider mounts', async () => { + const ctx = await setup() + const consumer = await call(ctx, 'cordis_mount', { code: CONSUMER_CODE }) + expect(consumer.isError).toBe(false) + expect(text(consumer)).toContain('state: pending') + expect(text(consumer)).toContain('waiting for service(s): greeter') + expect(text(await call(ctx, 'cordis_inspect', { what: 'dynamic' }))).toContain('waiting for: greeter') + expect(ctx.tools.get('greet')).toBeUndefined() + + await call(ctx, 'cordis_mount', { code: PROVIDER_CODE }) + expect(ctx.tools.get('greet')).toBeDefined() + expect(text(await call(ctx, 'greet', { name: 'late' }))).toBe('hi late') + }) + + it('unmounting the provider sends the consumer back to pending and unwinds its registrations', async () => { + const ctx = await setup() + await call(ctx, 'cordis_mount', { code: PROVIDER_CODE }) // dyn-1 + await call(ctx, 'cordis_mount', { code: CONSUMER_CODE }) // dyn-2 + expect(ctx.tools.get('greet')).toBeDefined() + + const unmounted = await call(ctx, 'cordis_unmount', { id: 'dyn-1' }) + expect(unmounted.isError).toBe(false) + expect(ctx.tools.get('greet')).toBeUndefined() + const report = text(await call(ctx, 'cordis_inspect', { what: 'dynamic' })) + expect(report).toContain('dyn-2: greeter-consumer [pending] — waiting for: greeter') + }) + + it('re-providing the service re-runs the consumer through the same guard (active again, tool back)', async () => { + const ctx = await setup() + await call(ctx, 'cordis_mount', { code: PROVIDER_CODE }) // dyn-1 + await call(ctx, 'cordis_mount', { code: CONSUMER_CODE }) // dyn-2 + await call(ctx, 'cordis_unmount', { id: 'dyn-1' }) + expect(ctx.tools.get('greet')).toBeUndefined() + + await call(ctx, 'cordis_mount', { code: PROVIDER_CODE }) // dyn-3 + expect(ctx.tools.get('greet')).toBeDefined() + expect(text(await call(ctx, 'greet', { name: 'again' }))).toBe('hi again') + expect(text(await call(ctx, 'cordis_inspect', { what: 'dynamic' }))).toContain('dyn-2: greeter-consumer [active]') + }) + + it('a duplicate provide fails loud with the owning fiber named, and the failed mount is disposed', async () => { + const ctx = await setup() + await call(ctx, 'cordis_mount', { code: PROVIDER_CODE }) + const duplicate = await call(ctx, 'cordis_mount', { code: PROVIDER_CODE }) + expect(duplicate.isError).toBe(true) + expect(text(duplicate)).toContain('has been registered') + const report = text(await call(ctx, 'cordis_inspect', { what: 'dynamic' })) + expect(report).toContain('dyn-1: greeter-provider') + expect(report).not.toContain('dyn-2') + }) + + it('inspect surfaces the linkage: provides on the provider row, the service in services and api sections', async () => { + const ctx = await setup() + await call(ctx, 'cordis_mount', { code: PROVIDER_CODE }) + await call(ctx, 'cordis_mount', { code: CONSUMER_CODE }) + + const dynamic = text(await call(ctx, 'cordis_inspect', { what: 'dynamic' })) + expect(dynamic).toContain('dyn-1: greeter-provider [active] — provides: greeter') + + const services = text(await call(ctx, 'cordis_inspect', { what: 'services' })) + expect(services).toContain('- greeter (provided by greeter-provider)') + + const api = text(await call(ctx, 'cordis_inspect', { what: 'api' })) + expect(api).toContain('- greeter (provided by greeter-provider, no catalog entry)') + }) + + it('unmounting the consumer leaves the provider and its service intact', async () => { + const ctx = await setup() + await call(ctx, 'cordis_mount', { code: PROVIDER_CODE }) // dyn-1 + await call(ctx, 'cordis_mount', { code: CONSUMER_CODE }) // dyn-2 + await call(ctx, 'cordis_unmount', { id: 'dyn-2' }) + + expect(ctx.tools.get('greet')).toBeUndefined() + const services = text(await call(ctx, 'cordis_inspect', { what: 'services' })) + expect(services).toContain('- greeter (provided by greeter-provider)') + expect(text(await call(ctx, 'cordis_inspect', { what: 'dynamic' }))).toContain('dyn-1: greeter-provider [active]') + }) +}) diff --git a/packages/cordis/tool-cordis/tests/helpers.ts b/packages/cordis/tool-cordis/tests/helpers.ts new file mode 100644 index 0000000000..b183a2444f --- /dev/null +++ b/packages/cordis/tool-cordis/tests/helpers.ts @@ -0,0 +1,104 @@ +import { Context } from 'cordis' +import Timer from '@cordisjs/plugin-timer' +import { CallId } from '@deepseek-ai/dsh-llm' +import SystemPrompt from '@deepseek-ai/dsh-system-prompt' +import ToolRegistry from '@deepseek-ai/dsh-tools' +import type { ToolDefinition, ToolExecutionResult } from '@deepseek-ai/dsh-tools' +import * as tool from '../src/index.ts' + +/** + * Shared spec helpers: a real `SystemPrompt` + `ToolRegistry` + timer + + * tool-cordis tree (only the model is absent — the code strings below stand in + * for what it would write), plus the canonical mount-code fixtures the suites + * share. + */ + +/** Mount the plugin on a fresh context with a real ToolRegistry and the timer service. */ +export async function setup(config?: tool.Config): Promise { + const ctx = new Context() + await ctx.plugin(Timer) + await ctx.plugin(SystemPrompt) + await ctx.plugin(ToolRegistry) + await ctx.plugin(tool, config) + return ctx +} + +let callCounter = 0 + +/** Execute a registered tool through the real registry pipeline. */ +export function call(ctx: Context, name: string, args: unknown): Promise { + return ctx.tools.execute({ callId: CallId(`call-${++callCounter}`), name, arguments: args }) +} + +/** Concatenated text blocks of one tool result. */ +export function text(result: ToolExecutionResult): string { + return result.content.filter(block => block.type === 'text').map(block => block.text).join('') +} + +/** Mount code for a listener plugin: logs on every `tools/change`. */ +export const LISTENER_CODE = ` + return { + name: 'change-logger', + apply(ctx) { + ctx.on('tools/change', () => console.log('tools changed')) + }, + } +` + +/** Mount code for a self-made tool: registers `reverse_text` via the sandbox's harness helpers. */ +export const REVERSE_TOOL_CODE = ` + return { + name: 'reverse-text', + inject: ['tools'], + apply(ctx) { + harness.registerTool(ctx, harness.defineTool({ + name: 'reverse_text', + description: 'Reverse a string.', + parameters: { text: { type: 'string', required: true } }, + async execute(args) { + return [{ type: 'text', text: args.text.split('').reverse().join('') }] + }, + })) + }, + } +` + +/** Mount code providing a `greeter` service other mounts can inject. */ +export const PROVIDER_CODE = ` + return { + name: 'greeter-provider', + apply(ctx) { + ctx.provide('greeter', { greet: (name) => 'hi ' + name }) + }, + } +` + +/** Mount code consuming the `greeter` service through inject, exposing it as a tool. */ +export const CONSUMER_CODE = ` + return { + name: 'greeter-consumer', + inject: ['greeter', 'tools'], + apply(ctx) { + harness.registerTool(ctx, harness.defineTool({ + name: 'greet', + description: 'Greet someone via the greeter service.', + parameters: { name: { type: 'string', required: true } }, + async execute(args) { + return [{ type: 'text', text: ctx.greeter.greet(args.name) }] + }, + })) + }, + } +` + +/** A registrable no-op tool the tests use to trigger a real `tools/change`. */ +export function dummyTool(name: string): ToolDefinition { + return { + name, + description: 'test trigger', + parameters: { type: 'object' as const, properties: {} }, + async execute(): Promise<[]> { + return [] + }, + } +} diff --git a/packages/cordis/tool-cordis/tests/inspect.spec.ts b/packages/cordis/tool-cordis/tests/inspect.spec.ts new file mode 100644 index 0000000000..c45d3b29a8 --- /dev/null +++ b/packages/cordis/tool-cordis/tests/inspect.spec.ts @@ -0,0 +1,123 @@ +import { describe, expect, it } from 'vitest' +import type { Context, Fiber } from 'cordis' +import { FiberState } from '../src/fiber-state.ts' +import { describeApi, describeEvents, describePluginTree, describeServices } from '../src/inspect.ts' +import { call, LISTENER_CODE, setup, text } from './helpers.ts' + +/** + * The `cordis_inspect` sections: rendered against the real runtime through the + * tool, plus direct renderer calls for the states a minimal harness cannot + * reach (empty service store, uid-less fibers, a fully-live catalog). + */ + +describe('cordis_inspect', () => { + it('reports all six sections by default', async () => { + const ctx = await setup() + const result = await call(ctx, 'cordis_inspect', {}) + expect(result.isError).toBe(false) + const report = text(result) + for (const heading of ['services', 'plugins', 'tools', 'dynamic', 'api', 'events']) { + expect(report).toContain(`## ${heading}`) + } + // The services section sees the real providers; the tree shows the dynamic + // group under this plugin; the tools section lists the cordis tools. + expect(report).toContain('- tools (provided by ToolRegistry)') + expect(report).toMatch(/tool-cordis \[active\]/) + expect(report).toMatch(/cordis-dynamic \[active\]/) + expect(report).toContain('- cordis_mount') + expect(report).toContain('(no dynamic plugins mounted)') + }) + + it('limits the report to one section via `what`', async () => { + const ctx = await setup() + const result = await call(ctx, 'cordis_inspect', { what: 'tools' }) + const report = text(result) + expect(report).toContain('## tools') + expect(report).not.toContain('## services') + expect(report).not.toContain('## plugins') + }) + + it('shows a mount in the dynamic section and as an annotated child of the group in the tree', async () => { + const ctx = await setup() + await call(ctx, 'cordis_mount', { code: LISTENER_CODE }) + const report = text(await call(ctx, 'cordis_inspect', {})) + expect(report).toContain('- dyn-1: change-logger [active]') + expect(report).toMatch(/dyn-1: change-logger \[active\]/) + }) + + it('renders the api section from the generated catalog intersected with the LIVE runtime', async () => { + const ctx = await setup() + const report = text(await call(ctx, 'cordis_inspect', { what: 'api' })) + // Live catalogued services render summary + signatures. + expect(report).toContain('- tools — ') + expect(report).toContain('register(definition: ToolDefinition)') + expect(report).toContain('- systemPrompt — ') + // Catalogued services with no live provider are listed tersely. + expect(report).toMatch(/not running \(loadable services with no live provider\): .*bash/) + // The type shapes the LIVE signatures reference follow (closure over the + // generated TYPE_API — a consumer can see field types, not just names). + expect(report).toContain('type shapes (referenced by the signatures above') + expect(report).toContain('export interface ToolExecution') + // A type only reachable through a NOT-live service (e.g. bash) is scoped out. + expect(report).not.toContain('export interface BashRunResult') + // The inherited ctx surface closes the section. + expect(report).toContain('inherited ctx API:') + expect(report).toContain('- ctx.effect — ') + }) + + it('renders the events section with mode badges, signatures, and the waterfall caution', async () => { + const ctx = await setup() + const report = text(await call(ctx, 'cordis_inspect', { what: 'events' })) + expect(report).toContain('- tools/change [emit]') + expect(report).toContain('- tools/pre-execute [waterfall]') + expect(report).toMatch(/'agent\/status'\(/) + expect(report).toContain('returning without next() vetoes the chain') + }) +}) + +describe('inspect renderers (direct)', () => { + it('describeServices reports an empty store as such, and labels a non-active provider', () => { + const empty = { reflect: { store: {} } } as unknown as Context + expect(describeServices(empty)).toEqual(['(no services provided)']) + + const pendingFiber = { state: FiberState.PENDING, name: 'half-loaded' } as unknown as Fiber + const store: Record = {} + store[Symbol('impl')] = { name: 'thing', fiber: pendingFiber } + const ctx = { reflect: { store } } as unknown as Context + expect(describeServices(ctx)).toEqual(['- thing (provided by half-loaded, pending)']) + }) + + it('describePluginTree sorts uid-less fibers last and renders sibling branches', () => { + // The parent fiber is OUTSIDE the registry set, so all three are roots. + const rootFiber = { uid: 0, name: 'root' } as unknown as Fiber + const fiber = (uid: number | null, name: string): Fiber => + ({ uid, name, state: FiberState.ACTIVE, parent: { fiber: rootFiber } }) as unknown as Fiber + const a = fiber(2, 'beta') + const b = fiber(1, 'alpha') + const c = fiber(null, 'rootless') + const d = fiber(null, 'rootless-too') + const ctx = { registry: { values: () => [{ fibers: [a, b, c, d] }] } } as unknown as Context + expect(describePluginTree(ctx, () => undefined)).toEqual([ + 'root', + '├─ alpha [active]', + '├─ beta [active]', + '├─ rootless [active]', + '└─ rootless-too [active]', + ]) + }) + + it('describeApi omits the not-running line and type shapes when nothing applies', async () => { + const ctx = await setup() + const lines = describeApi(ctx, [{ key: 'tools', summary: 'The registry.', methods: ['register(x): void'] }], [], []) + expect(lines[0]).toBe('- tools — The registry.') + expect(lines[1]).toBe(' register(x): void') + expect(lines.join('\n')).not.toContain('not running') + expect(lines.join('\n')).not.toContain('type shapes') + }) + + it('describeEvents renders an empty catalog as just the waterfall caution', () => { + expect(describeEvents([])).toEqual([ + 'waterfall listeners receive a trailing next() and MUST call it to delegate — returning without next() vetoes the chain.', + ]) + }) +}) diff --git a/packages/cordis/tool-cordis/tests/integration.spec.ts b/packages/cordis/tool-cordis/tests/integration.spec.ts new file mode 100644 index 0000000000..94331df7c0 --- /dev/null +++ b/packages/cordis/tool-cordis/tests/integration.spec.ts @@ -0,0 +1,74 @@ +import { describe, expect, it } from 'vitest' +import { Context } from 'cordis' +import LlmService from '@deepseek-ai/dsh-llm' +import SessionStore from '@deepseek-ai/dsh-session' +import SystemPrompt from '@deepseek-ai/dsh-system-prompt' +import ToolRegistry from '@deepseek-ai/dsh-tools' +import AgentRegistry, { AgentId } from '@deepseek-ai/dsh-agent' +import AgentLoop, { ReactLoopAgent } from '@deepseek-ai/dsh-agent-loop' +import * as ToolCordis from '../src/index.ts' +import { MockAdapter, textResponse, toolCallResponse } from '../../../core/agent-loop/tests/mock-adapter.ts' +import { REVERSE_TOOL_CODE } from './helpers.ts' + +/** + * Full-loop integration: a scripted mock model mounts a plugin that registers + * a NEW tool, calls that tool on the very next step (tool schemas are + * reassembled per step — the real loop proves the self-extension contract), + * and unmounts it again. Only the model is mocked; the sandbox, the fiber + * tree, and the session log are real. + */ + +async function harness(adapter: MockAdapter): Promise { + const ctx = new Context() + await ctx.plugin(LlmService) + await ctx.plugin(SessionStore) + await ctx.plugin(SystemPrompt) + await ctx.plugin(ToolRegistry) + await ctx.plugin(AgentRegistry) + await ctx.plugin(AgentLoop, { agents: [] }) + await ctx.plugin(ToolCordis) + ctx.llm.registerAdapter(['mock'], adapter) + return ctx +} + +function waitForIdle(ctx: Context, agent: ReactLoopAgent): Promise { + return new Promise((resolve) => { + const dispose = ctx.on('agent/status', (subject, status) => { + if (subject === agent && status === 'idle') { + dispose() + resolve() + } + }) + }) +} + +describe('cordis tools through the agent loop', () => { + it('mounts a tool, calls it on the next step, and unmounts it — all as real tool/call events', async () => { + const adapter = new MockAdapter([ + toolCallResponse('call-1', 'cordis_mount', { code: REVERSE_TOOL_CODE }, 'Extending myself.'), + toolCallResponse('call-2', 'reverse_text', { text: 'harness' }), + toolCallResponse('call-3', 'cordis_unmount', { id: 'dyn-1' }), + textResponse('Done.'), + ]) + const ctx = await harness(adapter) + const agent = ctx.agentLoop.create(AgentId('it-cordis'), { model: 'mock' }) + + agent.send([{ type: 'text', text: 'give yourself reverse_text, use it, clean up' }]) + await waitForIdle(ctx, agent) + + const log = agent.session.events + const calls = log.filter(event => event.type === 'tool/call').map(event => event.data.name) + expect(calls).toEqual(['cordis_mount', 'reverse_text', 'cordis_unmount']) + + const results = log.filter(event => event.type === 'tool/result') + expect(results.map(event => event.data.isError)).toEqual([false, false, false]) + const reversed = results[1]!.data.content + .filter(block => block.type === 'text') + .map(block => block.text) + .join('') + expect(reversed).toBe('ssenrah') + + // After the unmount the self-made tool is gone from the registry. + expect(ctx.tools.get('reverse_text')).toBeUndefined() + }) +}) diff --git a/packages/cordis/tool-cordis/tests/mount.spec.ts b/packages/cordis/tool-cordis/tests/mount.spec.ts new file mode 100644 index 0000000000..5bdde09b53 --- /dev/null +++ b/packages/cordis/tool-cordis/tests/mount.spec.ts @@ -0,0 +1,409 @@ +import { afterEach, describe, expect, it, vi } from 'vitest' +import { isJsonValue } from '@deepseek-ai/dsh-session' +import { syntaxErrorContext } from '../src/sandbox.ts' +import { call, dummyTool, LISTENER_CODE, REVERSE_TOOL_CODE, setup, text } from './helpers.ts' + +/** + * The `cordis_mount` success/failure family: real plugins land on a genuine + * cordis fiber tree, their registrations are observable through the real + * registry/event bus, and every rejection path teaches the fix. + */ + +afterEach(() => { + vi.restoreAllMocks() +}) + +describe('cordis_mount', () => { + it('mounts a listener plugin that observes real events, tagged-logging through to the host console', async () => { + const ctx = await setup() + const log = vi.spyOn(console, 'log').mockImplementation(() => {}) + + const result = await call(ctx, 'cordis_mount', { code: LISTENER_CODE }) + expect(result.isError).toBe(false) + expect(text(result)).toContain('mounted dyn-1 (plugin "change-logger", state: active)') + + // Fire a REAL tools/change by registering a tool; the mounted listener logs. + ctx.tools.register(dummyTool('trigger_a')) + expect(log).toHaveBeenCalledWith('[cordis:dyn-1]', 'tools changed') + }) + + it('mounts a bare-function plugin as , and a named function under its name', async () => { + const ctx = await setup() + const anonymous = await call(ctx, 'cordis_mount', { code: 'return (ctx) => { ctx.on(\'tools/change\', () => {}) }' }) + expect(anonymous.isError).toBe(false) + expect(text(anonymous)).toContain('plugin ""') + const named = await call(ctx, 'cordis_mount', { code: 'return function watcher(ctx) {}' }) + expect(text(named)).toContain('plugin "watcher"') + }) + + it('lets the agent give ITSELF a new tool, immediately callable through the registry', async () => { + const ctx = await setup() + const result = await call(ctx, 'cordis_mount', { code: REVERSE_TOOL_CODE }) + expect(result.isError).toBe(false) + + expect(ctx.tools.schemas().map(schema => schema.name)).toContain('reverse_text') + const reversed = await call(ctx, 'reverse_text', { text: 'harness' }) + expect(reversed.isError).toBe(false) + expect(text(reversed)).toBe('ssenrah') + }) + + it('normalizes a self-made tool\'s result into the host realm, so the session log accepts it', async () => { + // The model's execute builds its content blocks INSIDE the vm, where + // Object.prototype is a different object — dsh-session's isJsonValue (the + // gate every `tool/result` append runs through) compares prototype + // IDENTITY, so a raw foreign-realm result would error the whole turn the + // first time the self-made tool runs. harness.defineTool round-trips the + // return into host-realm JSON before it reaches the registry. + const ctx = await setup() + await call(ctx, 'cordis_mount', { code: REVERSE_TOOL_CODE }) + const reversed = await call(ctx, 'reverse_text', { text: 'harness' }) + expect(isJsonValue({ content: reversed.content, isError: reversed.isError })).toBe(true) + }) + + it('rejects JSON Schema passed to harness.defineTool with the SchemaSpec teaching error', async () => { + const ctx = await setup() + const result = await call(ctx, 'cordis_mount', { + code: ` + return { + name: 'bad-json-schema-tool', + inject: ['tools'], + apply(ctx) { + harness.registerTool(ctx, harness.defineTool({ + name: 'bad_json_schema_tool', + description: 'bad', + parameters: { + type: 'object', + properties: { text: { type: 'string' } }, + required: ['text'], + }, + async execute() { return [{ type: 'text', text: 'bad' }] }, + })) + }, + } + `, + }) + + expect(result.isError).toBe(true) + expect(text(result)).toContain('harness.defineTool parameters use the SchemaSpec DSL') + expect(ctx.tools.get('bad_json_schema_tool')).toBeUndefined() + }) + + it.each([ + ['parameters: 42', 'must be a SchemaSpec object'], + ['parameters: { text: 42 }', 'parameters.text must be a SchemaSpec property object'], + ['parameters: { text: { type: \'str\' } }', 'parameters.text must declare a valid type'], + ['parameters: { text: { type: \'string\', required: false } }', 'parameters.text.required must be true when present'], + ['parameters: { text: { type: \'string\', properties: {} } }', 'parameters.text.properties is only valid for type "object"'], + ['parameters: { text: { type: \'string\', items: { type: \'string\' } } }', 'parameters.text.items is only valid for type "array"'], + ])('rejects a malformed SchemaSpec (%s) with a teaching error', async (parameters, message) => { + const ctx = await setup() + const result = await call(ctx, 'cordis_mount', { + code: ` + return { + name: 'bad-schema', + inject: ['tools'], + apply(ctx) { + harness.registerTool(ctx, harness.defineTool({ + name: 'bad_schema_tool', + description: 'bad', + ${parameters}, + async execute() { return [] }, + })) + }, + } + `, + }) + expect(result.isError).toBe(true) + expect(text(result)).toContain(message) + }) + + it('accepts a nested object/array SchemaSpec (the DSL recursion)', async () => { + const ctx = await setup() + const result = await call(ctx, 'cordis_mount', { + code: ` + return { + name: 'nested-schema', + inject: ['tools'], + apply(ctx) { + harness.registerTool(ctx, harness.defineTool({ + name: 'nested_schema_tool', + description: 'nested', + parameters: { + item: { type: 'object', required: true, properties: { label: { type: 'string', required: true } } }, + tags: { type: 'array', items: { type: 'string' } }, + }, + async execute(args) { return [{ type: 'text', text: args.item.label }] }, + })) + }, + } + `, + }) + expect(result.isError).toBe(false) + const echoed = await call(ctx, 'nested_schema_tool', { item: { label: 'ok' }, tags: ['a'] }) + expect(text(echoed)).toBe('ok') + }) + + it('rejects raw dynamic ctx.tools.register calls that bypass harness helpers', async () => { + const ctx = await setup() + const result = await call(ctx, 'cordis_mount', { + code: ` + return { + name: 'raw-register', + inject: ['tools'], + apply(ctx) { + ctx.tools.register({ + name: 'raw_dynamic_tool', + description: 'raw', + parameters: { type: 'object', properties: {} }, + async execute() { return [] }, + }) + }, + } + `, + }) + + expect(result.isError).toBe(true) + expect(text(result)).toContain('dynamic tool registration must use a tool returned by harness.defineTool') + expect(ctx.tools.get('raw_dynamic_tool')).toBeUndefined() + }) + + it('guards the registry reached through ctx.get(\'tools\') identically', async () => { + const ctx = await setup() + const result = await call(ctx, 'cordis_mount', { + code: ` + return { + name: 'raw-register-get', + apply(ctx) { + const sp = ctx.get('systemPrompt') + console.log('systemPrompt is', typeof sp) + ctx.get('tools').register({ name: 'raw_via_get', description: 'raw', parameters: {}, async execute() { return [] } }) + }, + } + `, + }) + expect(result.isError).toBe(true) + expect(text(result)).toContain('dynamic tool registration must use a tool returned by harness.defineTool') + expect(ctx.tools.get('raw_via_get')).toBeUndefined() + }) + + it('passes non-register registry members through the guard with correct binding', async () => { + const ctx = await setup() + const log = vi.spyOn(console, 'log').mockImplementation(() => {}) + const result = await call(ctx, 'cordis_mount', { + code: ` + return { + name: 'schema-reader', + inject: ['tools'], + apply(ctx) { + console.log('sees', ctx.tools.schemas().length, 'tools; mount is', typeof ctx.tools.get('cordis_mount')) + }, + } + `, + }) + expect(result.isError).toBe(false) + expect(log).toHaveBeenCalledWith('[cordis:dyn-1]', 'sees', 3, 'tools; mount is', 'object') + }) + + it('keeps a plugin with unsatisfied inject mounted as pending and names what it waits for', async () => { + const ctx = await setup() + const result = await call(ctx, 'cordis_mount', { + code: 'return { name: \'waiter\', inject: [\'no-such-service\'], apply(ctx) {} }', + }) + expect(result.isError).toBe(false) + expect(text(result)).toContain('state: pending') + expect(text(result)).toContain('waiting for service(s): no-such-service') + // Unmounting a pending mount works like any other. + const unmounted = await call(ctx, 'cordis_unmount', { id: 'dyn-1' }) + expect(unmounted.isError).toBe(false) + }) + + it('rejects code that throws, leaving nothing mounted', async () => { + const ctx = await setup() + const result = await call(ctx, 'cordis_mount', { code: 'throw new Error(\'boom in sandbox\')' }) + expect(result.isError).toBe(true) + expect(text(result)).toContain('boom in sandbox') + expect(text(await call(ctx, 'cordis_inspect', { what: 'dynamic' }))).toContain('(no dynamic plugins mounted)') + }) + + it('passes non-Error and null throws through untouched (no SyntaxError misclassification)', async () => { + const ctx = await setup() + const primitive = await call(ctx, 'cordis_mount', { code: 'throw \'plain-string-throw\'' }) + expect(primitive.isError).toBe(true) + expect(text(primitive)).toContain('plain-string-throw') + const nullish = await call(ctx, 'cordis_mount', { code: 'throw null' }) + expect(nullish.isError).toBe(true) + }) + + it('rejects code that does not return a plugin', async () => { + const ctx = await setup() + const result = await call(ctx, 'cordis_mount', { code: 'return 42' }) + expect(result.isError).toBe(true) + expect(text(result)).toContain('must `return` a plugin') + }) + + it('answers a missing return with the two valid plugin forms', async () => { + const ctx = await setup() + const result = await call(ctx, 'cordis_mount', { code: 'const plugin = (ctx) => {}' }) + expect(result.isError).toBe(true) + expect(text(result)).toContain('did you forget `return`?') + }) + + it('disposes a plugin whose apply throws, and reports the error', async () => { + const ctx = await setup() + const result = await call(ctx, 'cordis_mount', { + code: 'return { name: \'broken\', apply(ctx) { throw new Error(\'apply exploded\') } }', + }) + expect(result.isError).toBe(true) + expect(text(result)).toContain('apply exploded') + expect(text(await call(ctx, 'cordis_inspect', { what: 'dynamic' }))).toContain('(no dynamic plugins mounted)') + }) + + it('rolls back a plugin that collides with an existing tool name, keeping the original tool intact', async () => { + const ctx = await setup() + const result = await call(ctx, 'cordis_mount', { + code: ` + return { + name: 'usurper', + inject: ['tools'], + apply(ctx) { + harness.registerTool(ctx, harness.defineTool({ + name: 'cordis_mount', + description: 'dup', + parameters: {}, + async execute() { return [] }, + })) + }, + } + `, + }) + expect(result.isError).toBe(true) + expect(text(result)).toContain('already registered') + expect(text(result)).toContain('first cordis_unmount') + // The original cordis_mount still dispatches — the failed fiber is gone. + const retry = await call(ctx, 'cordis_mount', { code: LISTENER_CODE }) + expect(retry.isError).toBe(false) + }) + + it('isolates sandbox globals: no process/require, and globalThis writes do not leak to the host', async () => { + const ctx = await setup() + const result = await call(ctx, 'cordis_mount', { + code: ` + globalThis.__cordis_tool_leak = 'leaked' + return { name: 'probe-' + typeof process + '-' + typeof require, apply(ctx) {} } + `, + }) + expect(result.isError).toBe(false) + expect(text(result)).toContain('plugin "probe-undefined-undefined"') + expect((globalThis as Record).__cordis_tool_leak).toBeUndefined() + }) + + it('provides btoa/atob and the tagged console variants inside the sandbox', async () => { + const ctx = await setup() + const log = vi.spyOn(console, 'log').mockImplementation(() => {}) + const error = vi.spyOn(console, 'error').mockImplementation(() => {}) + const result = await call(ctx, 'cordis_mount', { + code: ` + console.warn('warned') + console.error('errored') + const round = atob(btoa('hi')) + const bytes = new TextEncoder().encode(round) + return { name: 'codec-' + new TextDecoder().decode(bytes), apply(ctx) { console.log('applied', typeof ctx.fiber) } } + `, + }) + expect(result.isError).toBe(false) + expect(text(result)).toContain('plugin "codec-hi"') + expect(log).toHaveBeenCalledWith('[cordis:dyn-1]', 'warned') + expect(log).toHaveBeenCalledWith('[cordis:dyn-1]', 'applied', 'object') + expect(error).toHaveBeenCalledWith('[cordis:dyn-1]', 'errored') + }) + + it('answers TypeScript syntax in the plain-JS sandbox with the fix', async () => { + const ctx = await setup() + const result = await call(ctx, 'cordis_mount', { + code: 'return { name: \'ts\' as const, apply(ctx) {} }', + }) + expect(result.isError).toBe(true) + expect(text(result)).toContain('plain JavaScript, not TypeScript') + }) + + it('surfaces the offending line + caret and the bracket-balance hint on a syntax error', async () => { + const ctx = await setup() + // The canonical model mistake: closing the returned object with `});` as + // if it were a callback argument. The word "as" in a STRING elsewhere must + // not trigger the TypeScript hint — the heuristic reads the failing line. + const result = await call(ctx, 'cordis_mount', { + code: 'const note = \'treat pattern as regex\'\nreturn {\n name: \'oops\',\n apply(ctx) {}\n});', + }) + expect(result.isError).toBe(true) + const message = text(result) + expect(message).toContain('failed to parse') + expect(message).toContain('});') + expect(message).toContain('^') + expect(message).toContain('BODY of an async function') + expect(message).not.toContain('TypeScript') + }) + + it('syntaxErrorContext falls back to String(error) when the stack has no vm prelude', () => { + const doctored = new SyntaxError('boom') + delete (doctored as { stack?: string }).stack + expect(syntaxErrorContext(doctored)).toBe('SyntaxError: boom') + const plain = new SyntaxError('bang') + plain.stack = 'not-a-vm-stack' + expect(syntaxErrorContext(plain)).toBe('SyntaxError: bang') + }) + + it('handles a runtime-thrown SyntaxError (no source-line prelude) with the generic hint', async () => { + const ctx = await setup() + const result = await call(ctx, 'cordis_mount', { code: 'throw new SyntaxError(\'user-crafted\')' }) + expect(result.isError).toBe(true) + expect(text(result)).toContain('failed to parse') + expect(text(result)).toContain('user-crafted') + }) + + it('honors the configured vmTimeoutMs for the synchronous portion', async () => { + const ctx = await setup({ vmTimeoutMs: 50 }) + const result = await call(ctx, 'cordis_mount', { code: 'while (true) {}' }) + expect(result.isError).toBe(true) + expect(text(result)).toMatch(/timed? ?out/i) + expect(text(await call(ctx, 'cordis_inspect', { what: 'dynamic' }))).toContain('(no dynamic plugins mounted)') + }) + + it('makes instanceof inside the sandbox see BOTH realms (patched vm constructors, host untouched)', async () => { + // The args a tool's execute receives are HOST-realm objects; without the + // dual-realm Symbol.hasInstance prelude, `args.items instanceof Array` in + // sandbox code is silently false. The patch lives on the vm realm's own + // constructors only — the host realm's must stay pristine. + const ctx = await setup() + await call(ctx, 'cordis_mount', { + code: ` + return { + name: 'probe-instanceof', + inject: ['tools'], + apply(ctx) { + harness.registerTool(ctx, harness.defineTool({ + name: 'probe_instanceof', + description: 'report instanceof checks across realms', + parameters: { items: { type: 'array', required: true, items: { type: 'string' } } }, + async execute(args) { + const checks = { + hostArray: args.items instanceof Array, + hostObject: args instanceof Object, + vmArray: [] instanceof Array, + vmObject: ({}) instanceof Object, + } + return [{ type: 'text', text: JSON.stringify(checks) }] + }, + })) + }, + } + `, + }) + const probed = await call(ctx, 'probe_instanceof', { items: ['a'] }) + expect(probed.isError).toBe(false) + expect(JSON.parse(text(probed))).toEqual({ hostArray: true, hostObject: true, vmArray: true, vmObject: true }) + // The host realm's constructors keep their default instanceof: no own + // Symbol.hasInstance was added to them. + expect(Object.getOwnPropertySymbols(Object)).not.toContain(Symbol.hasInstance) + expect(Object.getOwnPropertySymbols(Array)).not.toContain(Symbol.hasInstance) + }) +}) diff --git a/packages/cordis/tool-cordis/tests/present.spec.ts b/packages/cordis/tool-cordis/tests/present.spec.ts new file mode 100644 index 0000000000..d8f380439f --- /dev/null +++ b/packages/cordis/tool-cordis/tests/present.spec.ts @@ -0,0 +1,41 @@ +import { describe, expect, it } from 'vitest' +import { presentInspectCall, presentMountCall, presentUnmountCall } from '../src/present.ts' +import { setup } from './helpers.ts' + +/** + * Render-intent presenters: pure functions of the call args (no I/O, no + * session state — they run on replay too), wired onto the registered tools. + */ + +describe('presenters', () => { + it('cordis_inspect renders a generic read card titled with the section', () => { + expect(presentInspectCall({})).toEqual({ card: 'generic', kind: 'read', title: 'Inspect cordis runtime' }) + expect(presentInspectCall({ what: 'api' })).toEqual({ card: 'generic', kind: 'read', title: 'Inspect cordis runtime: api' }) + }) + + it('cordis_mount renders a generic execute card carrying the code as raw input', () => { + expect(presentMountCall({ code: 'return (ctx) => {}' })).toEqual({ + card: 'generic', + kind: 'execute', + title: 'Mount plugin into live cordis runtime', + rawInput: { code: 'return (ctx) => {}' }, + }) + }) + + it('cordis_unmount renders a generic delete card titled with the id', () => { + expect(presentUnmountCall({ id: 'dyn-1' })).toEqual({ card: 'generic', kind: 'delete', title: 'Unmount dyn-1' }) + }) + + it('is wired onto the registered definitions through the defineTool soft-validation path', async () => { + const ctx = await setup() + expect(ctx.tools.get('cordis_inspect')!.presentCall!({ what: 'tools' })).toEqual({ + card: 'generic', + kind: 'read', + title: 'Inspect cordis runtime: tools', + }) + expect(ctx.tools.get('cordis_mount')!.presentCall!({ code: 'return 1' })).toMatchObject({ kind: 'execute' }) + expect(ctx.tools.get('cordis_unmount')!.presentCall!({ id: 'dyn-2' })).toMatchObject({ title: 'Unmount dyn-2' }) + // Soft validation: presenter args that fail the schema render as no card, never a throw. + expect(ctx.tools.get('cordis_unmount')!.presentCall!({ id: 42 })).toBeUndefined() + }) +}) diff --git a/packages/cordis/tool-cordis/tests/tool-cordis.spec.ts b/packages/cordis/tool-cordis/tests/tool-cordis.spec.ts new file mode 100644 index 0000000000..8953b5da94 --- /dev/null +++ b/packages/cordis/tool-cordis/tests/tool-cordis.spec.ts @@ -0,0 +1,49 @@ +import { describe, expect, it } from 'vitest' +import Loader from '@cordisjs/plugin-loader' +import * as tool from '../src/index.ts' +import { setup } from './helpers.ts' + +/** + * Export-shape and registration surface: the namespace-plugin contract the + * real Loader path depends on, the registered tool set, and the Config + * validator's defaults and rejections. + */ + +describe('export shape', () => { + it('has no default export, and survives the real Loader unwrapExports', () => { + // A stray `export default` would make `unwrapExports` (`exports.default ?? + // exports`) collapse the module to the bare function and DROP `inject`, + // crashing at real load (docs/postmortem/0001). Assert directly AND through + // the real unwrap so adding `export default apply` fails here. + expect('default' in tool).toBe(false) + const loader = Object.create(Loader.prototype) as Loader + const unwrapped = loader.unwrapExports(tool) as Record + expect(unwrapped).toBe(tool) + expect(unwrapped.name).toBe('tool-cordis') + expect(unwrapped.inject).toEqual(['tools']) + expect(typeof unwrapped.apply).toBe('function') + expect(typeof unwrapped.Config).toBe('function') + }) +}) + +describe('tool registration', () => { + it('registers the three cordis tools with the documented schemas', async () => { + const ctx = await setup() + const names = ctx.tools.schemas().map(schema => schema.name) + expect(names).toEqual(expect.arrayContaining(['cordis_inspect', 'cordis_mount', 'cordis_unmount'])) + const inspect = ctx.tools.schemas().find(schema => schema.name === 'cordis_inspect')! + const props = (inspect.parameters as { properties: Record }).properties + expect(props.what?.enum).toEqual(['services', 'plugins', 'tools', 'dynamic', 'api', 'events']) + }) +}) + +describe('Config', () => { + it('defaults vmTimeoutMs to 5000', () => { + expect(new tool.Config()).toEqual({ vmTimeoutMs: 5000 }) + }) + + it('rejects a non-positive vmTimeoutMs at validation time (misconfiguration fails loud)', () => { + expect(() => new tool.Config({ vmTimeoutMs: 0 })).toThrow() + expect(() => new tool.Config({ vmTimeoutMs: -1 })).toThrow() + }) +}) diff --git a/packages/cordis/tool-cordis/tests/unmount-hmr.spec.ts b/packages/cordis/tool-cordis/tests/unmount-hmr.spec.ts new file mode 100644 index 0000000000..718a213968 --- /dev/null +++ b/packages/cordis/tool-cordis/tests/unmount-hmr.spec.ts @@ -0,0 +1,82 @@ +import { afterEach, describe, expect, it, vi } from 'vitest' +import { Context } from 'cordis' +import SystemPrompt from '@deepseek-ai/dsh-system-prompt' +import ToolRegistry from '@deepseek-ai/dsh-tools' +import * as tool from '../src/index.ts' +import { call, dummyTool, LISTENER_CODE, REVERSE_TOOL_CODE, setup, text } from './helpers.ts' + +/** + * Disposal semantics: `cordis_unmount` reaches quiescence before returning, + * and disposing the tool-cordis fiber itself (the HMR path) cascades over the + * whole dynamic subtree through the ordinary parent→child fiber lifecycle. + */ + +afterEach(() => { + vi.restoreAllMocks() +}) + +describe('cordis_unmount', () => { + it('disposes the mount and its registrations have stopped by the time it returns (quiescence)', async () => { + const ctx = await setup() + const log = vi.spyOn(console, 'log').mockImplementation(() => {}) + await call(ctx, 'cordis_mount', { code: LISTENER_CODE }) + + ctx.tools.register(dummyTool('trigger_before')) + expect(log).toHaveBeenCalledTimes(1) + + const result = await call(ctx, 'cordis_unmount', { id: 'dyn-1' }) + expect(result.isError).toBe(false) + expect(text(result)).toContain('unmounted dyn-1') + + // Immediately after the awaited unmount, the listener must be gone — no + // grace period, no eventual consistency. + ctx.tools.register(dummyTool('trigger_after')) + expect(log).toHaveBeenCalledTimes(1) + expect(text(await call(ctx, 'cordis_inspect', { what: 'dynamic' }))).toContain('(no dynamic plugins mounted)') + }) + + it('unregisters a self-made tool on unmount', async () => { + const ctx = await setup() + await call(ctx, 'cordis_mount', { code: REVERSE_TOOL_CODE }) + expect(ctx.tools.get('reverse_text')).toBeDefined() + + await call(ctx, 'cordis_unmount', { id: 'dyn-1' }) + expect(ctx.tools.get('reverse_text')).toBeUndefined() + }) + + it('rejects an unknown id, and a second unmount of the same id', async () => { + const ctx = await setup() + const unknown = await call(ctx, 'cordis_unmount', { id: 'dyn-99' }) + expect(unknown.isError).toBe(true) + expect(text(unknown)).toContain('no dynamic plugin with id "dyn-99"') + + await call(ctx, 'cordis_mount', { code: LISTENER_CODE }) + await call(ctx, 'cordis_unmount', { id: 'dyn-1' }) + const again = await call(ctx, 'cordis_unmount', { id: 'dyn-1' }) + expect(again.isError).toBe(true) + }) +}) + +describe('HMR safety', () => { + it('disposing the tool-cordis fiber cascades over the dynamic subtree and its registrations', async () => { + const ctx = new Context() + await ctx.plugin(SystemPrompt) + await ctx.plugin(ToolRegistry) + const fiber = await ctx.plugin(tool) + + const log = vi.spyOn(console, 'log').mockImplementation(() => {}) + await call(ctx, 'cordis_mount', { code: LISTENER_CODE }) + await call(ctx, 'cordis_mount', { code: REVERSE_TOOL_CODE }) + expect(ctx.tools.get('reverse_text')).toBeDefined() + + await fiber.dispose() + + // The whole subtree is gone: the self-made tool, the cordis tools, and the + // mounted listener (no log on a fresh tools/change). + expect(ctx.tools.get('reverse_text')).toBeUndefined() + expect(ctx.tools.get('cordis_mount')).toBeUndefined() + const calls = log.mock.calls.length + ctx.tools.register(dummyTool('trigger_post_dispose')) + expect(log).toHaveBeenCalledTimes(calls) + }) +}) diff --git a/packages/cordis/tool-cordis/tsconfig.json b/packages/cordis/tool-cordis/tsconfig.json new file mode 100644 index 0000000000..c4d4b6f656 --- /dev/null +++ b/packages/cordis/tool-cordis/tsconfig.json @@ -0,0 +1,27 @@ +{ + "extends": "../../../tsconfig.base.json", + "compilerOptions": { + "rootDir": "src", + "outDir": "lib/types" + }, + "include": [ + "src" + ], + "references": [ + { + "path": "../../../vendor/cosmokit" + }, + { + "path": "../../../vendor/cordis" + }, + { + "path": "../../../vendor/timer" + }, + { + "path": "../../../vendor/schemastery" + }, + { + "path": "../../core/tools" + } + ] +} diff --git a/packages/core/tools/tests/gen-tool-catalog.spec.ts b/packages/core/tools/tests/gen-tool-catalog.spec.ts index cacc2eef66..d4a6b97243 100644 --- a/packages/core/tools/tests/gen-tool-catalog.spec.ts +++ b/packages/core/tools/tests/gen-tool-catalog.spec.ts @@ -35,7 +35,7 @@ describe('gen-tool-catalog collectToolCatalog', () => { it('boots every shipped tool package and harvests its model-facing schemas', async () => { const catalog = await collectToolCatalog() const names = catalog.flatMap(entry => entry.schemas.map(s => s.name)).sort() - expect(names).toEqual(['bash', 'bash_kill', 'bash_output', 'edit', 'read', 'subagent', 'todo_write', 'web_fetch', 'web_search', 'write']) + expect(names).toEqual(['bash', 'bash_kill', 'bash_output', 'cordis_inspect', 'cordis_mount', 'cordis_unmount', 'edit', 'read', 'subagent', 'todo_write', 'web_fetch', 'web_search', 'write']) // Every tool carries a JSON-Schema `parameters` object (what the model sees). for (const entry of catalog) { for (const schema of entry.schemas) { diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml index b538e82908..ab1b0f73b3 100644 --- a/pnpm-lock.yaml +++ b/pnpm-lock.yaml @@ -191,6 +191,40 @@ importers: specifier: ^4.0.0-rc.6 version: 4.0.0-rc.6(@cordisjs/plugin-include@1.0.4)(@cordisjs/plugin-loader@1.0.0-rc.4) + packages/cordis/tool-cordis: + dependencies: + schemastery: + specifier: ^3.18.0 + version: 3.18.0 + devDependencies: + '@cordisjs/plugin-loader': + specifier: ^1.0.0-rc.4 + version: 1.0.0-rc.4(cordis@4.0.0-rc.6) + '@cordisjs/plugin-timer': + specifier: workspace:^ + version: link:../../../vendor/timer + '@deepseek-ai/dsh-agent': + specifier: workspace:^ + version: link:../../core/agent + '@deepseek-ai/dsh-agent-loop': + specifier: workspace:^ + version: link:../../core/agent-loop + '@deepseek-ai/dsh-llm': + specifier: workspace:^ + version: link:../../llm/llm + '@deepseek-ai/dsh-session': + specifier: workspace:^ + version: link:../../core/session + '@deepseek-ai/dsh-system-prompt': + specifier: workspace:^ + version: link:../../core/system-prompt + '@deepseek-ai/dsh-tools': + specifier: workspace:^ + version: link:../../core/tools + cordis: + specifier: ^4.0.0-rc.6 + version: 4.0.0-rc.6(@cordisjs/plugin-include@1.0.4)(@cordisjs/plugin-loader@1.0.0-rc.4) + packages/core/agent: devDependencies: '@deepseek-ai/dsh-brand': diff --git a/scripts/gen-tool-catalog.ts b/scripts/gen-tool-catalog.ts index 24739e1388..714b15afdc 100644 --- a/scripts/gen-tool-catalog.ts +++ b/scripts/gen-tool-catalog.ts @@ -47,6 +47,7 @@ import * as WebFetchLocal from '@deepseek-ai/dsh-web-fetch-local' import SubagentService from '@deepseek-ai/dsh-subagent' import * as SubagentMock from '@deepseek-ai/dsh-subagent-mock' import * as ToolBash from '@deepseek-ai/dsh-tool-bash' +import * as ToolCordis from '@deepseek-ai/dsh-tool-cordis' import * as ToolFs from '@deepseek-ai/dsh-tool-fs' import * as ToolTodo from '@deepseek-ai/dsh-tool-todo' import * as ToolSubagent from '@deepseek-ai/dsh-tool-subagent' @@ -113,6 +114,18 @@ const TOOL_PACKAGES: ToolPackage[] = [ note: 'The bash/bash_output/bash_kill tools are model-facing consumers of the bash executor seam.', }, + { + pkg: '@deepseek-ai/dsh-tool-cordis', + dir: 'tool-cordis', + source: 'packages/cordis/tool-cordis/src/index.ts', + requires: ['ctx.tools'], + writes: ['tool/call', 'tool/result', 'live plugin-tree mutations (mount/unmount)'], + async mount(ctx) { + await ctx.plugin(ToolCordis) + }, + note: + 'Ships in examples/cordis-agent only (a deliberate opt-in — mounted code gets the real ctx, see docs/rfc/implemented/feature/2026-07-08-self-referential-cordis-toolset.md). Plugins the model mounts may register ADDITIONAL model-visible tools at runtime; the request-header ToolsDelta logs those tool-set changes.', + }, { pkg: '@deepseek-ai/dsh-tool-fs', dir: 'tool-fs', diff --git a/tsconfig.base.json b/tsconfig.base.json index e587d44a3d..b4a4e116d8 100644 --- a/tsconfig.base.json +++ b/tsconfig.base.json @@ -51,6 +51,7 @@ "./packages/web/*/src", "./packages/timeout/*/src", "./packages/todo/*/src", + "./packages/cordis/*/src", "./packages/hooks/*/src", "./packages/session-persistence/*/src", "./packages/ui/*/src", diff --git a/tsconfig.build.json b/tsconfig.build.json index 64fa70e9f9..fafe46d3c9 100644 --- a/tsconfig.build.json +++ b/tsconfig.build.json @@ -58,6 +58,7 @@ { "path": "./packages/subagent/subagent-acp" }, { "path": "./packages/todo/tool-todo" }, { "path": "./packages/guard/repeat-tool-guard" }, + { "path": "./packages/cordis/tool-cordis" }, { "path": "./packages/hooks/hook-protocol" }, { "path": "./packages/hooks/hooks-claude" }, { "path": "./packages/hooks/hooks-codex" } diff --git a/tsconfig.json b/tsconfig.json index 8feeea4fce..9d630d04c4 100644 --- a/tsconfig.json +++ b/tsconfig.json @@ -69,6 +69,7 @@ { "path": "./packages/subagent/subagent-acp" }, { "path": "./packages/todo/tool-todo" }, { "path": "./packages/guard/repeat-tool-guard" }, + { "path": "./packages/cordis/tool-cordis" }, { "path": "./packages/hooks/hook-protocol" }, { "path": "./packages/hooks/hooks-claude" }, { "path": "./packages/hooks/hooks-codex" } From 5edc9c573a6fd26d773cfcfcb933f0d138aa26c7 Mon Sep 17 00:00:00 2001 From: imccyu <276526105+imccyu@users.noreply.github.com> Date: Wed, 8 Jul 2026 11:47:15 +0800 Subject: [PATCH 04/15] =?UTF-8?q?examples:=20cordis-agent=20=E2=80=94=20th?= =?UTF-8?q?e=20self-referential=20demo?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The coding spine (DeepSeek V4 + local bash on dsh-stdio-agent) plus @deepseek-ai/dsh-tool-cordis loaded by package name, run via demo:cordis. Ships the keyless Loader smoke (the export-shape / package-name-resolution guard) and the with-key smoke: a real model mounts a listener whose tagged console line actually fires, builds and calls its own reverse_text tool, and composes two mounts via provide/inject — all world-verified against the registry and session events. --- examples/cordis-agent/README.md | 33 ++++ examples/cordis-agent/cordis.yml | 64 +++++++ examples/cordis-agent/package.json | 7 + .../cordis-agent/tests/cordis-tools.e2e.ts | 156 ++++++++++++++++++ examples/cordis-agent/tests/harness.ts | 46 ++++++ .../cordis-agent/tests/keyless-smoke.e2e.ts | 94 +++++++++++ package.json | 1 + 7 files changed, 401 insertions(+) create mode 100644 examples/cordis-agent/README.md create mode 100644 examples/cordis-agent/cordis.yml create mode 100644 examples/cordis-agent/package.json create mode 100644 examples/cordis-agent/tests/cordis-tools.e2e.ts create mode 100644 examples/cordis-agent/tests/harness.ts create mode 100644 examples/cordis-agent/tests/keyless-smoke.e2e.ts diff --git a/examples/cordis-agent/README.md b/examples/cordis-agent/README.md new file mode 100644 index 0000000000..ba9365498b --- /dev/null +++ b/examples/cordis-agent/README.md @@ -0,0 +1,33 @@ +# cordis-agent + +The self-referential harness demo: the coding-agent spine (DeepSeek V4 + local bash on the stdio chat app) plus [`@deepseek-ai/dsh-tool-cordis`](../../packages/cordis/tool-cordis/README.md), which hands the model three tools over the **live cordis runtime it is running inside** — inspect it, mount new plugins into it, and dispose them again. The design (sandbox semantics, mount lifecycle, cross-mount composition, caveats) lives in [the toolset RFC](../../docs/rfc/implemented/feature/2026-07-08-self-referential-cordis-toolset.md). + +## Run it + +```sh +# repo root .env (gitignored) or exported env: +# DEEPSEEK_API_KEY=sk-… +# DEEPSEEK_BASE_URL=https://… # optional; defaults to the public API +pnpm run demo:cordis +``` + +The intended demo is staged — verify the listener link first, then let the agent extend itself: + +``` +> Mount a plugin that listens to the 'agent/status' event and logs every status change, then run `echo hi` with bash. + [tool call] cordis_mount({"code": "return { name: 'status-logger', apply(ctx) { ctx.on('agent/status', (agent, status) => console.log('status →', status)) } }"}) + [tool result] mounted dyn-1 (plugin "status-logger", state: active) + [tool call] bash({"command": "echo hi"}) +[cordis:dyn-1] status → … ← the mounted listener firing, live +> Now give yourself a reverse_text tool and use it on "harness". + [tool call] cordis_mount({"code": "return { name: 'reverse-text', inject: ['tools'], apply(ctx) { ctx.tools.register(harness.defineTool({ name: 'reverse_text', … })) } }"}) + [tool call] reverse_text({"text": "harness"}) ← a tool the agent built for itself, one step earlier +> Unmount both. + [tool call] cordis_unmount({"id": "dyn-1"}) +``` + +Ask for `cordis_inspect` with `what: "api"` or `what: "events"` to see the generated service/event reference the agent writes plugin code against, and try two cooperating mounts (`ctx.provide` in one, `inject` in the other) to watch cordis park and revive the consumer. + +## End-to-end tests + +`tests/keyless-smoke.e2e.ts` boots the real `cordis.yml` through the Loader with a dummy key and asserts the banner + clean EOF exit (the export-shape / real-load-path guard, now across the package-name resolution). `tests/cordis-tools.e2e.ts` is the with-key smoke: a real model mounts a status listener (asserting the tagged console line actually fires — the world, not the agent's claim), builds itself a `reverse_text` tool and uses it, and composes two mounts via provide/inject. The tool logic itself is unit-tested in [`packages/cordis/tool-cordis`](../../packages/cordis/tool-cordis) under the per-file 100% coverage gate. diff --git a/examples/cordis-agent/cordis.yml b/examples/cordis-agent/cordis.yml new file mode 100644 index 0000000000..b5e08c8325 --- /dev/null +++ b/examples/cordis-agent/cordis.yml @@ -0,0 +1,64 @@ +# The cordis-agent plugin tree: the SELF-REFERENTIAL harness demo. Same spine +# as coding-agent (DeepSeek V4 + local bash on @deepseek-ai/dsh-stdio-agent), +# plus @deepseek-ai/dsh-tool-cordis, which gives the model three tools over the +# live cordis runtime it is running inside: cordis_inspect (services / plugin +# tree / tools / dynamic mounts / api / events), cordis_mount (evaluate +# model-written code in a vm sandbox and mount the returned plugin under the +# `cordis-dynamic` group), and cordis_unmount (dispose one mount by id). +# Requires DEEPSEEK_API_KEY (and optionally DEEPSEEK_BASE_URL) — the +# dsh-stdio-agent bin loads the gitignored repo-root .env first. +# +# Trust stance (docs/rfc/implemented/feature/2026-07-08-self-referential-cordis-toolset.md): +# the mounted code gets the REAL ctx — the +# vm sandbox only prevents accidental global pollution. Load the toolset as +# deliberately as you would grant a bash tool. + +# Hot-module reload for the dev/demo loop (needs `node --expose-internals`). +- id: hmr + name: '@cordisjs/plugin-hmr' + config: + root: ['.'] + +# The DeepSeek adapter. +- id: llm-deepseek + name: '@deepseek-ai/dsh-llm-deepseek' + config: + apiKey: !!js process.env.DEEPSEEK_API_KEY + baseURL: !!js process.env.DEEPSEEK_BASE_URL + models: + - deepseek-v4-pro + - deepseek-v4-flash + +# Local bash executor for agent-core's tool-bash schema — gives the agent an +# ordinary tool whose calls make the mounted listeners observably fire. +- id: bash + name: '@deepseek-ai/dsh-bash-local' + config: + timeoutMs: 60000 + +# The stdio chat app: the whole spine + front-door cluster, configured for the +# self-referential demo driving a pre-created `main` agent. +- id: stdio-agent + name: '@deepseek-ai/dsh-stdio-agent' + config: + model: deepseek-v4-flash + resumeSessionId: !!js process.env.RESUME_SESSION_ID + persistenceRoot: './.sessions' + welcome: 'cordis-agent ready. Ask it to inspect its runtime, mount a listener, or invent a tool for itself.' + persona: | + You are cordis-agent, a self-referential harness demo powered by the + {{model}} model. + + You run INSIDE a cordis plugin runtime, and your cordis_* tools operate + on that live runtime: cordis_inspect to look around (its `api` and + `events` sections document the service methods, type shapes, and events + your plugin code can use), cordis_mount to add a plugin (an event + listener, a brand-new tool for yourself, or a service other mounts + inject), cordis_unmount to clean one up. Prefer small single-purpose + plugins, prefer plain notification events over waterfall events unless + you intend to intercept, and unmount what you no longer need. Report + results briefly. + +# The self-referential cordis toolset (loaded after the app so ctx.tools exists). +- id: tool-cordis + name: '@deepseek-ai/dsh-tool-cordis' diff --git a/examples/cordis-agent/package.json b/examples/cordis-agent/package.json new file mode 100644 index 0000000000..8d5a693555 --- /dev/null +++ b/examples/cordis-agent/package.json @@ -0,0 +1,7 @@ +{ + "name": "cordis-agent-example", + "private": true, + "version": "0.0.1", + "type": "module", + "description": "Runnable demo: the self-referential harness — an agent that inspects and modifies its own cordis runtime" +} diff --git a/examples/cordis-agent/tests/cordis-tools.e2e.ts b/examples/cordis-agent/tests/cordis-tools.e2e.ts new file mode 100644 index 0000000000..388fcb0058 --- /dev/null +++ b/examples/cordis-agent/tests/cordis-tools.e2e.ts @@ -0,0 +1,156 @@ +import { afterEach, describe, expect, it, vi } from 'vitest' +import type { Context } from 'cordis' +import { CallId } from '@deepseek-ai/dsh-llm' +import { AgentId } from '@deepseek-ai/dsh-agent' +import { cordisHarness, waitForIdle } from './harness.ts' + +/** + * With-key smoke for the self-referential cordis tools: a REAL model drives + * cordis_mount/cordis_unmount against the live context the test observes. + * World-verified, not self-reported: the mounted listener must actually WRITE + * its tagged console line, the self-made tool must actually EXIST in the + * registry and appear as a real `tool/call`, the cross-mount service must + * actually LAND in the reflect store. Key-gated (see vitest.e2e.config.ts). + */ + +let ctx: Context | undefined + +afterEach(async () => { + vi.restoreAllMocks() + // Always dispose the harness, even on failure/retry/timeout: agent-loop + // teardown stops the loop, and disposing the tree unwinds every dynamic + // mount the model left behind. + await ctx?.fiber.dispose() + ctx = undefined +}) + +/** The tagged write-through lines (`[cordis:dyn-n] …`) captured by a console spy. */ +function taggedCalls(log: { mock: { calls: unknown[][] } }): unknown[][] { + return log.mock.calls.filter(call => typeof call[0] === 'string' && /^\[cordis:dyn-\d+\]$/.test(call[0])) +} + +/** Model-facing text of one tool result, concatenated. */ +function resultText(result: { content: { type: string; text?: string }[] }): string { + return result.content.filter(block => block.type === 'text').map(block => block.text).join('') +} + +describe.skipIf(!process.env.DEEPSEEK_API_KEY)('cordis tools: a real model modifies its own runtime', () => { + it('mounts a status listener whose tagged output actually fires, then unmounts it', async () => { + ctx = await cordisHarness() + const log = vi.spyOn(console, 'log').mockImplementation(() => {}) + const agent = ctx.agentLoop.create(AgentId('cordis-e2e-listener'), { model: 'deepseek-v4-flash' }) + + agent.send([{ + type: 'text', + text: 'Use cordis_mount to mount a plugin that listens to the \'agent/status\' ' + + 'cordis event and logs every change with console.log. Reply "mounted" once done.', + }]) + await waitForIdle(ctx, agent) + + // The WORLD check: the turn's own running→idle transition must have driven + // the mounted listener through the tagged sandbox console. + expect(taggedCalls(log).length).toBeGreaterThan(0) + const mid = await ctx.tools.execute({ + callId: CallId('verify-mounted'), name: 'cordis_inspect', arguments: { what: 'dynamic' }, + }) + expect(resultText(mid)).toContain('dyn-') + + agent.send([{ type: 'text', text: 'Now unmount the plugin you just mounted.' }]) + await waitForIdle(ctx, agent) + + const after = await ctx.tools.execute({ + callId: CallId('verify-unmounted'), name: 'cordis_inspect', arguments: { what: 'dynamic' }, + }) + expect(resultText(after)).toContain('(no dynamic plugins mounted)') + }, 120_000) + + it('builds itself a reverse_text tool and actually calls it', async () => { + ctx = await cordisHarness() + const agent = ctx.agentLoop.create(AgentId('cordis-e2e-selftool'), { model: 'deepseek-v4-flash' }) + + agent.send([{ + type: 'text', + text: 'Give yourself a new tool: use cordis_mount to mount a plugin with ' + + 'inject ["tools"] that calls harness.registerTool(ctx, harness.defineTool({...})) ' + + 'to register a tool named reverse_text with one required string parameter ' + + '"text", returning the text reversed. Then CALL reverse_text with the ' + + 'exact text "harness" and report its exact output.', + }]) + await waitForIdle(ctx, agent) + + // World checks: the tool exists in the registry, was invoked as a real + // tool call, and its RESULT (the self-made execute actually running) is the + // reversed string. The model's prose is not asserted — the tool result is + // the world; the summary sentence is just the self-report. + expect(ctx.tools.get('reverse_text')).toBeDefined() + const events = [...agent.session.events] + const calls = events.filter(event => event.type === 'tool/call') + expect(calls.some(event => event.data.name === 'cordis_mount')).toBe(true) + const reverseCalls = calls.filter(event => event.data.name === 'reverse_text') + expect(reverseCalls.length).toBeGreaterThan(0) + const reverseResults = events + .filter(event => event.type === 'tool/result') + .filter(event => reverseCalls.some(call => call.data.callId === event.data.callId)) + .flatMap(event => event.data.content.filter(block => block.type === 'text').map(block => block.text)) + // On failure, surface what the model actually mounted and what the tool + // returned — an e2e failing at a distance is undebuggable without it. + const mountCode = calls + .filter(event => event.data.name === 'cordis_mount') + .map(event => event.data.arguments) + .join('\n---\n') + const trace = events.map((event) => { + switch (event.type) { + case 'tool/call': return `tool/call:${event.data.name}` + case 'tool/result': return `tool/result:${event.data.isError ? 'ERR:' + JSON.stringify(event.data.content).slice(0, 200) : 'ok'}` + case 'turn/end': return `turn/end:${JSON.stringify(event.data.reason)}` + default: return event.type + } + }).join('\n') + expect( + reverseResults.some(text => text.includes('ssenrah')), + `no reversed output in reverse_text results.\nresults: ${JSON.stringify(reverseResults)}\nmount code: ${mountCode}\ntrace:\n${trace}`, + ).toBe(true) + }, 120_000) + + it('composes two mounts through provide/inject, and unmounting the provider parks the consumer', async () => { + ctx = await cordisHarness() + const agent = ctx.agentLoop.create(AgentId('cordis-e2e-compose'), { model: 'deepseek-v4-flash' }) + + agent.send([{ + type: 'text', + text: 'Mount TWO separate plugins with cordis_mount. First a provider: apply calls ' + + 'ctx.provide(\'shouter\', { shout: (s) => s.toUpperCase() }). Second a consumer with ' + + 'inject ["shouter", "tools"] that registers (via harness.registerTool + harness.defineTool) ' + + 'a tool named shout_text with one required string parameter "text" whose execute returns ' + + 'ctx.shouter.shout(args.text) as a text content block. Then CALL shout_text with "quiet" ' + + 'and report the exact output.', + }]) + await waitForIdle(ctx, agent) + + // World checks: the service is really in the store, the tool really ran. + expect(ctx.get('shouter')).toBeDefined() + expect(ctx.tools.get('shout_text')).toBeDefined() + const events = [...agent.session.events] + const shoutCalls = events + .filter(event => event.type === 'tool/call') + .filter(event => event.data.name === 'shout_text') + expect(shoutCalls.length).toBeGreaterThan(0) + const shoutResults = events + .filter(event => event.type === 'tool/result') + .filter(event => shoutCalls.some(call => call.data.callId === event.data.callId)) + .flatMap(event => event.data.content.filter(block => block.type === 'text').map(block => block.text)) + expect(shoutResults.some(text => text.includes('QUIET'))).toBe(true) + + agent.send([{ type: 'text', text: 'Now unmount ONLY the provider plugin (the one that provided shouter).' }]) + await waitForIdle(ctx, agent) + + // The consumer must have been parked by cordis itself: service gone, + // dependent tool unregistered, dynamic table naming the missing service. + expect(ctx.get('shouter')).toBeUndefined() + expect(ctx.tools.get('shout_text')).toBeUndefined() + const after = await ctx.tools.execute({ + callId: CallId('verify-parked'), name: 'cordis_inspect', arguments: { what: 'dynamic' }, + }) + expect(resultText(after)).toContain('waiting for: shouter') + }, 120_000) +}) diff --git a/examples/cordis-agent/tests/harness.ts b/examples/cordis-agent/tests/harness.ts new file mode 100644 index 0000000000..78e5b0bb93 --- /dev/null +++ b/examples/cordis-agent/tests/harness.ts @@ -0,0 +1,46 @@ +import { Context } from 'cordis' +import LlmService from '@deepseek-ai/dsh-llm' +import SessionStore from '@deepseek-ai/dsh-session' +import SystemPrompt from '@deepseek-ai/dsh-system-prompt' +import ToolRegistry from '@deepseek-ai/dsh-tools' +import AgentRegistry from '@deepseek-ai/dsh-agent' +import AgentLoop, { ReactLoopAgent } from '@deepseek-ai/dsh-agent-loop' +import * as LlmDeepSeek from '@deepseek-ai/dsh-llm-deepseek' +import * as ToolCordis from '@deepseek-ai/dsh-tool-cordis' + +/** + * Shared harness for the cordis-agent e2e suite: the agent spine with the real + * DeepSeek adapter and the real `@deepseek-ai/dsh-tool-cordis` plugin, so a + * live model can mount plugins into the very context the test observes. Lives + * outside the *.e2e.ts pattern so importing it never re-registers another + * file's tests. + */ + +const PERSONA = 'You are cordis-agent, a self-referential harness demo. ' + + 'Your cordis_* tools operate on the live cordis runtime you run inside: ' + + 'cordis_inspect to look around, cordis_mount to add a plugin, cordis_unmount ' + + 'to clean one up. Follow the tool descriptions exactly and report results briefly.' + +export async function cordisHarness(): Promise { + const ctx = new Context() + await ctx.plugin(LlmService) + await ctx.plugin(SessionStore) + await ctx.plugin(SystemPrompt, { persona: PERSONA }) + await ctx.plugin(ToolRegistry) + await ctx.plugin(AgentRegistry) + await ctx.plugin(AgentLoop, { agents: [] }) + await ctx.plugin(LlmDeepSeek, { models: ['deepseek-v4-flash'] }) + await ctx.plugin(ToolCordis) + return ctx +} + +export function waitForIdle(ctx: Context, agent: ReactLoopAgent): Promise { + return new Promise((resolve) => { + const dispose = ctx.on('agent/status', (subject, status) => { + if (subject === agent && status === 'idle') { + dispose() + resolve() + } + }) + }) +} diff --git a/examples/cordis-agent/tests/keyless-smoke.e2e.ts b/examples/cordis-agent/tests/keyless-smoke.e2e.ts new file mode 100644 index 0000000000..b37ea8d83e --- /dev/null +++ b/examples/cordis-agent/tests/keyless-smoke.e2e.ts @@ -0,0 +1,94 @@ +import { spawn, type ChildProcessWithoutNullStreams } from 'node:child_process' +import { mkdtemp, rm } from 'node:fs/promises' +import { tmpdir } from 'node:os' +import { join } from 'node:path' +import { fileURLToPath } from 'node:url' +import { afterEach, describe, expect, it } from 'vitest' + +/** + * Keyless Loader-path smoke for examples/cordis-agent: boot the REAL example + * through the `@deepseek-ai/dsh-stdio-agent` bin against its `cordis.yml` — + * the cordis Loader, `unwrapExports`, the full plugin tree INCLUDING the + * `@deepseek-ai/dsh-tool-cordis` package resolved by name (whose `inject` + * would crash a collapsed export shape at load, see docs/postmortem/0001) — + * then close stdin with no prompt and assert the ready banner + a clean exit. + * + * No prompt is ever sent, so the model is NEVER called — that is why it runs + * without a real key: `llm-deepseek`'s apply() only requires a key to be + * PRESENT, and the absence of any prompt guarantees no network call. The + * with-key product proof lives in cordis-tools.e2e.ts. + */ + +// The dsh-stdio-agent bin (the demo:cordis entry) and this example's cordis.yml. +// The bin resolves its config-path arg from CWD; the test spawns from a temp +// cwd, so we pass the example config's ABSOLUTE path. +const binScript = fileURLToPath(new URL('../../../packages/ui/stdio-agent/src/bin.ts', import.meta.url)) +const configPath = fileURLToPath(new URL('../cordis.yml', import.meta.url)) +const tsxLoader = fileURLToPath(import.meta.resolve('tsx')) +// Dev/test run UNBUILT: resolve `@deepseek-ai/dsh-*` through the root tsconfig +// `paths` map; tsx searches UP from cwd, and we spawn from a temp dir outside +// the repo, so point it at the repo tsconfig (root is three levels up). +const repoTsconfig = fileURLToPath(new URL('../../../tsconfig.json', import.meta.url)) + +let child: ChildProcessWithoutNullStreams | undefined +let workdir: string | undefined + +afterEach(async () => { + if (child !== undefined && child.exitCode === null) child.kill('SIGKILL') + child = undefined + if (workdir !== undefined) await rm(workdir, { recursive: true, force: true }) + workdir = undefined +}) + +async function bootAndEof(): Promise<{ stdout: string; code: number }> { + workdir = await mkdtemp(join(tmpdir(), 'cordis-smoke-')) + const cwd = workdir + return new Promise((resolve, reject) => { + const proc = spawn( + process.execPath, + // --expose-internals: cordis.yml loads the HMR plugin (mirrors demo:cordis). + ['--expose-internals', '--import', tsxLoader, binScript, configPath], + { + cwd, + env: { + ...process.env, + TSX_TSCONFIG_PATH: repoTsconfig, + // A dummy key so llm-deepseek's apply() (key-PRESENT check only) boots. + // No prompt is sent, so the adapter never streams — no network call. + DEEPSEEK_API_KEY: 'keyless-smoke-no-call', + }, + stdio: ['pipe', 'pipe', 'pipe'], + }, + ) + child = proc + let stdout = '' + let stderr = '' + proc.stdout.setEncoding('utf8') + proc.stdout.on('data', (chunk: string) => { stdout += chunk }) + proc.stderr.setEncoding('utf8') + proc.stderr.on('data', (chunk: string) => { stderr += chunk }) + + const timer = setTimeout(() => { + proc.kill('SIGKILL') + reject(new Error(`cordis-agent did not exit within 10s. stdout:\n${stdout}\nstderr:\n${stderr}`)) + }, 10_000) + + proc.on('exit', (code) => { + clearTimeout(timer) + if (code === 0) resolve({ stdout, code }) + else reject(new Error(`cordis-agent exited ${code}. stderr:\n${stderr}`)) + }) + proc.on('error', (err) => { clearTimeout(timer); reject(err) }) + + // No prompt — just EOF, so the stdio UI exits without ever running a turn. + proc.stdin.end() + }) +} + +describe('cordis-agent keyless smoke (real cordis.yml via the Loader)', () => { + it('boots the full plugin tree incl. tool-cordis, prints its banner, and exits cleanly on EOF', async () => { + const { stdout, code } = await bootAndEof() + expect(code).toBe(0) + expect(stdout).toContain('cordis-agent ready.') + }, 15_000) +}) diff --git a/package.json b/package.json index bba471ea5f..e4b071718a 100644 --- a/package.json +++ b/package.json @@ -63,6 +63,7 @@ "hygiene": "pnpm run knip && pnpm run publint && pnpm run constraints && pnpm run verify-node-next-types", "demo:echo": "node --expose-internals --import tsx packages/ui/stdio-agent/src/bin.ts examples/echo-agent/cordis.yml", "demo:repl": "node --expose-internals --import tsx packages/ui/stdio-agent/src/bin.ts examples/coding-agent/cordis.yml", + "demo:cordis": "node --expose-internals --import tsx packages/ui/stdio-agent/src/bin.ts examples/cordis-agent/cordis.yml", "demo:acp": "node --import tsx packages/ui/acp-agent/src/bin.ts examples/acp-agent/cordis.yml", "postinstall": "node scripts/install-lefthook.mjs" }, From 809329ea1ab6486fcc0774d39748eb8d6941adec Mon Sep 17 00:00:00 2001 From: imccyu <276526105+imccyu@users.noreply.github.com> Date: Wed, 8 Jul 2026 11:47:51 +0800 Subject: [PATCH 05/15] =?UTF-8?q?scripts:=20gen-cordis-api=20=E2=80=94=20t?= =?UTF-8?q?he=20generated=20runtime=20API=20catalog=20pipeline?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Emits packages/cordis/tool-cordis/src/api-catalog.ts (the data cordis_inspect serves the model) from the same JSDoc-enforcing AST walk as docs/cordis-catalog (collectServices/collectEvents, plus the now-exported INHERITED_SERVICES table): service summaries + method signatures, event modes + signatures, and the transitive closure of type shapes the signatures reference — so a mounted plugin reads that a bash run's stdout is { text, truncated } instead of guessing. verify-cordis-api joins doc-sync as the freshness gate. --- package.json | 4 +- scripts/gen-cordis-api.ts | 247 ++++++++++++++++++++++++++++++++++ scripts/gen-cordis-catalog.ts | 2 +- 3 files changed, 251 insertions(+), 2 deletions(-) create mode 100644 scripts/gen-cordis-api.ts diff --git a/package.json b/package.json index e4b071718a..652a8d88c4 100644 --- a/package.json +++ b/package.json @@ -47,6 +47,8 @@ "gen-cordis-catalog": "tsx scripts/gen-cordis-catalog.ts", "gen-rfc-index": "tsx scripts/gen-rfc-index.ts", "verify-cordis-catalog": "tsx scripts/gen-cordis-catalog.ts --check", + "gen-cordis-api": "tsx scripts/gen-cordis-api.ts", + "verify-cordis-api": "tsx scripts/gen-cordis-api.ts --check", "verify-export-jsdoc": "tsx scripts/verify-export-jsdoc.ts", "gen-tool-catalog": "tsx scripts/gen-tool-catalog.ts", "verify-tool-catalog": "tsx scripts/gen-tool-catalog.ts --check", @@ -59,7 +61,7 @@ "gen-module-graph": "tsx scripts/gen-module-graph.ts", "verify-module-graph": "tsx scripts/gen-module-graph.ts --check", "constraints": "tsx scripts/check-workspace-constraints.ts", - "doc-sync": "pnpm run doc-typecheck && pnpm run verify-cordis-catalog && pnpm run verify-export-jsdoc && pnpm run verify-tool-catalog && pnpm run verify-config-catalog && pnpm run verify-persistence-catalog && pnpm run verify-doc-graphs && pnpm run verify-md-wrap && pnpm run verify-md-links && pnpm run verify-doc-refs && pnpm run verify-package-paths && pnpm run verify-mermaid && pnpm run verify-rfc-classification && pnpm run verify-rfc-format && pnpm run verify-type-equiv && pnpm run verify-translation-pairing && pnpm run verify-doc-budgets", + "doc-sync": "pnpm run doc-typecheck && pnpm run verify-cordis-catalog && pnpm run verify-cordis-api && pnpm run verify-export-jsdoc && pnpm run verify-tool-catalog && pnpm run verify-config-catalog && pnpm run verify-persistence-catalog && pnpm run verify-doc-graphs && pnpm run verify-md-wrap && pnpm run verify-md-links && pnpm run verify-doc-refs && pnpm run verify-package-paths && pnpm run verify-mermaid && pnpm run verify-rfc-classification && pnpm run verify-rfc-format && pnpm run verify-type-equiv && pnpm run verify-translation-pairing && pnpm run verify-doc-budgets", "hygiene": "pnpm run knip && pnpm run publint && pnpm run constraints && pnpm run verify-node-next-types", "demo:echo": "node --expose-internals --import tsx packages/ui/stdio-agent/src/bin.ts examples/echo-agent/cordis.yml", "demo:repl": "node --expose-internals --import tsx packages/ui/stdio-agent/src/bin.ts examples/coding-agent/cordis.yml", diff --git a/scripts/gen-cordis-api.ts b/scripts/gen-cordis-api.ts new file mode 100644 index 0000000000..34583d2ead --- /dev/null +++ b/scripts/gen-cordis-api.ts @@ -0,0 +1,247 @@ +/** + * Generate (and verify) the runtime cordis API catalog the `cordis_inspect` + * tool serves to the model: packages/cordis/tool-cordis/src/api-catalog.ts. + * + * The artifact is the machine-readable sibling of docs/cordis-catalog: it + * reuses `collectServices` / `collectEvents` from `gen-cordis-catalog.ts` (the + * same JSDoc-completeness-enforcing AST walk), so the API the model reads at + * runtime and the API the docs render cannot diverge. Emitted as a typed + * TypeScript data module (not JSON): it compiles under the package tsconfig, + * passes lint and the export-JSDoc gate, and is trivially covered by import. + * + * The data is trimmed for a model-facing text surface: per service the + * `ctx.` name, the first sentence of the class doc, and the raw method + * signatures; per event the name, `@mode`, signature, and first sentence of + * doc; the SHAPES of every exported interface/type-alias the service + * signatures reference (transitively — so a model can see that e.g. a + * `BashRunResult.stdout` is `{ text, truncated }`, not a string); plus the + * curated inherited `ctx` surface shared with the docs catalog. Source + * pointers are dropped (a `file:line` means nothing to the model) and entries + * are sorted deterministically. + * + * `tsx scripts/gen-cordis-api.ts` → write the artifact + * `tsx scripts/gen-cordis-api.ts --check` → exit 1 if the committed file is + * stale (CI / pre-push gate) + */ + +import { globSync, readFileSync, writeFileSync } from 'node:fs' +import { resolve } from 'node:path' +import ts from 'typescript' +import { collectEvents, collectServices, INHERITED_SERVICES } from './gen-cordis-catalog.ts' + +const root = resolve(import.meta.dirname, '..') +const OUT = 'packages/cordis/tool-cordis/src/api-catalog.ts' + +/** Declarations longer than this render as a truncated stub — a shape the model cannot skim teaches nothing. */ +const MAX_DECL_CHARS = 1500 + +/** The first sentence of a (possibly multi-line) JSDoc prose block. */ +function firstSentence(doc: string): string { + const line = doc.split('\n', 1)[0] ?? '' + const match = /^(.*?[.!?])(?:\s|$)/.exec(line) + return (match?.[1] ?? line).trim() +} + +/** Render a string as a single-quoted, lint-clean TS literal. */ +function quote(value: string): string { + return `'${value.replace(/\\/g, '\\\\').replace(/'/g, '\\\'').replace(/\n/g, '\\n')}'` +} + +/** + * Every exported `interface` / `type` declaration under `packages///src`, + * printed without comments, keyed by name. A name declared in more than one + * package (e.g. each plugin's `Config`) is ambiguous and dropped entirely — + * serving the wrong package's shape is worse than serving none. + */ +function collectTypeDecls(scanRoot: string = root): Map { + const printer = ts.createPrinter({ removeComments: true }) + const decls = new Map() + const ambiguous = new Set() + for (const rel of globSync('packages/*/*/src/*.ts', { cwd: scanRoot }).sort()) { + const abs = resolve(scanRoot, rel) + const sf = ts.createSourceFile(abs, readFileSync(abs, 'utf8'), ts.ScriptTarget.Latest, true) + for (const stmt of sf.statements) { + if (!ts.isInterfaceDeclaration(stmt) && !ts.isTypeAliasDeclaration(stmt)) continue + if (!(stmt.modifiers?.some(m => m.kind === ts.SyntaxKind.ExportKeyword) ?? false)) continue + const name = stmt.name.text + if (decls.has(name)) { + ambiguous.add(name) + continue + } + const printed = printer.printNode(ts.EmitHint.Unspecified, stmt, sf).replace(/\r/g, '') + decls.set(name, printed.length > MAX_DECL_CHARS + ? `${printed.slice(0, MAX_DECL_CHARS)} /* …truncated — full shape in source */` + : printed) + } + } + for (const name of ambiguous) decls.delete(name) + return decls +} + +/** + * The transitive closure of type names referenced by the seed texts: every + * collected declaration whose name appears (word-bounded) in a seed or in an + * already-included declaration, sorted by name. + */ +function referencedTypes(seeds: string[], decls: Map): { name: string; declaration: string }[] { + const included = new Map() + let frontier = seeds + while (frontier.length > 0) { + const next: string[] = [] + for (const [name, declaration] of decls) { + if (included.has(name)) continue + const pattern = new RegExp(`\\b${name}\\b`) + if (frontier.some(text => pattern.test(text))) { + included.set(name, declaration) + next.push(declaration) + } + } + frontier = next + } + return [...included].map(([name, declaration]) => ({ name, declaration })).sort((a, b) => a.name.localeCompare(b.name)) +} + +/** Render the whole generated module (pure, deterministic given sorted collector output). */ +function render(): string { + const services = collectServices() + const events = collectEvents().sort((a, b) => a.name.localeCompare(b.name)) + const types = referencedTypes(services.flatMap(service => service.methods), collectTypeDecls()) + const lines: string[] = [ + '/**', + ' * Generated by scripts/gen-cordis-api.ts — do not edit by hand; run', + ' * `pnpm run gen-cordis-api` to regenerate (freshness-gated by', + ' * `pnpm run verify-cordis-api` in doc-sync).', + ' *', + ' * The machine-readable cordis API catalog `cordis_inspect` serves to the', + ' * model: harness services (summary + public method signatures), harness', + ' * events (mode + signature), and the inherited `ctx` surface. Produced by', + ' * the same AST walk as docs/cordis-catalog, so this data and the rendered', + ' * docs cannot diverge.', + ' *', + ' * @module @deepseek-ai/dsh-tool-cordis/api-catalog', + ' */', + '', + '/** One harness `ctx.` service: its one-line summary and public method signatures. */', + 'export interface ServiceApiEntry {', + ' /** The `ctx.` name, e.g. `tools`. */', + ' key: string', + ' /** First sentence of the service class JSDoc. */', + ' summary: string', + ' /** Public method signatures, bodies stripped, in source order. */', + ' methods: readonly string[]', + '}', + '', + '/** One harness event: its dispatch mode, exact signature, and one-line summary. */', + 'export interface EventApiEntry {', + ' /** The scoped event name, e.g. `agent/status`. */', + ' name: string', + ' /** The dispatch mode from the declaration\'s `@mode` tag. */', + ' mode: string', + ' /** The exact listener signature, whitespace-normalized. */', + ' signature: string', + ' /** First sentence of the event JSDoc. */', + ' summary: string', + '}', + '', + '/** One inherited (cordis core + loader/hmr/timer) `ctx` member group with its summary. */', + 'export interface InheritedApiEntry {', + ' /** The `ctx` member name(s), e.g. `ctx.on / ctx.once`. */', + ' name: string', + ' /** One-line summary of what the member does. */', + ' summary: string', + '}', + '', + '/** One named type shape the service signatures reference. */', + 'export interface TypeApiEntry {', + ' /** The exported type/interface name, e.g. `BashRunResult`. */', + ' name: string', + ' /** The full declaration text, comments stripped. */', + ' declaration: string', + '}', + '', + '/** Every harness `ctx.` service, sorted by key. */', + 'export const SERVICE_API: readonly ServiceApiEntry[] = [', + ] + for (const service of services) { + lines.push(' {') + lines.push(` key: ${quote(service.key)},`) + lines.push(` summary: ${quote(firstSentence(service.doc))},`) + if (service.methods.length === 0) { + lines.push(' methods: [],') + } else { + lines.push(' methods: [') + for (const method of service.methods) lines.push(` ${quote(method)},`) + lines.push(' ],') + } + lines.push(' },') + } + lines.push( + ']', + '', + '/** Every harness event, sorted by name. */', + 'export const EVENT_API: readonly EventApiEntry[] = [', + ) + for (const event of events) { + lines.push(' {') + lines.push(` name: ${quote(event.name)},`) + lines.push(` mode: ${quote(event.mode)},`) + lines.push(` signature: ${quote(event.signature)},`) + lines.push(` summary: ${quote(firstSentence(event.doc))},`) + lines.push(' },') + } + lines.push( + ']', + '', + '/** Shapes of every exported type the SERVICE_API signatures reference (transitively), sorted by name. */', + 'export const TYPE_API: readonly TypeApiEntry[] = [', + ) + for (const type of types) { + lines.push(' {') + lines.push(` name: ${quote(type.name)},`) + lines.push(` declaration: ${quote(type.declaration)},`) + lines.push(' },') + } + lines.push( + ']', + '', + '/** The inherited `ctx` surface (cordis core + loader/hmr/timer), in curated order. */', + 'export const INHERITED_CTX_API: readonly InheritedApiEntry[] = [', + ) + for (const inherited of INHERITED_SERVICES) { + lines.push(` { name: ${quote(inherited.name)}, summary: ${quote(inherited.summary)} },`) + } + lines.push(']', '') + return lines.join('\n') +} + +/** CLI entry: default writes the artifact, `--check` fails if the committed + * copy is stale. Guarded behind an entry-point check so importing this module + * for tests neither regenerates the committed file nor calls process.exit. */ +function main(): void { + const content = render() + if (process.argv.includes('--check')) { + let committed: string | null = null + try { + committed = readFileSync(resolve(root, OUT), 'utf8') + } catch { + // Only ENOENT (not yet generated) is expected; a present-but-unreadable + // file is not a state this repo produces. Either way the remedy is the + // same — regenerate — so treat a read failure as "stale". + committed = null + } + if (committed === content) { + console.log(`gen-cordis-api: ${OUT} is up to date.`) + process.exit(0) + } + console.error(`gen-cordis-api: ${OUT} is stale. Run \`pnpm run gen-cordis-api\` and commit ${OUT}.`) + process.exit(1) + } + + writeFileSync(resolve(root, OUT), content) + console.log(`gen-cordis-api: wrote ${OUT}.`) +} + +// Run only when invoked as a script, not when imported by a test. +if (process.argv[1] && import.meta.filename === resolve(process.argv[1])) { + main() +} diff --git a/scripts/gen-cordis-catalog.ts b/scripts/gen-cordis-catalog.ts index 6220006ede..9b8141807e 100644 --- a/scripts/gen-cordis-catalog.ts +++ b/scripts/gen-cordis-catalog.ts @@ -327,7 +327,7 @@ const INHERITED_EVENTS: InheritedEntry[] = [ { name: 'loader/patch-context', summary: 'A context is being patched during a reload.', source: 'vendor/loader/src/index.ts:27' }, ] -const INHERITED_SERVICES: InheritedEntry[] = [ +export const INHERITED_SERVICES: InheritedEntry[] = [ { name: 'ctx.on / ctx.once', summary: 'Register an event listener (disposable).', source: 'vendor/cordis/src/events.ts:29' }, { name: 'ctx.emit / ctx.parallel / ctx.serial / ctx.bail / ctx.waterfall', summary: 'Dispatch an event (sync / awaited / first-bail / veto-chain).', source: 'vendor/cordis/src/events.ts:29' }, { name: 'ctx.plugin / ctx.inject', summary: 'Load a plugin / declare required services.', source: 'vendor/cordis/src/registry.ts:144' }, From e51e58e9934cc3127854f0370ca918d3c0a01bad Mon Sep 17 00:00:00 2001 From: imccyu <276526105+imccyu@users.noreply.github.com> Date: Wed, 8 Jul 2026 11:50:12 +0800 Subject: [PATCH 06/15] chore: register the cordis group across repo gates and docs Everything outside the package and example that a new top-level group and a new demo touch: GROUP_ORDER in gen-module-graph and gen-doc-graphs (plus the tools-service consumers list, the APP_EXAMPLES entry, and the graph-atlas label/mode rows), the knip e2e entries, the packages/README group row, the AGENTS.md layout and demo lines, and the regenerated module-graph / config-catalog / graph-atlas / capability-seams / composition artifacts. AGENTS.md and examples/AGENTS.md word-budget ceilings rise to current+5% (1802 / 653): the new group and demo rows are genuine additions to both docs, not condensable restatements. --- AGENTS.md | 2 ++ docs/capability-seams.md | 4 ++- docs/config-catalog.md | 18 +++++++++++++ docs/graph-atlas.md | 1 + docs/module-graph.md | 5 ++++ examples/AGENTS.md | 1 + examples/README.md | 6 +++++ examples/cordis-agent/composition.md | 40 ++++++++++++++++++++++++++++ knip.json | 1 + packages/README.md | 1 + scripts/doc-budgets.manifest.json | 4 +-- scripts/gen-doc-graphs.ts | 13 ++++++++- scripts/gen-module-graph.ts | 1 + 13 files changed, 93 insertions(+), 4 deletions(-) create mode 100644 examples/cordis-agent/composition.md diff --git a/AGENTS.md b/AGENTS.md index 1ef6af2ba0..c272ad5dda 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -20,6 +20,7 @@ packages/ Harness packages at packages///, all named @deepseek-ai subagent/ subagent seam + spawn/fork/ACP backends + delegation tool todo/ the todo_write tool guard/ loop-hygiene plugins + cordis/ self-referential toolset: the agent inspects/mounts plugins in its own runtime hooks/ Claude Code / Codex hook bridges + shared wire-protocol library session-persistence/ persistence seam + JSONL/SQLite backends ui/ ACP bridge + app-boot glue + the stdio/ACP app bins @@ -48,6 +49,7 @@ pnpm run hygiene # knip + publint + workspace constraints + NodeNext cons pnpm run doc-sync # all documentation gates; see the doc-sync script in package.json pnpm run demo:echo # mock-model REPL, no key needed pnpm run demo:repl # real REPL coding agent (needs DEEPSEEK_API_KEY) +pnpm run demo:cordis # self-referential demo: the agent modifies its own runtime (needs key) pnpm run demo:acp # ACP server agent (needs DEEPSEEK_API_KEY) ``` diff --git a/docs/capability-seams.md b/docs/capability-seams.md index 12ce8033b9..b85fa40305 100644 --- a/docs/capability-seams.md +++ b/docs/capability-seams.md @@ -31,6 +31,7 @@ flowchart LR pkg_tool_web["tool-web"] svc_tools["ctx.tools
Tool registry and execution waterfall"] pkg_tool_bash["tool-bash"] + pkg_tool_cordis["tool-cordis"] pkg_tool_subagent["tool-subagent"] pkg_tool_todo["tool-todo"] svc_agents["ctx.agents
Agent registry"] @@ -121,6 +122,7 @@ flowchart LR svc_tools --> pkg_acp svc_tools --> pkg_agent_loop svc_tools --> pkg_tool_bash + svc_tools --> pkg_tool_cordis svc_tools --> pkg_tool_fs svc_tools --> pkg_tool_subagent svc_tools --> pkg_tool_todo @@ -135,7 +137,7 @@ flowchart LR | `ctx.sessions` | `core` | [`session`](../packages/core/session) | - | [`agent-loop`](../packages/core/agent-loop), [`agent`](../packages/core/agent), [`session-persistence`](../packages/session-persistence/session-persistence), [`subagent-inprocess`](../packages/subagent/subagent-inprocess), [`invariants`](../packages/support/invariants) | - | Owns append-only Session instances and emits the durable session event feed. | | `ctx.sessionPersistence` | `seam` | [`session-persistence`](../packages/session-persistence/session-persistence) | [`session-persistence-jsonl`](../packages/session-persistence/session-persistence-jsonl), [`session-persistence-sqlite`](../packages/session-persistence/session-persistence-sqlite) | [`agent-loop`](../packages/core/agent-loop), [`acp`](../packages/ui/acp) | - | Backends persist the same SessionEvent vocabulary; apps choose a backend at composition time. | | `ctx.systemPrompt` | `core` | [`system-prompt`](../packages/core/system-prompt) | - | [`agent-loop`](../packages/core/agent-loop), [`tools`](../packages/core/tools), [`tool-fs`](../packages/fs/tool-fs), [`tool-web`](../packages/web/tool-web) | - | Collects prompt sections and model-facing tool schemas for each step. | -| `ctx.tools` | `core` | [`tools`](../packages/core/tools) | - | [`agent-loop`](../packages/core/agent-loop), [`tool-bash`](../packages/bash/tool-bash), [`tool-fs`](../packages/fs/tool-fs), [`tool-subagent`](../packages/subagent/tool-subagent), [`tool-todo`](../packages/todo/tool-todo), [`tool-web`](../packages/web/tool-web), [`acp`](../packages/ui/acp) | - | Registers tool definitions, exposes schemas to the prompt, and routes calls through tools/pre-execute and tools/post-execute. | +| `ctx.tools` | `core` | [`tools`](../packages/core/tools) | - | [`agent-loop`](../packages/core/agent-loop), [`tool-bash`](../packages/bash/tool-bash), [`tool-cordis`](../packages/cordis/tool-cordis), [`tool-fs`](../packages/fs/tool-fs), [`tool-subagent`](../packages/subagent/tool-subagent), [`tool-todo`](../packages/todo/tool-todo), [`tool-web`](../packages/web/tool-web), [`acp`](../packages/ui/acp) | - | Registers tool definitions, exposes schemas to the prompt, and routes calls through tools/pre-execute and tools/post-execute. | | `ctx.agents` | `core` | [`agent`](../packages/core/agent) | - | [`agent-loop`](../packages/core/agent-loop), [`acp`](../packages/ui/acp), [`subagent-inprocess`](../packages/subagent/subagent-inprocess), [`stdio-agent`](../packages/ui/stdio-agent), [`invariants`](../packages/support/invariants) | - | Owns live Agent handles and the create/resume factory seam. | | `ctx.agentLoop` | `bundle` | [`agent-loop`](../packages/core/agent-loop) | - | [`agent-core`](../packages/core/agent-core) | - | The one concrete loop plugin; extension packages depend on dsh-agent events and services, not on this package. | | `ctx.bash` | `seam` | [`bash`](../packages/bash/bash) | [`bash-local`](../packages/bash/bash-local) | [`tool-bash`](../packages/bash/tool-bash), [`hooks-claude`](../packages/hooks/hooks-claude), [`hooks-codex`](../packages/hooks/hooks-codex) | - | The model-facing bash tools and hook bridges consume this seam; sandboxed or remote executors can replace bash-local. | diff --git a/docs/config-catalog.md b/docs/config-catalog.md index 2429fe3163..d466bff4c0 100644 --- a/docs/config-catalog.md +++ b/docs/config-catalog.md @@ -670,6 +670,24 @@ export interface Config { Source: [`packages/core/system-prompt/src/index.ts:179`](../packages/core/system-prompt/src/index.ts) +## `@deepseek-ai/dsh-tool-cordis` + +Requires: `tools` + +```ts config-catalog +/** Config for the tool-cordis plugin: the sandbox evaluation bound. */ +export interface Config { + /** + * Milliseconds the SYNCHRONOUS portion of mount code may run in the vm + * before evaluation is aborted (default 5000). An async body escapes this + * bound — see docs/rfc/implemented/feature/2026-07-08-self-referential-cordis-toolset.md for the trust stance. + */ + vmTimeoutMs?: number +} +``` + +Source: [`packages/cordis/tool-cordis/src/index.ts:49`](../packages/cordis/tool-cordis/src/index.ts) + ## `@deepseek-ai/dsh-tool-fs` Requires: `tools` · `fs` · `systemPrompt` diff --git a/docs/graph-atlas.md b/docs/graph-atlas.md index 2a3d674bec..60de01ef81 100644 --- a/docs/graph-atlas.md +++ b/docs/graph-atlas.md @@ -14,6 +14,7 @@ The process decision behind this index is recorded in [the documentation graph R | [capability seams and core services](capability-seams.md) | `hybrid generated` | | [echo-agent app composition](../examples/echo-agent/composition.md) | `hybrid generated` | | [coding-agent app composition](../examples/coding-agent/composition.md) | `hybrid generated` | +| [cordis-agent app composition](../examples/cordis-agent/composition.md) | `hybrid generated` | | [acp-agent app composition](../examples/acp-agent/composition.md) | `hybrid generated` | | [event producer/consumer matrix](event-producer-consumer.md) | `hybrid generated` | | [agent turn and step lifecycle](agent-lifecycle.md) | `curated` | diff --git a/docs/module-graph.md b/docs/module-graph.md index 1e4e70151f..beabf14c69 100644 --- a/docs/module-graph.md +++ b/docs/module-graph.md @@ -61,6 +61,9 @@ flowchart TD subgraph group_todo["packages/todo"] pkg_tool_todo["tool-todo"] end + subgraph group_cordis["packages/cordis"] + pkg_tool_cordis["tool-cordis"] + end subgraph group_hooks["packages/hooks"] pkg_hook_protocol["hook-protocol"] pkg_hooks_claude["hooks-claude"] @@ -164,6 +167,7 @@ flowchart TD pkg_tool_todo --> pkg_agent pkg_tool_todo --> pkg_session pkg_tool_todo --> pkg_tools + pkg_tool_cordis --> pkg_tools pkg_hooks_codex --> pkg_agent pkg_hooks_codex --> pkg_hook_protocol pkg_hooks_codex --> pkg_llm @@ -264,6 +268,7 @@ flowchart TD | [`tool-web`](../packages/web/tool-web) | `web` | [`llm`](../packages/llm/llm), [`system-prompt`](../packages/core/system-prompt), [`tools`](../packages/core/tools), [`web`](../packages/web/web) | | [`timeout-policy`](../packages/timeout/timeout-policy) | `timeout` | [`llm`](../packages/llm/llm), [`timeout`](../packages/util/timeout), [`tools`](../packages/core/tools) | | [`tool-todo`](../packages/todo/tool-todo) | `todo` | [`agent`](../packages/core/agent), [`session`](../packages/core/session), [`tools`](../packages/core/tools) | +| [`tool-cordis`](../packages/cordis/tool-cordis) | `cordis` | [`tools`](../packages/core/tools) | | [`hooks-codex`](../packages/hooks/hooks-codex) | `hooks` | [`agent`](../packages/core/agent), [`hook-protocol`](../packages/hooks/hook-protocol), [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`tools`](../packages/core/tools) | | [`acp`](../packages/ui/acp) | `ui` | [`agent`](../packages/core/agent), [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`session-persistence`](../packages/session-persistence/session-persistence), [`tools`](../packages/core/tools) | | [`repeat-tool-guard`](../packages/guard/repeat-tool-guard) | `guard` | [`agent`](../packages/core/agent), [`tools`](../packages/core/tools) | diff --git a/examples/AGENTS.md b/examples/AGENTS.md index 6c1cc717df..94597371cf 100644 --- a/examples/AGENTS.md +++ b/examples/AGENTS.md @@ -21,6 +21,7 @@ A keyless smoke that spawns the example from a temp cwd must set `TSX_TSCONFIG_P |---|---|---| | `echo-agent` | `tests/echo.e2e.ts` — boots the real `cordis.yml`, drives the echo tool round-trip and the direct canned reply | **N/A — keyless by nature** (the `mock-echo` model has no real provider) | | `coding-agent` | `tests/keyless-smoke.e2e.ts` — boots the full real tree (dummy key, no prompt → no model call), asserts banner + clean exit | `tests/{full-loop,coding-task,resume,compaction,todo-write}.e2e.ts` — real model + real bash + real todo_write, world-verified | +| `cordis-agent` | `tests/keyless-smoke.e2e.ts` — boots the real tree incl. `@deepseek-ai/dsh-tool-cordis` by package name; the tool logic is unit-tested in `packages/cordis/tool-cordis` | `tests/cordis-tools.e2e.ts` — real model mounts a listener (tagged line fires), builds+calls its own tool, composes two mounts via provide/inject | | `acp-agent` | `pnpm run test:snapshot` — boots the real ACP subprocess and replays a recorded session keyless (incl. the hook matrix: a scenario per hook point × outcome for BOTH the Claude and Codex bridges — block, deny, ask, context-fold, force-continue); `tests/acp.e2e.ts` also asserts stdout purity without a key | `tests/acp.e2e.ts` — real ACP prompt, verifies a file the agent wrote; `tests/hooks.e2e.ts` — a real `PreToolUse` hook blocks bash, verifies the file is NOT written | See [the root AGENTS.md](../AGENTS.md) for repo-wide conventions and [docs/architecture.md](../docs/architecture.md) for the design. diff --git a/examples/README.md b/examples/README.md index 1e3134ba2d..c308df73e1 100644 --- a/examples/README.md +++ b/examples/README.md @@ -19,6 +19,12 @@ A REPL agent demo: DeepSeek V4 + the `read`/`write`/`edit` filesystem tools + th Run with: `pnpm run demo:repl` (needs `DEEPSEEK_API_KEY` in the environment or a gitignored repo-root `.env`). See [coding-agent/README.md](coding-agent/README.md) for details. +## cordis-agent + +The **self-referential** demo: the coding spine plus [`@deepseek-ai/dsh-tool-cordis`](../packages/cordis/tool-cordis), whose three tools (`cordis_inspect` / `cordis_mount` / `cordis_unmount`) let the agent inspect the live cordis runtime it runs inside, mount model-written plugins into it (an event listener, a brand-new tool for itself, or a service another mount injects), and dispose them again — all dynamic mounts grouped under one `cordis-dynamic` fiber subtree. + +Run with: `pnpm run demo:cordis` (needs `DEEPSEEK_API_KEY`). See [cordis-agent/README.md](cordis-agent/README.md) for the staged demo script and [the toolset RFC](../docs/rfc/implemented/feature/2026-07-08-self-referential-cordis-toolset.md) for the design and sandbox caveats. + ## acp-agent An agent demo exposed as an **Agent Client Protocol (ACP)** server over JSON-RPC stdio, via the [`@deepseek-ai/dsh-acp-agent`](../packages/ui/acp-agent) app — drive it from Zed or any other ACP client. Also the home of the keyless snapshot tests. diff --git a/examples/cordis-agent/composition.md b/examples/cordis-agent/composition.md new file mode 100644 index 0000000000..6822129c26 --- /dev/null +++ b/examples/cordis-agent/composition.md @@ -0,0 +1,40 @@ + + +# Cordis Agent App Composition + +The self-referential demo puts @deepseek-ai/dsh-tool-cordis on the coding spine, letting the agent inspect its own runtime and mount/unmount plugins into it. + +```mermaid +flowchart LR + cfg["examples/cordis-agent
cordis.yml"] + plugin_cordis_hmr["hmr
@cordisjs/plugin-hmr"] + cfg --> plugin_cordis_hmr + plugin_cordis_llm_deepseek["llm-deepseek
@deepseek-ai/dsh-llm-deepseek"] + cfg --> plugin_cordis_llm_deepseek + plugin_cordis_bash["bash
@deepseek-ai/dsh-bash-local"] + cfg --> plugin_cordis_bash + plugin_cordis_stdio_agent["stdio-agent
@deepseek-ai/dsh-stdio-agent"] + cfg --> plugin_cordis_stdio_agent + plugin_cordis_stdio_agent --> bundle_agent_core["@deepseek-ai/dsh-agent-core"] + plugin_cordis_stdio_agent --> bundle_jsonl["@deepseek-ai/dsh-session-persistence-jsonl"] + plugin_cordis_stdio_agent --> frontdoor_stdio["readline UI
console logger
pre-created main agent"] + bundle_agent_core --> spine_llm["ctx.llm"] + bundle_agent_core --> spine_sessions["ctx.sessions"] + bundle_agent_core --> spine_tools["ctx.tools + tool-bash"] + bundle_agent_core --> spine_loop["ctx.agents + ctx.agentLoop"] + plugin_cordis_tool_cordis["tool-cordis
@deepseek-ai/dsh-tool-cordis"] + cfg --> plugin_cordis_tool_cordis +``` + +| Plugin id | Package / module | +| --- | --- | +| `hmr` | `@cordisjs/plugin-hmr` | +| `llm-deepseek` | `@deepseek-ai/dsh-llm-deepseek` | +| `bash` | `@deepseek-ai/dsh-bash-local` | +| `stdio-agent` | `@deepseek-ai/dsh-stdio-agent` | +| `tool-cordis` | `@deepseek-ai/dsh-tool-cordis` | + +Source config: [`examples/cordis-agent/cordis.yml`](cordis.yml). + +Maintenance mode: hybrid: the leaf plugin list is parsed from its `cordis.yml`; app package expansion is curated from package source. diff --git a/knip.json b/knip.json index 407f892775..198cad3cce 100644 --- a/knip.json +++ b/knip.json @@ -8,6 +8,7 @@ "examples/echo-agent/src/*.ts", "examples/echo-agent/tests/**/*.e2e.ts", "examples/coding-agent/tests/**/*.e2e.ts", + "examples/cordis-agent/tests/**/*.e2e.ts", "examples/acp-agent/tests/**/*.e2e.ts", "examples/*/tests/**/*.snapshot.ts" ], diff --git a/packages/README.md b/packages/README.md index bc09826777..d7c3c4caf1 100644 --- a/packages/README.md +++ b/packages/README.md @@ -19,6 +19,7 @@ Packages are grouped by modular role at `packages///`. The group dir | [`timeout/`](timeout/README.md) | Tool-call timeout policy: the `tools/execute` deadline enforcer | Product — stable surface | | [`todo/`](todo/README.md) | Todo/planning family: the model-facing `todo_write` tool | Product — stable surface | | [`guard/`](guard/README.md) | Loop-hygiene guards: advisory repeat-call reminders | Product — stable surface | +| [`cordis/`](cordis/README.md) | Self-referential runtime toolset: inspect the live runtime's plugins and services, mount/unmount model-written plugins ([design](../docs/rfc/implemented/feature/2026-07-08-self-referential-cordis-toolset.md)) | Product — stable surface | | [`hooks/`](hooks/README.md) | Hook bridges + the shared Claude Code / Codex wire-protocol library | Product — stable surface | | [`session-persistence/`](session-persistence/README.md) | Persistence capability family: the seam + JSONL/SQLite backends | Product — stable surface | | [`ui/`](ui/README.md) | Editor/client integration surfaces (the ACP bridge) + the app packages | Product — stable surface | diff --git a/scripts/doc-budgets.manifest.json b/scripts/doc-budgets.manifest.json index 337fc57763..8cadde12e9 100644 --- a/scripts/doc-budgets.manifest.json +++ b/scripts/doc-budgets.manifest.json @@ -1,11 +1,11 @@ { - "AGENTS.md": 1691, + "AGENTS.md": 1802, "docs/AGENTS.md": 1315, "docs/architecture.md": 1640, "docs/cordis-primer.md": 550, "docs/defensive-patterns.md": 550, "docs/testing.md": 800, - "examples/AGENTS.md": 610, + "examples/AGENTS.md": 653, "packages/AGENTS.md": 450, "packages/README.md": 610 } diff --git a/scripts/gen-doc-graphs.ts b/scripts/gen-doc-graphs.ts index 14396a6645..d8d320df33 100644 --- a/scripts/gen-doc-graphs.ts +++ b/scripts/gen-doc-graphs.ts @@ -75,6 +75,7 @@ const GROUP_ORDER = [ 'subagent', 'web', 'todo', + 'cordis', 'hooks', 'session-persistence', 'support', @@ -121,7 +122,7 @@ const SERVICE_ROLES: ServiceRole[] = [ pkg: 'tools', title: 'Tool registry and execution waterfall', mode: 'core', - consumers: ['agent-loop', 'tool-bash', 'tool-fs', 'tool-subagent', 'tool-todo', 'tool-web', 'acp'], + consumers: ['agent-loop', 'tool-bash', 'tool-cordis', 'tool-fs', 'tool-subagent', 'tool-todo', 'tool-web', 'acp'], note: 'Registers tool definitions, exposes schemas to the prompt, and routes calls through tools/pre-execute and tools/post-execute.', }, { @@ -409,6 +410,14 @@ const APP_EXAMPLES = [ config: 'examples/coding-agent/cordis.yml', summary: 'The coding REPL demo adds the real DeepSeek adapter, filesystem tools, todo_write, compaction, and both subagent transports on top of the stdio app package.', }, + { + id: 'cordis', + rel: 'examples/cordis-agent/composition.md', + title: 'Cordis Agent App Composition', + label: 'examples/cordis-agent', + config: 'examples/cordis-agent/cordis.yml', + summary: 'The self-referential demo puts @deepseek-ai/dsh-tool-cordis on the coding spine, letting the agent inspect its own runtime and mount/unmount plugins into it.', + }, { id: 'acp', rel: 'examples/acp-agent/composition.md', @@ -718,6 +727,7 @@ function renderIndex(docs: GraphDoc[]): string { 'docs/capability-seams.md': 'capability seams and core services', 'examples/echo-agent/composition.md': 'echo-agent app composition', 'examples/coding-agent/composition.md': 'coding-agent app composition', + 'examples/cordis-agent/composition.md': 'cordis-agent app composition', 'examples/acp-agent/composition.md': 'acp-agent app composition', 'docs/event-producer-consumer.md': 'event producer/consumer matrix', 'docs/agent-lifecycle.md': 'agent turn and step lifecycle', @@ -728,6 +738,7 @@ function renderIndex(docs: GraphDoc[]): string { 'docs/capability-seams.md': 'hybrid generated', 'examples/echo-agent/composition.md': 'hybrid generated', 'examples/coding-agent/composition.md': 'hybrid generated', + 'examples/cordis-agent/composition.md': 'hybrid generated', 'examples/acp-agent/composition.md': 'hybrid generated', 'docs/event-producer-consumer.md': 'hybrid generated', 'docs/agent-lifecycle.md': 'curated', diff --git a/scripts/gen-module-graph.ts b/scripts/gen-module-graph.ts index fe39d325f8..dc66dc843e 100644 --- a/scripts/gen-module-graph.ts +++ b/scripts/gen-module-graph.ts @@ -47,6 +47,7 @@ const GROUP_ORDER = [ 'web', 'timeout', 'todo', + 'cordis', 'hooks', 'session-persistence', 'support', From db4576951320b1d7e73c320c8519a4f9a6657012 Mon Sep 17 00:00:00 2001 From: imccyu <276526105+imccyu@users.noreply.github.com> Date: Wed, 8 Jul 2026 11:51:24 +0800 Subject: [PATCH 07/15] feat(tool-cordis): Node-API traps + fs/web capability routing MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The sandbox deliberately provides no Node API, and now says so instead of letting a bare ReferenceError teach nothing: require, the timers, and fetch are callable traps whose error redirects to the cordis alternative (inject: ['fs'] + ctx.fs, ['web'] + ctx.web, ['bash'] + ctx.bash, ['timer'] + ctx.setTimeout — a fiber effect, unwound on unmount). Only function-shaped globals are trapped; process/Buffer stay undefined so typeof feature probes stay inert. The mount description and the demo persona state the routing rule, and the demo mounts ctx.fs (local provider) and ctx.web (seam + keyless local fetch provider) so agent-built plugins have real capabilities to build on. Live-validated: a model that reached for Node setTimeout self-corrected to inject: ['timer'] in one step and built a working ctx.web fetch tool. --- docs/tool-catalog.md | 2 +- examples/README.md | 2 +- examples/cordis-agent/README.md | 2 +- examples/cordis-agent/composition.md | 9 +++ examples/cordis-agent/cordis.yml | 27 +++++++-- packages/cordis/tool-cordis/src/index.ts | 9 ++- packages/cordis/tool-cordis/src/sandbox.ts | 59 ++++++++++++++++--- .../cordis/tool-cordis/tests/mount.spec.ts | 37 +++++++++++- 8 files changed, 129 insertions(+), 18 deletions(-) diff --git a/docs/tool-catalog.md b/docs/tool-catalog.md index e77716f736..f0a3fab35d 100644 --- a/docs/tool-catalog.md +++ b/docs/tool-catalog.md @@ -136,7 +136,7 @@ Source: [`packages/cordis/tool-cordis/src/index.ts`](../packages/cordis/tool-cor ### `cordis_mount` -Mount a NEW cordis plugin into the live runtime that is running THIS agent (self-modification). `code` runs as the body of an async JavaScript function in an isolated sandbox and MUST `return` a plugin. Two forms: FUNCTION form `return (ctx) => { … }` — cannot declare inject, uses whatever services are on the parent context, and accessing a service without inject (e.g. ctx.bash) throws; use it only when you need no injected services. OBJECT form `return { name?, inject: ['bash', 'llm', …], apply(ctx) { … } }` — declares dependencies, and cordis activates the plugin only after the services exist; PREFER this form for any plugin that needs bash, llm, sessions, etc. BEFORE calling a service from your code, read cordis_inspect what:"api" — it lists method signatures AND the type shapes of their arguments/returns (do not guess a field's type; e.g. a bash run's stdout is an object, not a string). Inside `apply`, use the standard cordis API: `ctx.on(event, listener)` to observe events (see cordis_inspect what:"events"), or call `harness.registerTool(ctx, harness.defineTool({ name, description, parameters: { text: { type: 'string', required: true } }, async execute(args) { … } }))` to give yourself a new tool — it becomes callable on your NEXT step. A tool's `execute` MUST return an ARRAY of content blocks, e.g. `return [{ type: 'text', text: someString }]` — never a bare string. Mounts can COMPOSE: one plugin may `ctx.provide('name', value)` a service and another may declare `inject: ['name']` to consume it — the consumer stays pending until the provider exists and returns to pending when the provider is unmounted. Everything registered inside `apply` is cleaned up automatically on unmount. Sandbox globals: `console` (tagged `[cordis:]`, writes through to the harness terminal), `harness.defineTool`, `harness.registerTool`, `btoa`, `atob`, `TextEncoder`, `TextDecoder`; there is no `require`, `process`, `Buffer`, or network. Write PLAIN JavaScript, not TypeScript (no `as`, no type annotations). Cautions: (1) waterfall events (e.g. tools/pre-execute) hand the listener a trailing `next` callback which MUST be called — returning without `next()` VETOES the call; prefer plain notification events unless you intend to intercept. (2) Never await something that only resolves after the current turn (your code runs INSIDE a tool call of that turn — it would deadlock). (3) The sandbox prevents accidental global pollution, not malice: `ctx` is the real, fully privileged runtime handle. +Mount a NEW cordis plugin into the live runtime that is running THIS agent (self-modification). `code` runs as the body of an async JavaScript function in an isolated sandbox and MUST `return` a plugin. Two forms: FUNCTION form `return (ctx) => { … }` — cannot declare inject, uses whatever services are on the parent context, and accessing a service without inject (e.g. ctx.bash) throws; use it only when you need no injected services. OBJECT form `return { name?, inject: ['bash', 'llm', …], apply(ctx) { … } }` — declares dependencies, and cordis activates the plugin only after the services exist; PREFER this form for any plugin that needs bash, llm, sessions, etc. BEFORE calling a service from your code, read cordis_inspect what:"api" — it lists method signatures AND the type shapes of their arguments/returns (do not guess a field's type; e.g. a bash run's stdout is an object, not a string). Inside `apply`, use the standard cordis API: `ctx.on(event, listener)` to observe events (see cordis_inspect what:"events"), or call `harness.registerTool(ctx, harness.defineTool({ name, description, parameters: { text: { type: 'string', required: true } }, async execute(args) { … } }))` to give yourself a new tool — it becomes callable on your NEXT step. A tool's `execute` MUST return an ARRAY of content blocks, e.g. `return [{ type: 'text', text: someString }]` — never a bare string. Mounts can COMPOSE: one plugin may `ctx.provide('name', value)` a service and another may declare `inject: ['name']` to consume it — the consumer stays pending until the provider exists and returns to pending when the provider is unmounted. Everything registered inside `apply` is cleaned up automatically on unmount. Sandbox globals: `console` (tagged `[cordis:]`, writes through to the harness terminal), `harness.defineTool`, `harness.registerTool`, `btoa`, `atob`, `TextEncoder`, `TextDecoder`. Node APIs are DISABLED — do filesystem/network/timer work through the cordis services, never Node built-ins: `require`, `setTimeout`/`setInterval`, and `fetch` throw redirect errors; `process` and `Buffer` are undefined. Instead use inject: ['fs'] + ctx.fs for files, inject: ['web'] + ctx.web for HTTP, inject: ['bash'] + ctx.bash for processes, and inject: ['timer'] + ctx.setTimeout/ctx.setInterval for timing (fiber effects, auto-cleaned on unmount) — cordis_inspect what:"api" shows what THIS runtime provides. Write PLAIN JavaScript, not TypeScript (no `as`, no type annotations). Cautions: (1) waterfall events (e.g. tools/pre-execute) hand the listener a trailing `next` callback which MUST be called — returning without `next()` VETOES the call; prefer plain notification events unless you intend to intercept. (2) Never await something that only resolves after the current turn (your code runs INSIDE a tool call of that turn — it would deadlock). (3) The sandbox prevents accidental global pollution, not malice: `ctx` is the real, fully privileged runtime handle. ```json { diff --git a/examples/README.md b/examples/README.md index c308df73e1..c86f83022a 100644 --- a/examples/README.md +++ b/examples/README.md @@ -21,7 +21,7 @@ Run with: `pnpm run demo:repl` (needs `DEEPSEEK_API_KEY` in the environment or a ## cordis-agent -The **self-referential** demo: the coding spine plus [`@deepseek-ai/dsh-tool-cordis`](../packages/cordis/tool-cordis), whose three tools (`cordis_inspect` / `cordis_mount` / `cordis_unmount`) let the agent inspect the live cordis runtime it runs inside, mount model-written plugins into it (an event listener, a brand-new tool for itself, or a service another mount injects), and dispose them again — all dynamic mounts grouped under one `cordis-dynamic` fiber subtree. +The **self-referential** demo: the coding spine plus [`@deepseek-ai/dsh-tool-cordis`](../packages/cordis/tool-cordis), whose three tools (`cordis_inspect` / `cordis_mount` / `cordis_unmount`) let the agent inspect the live cordis runtime it runs inside, mount model-written plugins into it (an event listener, a brand-new tool for itself, or a service another mount injects), and dispose them again — all dynamic mounts grouped under one `cordis-dynamic` fiber subtree. The `ctx.fs`/`ctx.web` services ride along provider-only, as the capabilities those plugins build on. Run with: `pnpm run demo:cordis` (needs `DEEPSEEK_API_KEY`). See [cordis-agent/README.md](cordis-agent/README.md) for the staged demo script and [the toolset RFC](../docs/rfc/implemented/feature/2026-07-08-self-referential-cordis-toolset.md) for the design and sandbox caveats. diff --git a/examples/cordis-agent/README.md b/examples/cordis-agent/README.md index ba9365498b..953533d35b 100644 --- a/examples/cordis-agent/README.md +++ b/examples/cordis-agent/README.md @@ -1,6 +1,6 @@ # cordis-agent -The self-referential harness demo: the coding-agent spine (DeepSeek V4 + local bash on the stdio chat app) plus [`@deepseek-ai/dsh-tool-cordis`](../../packages/cordis/tool-cordis/README.md), which hands the model three tools over the **live cordis runtime it is running inside** — inspect it, mount new plugins into it, and dispose them again. The design (sandbox semantics, mount lifecycle, cross-mount composition, caveats) lives in [the toolset RFC](../../docs/rfc/implemented/feature/2026-07-08-self-referential-cordis-toolset.md). +The self-referential harness demo: the coding-agent spine (DeepSeek V4 + local bash on the stdio chat app) plus [`@deepseek-ai/dsh-tool-cordis`](../../packages/cordis/tool-cordis/README.md), which hands the model three tools over the **live cordis runtime it is running inside** — inspect it, mount new plugins into it, and dispose them again. The `ctx.fs` and `ctx.web` services are mounted (provider-only, no model-facing file/web tools) so the plugins the agent writes have real capabilities to build on; Node built-ins are trapped in the sandbox and redirect to those services. The design (sandbox semantics, mount lifecycle, cross-mount composition, caveats) lives in [the toolset RFC](../../docs/rfc/implemented/feature/2026-07-08-self-referential-cordis-toolset.md). ## Run it diff --git a/examples/cordis-agent/composition.md b/examples/cordis-agent/composition.md index 6822129c26..015bec724e 100644 --- a/examples/cordis-agent/composition.md +++ b/examples/cordis-agent/composition.md @@ -14,6 +14,12 @@ flowchart LR cfg --> plugin_cordis_llm_deepseek plugin_cordis_bash["bash
@deepseek-ai/dsh-bash-local"] cfg --> plugin_cordis_bash + plugin_cordis_fs_local["fs-local
@deepseek-ai/dsh-fs-local"] + cfg --> plugin_cordis_fs_local + plugin_cordis_web["web
@deepseek-ai/dsh-web"] + cfg --> plugin_cordis_web + plugin_cordis_web_fetch_local["web-fetch-local
@deepseek-ai/dsh-web-fetch-local"] + cfg --> plugin_cordis_web_fetch_local plugin_cordis_stdio_agent["stdio-agent
@deepseek-ai/dsh-stdio-agent"] cfg --> plugin_cordis_stdio_agent plugin_cordis_stdio_agent --> bundle_agent_core["@deepseek-ai/dsh-agent-core"] @@ -32,6 +38,9 @@ flowchart LR | `hmr` | `@cordisjs/plugin-hmr` | | `llm-deepseek` | `@deepseek-ai/dsh-llm-deepseek` | | `bash` | `@deepseek-ai/dsh-bash-local` | +| `fs-local` | `@deepseek-ai/dsh-fs-local` | +| `web` | `@deepseek-ai/dsh-web` | +| `web-fetch-local` | `@deepseek-ai/dsh-web-fetch-local` | | `stdio-agent` | `@deepseek-ai/dsh-stdio-agent` | | `tool-cordis` | `@deepseek-ai/dsh-tool-cordis` | diff --git a/examples/cordis-agent/cordis.yml b/examples/cordis-agent/cordis.yml index b5e08c8325..65d5e6eb36 100644 --- a/examples/cordis-agent/cordis.yml +++ b/examples/cordis-agent/cordis.yml @@ -36,6 +36,23 @@ config: timeoutMs: 60000 +# Filesystem service for mounted plugins (ctx.fs) — the local provider only. +# The model-facing read/write/edit tools stay unmounted on purpose: this demo +# is about the agent building its own tools over the services. +- id: fs-local + name: '@deepseek-ai/dsh-fs-local' + config: + cwd: !!js process.cwd() + +# Web service for mounted plugins (ctx.web): the seam plus the anonymous local +# fetch provider (keyless). No search provider is loaded — ctx.web search +# calls fail loud until a deployment adds one. +- id: web + name: '@deepseek-ai/dsh-web' + +- id: web-fetch-local + name: '@deepseek-ai/dsh-web-fetch-local' + # The stdio chat app: the whole spine + front-door cluster, configured for the # self-referential demo driving a pre-created `main` agent. - id: stdio-agent @@ -54,10 +71,12 @@ `events` sections document the service methods, type shapes, and events your plugin code can use), cordis_mount to add a plugin (an event listener, a brand-new tool for yourself, or a service other mounts - inject), cordis_unmount to clean one up. Prefer small single-purpose - plugins, prefer plain notification events over waterfall events unless - you intend to intercept, and unmount what you no longer need. Report - results briefly. + inject), cordis_unmount to clean one up. In mounted code, NEVER use Node + built-ins (require/setTimeout/fetch) — use the runtime's cordis services + via inject: fs, web, bash, and timer (ctx.setTimeout). Prefer small + single-purpose plugins, prefer plain notification events over waterfall + events unless you intend to intercept, and unmount what you no longer + need. Report results briefly. # The self-referential cordis toolset (loaded after the app so ctx.tools exists). - id: tool-cordis diff --git a/packages/cordis/tool-cordis/src/index.ts b/packages/cordis/tool-cordis/src/index.ts index d4492b4768..de028b384a 100644 --- a/packages/cordis/tool-cordis/src/index.ts +++ b/packages/cordis/tool-cordis/src/index.ts @@ -152,8 +152,13 @@ export function apply(ctx: Context, config: Config): void { + 'Everything registered inside `apply` is cleaned up automatically on unmount. ' + 'Sandbox globals: `console` (tagged `[cordis:]`, writes through to the harness ' + 'terminal), `harness.defineTool`, `harness.registerTool`, ' - + '`btoa`, `atob`, `TextEncoder`, `TextDecoder`; ' - + 'there is no `require`, `process`, `Buffer`, or network. ' + + '`btoa`, `atob`, `TextEncoder`, `TextDecoder`. ' + + 'Node APIs are DISABLED — do filesystem/network/timer work through the cordis services, ' + + 'never Node built-ins: `require`, `setTimeout`/`setInterval`, and `fetch` throw redirect ' + + 'errors; `process` and `Buffer` are undefined. Instead use inject: [\'fs\'] + ctx.fs for ' + + 'files, inject: [\'web\'] + ctx.web for HTTP, inject: [\'bash\'] + ctx.bash for processes, ' + + 'and inject: [\'timer\'] + ctx.setTimeout/ctx.setInterval for timing (fiber effects, ' + + 'auto-cleaned on unmount) — cordis_inspect what:"api" shows what THIS runtime provides. ' + 'Write PLAIN JavaScript, not TypeScript (no `as`, no type annotations). ' + 'Cautions: (1) waterfall events (e.g. tools/pre-execute) hand the listener a ' + 'trailing `next` callback which MUST be called — returning without `next()` ' diff --git a/packages/cordis/tool-cordis/src/sandbox.ts b/packages/cordis/tool-cordis/src/sandbox.ts index 4d3eb16dfc..add858f3ce 100644 --- a/packages/cordis/tool-cordis/src/sandbox.ts +++ b/packages/cordis/tool-cordis/src/sandbox.ts @@ -1,10 +1,16 @@ /** * The `node:vm` sandbox `cordis_mount` code evaluates in: a fresh realm whose * globals are a tagged write-through console, the `harness` registration - * helpers, and the encoding primitives a bare vm context lacks. The sandbox - * guards against ACCIDENTAL global pollution only — it is not a security - * boundary; the `ctx` a mounted plugin's `apply` later receives is the real, - * fully privileged runtime handle, and that is the point of the toolset. + * helpers, the encoding primitives a bare vm context lacks, and callable traps + * over the Node APIs the sandbox deliberately withholds. Capability access is + * routed through cordis services, never Node built-ins: filesystem work goes + * through `ctx.fs`, network through `ctx.web`, processes through `ctx.bash`, + * timers through the `ctx.timer` helpers (fiber effects, unwound on unmount) + * — so everything a mounted plugin does stays inspectable and disposable. The + * sandbox guards against ACCIDENTAL global pollution only — it is not a + * security boundary; the `ctx` a mounted plugin's `apply` later receives is + * the real, fully privileged runtime handle, and that is the point of the + * toolset. * * @module @deepseek-ai/dsh-tool-cordis/sandbox */ @@ -60,19 +66,58 @@ function patchDualRealmInstanceof(sandbox: object): void { patch({ Object, Array, Function, Error, TypeError, RangeError, SyntaxError, Promise, RegExp, Date, Map, Set }) } +const TIMER_REDIRECT + = 'Node timers are unavailable. Use the cordis timer service instead: declare inject: [\'timer\'] on your plugin ' + + 'and call ctx.setTimeout / ctx.setInterval — those are fiber effects, cleaned up automatically on unmount.' + +/** + * The callable Node APIs the sandbox deliberately disables, each mapped to the + * cordis alternative its trap error names. Only FUNCTION-shaped globals are + * trapped — a data-shaped global like `process` stays `undefined`, because a + * throwing accessor would detonate the common `typeof process` feature probe + * at resolution time. + */ +const NODE_API_REDIRECTS: Record = { + require: + 'Node modules are unavailable. Use the cordis services on ctx instead — e.g. inject: [\'fs\'] for files, ' + + '[\'web\'] for HTTP, [\'bash\'] for processes; cordis_inspect what:"api" lists what THIS runtime provides.', + setTimeout: TIMER_REDIRECT, + setInterval: TIMER_REDIRECT, + setImmediate: TIMER_REDIRECT, + clearTimeout: TIMER_REDIRECT, + clearInterval: TIMER_REDIRECT, + fetch: + 'Network access goes through the cordis web service: declare inject: [\'web\'] and call ctx.web ' + + '(see cordis_inspect what:"api" for its methods).', +} + +/** Build the trap functions for {@link NODE_API_REDIRECTS}: calling one throws the redirect. */ +function nodeApiTraps(): Record never> { + const traps: Record never> = {} + for (const [name, redirect] of Object.entries(NODE_API_REDIRECTS)) { + traps[name] = () => { + throw new Error(`${name} is not available in the mount sandbox — ${redirect}`) + } + } + return traps +} + /** * Build the vm context one `cordis_mount` call evaluates in: the tagged - * console, the `harness` registration helpers, the encoding primitives, and - * the dual-realm `instanceof` patch, already `createContext`-ed. + * console, the `harness` registration helpers, the encoding primitives, the + * Node-API traps, and the dual-realm `instanceof` patch, already + * `createContext`-ed. * @param id - the mount id (`dyn-`), used as the console tag and filename stem. * @returns the contextified sandbox object to pass to {@link evaluateMountCode}. */ export function createSandbox(id: string): object { const sandbox = { + ...nodeApiTraps(), console: taggedConsole(id), harness: { defineTool: sandboxDefineTool, registerTool: sandboxRegisterTool }, // Web APIs absent from fresh vm contexts — made available so the model - // can encode/decode base64 without Buffer (which is also absent). + // can encode/decode base64 without Buffer (which is also absent). Host + // closures over Buffer, never Buffer itself. btoa: (s: string) => Buffer.from(s, 'utf-8').toString('base64'), atob: (s: string) => Buffer.from(s, 'base64').toString('utf-8'), TextEncoder, diff --git a/packages/cordis/tool-cordis/tests/mount.spec.ts b/packages/cordis/tool-cordis/tests/mount.spec.ts index 5bdde09b53..03038f818c 100644 --- a/packages/cordis/tool-cordis/tests/mount.spec.ts +++ b/packages/cordis/tool-cordis/tests/mount.spec.ts @@ -284,12 +284,12 @@ describe('cordis_mount', () => { expect(retry.isError).toBe(false) }) - it('isolates sandbox globals: no process/require, and globalThis writes do not leak to the host', async () => { + it('isolates sandbox globals: no process/Buffer, and globalThis writes do not leak to the host', async () => { const ctx = await setup() const result = await call(ctx, 'cordis_mount', { code: ` globalThis.__cordis_tool_leak = 'leaked' - return { name: 'probe-' + typeof process + '-' + typeof require, apply(ctx) {} } + return { name: 'probe-' + typeof process + '-' + typeof Buffer, apply(ctx) {} } `, }) expect(result.isError).toBe(false) @@ -297,6 +297,39 @@ describe('cordis_mount', () => { expect((globalThis as Record).__cordis_tool_leak).toBeUndefined() }) + it.each([ + ['require(\'fs\')', 'require is not available in the mount sandbox', 'inject: [\'fs\']'], + ['setTimeout(() => {}, 5)', 'setTimeout is not available in the mount sandbox', 'ctx.setTimeout'], + ['fetch(\'https://example.com\')', 'fetch is not available in the mount sandbox', 'ctx.web'], + ])('traps the Node API call %s with a redirect to the cordis alternative', async (invocation, trapMessage, redirect) => { + const ctx = await setup() + const result = await call(ctx, 'cordis_mount', { code: `${invocation}\nreturn (ctx) => {}` }) + expect(result.isError).toBe(true) + expect(text(result)).toContain(trapMessage) + expect(text(result)).toContain(redirect) + expect(text(await call(ctx, 'cordis_inspect', { what: 'dynamic' }))).toContain('(no dynamic plugins mounted)') + }) + + it('lets a mounted plugin schedule through the cordis timer service (inject: [\'timer\'])', async () => { + const ctx = await setup() + const log = vi.spyOn(console, 'log').mockImplementation(() => {}) + const result = await call(ctx, 'cordis_mount', { + code: ` + return { + name: 'ticker', + inject: ['timer'], + apply(ctx) { + ctx.setTimeout(() => console.log('tick'), 10) + }, + } + `, + }) + expect(result.isError).toBe(false) + expect(text(result)).toContain('state: active') + await new Promise(resolve => setTimeout(resolve, 50)) + expect(log).toHaveBeenCalledWith('[cordis:dyn-1]', 'tick') + }) + it('provides btoa/atob and the tagged console variants inside the sandbox', async () => { const ctx = await setup() const log = vi.spyOn(console, 'log').mockImplementation(() => {}) From a500c791f7faa2a29437a8a446f73541e0f056fb Mon Sep 17 00:00:00 2001 From: imccyu <276526105+imccyu@users.noreply.github.com> Date: Wed, 8 Jul 2026 14:51:35 +0800 Subject: [PATCH 08/15] fix(tool-cordis): normalize the JSON-Schema dialect at the defineTool boundary MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Field sessions showed models writing tool schemas in the JSON-Schema dialect by strong prior — type: 'integer', required: false, then the full { type:'object', properties, required: [...] } wrapper — and the rejection text itself pushed a nearly-correct DSL attempt BACK to raw JSON Schema: one stats tool cost three consecutive schema errors before mounting. The boundary now normalizes wherever the input has exactly one meaning (wrapper unwrapped with the required array becoming per-property flags at any nesting level, integer → number, required: false → optional, all rebuilt as fresh host-realm objects) and rejects only genuinely meaningless input, enumerating the valid vocabulary in the error. Re-running the failing session mounts first-try. The mount description documents both accepted forms. --- ...6-07-08-self-referential-cordis-toolset.md | 4 +- docs/tool-catalog.md | 2 +- packages/cordis/tool-cordis/src/guard.ts | 102 ++++++++++++------ packages/cordis/tool-cordis/src/index.ts | 5 +- .../cordis/tool-cordis/tests/mount.spec.ts | 68 ++++++++++-- 5 files changed, 132 insertions(+), 49 deletions(-) diff --git a/docs/rfc/implemented/feature/2026-07-08-self-referential-cordis-toolset.md b/docs/rfc/implemented/feature/2026-07-08-self-referential-cordis-toolset.md index 95cb12b571..14e05b0afd 100644 --- a/docs/rfc/implemented/feature/2026-07-08-self-referential-cordis-toolset.md +++ b/docs/rfc/implemented/feature/2026-07-08-self-referential-cordis-toolset.md @@ -32,7 +32,7 @@ Sandbox globals are deliberately small: a tagged write-through `console` (`[cord Three boundary mechanisms make model-written code behave correctly across the realm seam. **Dual-realm `instanceof`**: most objects sandbox code touches are host-realm (tool `args`, event payloads, service returns), so a plain `x instanceof Array` in the vm would silently be false — a per-sandbox prelude gives the vm realm's own constructors a `Symbol.hasInstance` that checks both the vm constructor and its host counterpart, patching only vm-realm globals. **Realm normalization of tool results**: objects built inside the vm carry the vm realm's `Object.prototype`, which the session log's append-time plainness check (`isJsonValue` in `dsh-session`, a prototype-identity comparison) rejects, so the sandbox's `harness.defineTool` JSON round-trips every `execute` return into the host realm — which also projects it onto exactly what the log durably stores. **Guarded registration**: the `ctx` a mounted plugin receives is a proxy whose `tools.register` accepts only definitions returned by `harness.defineTool` (a marker symbol), so every dynamic tool passes SchemaSpec validation and realm normalization; everything else on `ctx` passes through with correct `this` binding, which is what keeps cross-mount `provide`/`inject` working. -Boundary errors are written around the mistakes models actually make (see [Consequences](#consequences) for how each was found): JSON Schema where the SchemaSpec DSL is expected gets a ✗/✓ example pair; an unbalanced `});` closing gets the vm's offending source line plus a "code is a function body" reminder; TypeScript syntax gets the remove-annotations fix (detected on the failing line only, so an ` as ` inside a description string does not misfire); a forgotten `return` gets the two valid plugin forms; a Node built-in call gets the redirect to its cordis service; a tool-name collision on re-mount gets the unmount-first-then-remount recipe. +Boundary errors are written around the mistakes models actually make (see [Consequences](#consequences) for how each was found), and the boundary normalizes rather than lectures wherever the input has exactly one meaning: schema `parameters` accept the JSON-Schema dialect models write by strong prior — the `{ type: 'object', properties, required: […] }` wrapper unwraps to the SchemaSpec DSL (the `required` array becoming per-property flags, at any nesting level), `type: 'integer'` maps to `number`, and `required: false` reads as optional — while genuinely meaningless input is rejected with the vocabulary enumerated (an unknown type lists the five valid ones; a non-boolean `required` names the rule). The remaining teaching errors: an unbalanced `});` closing gets the vm's offending source line plus a "code is a function body" reminder; TypeScript syntax gets the remove-annotations fix (detected on the failing line only, so an ` as ` inside a description string does not misfire); a forgotten `return` gets the two valid plugin forms; a Node built-in call gets the redirect to its cordis service; a tool-name collision on re-mount gets the unmount-first-then-remount recipe. ### The dynamic group and mount lifecycle @@ -79,6 +79,6 @@ The correctness investment therefore goes where it pays for every capability at The toolset is a deliberate opt-in with a fully-privileged `ctx`, so a deployment adopts it as consciously as a bash tool. Several facts follow that the tool descriptions warn the model about directly: a waterfall listener (e.g. `tools/pre-execute`) that returns without calling `next()` vetoes the chain, so a mounted listener can lobotomize the agent's own tool dispatch ([waterfall semantics](../../../cordis-primer.md#cordis-waterfall-semantics)); mount code runs inside a tool call of the current turn, so awaiting anything that resolves only after the turn deadlocks; `vmTimeoutMs` bounds synchronous evaluation only; and mounts do not survive session resume. -The instructive boundary errors were not guessed — they were written against a live self-design session in which a real model was asked to build itself coding tools. That session surfaced the failure modes now mitigated: the model closed a returned plugin object with `});` and got only a bare `Unexpected token ')'` it retried blind; it hit a false-positive "this is TypeScript" hint because a description string contained the word "as"; and, most costly, it guessed a bash run's `stdout` was a string and burned six steps building throwaway debug tools to discover it is `{ text, truncated }`. The fixes — source-line-plus-caret parse errors, line-scoped TypeScript detection, the type-shape closure in the API catalog, and the redirect traps — cut a second session from dozens of tool calls with repeated errors to a first-try success on every capability, including a model that hit a Node-`setTimeout` trap and self-corrected to `inject: ['timer']` in one step. +The instructive boundary errors were not guessed — they were written against live self-design sessions in which a real model was asked to build itself coding tools. Those sessions surfaced the failure modes now mitigated: the model closed a returned plugin object with `});` and got only a bare `Unexpected token ')'` it retried blind; it hit a false-positive "this is TypeScript" hint because a description string contained the word "as"; it guessed a bash run's `stdout` was a string and burned six steps building throwaway debug tools to discover it is `{ text, truncated }`; and it wrote tool schemas in the JSON-Schema dialect (`type: 'integer'`, `required: false`, then the full wrapper) three rejections in a row — the rejection text itself pushing it from a nearly-correct DSL attempt back to raw JSON Schema. The fixes — source-line-plus-caret parse errors, line-scoped TypeScript detection, the type-shape closure in the API catalog, the redirect traps, and schema-dialect normalization in place of rejection — cut later sessions from dozens of tool calls with repeated errors to a first-try success on every capability, including a model that hit a Node-`setTimeout` trap and self-corrected to `inject: ['timer']` in one step. Coverage is named per tier: package unit specs drive the three tools through a real `ToolRegistry` on a real fiber tree (the mount success/failure family, vm isolation, dual-realm `instanceof`, realm normalization against the real `isJsonValue`, the SchemaSpec and raw-registration rejections, the Node-API traps, the cross-mount provide/inject matrix, catalog-backed `api`/`events` rendering, config validation, presenters, quiescent unmount, and the HMR cascade), a `MockAdapter` loop test proves a tool mounted in one step is dispatchable in the next, and the example carries a keyless Loader smoke plus a with-key smoke that world-verifies a live model mounting a listener, building its own tool, and composing two mounts. No snapshot scenario is added: the toolset ships in no ACP-served app, so it changes no editor-facing transcript, and its presenters are unit-tested pure functions — adding it to the ACP example solely for a golden would rewrite the pinned request-header tool set of every recorded scenario. diff --git a/docs/tool-catalog.md b/docs/tool-catalog.md index f0a3fab35d..91c2104a13 100644 --- a/docs/tool-catalog.md +++ b/docs/tool-catalog.md @@ -136,7 +136,7 @@ Source: [`packages/cordis/tool-cordis/src/index.ts`](../packages/cordis/tool-cor ### `cordis_mount` -Mount a NEW cordis plugin into the live runtime that is running THIS agent (self-modification). `code` runs as the body of an async JavaScript function in an isolated sandbox and MUST `return` a plugin. Two forms: FUNCTION form `return (ctx) => { … }` — cannot declare inject, uses whatever services are on the parent context, and accessing a service without inject (e.g. ctx.bash) throws; use it only when you need no injected services. OBJECT form `return { name?, inject: ['bash', 'llm', …], apply(ctx) { … } }` — declares dependencies, and cordis activates the plugin only after the services exist; PREFER this form for any plugin that needs bash, llm, sessions, etc. BEFORE calling a service from your code, read cordis_inspect what:"api" — it lists method signatures AND the type shapes of their arguments/returns (do not guess a field's type; e.g. a bash run's stdout is an object, not a string). Inside `apply`, use the standard cordis API: `ctx.on(event, listener)` to observe events (see cordis_inspect what:"events"), or call `harness.registerTool(ctx, harness.defineTool({ name, description, parameters: { text: { type: 'string', required: true } }, async execute(args) { … } }))` to give yourself a new tool — it becomes callable on your NEXT step. A tool's `execute` MUST return an ARRAY of content blocks, e.g. `return [{ type: 'text', text: someString }]` — never a bare string. Mounts can COMPOSE: one plugin may `ctx.provide('name', value)` a service and another may declare `inject: ['name']` to consume it — the consumer stays pending until the provider exists and returns to pending when the provider is unmounted. Everything registered inside `apply` is cleaned up automatically on unmount. Sandbox globals: `console` (tagged `[cordis:]`, writes through to the harness terminal), `harness.defineTool`, `harness.registerTool`, `btoa`, `atob`, `TextEncoder`, `TextDecoder`. Node APIs are DISABLED — do filesystem/network/timer work through the cordis services, never Node built-ins: `require`, `setTimeout`/`setInterval`, and `fetch` throw redirect errors; `process` and `Buffer` are undefined. Instead use inject: ['fs'] + ctx.fs for files, inject: ['web'] + ctx.web for HTTP, inject: ['bash'] + ctx.bash for processes, and inject: ['timer'] + ctx.setTimeout/ctx.setInterval for timing (fiber effects, auto-cleaned on unmount) — cordis_inspect what:"api" shows what THIS runtime provides. Write PLAIN JavaScript, not TypeScript (no `as`, no type annotations). Cautions: (1) waterfall events (e.g. tools/pre-execute) hand the listener a trailing `next` callback which MUST be called — returning without `next()` VETOES the call; prefer plain notification events unless you intend to intercept. (2) Never await something that only resolves after the current turn (your code runs INSIDE a tool call of that turn — it would deadlock). (3) The sandbox prevents accidental global pollution, not malice: `ctx` is the real, fully privileged runtime handle. +Mount a NEW cordis plugin into the live runtime that is running THIS agent (self-modification). `code` runs as the body of an async JavaScript function in an isolated sandbox and MUST `return` a plugin. Two forms: FUNCTION form `return (ctx) => { … }` — cannot declare inject, uses whatever services are on the parent context, and accessing a service without inject (e.g. ctx.bash) throws; use it only when you need no injected services. OBJECT form `return { name?, inject: ['bash', 'llm', …], apply(ctx) { … } }` — declares dependencies, and cordis activates the plugin only after the services exist; PREFER this form for any plugin that needs bash, llm, sessions, etc. BEFORE calling a service from your code, read cordis_inspect what:"api" — it lists method signatures AND the type shapes of their arguments/returns (do not guess a field's type; e.g. a bash run's stdout is an object, not a string). Inside `apply`, use the standard cordis API: `ctx.on(event, listener)` to observe events (see cordis_inspect what:"events"), or call `harness.registerTool(ctx, harness.defineTool({ name, description, parameters: { text: { type: 'string', required: true } }, async execute(args) { … } }))` to give yourself a new tool — it becomes callable on your NEXT step. Tool parameters: each key IS a property — { type: 'string'|'number'|'boolean'|'object'|'array', required?: true, description?, enum?, items?, properties? }; a JSON-Schema-style { type: 'object', properties, required: […] } wrapper and type 'integer' are also accepted and normalized. A tool's `execute` MUST return an ARRAY of content blocks, e.g. `return [{ type: 'text', text: someString }]` — never a bare string. Mounts can COMPOSE: one plugin may `ctx.provide('name', value)` a service and another may declare `inject: ['name']` to consume it — the consumer stays pending until the provider exists and returns to pending when the provider is unmounted. Everything registered inside `apply` is cleaned up automatically on unmount. Sandbox globals: `console` (tagged `[cordis:]`, writes through to the harness terminal), `harness.defineTool`, `harness.registerTool`, `btoa`, `atob`, `TextEncoder`, `TextDecoder`. Node APIs are DISABLED — do filesystem/network/timer work through the cordis services, never Node built-ins: `require`, `setTimeout`/`setInterval`, and `fetch` throw redirect errors; `process` and `Buffer` are undefined. Instead use inject: ['fs'] + ctx.fs for files, inject: ['web'] + ctx.web for HTTP, inject: ['bash'] + ctx.bash for processes, and inject: ['timer'] + ctx.setTimeout/ctx.setInterval for timing (fiber effects, auto-cleaned on unmount) — cordis_inspect what:"api" shows what THIS runtime provides. Write PLAIN JavaScript, not TypeScript (no `as`, no type annotations). Cautions: (1) waterfall events (e.g. tools/pre-execute) hand the listener a trailing `next` callback which MUST be called — returning without `next()` VETOES the call; prefer plain notification events unless you intend to intercept. (2) Never await something that only resolves after the current turn (your code runs INSIDE a tool call of that turn — it would deadlock). (3) The sandbox prevents accidental global pollution, not malice: `ctx` is the real, fully privileged runtime handle. ```json { diff --git a/packages/cordis/tool-cordis/src/guard.ts b/packages/cordis/tool-cordis/src/guard.ts index 09d804771f..998997a8f9 100644 --- a/packages/cordis/tool-cordis/src/guard.ts +++ b/packages/cordis/tool-cordis/src/guard.ts @@ -1,19 +1,27 @@ /** * The registration boundary between sandboxed mount code and the real runtime: - * SchemaSpec validation with teaching errors, the marker-guarded - * `harness.defineTool` / `harness.registerTool` pair, the guarded `ctx` proxy a - * mounted plugin receives, and the plugin-shape helpers the mount lifecycle - * narrows sandbox return values with. + * SchemaSpec normalization + validation with teaching errors, the + * marker-guarded `harness.defineTool` / `harness.registerTool` pair, the + * guarded `ctx` proxy a mounted plugin receives, and the plugin-shape helpers + * the mount lifecycle narrows sandbox return values with. * * Two realm facts drive the design. Objects built inside the vm carry the vm * realm's `Object.prototype`, and the session log's append-time plainness check * (`dsh-session`'s `isJsonValue`, a prototype-identity comparison) rejects * foreign-realm data — so every dynamic tool's `execute` return is JSON - * round-tripped into the host realm before it reaches the registry. And a - * malformed tool schema must fail at REGISTRATION, not when a later request - * assembles it — so dynamic `ctx.tools.register` calls accept only definitions - * produced by the sandbox's `harness.defineTool`, which asserts the SchemaSpec - * DSL up front. + * round-tripped into the host realm before it reaches the registry, and the + * schema itself is rebuilt as fresh host-realm objects. And a malformed tool + * schema must fail at REGISTRATION, not when a later request assembles it — so + * dynamic `ctx.tools.register` calls accept only definitions produced by the + * sandbox's `harness.defineTool`, which normalizes `parameters` up front. + * + * Normalize, don't lecture, where the input has exactly one meaning: models + * write the JSON-Schema dialect by strong prior (the `{ type: 'object', + * properties, required: […] }` wrapper, `type: 'integer'`, `required: false`), + * and each rejection costs a model turn — so those convert to the SchemaSpec + * DSL silently, and only genuinely meaningless input (an unknown type, a + * non-boolean `required`) is rejected, with the error enumerating the valid + * vocabulary. * * @module @deepseek-ai/dsh-tool-cordis/guard */ @@ -24,6 +32,7 @@ import type { ToolDefinition, ToolExecuteReturn } from '@deepseek-ai/dsh-tools' const DYNAMIC_TOOL = Symbol('tool-cordis.dynamic-tool') const SCHEMA_TYPES = new Set(['string', 'number', 'boolean', 'object', 'array']) +const VALID_TYPES = '\'string\' | \'number\' | \'boolean\' | \'object\' | \'array\'' type DynamicToolDefinition = ToolDefinition & { [DYNAMIC_TOOL]: true } type DynamicToolMarker = { [DYNAMIC_TOOL]?: unknown } @@ -32,47 +41,70 @@ function isPlainRecord(value: unknown): value is Record { return Object.prototype.toString.call(value) === '[object Object]' } -/** Assert a sandbox-provided `parameters` value is a SchemaSpec object, with a teaching error for the common JSON-Schema mistake. */ -function assertSchemaSpec(value: unknown): void { +/** + * Normalize a sandbox-provided `parameters` value into a fresh host-realm + * SchemaSpec. Accepts the DSL directly, or the JSON-Schema-style + * `{ type: 'object', properties, required: […] }` wrapper models write by + * prior — the wrapper unwraps and its `required` array becomes per-property + * flags (see the module doc). + */ +function normalizeSchemaSpec(value: unknown, path = 'parameters'): Record { if (!isPlainRecord(value)) { - throw new Error('harness.defineTool parameters must be a SchemaSpec object') + throw new Error(`harness.defineTool ${path} must be a SchemaSpec object`) } + let entries = value + const requiredNames = new Set() if (value.type === 'object' && isPlainRecord(value.properties)) { - throw new Error( - 'harness.defineTool parameters use the SchemaSpec DSL (NOT JSON Schema).\n' - + ' ✗ { type: \'object\', properties: { name: { type: \'string\' } }, required: [\'name\'] }\n' - + ' ✓ { name: { type: \'string\', required: true } }\n' - + 'Remove the outer { type: \'object\', properties, required } wrapper; ' - + 'each key IS a property directly on the parameters object.', - ) + if (Array.isArray(value.required)) { + for (const name of value.required) requiredNames.add(name) + } + entries = value.properties } - for (const [key, prop] of Object.entries(value)) { - assertSchemaProp(prop, `parameters.${key}`) + const spec: Record = {} + for (const [key, prop] of Object.entries(entries)) { + spec[key] = normalizeSchemaProp(prop, `${path}.${key}`, requiredNames.has(key)) } + return spec } -function assertSchemaProp(value: unknown, path: string): void { +/** Normalize one property: `integer` → `number`, `required: false` → absent, nested wrappers unwrapped recursively. */ +function normalizeSchemaProp(value: unknown, path: string, forceRequired = false): Record { if (!isPlainRecord(value)) { throw new Error(`harness.defineTool ${path} must be a SchemaSpec property object`) } - if (!SCHEMA_TYPES.has(value.type)) { - throw new Error(`harness.defineTool ${path} must declare a valid type`) + const type = value.type === 'integer' ? 'number' : value.type + if (!SCHEMA_TYPES.has(type)) { + throw new Error(`harness.defineTool ${path} must declare a valid type: ${VALID_TYPES} (got ${JSON.stringify(value.type)})`) } - if (value.required !== undefined && value.required !== true) { - throw new Error(`harness.defineTool ${path}.required must be true when present`) + // On an object property a JSON-Schema-style `required` ARRAY names required + // children (handled by the nested unwrap below); everywhere else `required` + // must be a boolean, and `false` simply reads as optional. + const nestedRequiredArray = type === 'object' && Array.isArray(value.required) + if (value.required !== undefined && typeof value.required !== 'boolean' && !nestedRequiredArray) { + throw new Error(`harness.defineTool ${path}.required must be a boolean when present`) } + const prop: Record = { type } + if (forceRequired || value.required === true) prop.required = true + if (typeof value.description === 'string') prop.description = value.description + if (Array.isArray(value.enum)) prop.enum = [...value.enum as unknown[]] + if (value.default !== undefined) prop.default = value.default if (value.properties !== undefined) { - if (value.type !== 'object') { + if (type !== 'object') { throw new Error(`harness.defineTool ${path}.properties is only valid for type "object"`) } - assertSchemaSpec(value.properties) + // Re-wrap so the nested unwrap applies a nested `required` array too. + prop.properties = normalizeSchemaSpec( + { type: 'object', properties: value.properties, required: value.required }, + `${path}.properties`, + ) } if (value.items !== undefined) { - if (value.type !== 'array') { + if (type !== 'array') { throw new Error(`harness.defineTool ${path}.items is only valid for type "array"`) } - assertSchemaProp(value.items, `${path}.items`) + prop.items = normalizeSchemaProp(value.items, `${path}.items`) } + return prop } function markDynamicTool(tool: ToolDefinition): DynamicToolDefinition { @@ -87,17 +119,19 @@ function assertDynamicTool(tool: unknown): asserts tool is DynamicToolDefinition } /** - * The `harness.defineTool` handed into the sandbox: the real DSL, with the + * The `harness.defineTool` handed into the sandbox: the real DSL, with + * `parameters` normalized into a fresh host-realm SchemaSpec (JSON-Schema + * wrapper unwrapped, `integer` mapped, `required: false` dropped) and the * tool's `execute` return normalized into the host realm via a JSON round-trip * (see the module doc). The round-trip also projects the return onto exactly * what the log would durably store, so a non-JSON-serializable return surfaces * as that one call's error instead of poisoning the turn. - * @param options - the standard `defineTool` options, with `parameters` asserted against the SchemaSpec DSL before the DSL sees them. + * @param options - the standard `defineTool` options; `parameters` may be the SchemaSpec DSL or a JSON-Schema-style wrapper. * @returns the marker-tagged definition `harness.registerTool` (and the guarded `ctx.tools.register`) accepts. */ export function sandboxDefineTool(options: Parameters[0]): ToolDefinition { - assertSchemaSpec((options as { parameters?: unknown }).parameters) - const tool = defineTool(options) + const parameters = normalizeSchemaSpec((options as { parameters?: unknown }).parameters) + const tool = defineTool({ ...options, parameters } as Parameters[0]) const execute = tool.execute.bind(tool) return markDynamicTool({ ...tool, diff --git a/packages/cordis/tool-cordis/src/index.ts b/packages/cordis/tool-cordis/src/index.ts index de028b384a..7dff9b993d 100644 --- a/packages/cordis/tool-cordis/src/index.ts +++ b/packages/cordis/tool-cordis/src/index.ts @@ -143,7 +143,10 @@ export function apply(ctx: Context, config: Config): void { + 'events (see cordis_inspect what:"events"), or call ' + '`harness.registerTool(ctx, harness.defineTool({ name, description, parameters: ' + '{ text: { type: \'string\', required: true } }, async execute(args) { … } }))` ' - + 'to give yourself a new tool — it becomes callable on your NEXT step. A ' + + 'to give yourself a new tool — it becomes callable on your NEXT step. ' + + 'Tool parameters: each key IS a property — { type: \'string\'|\'number\'|\'boolean\'|\'object\'|\'array\', ' + + 'required?: true, description?, enum?, items?, properties? }; a JSON-Schema-style ' + + '{ type: \'object\', properties, required: […] } wrapper and type \'integer\' are also accepted and normalized. A ' + 'tool\'s `execute` MUST return an ARRAY of content blocks, e.g. `return ' + '[{ type: \'text\', text: someString }]` — never a bare string. ' + 'Mounts can COMPOSE: one plugin may `ctx.provide(\'name\', value)` a service and ' diff --git a/packages/cordis/tool-cordis/tests/mount.spec.ts b/packages/cordis/tool-cordis/tests/mount.spec.ts index 03038f818c..543b38307f 100644 --- a/packages/cordis/tool-cordis/tests/mount.spec.ts +++ b/packages/cordis/tool-cordis/tests/mount.spec.ts @@ -60,39 +60,85 @@ describe('cordis_mount', () => { expect(isJsonValue({ content: reversed.content, isError: reversed.isError })).toBe(true) }) - it('rejects JSON Schema passed to harness.defineTool with the SchemaSpec teaching error', async () => { + it('accepts a JSON-Schema-style parameters wrapper and normalizes it to the DSL', async () => { + // The dialect models write by strong prior: the { type:'object', + // properties, required: […] } wrapper, `type: 'integer'`, and + // `required: false`. All of it has exactly one meaning — normalize instead + // of burning a model turn on a lecture. const ctx = await setup() const result = await call(ctx, 'cordis_mount', { code: ` return { - name: 'bad-json-schema-tool', + name: 'json-schema-tool', inject: ['tools'], apply(ctx) { harness.registerTool(ctx, harness.defineTool({ - name: 'bad_json_schema_tool', - description: 'bad', + name: 'json_schema_tool', + description: 'written in the JSON-Schema dialect', parameters: { type: 'object', - properties: { text: { type: 'string' } }, + properties: { + text: { type: 'string', description: 'the text' }, + count: { type: 'integer', default: 1 }, + mode: { type: 'string', enum: ['fast', 'slow'] }, + extra: { type: 'string', required: false }, + }, required: ['text'], }, - async execute() { return [{ type: 'text', text: 'bad' }] }, + async execute(args) { return [{ type: 'text', text: args.text + ':' + (args.count ?? 0) }] }, })) }, } `, }) + expect(result.isError).toBe(false) - expect(result.isError).toBe(true) - expect(text(result)).toContain('harness.defineTool parameters use the SchemaSpec DSL') - expect(ctx.tools.get('bad_json_schema_tool')).toBeUndefined() + // The registered schema is canonical JSON Schema derived from the DSL: + // the required array survived, integer became number, extra is optional. + const schema = ctx.tools.schemas().find(s => s.name === 'json_schema_tool')! + const parameters = schema.parameters as { properties: Record; required?: string[] } + expect(parameters.required).toEqual(['text']) + expect(parameters.properties.count!.type).toBe('number') + expect(parameters.properties.mode!.enum).toEqual(['fast', 'slow']) + // Arg validation enforces the normalized spec: text required, extra not. + expect((await call(ctx, 'json_schema_tool', { count: 2 })).isError).toBe(true) + expect(text(await call(ctx, 'json_schema_tool', { text: 'ok', count: 2 }))).toBe('ok:2') + }) + + it('normalizes a nested object property carrying a JSON-Schema required array', async () => { + // On an object PROPERTY, a JSON-Schema-style `required` array names the + // required children — the nested unwrap converts it just like the top level. + const ctx = await setup() + const result = await call(ctx, 'cordis_mount', { + code: ` + return { + name: 'nested-json-schema', + inject: ['tools'], + apply(ctx) { + harness.registerTool(ctx, harness.defineTool({ + name: 'nested_json_schema_tool', + description: 'nested dialect', + parameters: { + cfg: { type: 'object', properties: { label: { type: 'string' } }, required: ['label'] }, + }, + async execute(args) { return [{ type: 'text', text: args.cfg.label }] }, + })) + }, + } + `, + }) + expect(result.isError).toBe(false) + const schema = ctx.tools.schemas().find(s => s.name === 'nested_json_schema_tool')! + const cfg = (schema.parameters as { properties: { cfg: { required?: string[] } } }).properties.cfg + expect(cfg.required).toEqual(['label']) + expect(text(await call(ctx, 'nested_json_schema_tool', { cfg: { label: 'hi' } }))).toBe('hi') }) it.each([ ['parameters: 42', 'must be a SchemaSpec object'], ['parameters: { text: 42 }', 'parameters.text must be a SchemaSpec property object'], - ['parameters: { text: { type: \'str\' } }', 'parameters.text must declare a valid type'], - ['parameters: { text: { type: \'string\', required: false } }', 'parameters.text.required must be true when present'], + ['parameters: { text: { type: \'str\' } }', 'parameters.text must declare a valid type: \'string\' | \'number\' | \'boolean\' | \'object\' | \'array\' (got "str")'], + ['parameters: { text: { type: \'string\', required: \'yes\' } }', 'parameters.text.required must be a boolean when present'], ['parameters: { text: { type: \'string\', properties: {} } }', 'parameters.text.properties is only valid for type "object"'], ['parameters: { text: { type: \'string\', items: { type: \'string\' } } }', 'parameters.text.items is only valid for type "array"'], ])('rejects a malformed SchemaSpec (%s) with a teaching error', async (parameters, message) => { From ea66641b84c170d0b133ee66ab6c7cc955b12cf8 Mon Sep 17 00:00:00 2001 From: imccyu <276526105+imccyu@users.noreply.github.com> Date: Wed, 8 Jul 2026 21:01:49 +0800 Subject: [PATCH 09/15] feat(tool-cordis): flatten the inspect plugins section to a capability list MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The tree SHAPE was the wrong surface for the model: what it needs from cordis_inspect is what services, plugins, and capabilities are loaded, not the fiber hierarchy. The plugins section is now a flat name + lifecycle-state list from ctx.registry (deterministically sorted, one line per instance); the ASCII tree renderer, the parent→child rebuild, and the dyn-id tree annotation are deleted — dynamic mounts keep their own richer dynamic section (id, state, provides, waits). Net -49 lines; RFC and READMEs state the flat-list contract. --- ...6-07-08-self-referential-cordis-toolset.md | 8 +-- docs/tool-catalog.md | 2 +- packages/cordis/README.md | 2 +- packages/cordis/tool-cordis/README.md | 2 +- .../cordis/tool-cordis/src/fiber-state.ts | 2 +- packages/cordis/tool-cordis/src/index.ts | 25 +++----- packages/cordis/tool-cordis/src/inspect.ts | 60 ++++--------------- .../cordis/tool-cordis/tests/inspect.spec.ts | 42 ++++++------- 8 files changed, 47 insertions(+), 96 deletions(-) diff --git a/docs/rfc/implemented/feature/2026-07-08-self-referential-cordis-toolset.md b/docs/rfc/implemented/feature/2026-07-08-self-referential-cordis-toolset.md index 14e05b0afd..26daf4a844 100644 --- a/docs/rfc/implemented/feature/2026-07-08-self-referential-cordis-toolset.md +++ b/docs/rfc/implemented/feature/2026-07-08-self-referential-cordis-toolset.md @@ -22,11 +22,11 @@ The trust stance, stated once and threaded through the rest: the `node:vm` sandb | `cordis_mount` | Evaluates `code` (the body of an async JavaScript function) in a `node:vm` sandbox; the code must `return` a cordis plugin, which is mounted as a child of the `cordis-dynamic` group fiber and tracked under a fresh id (`dyn-1`, `dyn-2`, …). | | `cordis_unmount` | Disposes one dynamic mount by id and returns only after disposal reaches quiescence — every registration the plugin made is unwound, not merely requested to stop. | -`cordis_inspect` sections: `services` (every provided ctx service and the owning fiber, non-active owners flagged), `plugins` (the whole plugin fiber tree rebuilt from `ctx.registry`, ASCII, dynamic mounts annotated with their ids), `tools` (what the model can call), `dynamic` (the mount table: id, name, state, provided services, awaited services), `api` (live service signatures + the type shapes they reference, from the generated catalog), and `events` (harness events with dispatch mode and signature). The model-facing tool descriptions carry the operational rules the model needs at call time; [the generated tool catalog](../../../tool-catalog.md) is their exhaustive rendering. +`cordis_inspect` sections: `services` (every provided ctx service and the owning fiber, non-active owners flagged), `plugins` (a flat list of every loaded plugin with its lifecycle state, from `ctx.registry` — what capabilities are loaded, deliberately not the tree shape), `tools` (what the model can call), `dynamic` (the mount table: id, name, state, provided services, awaited services), `api` (live service signatures + the type shapes they reference, from the generated catalog), and `events` (harness events with dispatch mode and signature). The model-facing tool descriptions carry the operational rules the model needs at call time; [the generated tool catalog](../../../tool-catalog.md) is their exhaustive rendering. ### Sandbox semantics -Mount code runs via `vm.createContext` + `runInContext`, wrapped as the body of an async function under a per-mount filename (`cordis-mount-.js`). The vm gives the code a fresh realm: writes to `globalThis` stay inside the sandbox, and no Node API is provided — capability access is routed through the cordis services (`ctx.fs` for files, `ctx.web` for HTTP, `ctx.bash` for processes, the `ctx.timer` helpers for timing), never Node built-ins, so everything a mounted plugin does stays inspectable through the fiber tree and disposable with it. The `vmTimeoutMs` config bounds only the synchronous portion of evaluation; an async body escapes the bound (acceptable under the trust stance above). +Mount code runs via `vm.createContext` + `runInContext`, wrapped as the body of an async function under a per-mount filename (`cordis-mount-.js`). The vm gives the code a fresh realm: writes to `globalThis` stay inside the sandbox, and no Node API is provided — capability access is routed through the cordis services (`ctx.fs` for files, `ctx.web` for HTTP, `ctx.bash` for processes, the `ctx.timer` helpers for timing), never Node built-ins, so everything a mounted plugin does stays inspectable through `cordis_inspect` and disposable with its fiber. The `vmTimeoutMs` config bounds only the synchronous portion of evaluation; an async body escapes the bound (acceptable under the trust stance above). Sandbox globals are deliberately small: a tagged write-through `console` (`[cordis:] …` on the host stdout/stderr, so a listener that fires long after the mount call still lands somewhere the user sees), the `harness.defineTool` / `harness.registerTool` registration pair, the encoding primitives fresh vm contexts lack (`btoa`/`atob` as host closures over `Buffer` — a sanctioned exception, `Buffer` itself is never exposed — plus `TextEncoder`/`TextDecoder`), and callable traps over the withheld Node APIs (`require`, `setTimeout`/`setInterval`/`setImmediate`/`clearTimeout`/`clearInterval`, `fetch`) that throw a redirect naming the cordis alternative. Only function-shaped globals are trapped; `process` and `Buffer` stay `undefined` so a `typeof` feature probe stays inert rather than detonating a throwing accessor. @@ -36,7 +36,7 @@ Boundary errors are written around the mistakes models actually make (see [Conse ### The dynamic group and mount lifecycle -Every dynamic mount is a child of a single `cordis-dynamic` group fiber, itself a child of the `tool-cordis` plugin's fiber. The group exists so the mounts form one subtree: they read as a unit in the inspect tree, and disposing `tool-cordis` (HMR reload, config unload) cascades over every mount through the ordinary parent→child fiber lifecycle — no bespoke cleanup. Mounting settles before it reports: the returned fiber is `await()`ed, and a startup error (a throwing `apply`, a duplicate tool name, a duplicate service) disposes the fiber and surfaces as the tool error, so a failed mount never lingers. A settled fiber that is not active is a legal pending mount — cordis semantics for unsatisfied `inject` — kept mounted and reported with what it waits for. Everything the plugin registers is an effect on its fiber, so `cordis_unmount` is nothing but an awaited `fiber.dispose()`. +Every dynamic mount is a child of a single `cordis-dynamic` group fiber, itself a child of the `tool-cordis` plugin's fiber. The group exists so the mounts form one subtree: they are disposed as a unit, and disposing `tool-cordis` (HMR reload, config unload) cascades over every mount through the ordinary parent→child fiber lifecycle — no bespoke cleanup. Mounting settles before it reports: the returned fiber is `await()`ed, and a startup error (a throwing `apply`, a duplicate tool name, a duplicate service) disposes the fiber and surfaces as the tool error, so a failed mount never lingers. A settled fiber that is not active is a legal pending mount — cordis semantics for unsatisfied `inject` — kept mounted and reported with what it waits for. Everything the plugin registers is an effect on its fiber, so `cordis_unmount` is nothing but an awaited `fiber.dispose()`. ### Cross-mount composition via provide/inject @@ -64,7 +64,7 @@ Model-visible ⟺ logged holds with no new session event type: a mount or unmoun | The code field | An `execute` body is still model-written JS in a vm; the realm and service-call correctness problems are unchanged | One sandbox, one normalization path, one guarded registration | | Capability coverage | Tools only; listeners, services, `inject` relations each need another structured tool — a surface that grows without bound | One vocabulary (a cordis plugin) covers every effect, present and future | | Cross-mount composition | Not expressible in a tool-registration payload | Native `provide`/`inject`, ordinary cordis semantics | -| Inspectability | Registers something the plugin tree cannot show as a plugin | What the model mounts is exactly what `cordis_inspect` renders | +| Inspectability | Registers something the plugin list cannot show as a plugin | What the model mounts is exactly what `cordis_inspect` renders | | Model ergonomics | Wins for the single most common case (no plugin boilerplate) | Mitigated by the canonical recipe in the mount description plus boundary errors that teach the fix | The correctness investment therefore goes where it pays for every capability at once: the generated API catalog surfaced through `cordis_inspect`, and sandbox-boundary validation whose error messages teach the correct call. A structured registration tool remains addable later as sugar that synthesizes mount code; nothing here forecloses it. diff --git a/docs/tool-catalog.md b/docs/tool-catalog.md index 91c2104a13..ec1546592c 100644 --- a/docs/tool-catalog.md +++ b/docs/tool-catalog.md @@ -110,7 +110,7 @@ The bash/bash_output/bash_kill tools are model-facing consumers of the bash exec ### `cordis_inspect` -Inspect the live cordis runtime that is running THIS agent. Read-only. Sections: `services` (every provided ctx service and the plugin fiber that owns it), `plugins` (the whole plugin fiber tree with lifecycle states, as an ASCII tree — dynamic mounts appear under the `cordis-dynamic` group with their ids), `tools` (the model-facing tools currently registered, i.e. what you can call), `dynamic` (plugins you mounted via cordis_mount: id, name, state, provided services, awaited services), `api` (method signatures AND argument/return type shapes for every LIVE service — read this before writing plugin code that calls a service), `events` (every harness event with its dispatch mode and exact signature — pick listener targets here). Omit `what` to get all six sections. +Inspect the live cordis runtime that is running THIS agent. Read-only. Sections: `services` (every provided ctx service and the plugin fiber that owns it), `plugins` (a flat list of the loaded plugins with their lifecycle states), `tools` (the model-facing tools currently registered, i.e. what you can call), `dynamic` (plugins you mounted via cordis_mount: id, name, state, provided services, awaited services), `api` (method signatures AND argument/return type shapes for every LIVE service — read this before writing plugin code that calls a service), `events` (every harness event with its dispatch mode and exact signature — pick listener targets here). Omit `what` to get all six sections. ```json { diff --git a/packages/cordis/README.md b/packages/cordis/README.md index 2eb33006e5..70c7e41ce0 100644 --- a/packages/cordis/README.md +++ b/packages/cordis/README.md @@ -1,6 +1,6 @@ # packages/cordis — the self-referential runtime toolset -Model-facing tools over the live cordis runtime the agent itself runs inside: inspect the plugin tree and service surface, mount model-written plugins, and dispose them again. Design home: [the toolset RFC](../../docs/rfc/implemented/feature/2026-07-08-self-referential-cordis-toolset.md). +Model-facing tools over the live cordis runtime the agent itself runs inside: inspect the loaded plugins and service surface, mount model-written plugins, and dispose them again. Design home: [the toolset RFC](../../docs/rfc/implemented/feature/2026-07-08-self-referential-cordis-toolset.md). | Package | Role | ctx key | |---|---|---| diff --git a/packages/cordis/tool-cordis/README.md b/packages/cordis/tool-cordis/README.md index 71b79fecad..b369a7209b 100644 --- a/packages/cordis/tool-cordis/README.md +++ b/packages/cordis/tool-cordis/README.md @@ -4,7 +4,7 @@ The self-referential cordis toolset: three model-facing tools over the live runt ## What it does -- `cordis_inspect` — read-only report over the runtime: services, the plugin fiber tree (ASCII), registered tools, the dynamic-mount table, and the catalog-backed `api` / `events` references. +- `cordis_inspect` — read-only report over the runtime: services, the loaded-plugin list, registered tools, the dynamic-mount table, and the catalog-backed `api` / `events` references. - `cordis_mount` — evaluates model-written JavaScript (the body of an async function) in a `node:vm` sandbox; the code must `return` a cordis plugin, which is mounted under the `cordis-dynamic` group fiber and tracked as `dyn-`. - `cordis_unmount` — disposes one mount by id, returning only after quiescence. diff --git a/packages/cordis/tool-cordis/src/fiber-state.ts b/packages/cordis/tool-cordis/src/fiber-state.ts index e46700c387..2b1ee166b7 100644 --- a/packages/cordis/tool-cordis/src/fiber-state.ts +++ b/packages/cordis/tool-cordis/src/fiber-state.ts @@ -1,7 +1,7 @@ /** * Runtime mirror of the cordis `FiberState` const enum plus human-readable * labels, shared by the mount lifecycle (state reporting) and the inspect - * renderers (tree and mount-table labels). + * renderers (plugin-list and mount-table labels). * * Cordis exposes `FiberState` as a `const enum`: there is no runtime object for * Node's type-stripping runner to import, so the members are mirrored here as diff --git a/packages/cordis/tool-cordis/src/index.ts b/packages/cordis/tool-cordis/src/index.ts index 7dff9b993d..875637bfc4 100644 --- a/packages/cordis/tool-cordis/src/index.ts +++ b/packages/cordis/tool-cordis/src/index.ts @@ -2,8 +2,8 @@ * The self-referential cordis toolset: three model-facing tools that let the * agent inspect and MODIFY the live cordis runtime it is running inside. * - * - `cordis_inspect` — read-only: provided services, the plugin fiber tree - * (rendered as an ASCII tree), registered tools, the dynamic mounts, and the + * - `cordis_inspect` — read-only: provided services, the flat plugin list + * with lifecycle states, registered tools, the dynamic mounts, and the * catalog-backed `api` / `events` references. * - `cordis_mount` — evaluate model-written code in a `node:vm` sandbox; the * code returns a cordis plugin, which is mounted as a child of a dedicated @@ -14,8 +14,8 @@ * `harness.registerTool`, services via `ctx.provide`) is an effect on the * dynamic fiber, so unmounting — or disposing this plugin itself (HMR) — cleans * it all up through the ordinary cordis lifecycle. The group fiber exists - * exactly so the dynamic mounts form ONE subtree: visible as a unit in the - * inspect tree and disposed as a unit with this plugin. Design home: + * exactly so the dynamic mounts form ONE subtree, disposed as a unit with + * this plugin. Design home: * docs/rfc/implemented/feature/2026-07-08-self-referential-cordis-toolset.md. * * The vm sandbox guards against ACCIDENTAL global pollution only — it is not a @@ -31,12 +31,12 @@ * @module @deepseek-ai/dsh-tool-cordis */ -import type { Context, Fiber } from 'cordis' +import type { Context } from 'cordis' import z from 'schemastery' import { defineTool } from '@deepseek-ai/dsh-tools' import { STATE_LABELS } from './fiber-state.ts' import { isPlugin, pluginName } from './guard.ts' -import { describeApi, describeDynamic, describeEvents, describePluginTree, describeServices, describeTools } from './inspect.ts' +import { describeApi, describeDynamic, describeEvents, describePlugins, describeServices, describeTools } from './inspect.ts' import { missingServices, mountDynamic } from './mount.ts' import type { DynamicMount } from './mount.ts' import { presentInspectCall, presentMountCall, presentUnmountCall } from './present.ts' @@ -79,21 +79,12 @@ export function apply(ctx: Context, config: Config): void { const mounts = new Map() let nextId = 1 - /** The dynamic-mount id for a fiber, when that fiber is a tracked mount. */ - function mountIdOf(fiber: Fiber): string | undefined { - for (const [id, mount] of mounts) { - if (mount.fiber === fiber) return id - } - return undefined - } - ctx.tools.register(defineTool({ name: 'cordis_inspect', description: 'Inspect the live cordis runtime that is running THIS agent. Read-only. ' + 'Sections: `services` (every provided ctx service and the plugin fiber that owns it), ' - + '`plugins` (the whole plugin fiber tree with lifecycle states, as an ASCII tree — ' - + 'dynamic mounts appear under the `cordis-dynamic` group with their ids), ' + + '`plugins` (a flat list of the loaded plugins with their lifecycle states), ' + '`tools` (the model-facing tools currently registered, i.e. what you can call), ' + '`dynamic` (plugins you mounted via cordis_mount: id, name, state, provided services, awaited services), ' + '`api` (method signatures AND argument/return type shapes for every LIVE service — read this before writing plugin code that calls a service), ' @@ -109,7 +100,7 @@ export function apply(ctx: Context, config: Config): void { execute(args): Promise<{ type: 'text'; text: string }[]> { const sections: [heading: string, body: () => string[]][] = [ ['services', () => describeServices(ctx)], - ['plugins', () => describePluginTree(ctx, mountIdOf)], + ['plugins', () => describePlugins(ctx)], ['tools', () => describeTools(ctx)], ['dynamic', () => describeDynamic(ctx, mounts)], ['api', () => describeApi(ctx)], diff --git a/packages/cordis/tool-cordis/src/inspect.ts b/packages/cordis/tool-cordis/src/inspect.ts index dfcc9a0c6b..5b44ed7ca5 100644 --- a/packages/cordis/tool-cordis/src/inspect.ts +++ b/packages/cordis/tool-cordis/src/inspect.ts @@ -1,6 +1,6 @@ /** * Read-only renderers over the live runtime for `cordis_inspect`: the service - * list, the plugin fiber tree (ASCII), the registered tools, the dynamic-mount + * list, the flat plugin list, the registered tools, the dynamic-mount * table (with per-mount provides/waits), and the catalog-backed `api` / * `events` sections. Every renderer is a pure function of the runtime handles * it receives — no session state, no clock — so inspect output is exactly the @@ -57,56 +57,22 @@ export function describeServices(ctx: Context): string[] { return lines.length > 0 ? lines : ['(no services provided)'] } -/** The tree node shape {@link renderTree} draws: one line per fiber, children indented. */ -interface TreeNode { - label: string - children: TreeNode[] -} - -/** Render a node list as an ASCII tree (`├─`/`└─` box drawing). */ -function renderTree(nodes: TreeNode[], prefix = ''): string[] { - return nodes.flatMap((node, index) => { - const last = index === nodes.length - 1 - const line = `${prefix}${last ? '└─' : '├─'} ${node.label}` - const childPrefix = `${prefix}${last ? ' ' : '│ '}` - return [line, ...renderTree(node.children, childPrefix)] - }) -} - /** - * The `plugins` section: every fiber the registry knows, rebuilt into the - * parent→child tree from each fiber's mounting context and rendered as an - * ASCII tree with lifecycle states. Fibers whose parent fiber is outside the - * registry (i.e. mounted on the root context) become roots. - * @param ctx - the runtime whose registry is walked. - * @param mountIdOf - resolves a fiber to its dynamic-mount id, so mounts render as `dyn-: name`. - * @returns the tree lines, starting at the synthetic `root` line. + * The `plugins` section: a flat list of every fiber the registry knows, one + * line per fiber with its lifecycle state, sorted by plugin name (a plugin + * mounted more than once repeats — one line per instance). Dynamic mounts are + * listed like any other plugin; their ids live in the `dynamic` section. + * @param ctx - the runtime whose registry is enumerated. + * @returns one line per loaded plugin fiber. */ -export function describePluginTree(ctx: Context, mountIdOf: (fiber: Fiber) => string | undefined): string[] { - const fibers = new Set() +export function describePlugins(ctx: Context): string[] { + const fibers: Fiber[] = [] for (const runtime of ctx.registry.values()) { - for (const fiber of runtime.fibers) fibers.add(fiber) + for (const fiber of runtime.fibers) fibers.push(fiber) } - const childrenOf = new Map() - const roots: Fiber[] = [] - for (const fiber of fibers) { - const parent = fiber.parent.fiber - if (fibers.has(parent)) { - const siblings = childrenOf.get(parent) ?? [] - siblings.push(fiber) - childrenOf.set(parent, siblings) - } else { - roots.push(fiber) - } - } - const byUid = (a: Fiber, b: Fiber): number => (a.uid ?? Infinity) - (b.uid ?? Infinity) - const toNode = (fiber: Fiber): TreeNode => { - const id = mountIdOf(fiber) - const label = `${id ? `${id}: ` : ''}${fiber.name} [${STATE_LABELS[fiber.state]}]` - const children = (childrenOf.get(fiber) ?? []).sort(byUid).map(toNode) - return { label, children } - } - return ['root', ...renderTree(roots.sort(byUid).map(toNode))] + return fibers + .sort((a, b) => a.name.localeCompare(b.name)) + .map(fiber => `- ${fiber.name} [${STATE_LABELS[fiber.state]}]`) } /** diff --git a/packages/cordis/tool-cordis/tests/inspect.spec.ts b/packages/cordis/tool-cordis/tests/inspect.spec.ts index c45d3b29a8..1a8c39467a 100644 --- a/packages/cordis/tool-cordis/tests/inspect.spec.ts +++ b/packages/cordis/tool-cordis/tests/inspect.spec.ts @@ -1,13 +1,13 @@ import { describe, expect, it } from 'vitest' import type { Context, Fiber } from 'cordis' import { FiberState } from '../src/fiber-state.ts' -import { describeApi, describeEvents, describePluginTree, describeServices } from '../src/inspect.ts' +import { describeApi, describeEvents, describePlugins, describeServices } from '../src/inspect.ts' import { call, LISTENER_CODE, setup, text } from './helpers.ts' /** * The `cordis_inspect` sections: rendered against the real runtime through the * tool, plus direct renderer calls for the states a minimal harness cannot - * reach (empty service store, uid-less fibers, a fully-live catalog). + * reach (empty service store, same-named sibling fibers, a fully-live catalog). */ describe('cordis_inspect', () => { @@ -19,11 +19,12 @@ describe('cordis_inspect', () => { for (const heading of ['services', 'plugins', 'tools', 'dynamic', 'api', 'events']) { expect(report).toContain(`## ${heading}`) } - // The services section sees the real providers; the tree shows the dynamic - // group under this plugin; the tools section lists the cordis tools. + // The services section sees the real providers; the plugins list shows + // this plugin and its dynamic group flat; the tools section lists the + // cordis tools. expect(report).toContain('- tools (provided by ToolRegistry)') - expect(report).toMatch(/tool-cordis \[active\]/) - expect(report).toMatch(/cordis-dynamic \[active\]/) + expect(report).toContain('- tool-cordis [active]') + expect(report).toContain('- cordis-dynamic [active]') expect(report).toContain('- cordis_mount') expect(report).toContain('(no dynamic plugins mounted)') }) @@ -37,12 +38,12 @@ describe('cordis_inspect', () => { expect(report).not.toContain('## plugins') }) - it('shows a mount in the dynamic section and as an annotated child of the group in the tree', async () => { + it('shows a mount in the dynamic section and in the flat plugins list', async () => { const ctx = await setup() await call(ctx, 'cordis_mount', { code: LISTENER_CODE }) const report = text(await call(ctx, 'cordis_inspect', {})) expect(report).toContain('- dyn-1: change-logger [active]') - expect(report).toMatch(/dyn-1: change-logger \[active\]/) + expect(report).toContain('- change-logger [active]') }) it('renders the api section from the generated catalog intersected with the LIVE runtime', async () => { @@ -87,22 +88,15 @@ describe('inspect renderers (direct)', () => { expect(describeServices(ctx)).toEqual(['- thing (provided by half-loaded, pending)']) }) - it('describePluginTree sorts uid-less fibers last and renders sibling branches', () => { - // The parent fiber is OUTSIDE the registry set, so all three are roots. - const rootFiber = { uid: 0, name: 'root' } as unknown as Fiber - const fiber = (uid: number | null, name: string): Fiber => - ({ uid, name, state: FiberState.ACTIVE, parent: { fiber: rootFiber } }) as unknown as Fiber - const a = fiber(2, 'beta') - const b = fiber(1, 'alpha') - const c = fiber(null, 'rootless') - const d = fiber(null, 'rootless-too') - const ctx = { registry: { values: () => [{ fibers: [a, b, c, d] }] } } as unknown as Context - expect(describePluginTree(ctx, () => undefined)).toEqual([ - 'root', - '├─ alpha [active]', - '├─ beta [active]', - '├─ rootless [active]', - '└─ rootless-too [active]', + it('describePlugins lists every fiber flat, sorted by name, one line per instance', () => { + const fiber = (name: string): Fiber => ({ name, state: FiberState.ACTIVE }) as unknown as Fiber + const ctx = { + registry: { values: () => [{ fibers: [fiber('beta'), fiber('alpha')] }, { fibers: [fiber('alpha')] }] }, + } as unknown as Context + expect(describePlugins(ctx)).toEqual([ + '- alpha [active]', + '- alpha [active]', + '- beta [active]', ]) }) From aed752a75da17e0b89263cbbb5c8b362d12785a0 Mon Sep 17 00:00:00 2001 From: imccyu <276526105+imccyu@users.noreply.github.com> Date: Wed, 8 Jul 2026 21:30:17 +0800 Subject: [PATCH 10/15] fix: update doc budget --- scripts/doc-budgets.manifest.json | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/scripts/doc-budgets.manifest.json b/scripts/doc-budgets.manifest.json index 8cadde12e9..49535f0efb 100644 --- a/scripts/doc-budgets.manifest.json +++ b/scripts/doc-budgets.manifest.json @@ -7,5 +7,5 @@ "docs/testing.md": 800, "examples/AGENTS.md": 653, "packages/AGENTS.md": 450, - "packages/README.md": 610 + "packages/README.md": 660 } From 1b1ba96d4f608d7ea3bd9ea74d5b5ea1c169b14b Mon Sep 17 00:00:00 2001 From: imccyu <276526105+imccyu@users.noreply.github.com> Date: Thu, 9 Jul 2026 01:37:40 +0800 Subject: [PATCH 11/15] =?UTF-8?q?fix(tool-cordis):=20replace=20the=20pass-?= =?UTF-8?q?through=20ctx=20proxy=20with=20a=20whitelist=20fa=C3=A7ade?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Review finding (#220): the guarded proxy only special-cased ctx.tools, so mount code could reach an UNGUARDED context through ctx.root, ctx.extend(), or a service instance's .ctx, then ctx.root.tools.register({…}) to bypass the marker check and host-realm normalization — a raw vm-realm result would later error a real agent turn at the session-log plainness check. The sandbox ctx is now a whitelist façade, not a pass-through proxy: it exposes only what a mount needs — tools.register (marker-guarded), on/once, provide, the timer helpers, and injected services resolved through a guarded get — and denies every framework-plumbing member (root, parent, fiber, reflect, registry, extend, isolate, intercept, plugin, set, mixin, …) with a teaching error. Injected services are wrapped so a method returning a Context is rejected on the way back (the .ctx escape), closing the one indirect leak. There is no context-valued member left to reach; cross-mount provide/inject is untouched (the plugin's own inject and the fiber's pending/active gating are unchanged). ctx.plugin (child plugins) and ctx.set are denied by design; ctx.effect is deferred (FIXME). Adds tests/sandbox-context.spec.ts covering the escape class (root/extend/fiber/ plugin/set/… denied, the classic root.tools.register bypass, the .ctx escape, read-only writes) plus the async-service and symbol/in-operator paths for 100% coverage. RFC/README/tool-catalog/config-catalog updated; api-catalog.ts regenerated (also picks up the codeRuntime service that entered on the master merge and was left stale). --- docs/config-catalog.md | 2 +- ...6-07-08-self-referential-cordis-toolset.md | 8 +- docs/tool-catalog.md | 2 +- packages/cordis/tool-cordis/README.md | 2 +- .../cordis/tool-cordis/src/api-catalog.ts | 31 ++++ packages/cordis/tool-cordis/src/guard.ts | 169 ++++++++++++++---- packages/cordis/tool-cordis/src/index.ts | 19 +- .../cordis/tool-cordis/tests/mount.spec.ts | 4 +- .../tool-cordis/tests/sandbox-context.spec.ts | 156 ++++++++++++++++ 9 files changed, 348 insertions(+), 45 deletions(-) create mode 100644 packages/cordis/tool-cordis/tests/sandbox-context.spec.ts diff --git a/docs/config-catalog.md b/docs/config-catalog.md index d466bff4c0..2e6be3a1ea 100644 --- a/docs/config-catalog.md +++ b/docs/config-catalog.md @@ -686,7 +686,7 @@ export interface Config { } ``` -Source: [`packages/cordis/tool-cordis/src/index.ts:49`](../packages/cordis/tool-cordis/src/index.ts) +Source: [`packages/cordis/tool-cordis/src/index.ts:53`](../packages/cordis/tool-cordis/src/index.ts) ## `@deepseek-ai/dsh-tool-fs` diff --git a/docs/rfc/implemented/feature/2026-07-08-self-referential-cordis-toolset.md b/docs/rfc/implemented/feature/2026-07-08-self-referential-cordis-toolset.md index 26daf4a844..2ba398301b 100644 --- a/docs/rfc/implemented/feature/2026-07-08-self-referential-cordis-toolset.md +++ b/docs/rfc/implemented/feature/2026-07-08-self-referential-cordis-toolset.md @@ -12,7 +12,7 @@ First, model-written registration must be validated where it happens: a malforme The toolset ships as [`@deepseek-ai/dsh-tool-cordis`](../../../../packages/cordis/tool-cordis/README.md) — a new top-level `packages/cordis/` group — and is demoed by [`examples/cordis-agent`](../../../../examples/cordis-agent/README.md). It gives the model three tools over the live cordis runtime it is running inside: inspect it, mount model-written plugins into it, dispose them again. -The trust stance, stated once and threaded through the rest: the `node:vm` sandbox isolates the global context only — it prevents accidental global pollution, not malice. The `ctx` handed to a mounted plugin's `apply` is the real, fully privileged runtime handle; handing the model that handle is the point of the toolset. A deployment loads this plugin exactly as deliberately as it grants a bash tool — an opt-in capability in the app's `cordis.yml`, never a product default. +The trust stance, stated once and threaded through the rest: the `node:vm` sandbox isolates the global context only — it prevents accidental global pollution, not malice — and the `ctx` a mounted plugin's `apply` receives is a whitelist façade that narrows the *surface* (framework internals withheld) but not the *privilege* of what it exposes. The verbs the façade does expose reach the real runtime: a mounted tool can shell out through `ctx.bash`, read the filesystem through `ctx.fs`, reach the network through `ctx.web`. Neither the sandbox nor the façade is a security boundary; handing the model this power is the point of the toolset. A deployment loads this plugin exactly as deliberately as it grants a bash tool — an opt-in capability in the app's `cordis.yml`, never a product default. ### The three tools @@ -30,7 +30,7 @@ Mount code runs via `vm.createContext` + `runInContext`, wrapped as the body of Sandbox globals are deliberately small: a tagged write-through `console` (`[cordis:] …` on the host stdout/stderr, so a listener that fires long after the mount call still lands somewhere the user sees), the `harness.defineTool` / `harness.registerTool` registration pair, the encoding primitives fresh vm contexts lack (`btoa`/`atob` as host closures over `Buffer` — a sanctioned exception, `Buffer` itself is never exposed — plus `TextEncoder`/`TextDecoder`), and callable traps over the withheld Node APIs (`require`, `setTimeout`/`setInterval`/`setImmediate`/`clearTimeout`/`clearInterval`, `fetch`) that throw a redirect naming the cordis alternative. Only function-shaped globals are trapped; `process` and `Buffer` stay `undefined` so a `typeof` feature probe stays inert rather than detonating a throwing accessor. -Three boundary mechanisms make model-written code behave correctly across the realm seam. **Dual-realm `instanceof`**: most objects sandbox code touches are host-realm (tool `args`, event payloads, service returns), so a plain `x instanceof Array` in the vm would silently be false — a per-sandbox prelude gives the vm realm's own constructors a `Symbol.hasInstance` that checks both the vm constructor and its host counterpart, patching only vm-realm globals. **Realm normalization of tool results**: objects built inside the vm carry the vm realm's `Object.prototype`, which the session log's append-time plainness check (`isJsonValue` in `dsh-session`, a prototype-identity comparison) rejects, so the sandbox's `harness.defineTool` JSON round-trips every `execute` return into the host realm — which also projects it onto exactly what the log durably stores. **Guarded registration**: the `ctx` a mounted plugin receives is a proxy whose `tools.register` accepts only definitions returned by `harness.defineTool` (a marker symbol), so every dynamic tool passes SchemaSpec validation and realm normalization; everything else on `ctx` passes through with correct `this` binding, which is what keeps cross-mount `provide`/`inject` working. +Three boundary mechanisms make model-written code behave correctly across the realm seam. **Dual-realm `instanceof`**: most objects sandbox code touches are host-realm (tool `args`, event payloads, service returns), so a plain `x instanceof Array` in the vm would silently be false — a per-sandbox prelude gives the vm realm's own constructors a `Symbol.hasInstance` that checks both the vm constructor and its host counterpart, patching only vm-realm globals. **Realm normalization of tool results**: objects built inside the vm carry the vm realm's `Object.prototype`, which the session log's append-time plainness check (`isJsonValue` in `dsh-session`, a prototype-identity comparison) rejects, so the sandbox's `harness.defineTool` JSON round-trips every `execute` return into the host realm — which also projects it onto exactly what the log durably stores. **A whitelist context façade**: the `ctx` a mounted plugin's `apply` receives is NOT the real context nor a pass-through proxy over it — it is a façade exposing only what a mount legitimately needs (`tools.register` marker-guarded, `on`/`once`, `provide`, the timer helpers, and injected services resolved through a guarded `get`), with every framework-plumbing member (`root`, `parent`, `fiber`, `reflect`, `registry`, `extend`, `isolate`, `intercept`, `plugin`, `set`, `mixin`, …) denied with a teaching error. This closes an escape *class* rather than a single hole: a proxy that merely special-cased `ctx.tools` still handed back the raw context through `ctx.root`, `ctx.extend()`, or a service instance's `.ctx`, and mount code could then `ctx.root.tools.register({…})` to bypass the marker check and realm normalization — a raw vm-realm result then errors a real agent turn at the plainness check. The façade has no context-valued member to reach, and the one indirect leak (an injected-service method returning a `Context`) is rejected on the way back to sandbox code; cross-mount `provide`/`inject` keeps working because the plugin's own `inject` and the fiber's pending/active gating are untouched — only the `apply`-time `ctx` surface is narrowed. Boundary errors are written around the mistakes models actually make (see [Consequences](#consequences) for how each was found), and the boundary normalizes rather than lectures wherever the input has exactly one meaning: schema `parameters` accept the JSON-Schema dialect models write by strong prior — the `{ type: 'object', properties, required: […] }` wrapper unwraps to the SchemaSpec DSL (the `required` array becoming per-property flags, at any nesting level), `type: 'integer'` maps to `number`, and `required: false` reads as optional — while genuinely meaningless input is rejected with the vocabulary enumerated (an unknown type lists the five valid ones; a non-boolean `required` names the rule). The remaining teaching errors: an unbalanced `});` closing gets the vm's offending source line plus a "code is a function body" reminder; TypeScript syntax gets the remove-annotations fix (detected on the failing line only, so an ` as ` inside a description string does not misfire); a forgotten `return` gets the two valid plugin forms; a Node built-in call gets the redirect to its cordis service; a tool-name collision on re-mount gets the unmount-first-then-remount recipe. @@ -40,7 +40,7 @@ Every dynamic mount is a child of a single `cordis-dynamic` group fiber, itself ### Cross-mount composition via provide/inject -Mounts relate to each other through ordinary cordis service semantics, with their ids as the lifecycle handles: mount A calls `ctx.provide('foo', value)`, mount B declares `inject: ['foo']` and activates the moment `foo` exists; mounted first, B stays pending and names the missing service; unmounting A sends B back to pending (its registrations unwound) and a later re-provide re-runs B's `apply` through the same guarded context; a duplicate provide fails loud with the owning fiber named. One realm caveat: a service value provided by a mount is a vm-realm object — method calls on it work from anywhere, but consumers must not assume host prototypes on it. +Mounts relate to each other through ordinary cordis service semantics, with their ids as the lifecycle handles: mount A calls `ctx.provide('foo', value)`, mount B declares `inject: ['foo']` and activates the moment `foo` exists; mounted first, B stays pending and names the missing service; unmounting A sends B back to pending (its registrations unwound) and a later re-provide re-runs B's `apply` through a fresh sandbox façade; a duplicate provide fails loud with the owning fiber named. One realm caveat: a service value provided by a mount is a vm-realm object — method calls on it work from anywhere, but consumers must not assume host prototypes on it. ### The generated API catalog @@ -73,7 +73,7 @@ The correctness investment therefore goes where it pays for every capability at **A new `cordis/mount` session event.** A durable provenance event recording each mount (source, name) has clear precedent (`hook/invoked`, `compact/start`). It was declined for v1: mount and unmount are already visible as `tool/call` / `tool/result` pairs and the tool-set change is already logged as a request-header delta, so a dedicated event would only duplicate the record. It remains addable if an audit use case needs mount provenance separable from the tool call. -**A hardened / capability-restricted sandbox.** Trapping Node built-ins might suggest an intent to sandbox for safety. It is explicitly not that: the traps redirect the model toward cordis services (and away from leak-prone Node timers) for correctness and inspectability, but `ctx` is fully privileged and the vm is not a security boundary. A real security boundary (separate process, permission prompts) was out of scope for a dev/opt-in toolset and would fight the entire point — handing the model the live runtime. +**A hardened / capability-restricted sandbox.** Trapping Node built-ins and handing mount code a whitelist façade rather than the raw context might suggest an intent to sandbox for safety. It is explicitly not that: the traps and the façade narrow the *surface* mount code sees — steering it onto cordis services and away from leak-prone Node built-ins and framework internals — for correctness and to close the unguarded-context escape, but the capabilities the façade exposes (`ctx.bash`, `ctx.fs`, `ctx.web`) reach the real runtime, so it is not a security boundary. A real one (separate process, permission prompts) was out of scope for a dev/opt-in toolset and would fight the entire point — handing the model the live runtime. ## Consequences diff --git a/docs/tool-catalog.md b/docs/tool-catalog.md index ec1546592c..990e135b1c 100644 --- a/docs/tool-catalog.md +++ b/docs/tool-catalog.md @@ -136,7 +136,7 @@ Source: [`packages/cordis/tool-cordis/src/index.ts`](../packages/cordis/tool-cor ### `cordis_mount` -Mount a NEW cordis plugin into the live runtime that is running THIS agent (self-modification). `code` runs as the body of an async JavaScript function in an isolated sandbox and MUST `return` a plugin. Two forms: FUNCTION form `return (ctx) => { … }` — cannot declare inject, uses whatever services are on the parent context, and accessing a service without inject (e.g. ctx.bash) throws; use it only when you need no injected services. OBJECT form `return { name?, inject: ['bash', 'llm', …], apply(ctx) { … } }` — declares dependencies, and cordis activates the plugin only after the services exist; PREFER this form for any plugin that needs bash, llm, sessions, etc. BEFORE calling a service from your code, read cordis_inspect what:"api" — it lists method signatures AND the type shapes of their arguments/returns (do not guess a field's type; e.g. a bash run's stdout is an object, not a string). Inside `apply`, use the standard cordis API: `ctx.on(event, listener)` to observe events (see cordis_inspect what:"events"), or call `harness.registerTool(ctx, harness.defineTool({ name, description, parameters: { text: { type: 'string', required: true } }, async execute(args) { … } }))` to give yourself a new tool — it becomes callable on your NEXT step. Tool parameters: each key IS a property — { type: 'string'|'number'|'boolean'|'object'|'array', required?: true, description?, enum?, items?, properties? }; a JSON-Schema-style { type: 'object', properties, required: […] } wrapper and type 'integer' are also accepted and normalized. A tool's `execute` MUST return an ARRAY of content blocks, e.g. `return [{ type: 'text', text: someString }]` — never a bare string. Mounts can COMPOSE: one plugin may `ctx.provide('name', value)` a service and another may declare `inject: ['name']` to consume it — the consumer stays pending until the provider exists and returns to pending when the provider is unmounted. Everything registered inside `apply` is cleaned up automatically on unmount. Sandbox globals: `console` (tagged `[cordis:]`, writes through to the harness terminal), `harness.defineTool`, `harness.registerTool`, `btoa`, `atob`, `TextEncoder`, `TextDecoder`. Node APIs are DISABLED — do filesystem/network/timer work through the cordis services, never Node built-ins: `require`, `setTimeout`/`setInterval`, and `fetch` throw redirect errors; `process` and `Buffer` are undefined. Instead use inject: ['fs'] + ctx.fs for files, inject: ['web'] + ctx.web for HTTP, inject: ['bash'] + ctx.bash for processes, and inject: ['timer'] + ctx.setTimeout/ctx.setInterval for timing (fiber effects, auto-cleaned on unmount) — cordis_inspect what:"api" shows what THIS runtime provides. Write PLAIN JavaScript, not TypeScript (no `as`, no type annotations). Cautions: (1) waterfall events (e.g. tools/pre-execute) hand the listener a trailing `next` callback which MUST be called — returning without `next()` VETOES the call; prefer plain notification events unless you intend to intercept. (2) Never await something that only resolves after the current turn (your code runs INSIDE a tool call of that turn — it would deadlock). (3) The sandbox prevents accidental global pollution, not malice: `ctx` is the real, fully privileged runtime handle. +Mount a NEW cordis plugin into the live runtime that is running THIS agent (self-modification). `code` runs as the body of an async JavaScript function in an isolated sandbox and MUST `return` a plugin. Two forms: FUNCTION form `return (ctx) => { … }` — cannot declare inject, uses whatever services are on the parent context, and accessing a service without inject (e.g. ctx.bash) throws; use it only when you need no injected services. OBJECT form `return { name?, inject: ['bash', 'llm', …], apply(ctx) { … } }` — declares dependencies, and cordis activates the plugin only after the services exist; PREFER this form for any plugin that needs bash, llm, sessions, etc. BEFORE calling a service from your code, read cordis_inspect what:"api" — it lists method signatures AND the type shapes of their arguments/returns (do not guess a field's type; e.g. a bash run's stdout is an object, not a string). Inside `apply`, use the standard cordis API: `ctx.on(event, listener)` to observe events (see cordis_inspect what:"events"), or call `harness.registerTool(ctx, harness.defineTool({ name, description, parameters: { text: { type: 'string', required: true } }, async execute(args) { … } }))` to give yourself a new tool — it becomes callable on your NEXT step. Tool parameters: each key IS a property — { type: 'string'|'number'|'boolean'|'object'|'array', required?: true, description?, enum?, items?, properties? }; a JSON-Schema-style { type: 'object', properties, required: […] } wrapper and type 'integer' are also accepted and normalized. A tool's `execute` MUST return an ARRAY of content blocks, e.g. `return [{ type: 'text', text: someString }]` — never a bare string. Mounts can COMPOSE: one plugin may `ctx.provide('name', value)` a service and another may declare `inject: ['name']` to consume it — the consumer stays pending until the provider exists and returns to pending when the provider is unmounted. Everything registered inside `apply` is cleaned up automatically on unmount. Sandbox globals: `console` (tagged `[cordis:]`, writes through to the harness terminal), `harness.defineTool`, `harness.registerTool`, `btoa`, `atob`, `TextEncoder`, `TextDecoder`. Node APIs are DISABLED — do filesystem/network/timer work through the cordis services, never Node built-ins: `require`, `setTimeout`/`setInterval`, and `fetch` throw redirect errors; `process` and `Buffer` are undefined. Instead use inject: ['fs'] + ctx.fs for files, inject: ['web'] + ctx.web for HTTP, inject: ['bash'] + ctx.bash for processes, and inject: ['timer'] + ctx.setTimeout/ctx.setInterval for timing (fiber effects, auto-cleaned on unmount) — cordis_inspect what:"api" shows what THIS runtime provides. Write PLAIN JavaScript, not TypeScript (no `as`, no type annotations). Cautions: (1) waterfall events (e.g. tools/pre-execute) hand the listener a trailing `next` callback which MUST be called — returning without `next()` VETOES the call; prefer plain notification events unless you intend to intercept. (2) Never await something that only resolves after the current turn (your code runs INSIDE a tool call of that turn — it would deadlock). (3) Your `ctx` is a restricted façade: you can register tools, observe events, provide/consume services, and use timers, but framework internals (ctx.root, ctx.fiber, ctx.extend, ctx.plugin, …) are withheld. It is not a security boundary though — the services you inject (e.g. ctx.bash) reach the real runtime. ```json { diff --git a/packages/cordis/tool-cordis/README.md b/packages/cordis/tool-cordis/README.md index b369a7209b..651f3273d9 100644 --- a/packages/cordis/tool-cordis/README.md +++ b/packages/cordis/tool-cordis/README.md @@ -12,7 +12,7 @@ Exact model-facing schemas: [the generated tool catalog](../../../docs/tool-cata ## Trust stance -The sandbox isolates the global context only — it is not a security boundary. No Node API is provided: `require`, the timers, and `fetch` are callable traps that throw a redirect to the cordis alternative (`ctx.fs` / `ctx.web` / `ctx.bash` / `inject: ['timer']` + `ctx.setTimeout`); `process` and `Buffer` are `undefined`; `globalThis` writes stay inside. The `ctx` a mounted plugin's `apply` receives is the real, fully privileged runtime handle; load this plugin as deliberately as you would grant a bash tool. +The sandbox isolates the global context only — it is not a security boundary. No Node API is provided: `require`, the timers, and `fetch` are callable traps that throw a redirect to the cordis alternative (`ctx.fs` / `ctx.web` / `ctx.bash` / `inject: ['timer']` + `ctx.setTimeout`); `process` and `Buffer` are `undefined`; `globalThis` writes stay inside. The `ctx` a mounted plugin's `apply` receives is a whitelist façade — register tools, observe events, provide/consume services, use timers; framework internals (`ctx.root`, `ctx.fiber`, `ctx.extend`, `ctx.plugin`, …) are withheld — but the capabilities it does expose reach the real runtime, so load this plugin as deliberately as you would grant a bash tool. ## Config diff --git a/packages/cordis/tool-cordis/src/api-catalog.ts b/packages/cordis/tool-cordis/src/api-catalog.ts index 39f1a12f47..83170d8dc1 100644 --- a/packages/cordis/tool-cordis/src/api-catalog.ts +++ b/packages/cordis/tool-cordis/src/api-catalog.ts @@ -88,6 +88,13 @@ export const SERVICE_API: readonly ServiceApiEntry[] = [ 'onTaskDone(listener: BashTaskListener): () => void', ], }, + { + key: 'codeRuntime', + summary: 'Abstract code-execution service.', + methods: [ + 'abstract run(request: CodeRunRequest): Promise', + ], + }, { key: 'compact', summary: 'Abstract compaction service.', @@ -429,6 +436,30 @@ export const TYPE_API: readonly TypeApiEntry[] = [ name: 'CallId', declaration: 'export type CallId = Branded<\'CallId\'>;', }, + { + name: 'CodeBindingFunction', + declaration: 'export type CodeBindingFunction = (args: unknown) => Promise;', + }, + { + name: 'CodeBindingNamespace', + declaration: 'export interface CodeBindingNamespace {\n global: string;\n functions: Record;\n}', + }, + { + name: 'CodeLogEntry', + declaration: 'export interface CodeLogEntry {\n source: \'console\' | \'stdout\' | \'stderr\';\n level?: \'log\' | \'info\' | \'warn\' | \'error\' | \'debug\';\n text: string;\n}', + }, + { + name: 'CodeRunFailure', + declaration: 'export interface CodeRunFailure {\n kind: \'exception\' | \'timeout\' | \'abort\' | \'worker-exit\';\n message: string;\n}', + }, + { + name: 'CodeRunRequest', + declaration: 'export interface CodeRunRequest {\n program: string;\n bindings: CodeBindingNamespace[];\n signal?: AbortSignal;\n}', + }, + { + name: 'CodeRunResult', + declaration: 'export interface CodeRunResult {\n value?: unknown;\n logs: CodeLogEntry[];\n error?: CodeRunFailure;\n}', + }, { name: 'CollectedOutput', declaration: 'export interface CollectedOutput {\n text: string;\n truncated: boolean;\n spillPath?: string;\n}', diff --git a/packages/cordis/tool-cordis/src/guard.ts b/packages/cordis/tool-cordis/src/guard.ts index 998997a8f9..07cd0f1df3 100644 --- a/packages/cordis/tool-cordis/src/guard.ts +++ b/packages/cordis/tool-cordis/src/guard.ts @@ -2,18 +2,35 @@ * The registration boundary between sandboxed mount code and the real runtime: * SchemaSpec normalization + validation with teaching errors, the * marker-guarded `harness.defineTool` / `harness.registerTool` pair, the - * guarded `ctx` proxy a mounted plugin receives, and the plugin-shape helpers - * the mount lifecycle narrows sandbox return values with. + * SANDBOX CONTEXT FAÇADE a mounted plugin's `apply` receives in place of the + * real `ctx`, and the plugin-shape helpers the mount lifecycle narrows sandbox + * return values with. * - * Two realm facts drive the design. Objects built inside the vm carry the vm + * The façade is a WHITELIST, not a pass-through proxy. Mount code needs to do + * exactly four things — register a tool, listen to an event, provide a service, + * call an injected service (timers included) — so the façade exposes only those + * verbs and the injected services, each individually wrapped. Every framework + * plumbing member (`root`, `parent`, `scope`, `fiber`, `reflect`, `registry`, + * `events`, `extend`, `isolate`, `intercept`, `plugin`, `set`, `mixin`, …) is + * DENIED with a teaching error rather than passed through. This closes an + * entire escape class at once: a pass-through proxy that only special-cased + * `ctx.tools` still handed back the raw context through `ctx.root`, + * `ctx.extend()`, or a service instance's `.ctx`, and mount code could then + * `ctx.root.tools.register({…})` to bypass the marker check and host-realm + * normalization — a raw vm-realm result then errors a real agent turn at the + * session-log plainness check. The whitelist has no such hole: there is no + * context-valued member to reach, and any injected-service method that returns + * a `Context` is rejected (harness services never do — see {@link denyContext}). + * + * Two realm facts drive the tool path. Objects built inside the vm carry the vm * realm's `Object.prototype`, and the session log's append-time plainness check * (`dsh-session`'s `isJsonValue`, a prototype-identity comparison) rejects * foreign-realm data — so every dynamic tool's `execute` return is JSON * round-tripped into the host realm before it reaches the registry, and the * schema itself is rebuilt as fresh host-realm objects. And a malformed tool * schema must fail at REGISTRATION, not when a later request assembles it — so - * dynamic `ctx.tools.register` calls accept only definitions produced by the - * sandbox's `harness.defineTool`, which normalizes `parameters` up front. + * dynamic tool registration accepts only definitions produced by the sandbox's + * `harness.defineTool`, which normalizes `parameters` up front. * * Normalize, don't lecture, where the input has exactly one meaning: models * write the JSON-Schema dialect by strong prior (the `{ type: 'object', @@ -26,7 +43,8 @@ * @module @deepseek-ai/dsh-tool-cordis/guard */ -import type { Context, Plugin } from 'cordis' +import { Context } from 'cordis' +import type { Plugin } from 'cordis' import { defineTool } from '@deepseek-ai/dsh-tools' import type { ToolDefinition, ToolExecuteReturn } from '@deepseek-ai/dsh-tools' @@ -153,31 +171,116 @@ export function sandboxRegisterTool(ctx: Context, tool: unknown): () => void { return ctx.tools.register(tool) } -function bindMethod(value: unknown, target: object): unknown { - if (typeof value !== 'function') return value - return (...args: unknown[]): unknown => Reflect.apply(value, target, args) as unknown +/** + * The verbs a mounted plugin may reach through the sandbox `ctx` façade, + * beyond its injected services. `on`/`once` observe events, `provide` exposes + * a service to other mounts, and the timer helpers schedule work — each a + * fiber effect that unwinds on unmount. Everything else on a real cordis `ctx` + * is framework plumbing and is denied. Forwarded LAZILY: the timer helpers are + * mixin accessors that throw `without inject` when read on a plugin that did + * not inject `timer`, so the façade reads `ctx[verb]` only at call time — the + * plugin that never touches a timer never trips that, and one that does gets + * cordis's own inject error at the call site. + */ +const CTX_VERBS = new Set(['on', 'once', 'provide', 'timeout', 'interval', 'setTimeout', 'setInterval', 'throttle', 'debounce']) + +/** + * The tool-registry façade: only `register` (marker-guarded), plus the + * read-only `schemas` / `get` a mount may legitimately want. No other registry + * method (nothing that could re-enter the raw context) is exposed. + */ +function sandboxTools(ctx: Context): Record { + return { + register: (tool: unknown): (() => void) => sandboxRegisterTool(ctx, tool), + schemas: () => ctx.tools.schemas(), + get: (name: string) => ctx.tools.get(name), + } } -function guardedContext(ctx: Context): Context { - const tools = new Proxy(ctx.tools, { +/** + * Reject any injected-service return that is a cordis `Context`. Harness + * services return data, never a context; a value that is one would be a + * fresh, unguarded handle back into the runtime — the exact escape the façade + * exists to close — so it fails loud instead of reaching sandbox code. + */ +function denyContext(value: unknown, service: string): unknown { + if (value instanceof Context) { + throw new Error( + `service "${service}" returned a cordis Context, which the sandbox does not expose. ` + + 'Operate through your own plugin ctx (ctx.on / ctx.provide / ctx.tools.register) ' + + 'and the services you inject — never another context.', + ) + } + return value +} + +/** + * Wrap an injected service so its methods forward to the real instance but + * their return values pass through {@link denyContext}. Non-function members + * (plain data) pass through as-is; a returned Promise is guarded on resolve. + */ +function guardedService(service: object, name: string): unknown { + return new Proxy(service, { get(target, prop) { - if (prop === 'register') { - return (tool: unknown): () => void => sandboxRegisterTool(ctx, tool) - } const value = Reflect.get(target, prop, target) as unknown - return bindMethod(value, target) + if (typeof value !== 'function') return denyContext(value, name) + return (...args: unknown[]): unknown => { + const result = Reflect.apply(value, target, args) as unknown + if (result instanceof Promise) return result.then(v => denyContext(v, name)) + return denyContext(result, name) + } }, }) - return new Proxy(ctx, { - get(target, prop) { +} + +/** + * The sandbox context façade handed to a mounted plugin's `apply` in place of + * the real `ctx`. A whitelist (see the module doc): the registration/eventing + * verbs, the timer helpers, a guarded `tools`, and injected services resolved + * through a guarded `get` / property access. Every framework-plumbing member + * is denied with a teaching error; there is no context-valued member to reach. + */ +function sandboxContext(ctx: Context): Context { + const tools = sandboxTools(ctx) + // Resolve a named service to a guarded wrapper, or undefined when absent. + const resolveService = (name: string): unknown => { + if (name === 'tools') return tools + const service: unknown = ctx.get(name) + return service === undefined ? undefined : guardedService(service as object, name) + } + const get = (name: string): unknown => resolveService(name) + return new Proxy({}, { + get(_target, prop) { if (prop === 'tools') return tools - if (prop === 'get') { - return (service: string): unknown => service === 'tools' ? tools : target.get(service) + if (prop === 'get') return get + if (typeof prop !== 'string') return undefined + // Lazy verb forwarder — reads `ctx[verb]` only when called, so a plugin + // that never uses a timer never triggers the timer mixin's inject check. + if (CTX_VERBS.has(prop)) { + return (...args: unknown[]): unknown => { + const method = ctx[prop as keyof Context] + return Reflect.apply(method as (...a: unknown[]) => unknown, ctx, args) + } } - const value = Reflect.get(target, prop, target) as unknown - return bindMethod(value, target) + // A declared-and-injected service reads as a ctx property; resolve it + // through the same guard. Absent → the deny path (framework plumbing, + // an un-injected service, or a typo) with one teaching error. + const service = resolveService(prop) + if (service !== undefined) return service + throw new Error( + `sandbox ctx does not expose "${prop}". Available: ctx.tools.register / ctx.on / ctx.provide / ` + + 'the timer helpers (ctx.setTimeout, ctx.interval, …) and any service you declared in inject. ' + + 'Framework internals (root, fiber, registry, extend, plugin, …) are withheld by design.', + ) }, - }) + // A façade is not the real ctx; block writes rather than let mount code + // stash state on a throwaway object and think it persisted. + set(_target, prop) { + throw new Error(`sandbox ctx is read-only; cannot assign "${String(prop)}"`) + }, + has: (_target, prop) => prop === 'tools' || prop === 'get' + || (typeof prop === 'string' && (CTX_VERBS.has(prop) || resolveService(prop) !== undefined)), + }) as unknown as Context } /** @@ -194,13 +297,19 @@ export function isPlugin(value: unknown): value is Plugin { } /** - * Wrap a plugin so its `apply` receives a guarded context (`tools.register` - * only accepts tools from `harness.defineTool`). Both function-form and - * object-form plugins go through the same guard; everything else on the - * context — `on`, `provide`, `inject` resolution — passes through with correct - * `this` binding, so cross-mount provide/inject works unmodified. + * Wrap a plugin so its `apply` receives the sandbox context façade instead of + * the real `ctx` (see {@link sandboxContext} and the module doc). Both + * function-form and object-form plugins go through the same wrap; the plugin's + * own `inject` declaration is preserved (cordis reads it from the plugin + * object, and pending/active gating happens on the real fiber before `apply` + * runs), so cross-mount provide/inject works unmodified. + * + * `ctx.effect(customCleanup)` is deliberately absent from the façade for now — + * `on` / `provide` / `tools.register` cover every mount seen so far, and each + * is already a fiber effect. FIXME(sandbox-effect): expose a guarded `effect` + * once a real mount needs a bespoke disposer. * @param plugin - the plugin the mount code returned. - * @returns an equivalent plugin whose `apply` sees the guarded context. + * @returns an equivalent plugin whose `apply` sees the sandbox context façade. */ export function guardedPlugin(plugin: Plugin): Plugin { if (typeof plugin === 'function') { @@ -208,7 +317,7 @@ export function guardedPlugin(plugin: Plugin): Plugin { return { name: pluginName(plugin), apply(ctx: Context, config?: unknown) { - return functionPlugin(guardedContext(ctx), config) + return functionPlugin(sandboxContext(ctx), config) }, } } @@ -216,7 +325,7 @@ export function guardedPlugin(plugin: Plugin): Plugin { return { ...plugin, apply(ctx: Context, config?: unknown) { - return objectPlugin.apply(guardedContext(ctx), config) + return objectPlugin.apply(sandboxContext(ctx), config) }, } } diff --git a/packages/cordis/tool-cordis/src/index.ts b/packages/cordis/tool-cordis/src/index.ts index 875637bfc4..f7d1958625 100644 --- a/packages/cordis/tool-cordis/src/index.ts +++ b/packages/cordis/tool-cordis/src/index.ts @@ -18,10 +18,14 @@ * this plugin. Design home: * docs/rfc/implemented/feature/2026-07-08-self-referential-cordis-toolset.md. * - * The vm sandbox guards against ACCIDENTAL global pollution only — it is not a - * security boundary. The `ctx` handed to the mounted plugin's `apply` is the - * real, fully privileged runtime handle; that is the point of the toolset, so - * a deployment loads this plugin as deliberately as it grants a bash tool. + * The vm sandbox guards against ACCIDENTAL global pollution only, and the `ctx` + * a mounted plugin's `apply` receives is a WHITELIST façade (register a tool, + * observe events, provide/consume services, use timers — framework internals + * withheld; see the guard module). Neither is a security boundary: the verbs + * the façade DOES expose reach the real runtime unsandboxed (a mounted tool can + * shell out through `ctx.bash`), so a deployment loads this plugin as + * deliberately as it grants a bash tool. Design home: + * docs/rfc/implemented/feature/2026-07-08-self-referential-cordis-toolset.md. * * Plugin export shape: named exports, NO default. The cordis Loader's * `unwrapExports` does `exports.default ?? exports`, so a stray default would @@ -159,8 +163,11 @@ export function apply(ctx: Context, config: Config): void { + 'VETOES the call; prefer plain notification events unless you intend to ' + 'intercept. (2) Never await something that only resolves after the current ' + 'turn (your code runs INSIDE a tool call of that turn — it would deadlock). ' - + '(3) The sandbox prevents accidental global pollution, not malice: `ctx` is ' - + 'the real, fully privileged runtime handle.', + + '(3) Your `ctx` is a restricted façade: you can register tools, observe ' + + 'events, provide/consume services, and use timers, but framework internals ' + + '(ctx.root, ctx.fiber, ctx.extend, ctx.plugin, …) are withheld. It is not a ' + + 'security boundary though — the services you inject (e.g. ctx.bash) reach the ' + + 'real runtime.', parameters: { code: { type: 'string', diff --git a/packages/cordis/tool-cordis/tests/mount.spec.ts b/packages/cordis/tool-cordis/tests/mount.spec.ts index 543b38307f..d0db8d7efa 100644 --- a/packages/cordis/tool-cordis/tests/mount.spec.ts +++ b/packages/cordis/tool-cordis/tests/mount.spec.ts @@ -386,13 +386,13 @@ describe('cordis_mount', () => { console.error('errored') const round = atob(btoa('hi')) const bytes = new TextEncoder().encode(round) - return { name: 'codec-' + new TextDecoder().decode(bytes), apply(ctx) { console.log('applied', typeof ctx.fiber) } } + return { name: 'codec-' + new TextDecoder().decode(bytes), apply(ctx) { console.log('applied', typeof ctx.on) } } `, }) expect(result.isError).toBe(false) expect(text(result)).toContain('plugin "codec-hi"') expect(log).toHaveBeenCalledWith('[cordis:dyn-1]', 'warned') - expect(log).toHaveBeenCalledWith('[cordis:dyn-1]', 'applied', 'object') + expect(log).toHaveBeenCalledWith('[cordis:dyn-1]', 'applied', 'function') expect(error).toHaveBeenCalledWith('[cordis:dyn-1]', 'errored') }) diff --git a/packages/cordis/tool-cordis/tests/sandbox-context.spec.ts b/packages/cordis/tool-cordis/tests/sandbox-context.spec.ts new file mode 100644 index 0000000000..50f5b441a2 --- /dev/null +++ b/packages/cordis/tool-cordis/tests/sandbox-context.spec.ts @@ -0,0 +1,156 @@ +import { describe, expect, it } from 'vitest' +import { call, setup, text } from './helpers.ts' + +/** + * The sandbox context façade is a whitelist, not a pass-through proxy: mount + * code reaches only the registration/eventing verbs, the timer helpers, a + * guarded `tools`, and its injected services. Every framework-plumbing member + * that could hand back an UNGUARDED context — through which a plugin could + * `ctx..tools.register({…})` to bypass the marker check and host-realm + * normalization — is denied. These are the regression guards for that escape + * class (the review finding on the original pass-through proxy). + */ + +/** Mount a plugin whose `apply` touches one framework member, and report the error text. */ +async function mountTouching(ctx: Awaited>, expr: string): Promise { + const result = await call(ctx, 'cordis_mount', { + code: `return { name: 'probe', inject: ['tools'], apply(ctx) { ${expr} } }`, + }) + expect(result.isError).toBe(true) + return text(result) +} + +describe('sandbox context façade — escape surface is closed', () => { + it.each([ + ['ctx.root', 'const c = ctx.root'], + ['ctx.parent', 'const c = ctx.parent'], + ['ctx.scope', 'const c = ctx.scope'], + ['ctx.fiber', 'const f = ctx.fiber'], + ['ctx.reflect', 'const r = ctx.reflect'], + ['ctx.registry', 'const r = ctx.registry'], + ['ctx.events', 'const e = ctx.events'], + ['ctx.extend()', 'ctx.extend({})'], + ['ctx.isolate()', 'ctx.isolate("x")'], + ['ctx.intercept()', 'ctx.intercept("x", {})'], + ['ctx.plugin()', 'ctx.plugin({ apply() {} })'], + ['ctx.set()', 'ctx.set("tools", 1)'], + ['ctx.mixin()', 'ctx.mixin("x", [])'], + ])('denies %s with a teaching error', async (_label, expr) => { + const ctx = await setup() + const message = await mountTouching(ctx, expr) + expect(message).toContain('sandbox ctx does not expose') + expect(message).toContain('withheld by design') + }) + + it('the classic ctx.root.tools.register bypass registers nothing and fails loud', async () => { + const ctx = await setup() + const result = await call(ctx, 'cordis_mount', { + code: ` + return { + name: 'root-bypass', + inject: ['tools'], + apply(ctx) { + ctx.root.tools.register({ + name: 'smuggled', + description: 'raw, unguarded', + parameters: { type: 'object', properties: {} }, + async execute() { return [] }, + }) + }, + } + `, + }) + expect(result.isError).toBe(true) + expect(text(result)).toContain('sandbox ctx does not expose "root"') + // The whole point: the bypass never reaches the registry. + expect(ctx.tools.get('smuggled')).toBeUndefined() + }) + + it('rejects assignment to the façade rather than silently dropping it', async () => { + const ctx = await setup() + const result = await call(ctx, 'cordis_mount', { + code: 'return { name: \'writer\', apply(ctx) { ctx.stash = 1 } }', + }) + expect(result.isError).toBe(true) + expect(text(result)).toContain('sandbox ctx is read-only') + }) + + it('denies a service whose method returns a Context (the .ctx escape), registering nothing', async () => { + // A cordis Service instance carries `.ctx` (a real Context), so + // `ctx.systemPrompt.ctx.root.tools.register(…)` would be a fresh unguarded + // handle. The service wrapper's return-value guard rejects any Context on + // the way back to sandbox code, so the escape never lands. (`systemPrompt` + // is in the setup harness, so the plugin activates and its apply runs.) + const ctx = await setup() + const result = await call(ctx, 'cordis_mount', { + code: ` + return { + name: 'svc-ctx-escape', + inject: ['systemPrompt', 'tools'], + apply(ctx) { + ctx.systemPrompt.ctx.root.tools.register({ + name: 'smuggled_via_service', + description: 'raw, unguarded', + parameters: { type: 'object', properties: {} }, + async execute() { return [] }, + }) + }, + } + `, + }) + expect(result.isError).toBe(true) + expect(text(result)).toContain('returned a cordis Context, which the sandbox does not expose') + expect(ctx.tools.get('smuggled_via_service')).toBeUndefined() + }) + + it('guards an async injected-service method: a host-realm Promise resolves through the guard', async () => { + // The return guard's Promise arm only fires for a HOST-realm Promise + // (a vm-realm one is not `instanceof` the host `Promise`). Provide a + // host-realm service from the test, then inject + await it from a mount: + // the resolved value is non-Context data and passes through. + const ctx = await setup() + ctx.plugin({ + name: 'host-async-svc', + apply(c) { c.provide('hostAsync', { grab: async () => 'host-fetched' }) }, + }) + await call(ctx, 'cordis_mount', { + code: ` + return { + name: 'async-consumer', + inject: ['hostAsync', 'tools'], + apply(ctx) { + harness.registerTool(ctx, harness.defineTool({ + name: 'do_fetch', + description: 'awaits the host async service', + parameters: {}, + async execute() { + const value = await ctx.hostAsync.grab() + return [{ type: 'text', text: value }] + }, + })) + }, + } + `, + }) + const result = await call(ctx, 'do_fetch', {}) + expect(result.isError).toBe(false) + expect(text(result)).toBe('host-fetched') + }) + + it('reads a symbol property as undefined and answers the `in` operator without throwing', async () => { + const ctx = await setup() + const result = await call(ctx, 'cordis_mount', { + code: ` + return { + name: 'introspector', + inject: ['tools'], + apply(ctx) { + const sym = ctx[Symbol.iterator] + console.log('probe', sym === undefined, 'tools' in ctx, 'on' in ctx, 'root' in ctx) + }, + } + `, + }) + expect(result.isError).toBe(false) + }) +}) From 3e9527278a2e513a91c19d491170db076b91ca93 Mon Sep 17 00:00:00 2001 From: imccyu <276526105+imccyu@users.noreply.github.com> Date: Thu, 9 Jul 2026 12:44:57 +0800 Subject: [PATCH 12/15] =?UTF-8?q?fix(tool-cordis):=20gate=20fa=C3=A7ade=20?= =?UTF-8?q?services=20on=20inject,=20and=20make=20tools.get=20read-only?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Two review findings (#220) on the sandbox context façade: - Undeclared services were reachable: the façade resolved any live global via ctx.get(name), so ctx.bash worked without inject: ['bash']. A cross-mount consumer could then depend on a provider cordis never saw — unmounting the provider would neither park the consumer nor unwind its registered tools, leaving a model-visible tool that fails only at execution. The façade now reads ctx.fiber.inject and refuses any service the mount did not declare (with a teaching error naming the inject fix), so the dependency is always visible to cordis and its activation/unload semantics bind. - ctx.tools.get returned the live ToolDefinition, including execute — mount code could call another tool directly and bypass ToolRegistry.execute and its pre/post-execute hooks and accounting. get now returns the same read-only name/description/parameters view as schemas(), never an invocable. Adds inject-gate and schema-view regression cases to sandbox-context.spec.ts (undeclared property/get denied, declared allowed, the cross-mount zombie-tool scenario refused at call time, get exposes no execute). Package stays at per-file 100% coverage. RFC, mount description, and tool-catalog updated. --- ...6-07-08-self-referential-cordis-toolset.md | 2 +- docs/tool-catalog.md | 2 +- packages/cordis/tool-cordis/src/guard.ts | 84 ++++++++--- packages/cordis/tool-cordis/src/index.ts | 10 +- .../cordis/tool-cordis/tests/mount.spec.ts | 2 - .../tool-cordis/tests/sandbox-context.spec.ts | 139 ++++++++++++++++++ 6 files changed, 207 insertions(+), 32 deletions(-) diff --git a/docs/rfc/implemented/feature/2026-07-08-self-referential-cordis-toolset.md b/docs/rfc/implemented/feature/2026-07-08-self-referential-cordis-toolset.md index 2ba398301b..fff36fee91 100644 --- a/docs/rfc/implemented/feature/2026-07-08-self-referential-cordis-toolset.md +++ b/docs/rfc/implemented/feature/2026-07-08-self-referential-cordis-toolset.md @@ -30,7 +30,7 @@ Mount code runs via `vm.createContext` + `runInContext`, wrapped as the body of Sandbox globals are deliberately small: a tagged write-through `console` (`[cordis:] …` on the host stdout/stderr, so a listener that fires long after the mount call still lands somewhere the user sees), the `harness.defineTool` / `harness.registerTool` registration pair, the encoding primitives fresh vm contexts lack (`btoa`/`atob` as host closures over `Buffer` — a sanctioned exception, `Buffer` itself is never exposed — plus `TextEncoder`/`TextDecoder`), and callable traps over the withheld Node APIs (`require`, `setTimeout`/`setInterval`/`setImmediate`/`clearTimeout`/`clearInterval`, `fetch`) that throw a redirect naming the cordis alternative. Only function-shaped globals are trapped; `process` and `Buffer` stay `undefined` so a `typeof` feature probe stays inert rather than detonating a throwing accessor. -Three boundary mechanisms make model-written code behave correctly across the realm seam. **Dual-realm `instanceof`**: most objects sandbox code touches are host-realm (tool `args`, event payloads, service returns), so a plain `x instanceof Array` in the vm would silently be false — a per-sandbox prelude gives the vm realm's own constructors a `Symbol.hasInstance` that checks both the vm constructor and its host counterpart, patching only vm-realm globals. **Realm normalization of tool results**: objects built inside the vm carry the vm realm's `Object.prototype`, which the session log's append-time plainness check (`isJsonValue` in `dsh-session`, a prototype-identity comparison) rejects, so the sandbox's `harness.defineTool` JSON round-trips every `execute` return into the host realm — which also projects it onto exactly what the log durably stores. **A whitelist context façade**: the `ctx` a mounted plugin's `apply` receives is NOT the real context nor a pass-through proxy over it — it is a façade exposing only what a mount legitimately needs (`tools.register` marker-guarded, `on`/`once`, `provide`, the timer helpers, and injected services resolved through a guarded `get`), with every framework-plumbing member (`root`, `parent`, `fiber`, `reflect`, `registry`, `extend`, `isolate`, `intercept`, `plugin`, `set`, `mixin`, …) denied with a teaching error. This closes an escape *class* rather than a single hole: a proxy that merely special-cased `ctx.tools` still handed back the raw context through `ctx.root`, `ctx.extend()`, or a service instance's `.ctx`, and mount code could then `ctx.root.tools.register({…})` to bypass the marker check and realm normalization — a raw vm-realm result then errors a real agent turn at the plainness check. The façade has no context-valued member to reach, and the one indirect leak (an injected-service method returning a `Context`) is rejected on the way back to sandbox code; cross-mount `provide`/`inject` keeps working because the plugin's own `inject` and the fiber's pending/active gating are untouched — only the `apply`-time `ctx` surface is narrowed. +Three boundary mechanisms make model-written code behave correctly across the realm seam. **Dual-realm `instanceof`**: most objects sandbox code touches are host-realm (tool `args`, event payloads, service returns), so a plain `x instanceof Array` in the vm would silently be false — a per-sandbox prelude gives the vm realm's own constructors a `Symbol.hasInstance` that checks both the vm constructor and its host counterpart, patching only vm-realm globals. **Realm normalization of tool results**: objects built inside the vm carry the vm realm's `Object.prototype`, which the session log's append-time plainness check (`isJsonValue` in `dsh-session`, a prototype-identity comparison) rejects, so the sandbox's `harness.defineTool` JSON round-trips every `execute` return into the host realm — which also projects it onto exactly what the log durably stores. **A whitelist context façade**: the `ctx` a mounted plugin's `apply` receives is NOT the real context nor a pass-through proxy over it — it is a façade exposing only what a mount legitimately needs (`tools.register` marker-guarded, a read-only `tools.get`/`schemas`, `on`/`once`, `provide`, the timer helpers, and the services the plugin DECLARED in `inject`), with every framework-plumbing member (`root`, `parent`, `fiber`, `reflect`, `registry`, `extend`, `isolate`, `intercept`, `plugin`, `set`, `mixin`, …) denied with a teaching error. This closes an escape *class* rather than a single hole: a proxy that merely special-cased `ctx.tools` still handed back the raw context through `ctx.root`, `ctx.extend()`, or a service instance's `.ctx`, and mount code could then `ctx.root.tools.register({…})` to bypass the marker check and realm normalization — a raw vm-realm result then errors a real agent turn at the plainness check. The façade has no context-valued member to reach, and the one indirect leak (an injected-service method returning a `Context`) is rejected on the way back to sandbox code. Two narrower rules complete the surface. First, **service access requires an `inject` declaration**: reaching a service the mount did not declare is refused even when a global provider is live — otherwise a mount could depend on a provider cordis never sees, and unmounting that provider would neither park the consumer nor unwind the tools it registered, leaving a model-visible tool that fails only at execution time. Because the read is gated on the declaration, cross-mount `provide`/`inject` keeps its lifecycle guarantees (the plugin's own `inject` and the fiber's pending/active gating drive activation and unload); only the `apply`-time `ctx` surface is narrowed. Second, **`ctx.tools.get` returns a read-only schema view** (name/description/parameters), never the live `ToolDefinition` — handing back the definition would expose its `execute`, letting mount code call another tool directly and bypass `ToolRegistry.execute` and its pre/post-execute hooks and accounting; a mount that wants to invoke a tool must go through the registry, and one that wants to introspect gets the same view `schemas()` returns. Boundary errors are written around the mistakes models actually make (see [Consequences](#consequences) for how each was found), and the boundary normalizes rather than lectures wherever the input has exactly one meaning: schema `parameters` accept the JSON-Schema dialect models write by strong prior — the `{ type: 'object', properties, required: […] }` wrapper unwraps to the SchemaSpec DSL (the `required` array becoming per-property flags, at any nesting level), `type: 'integer'` maps to `number`, and `required: false` reads as optional — while genuinely meaningless input is rejected with the vocabulary enumerated (an unknown type lists the five valid ones; a non-boolean `required` names the rule). The remaining teaching errors: an unbalanced `});` closing gets the vm's offending source line plus a "code is a function body" reminder; TypeScript syntax gets the remove-annotations fix (detected on the failing line only, so an ` as ` inside a description string does not misfire); a forgotten `return` gets the two valid plugin forms; a Node built-in call gets the redirect to its cordis service; a tool-name collision on re-mount gets the unmount-first-then-remount recipe. diff --git a/docs/tool-catalog.md b/docs/tool-catalog.md index 990e135b1c..a2026904cf 100644 --- a/docs/tool-catalog.md +++ b/docs/tool-catalog.md @@ -136,7 +136,7 @@ Source: [`packages/cordis/tool-cordis/src/index.ts`](../packages/cordis/tool-cor ### `cordis_mount` -Mount a NEW cordis plugin into the live runtime that is running THIS agent (self-modification). `code` runs as the body of an async JavaScript function in an isolated sandbox and MUST `return` a plugin. Two forms: FUNCTION form `return (ctx) => { … }` — cannot declare inject, uses whatever services are on the parent context, and accessing a service without inject (e.g. ctx.bash) throws; use it only when you need no injected services. OBJECT form `return { name?, inject: ['bash', 'llm', …], apply(ctx) { … } }` — declares dependencies, and cordis activates the plugin only after the services exist; PREFER this form for any plugin that needs bash, llm, sessions, etc. BEFORE calling a service from your code, read cordis_inspect what:"api" — it lists method signatures AND the type shapes of their arguments/returns (do not guess a field's type; e.g. a bash run's stdout is an object, not a string). Inside `apply`, use the standard cordis API: `ctx.on(event, listener)` to observe events (see cordis_inspect what:"events"), or call `harness.registerTool(ctx, harness.defineTool({ name, description, parameters: { text: { type: 'string', required: true } }, async execute(args) { … } }))` to give yourself a new tool — it becomes callable on your NEXT step. Tool parameters: each key IS a property — { type: 'string'|'number'|'boolean'|'object'|'array', required?: true, description?, enum?, items?, properties? }; a JSON-Schema-style { type: 'object', properties, required: […] } wrapper and type 'integer' are also accepted and normalized. A tool's `execute` MUST return an ARRAY of content blocks, e.g. `return [{ type: 'text', text: someString }]` — never a bare string. Mounts can COMPOSE: one plugin may `ctx.provide('name', value)` a service and another may declare `inject: ['name']` to consume it — the consumer stays pending until the provider exists and returns to pending when the provider is unmounted. Everything registered inside `apply` is cleaned up automatically on unmount. Sandbox globals: `console` (tagged `[cordis:]`, writes through to the harness terminal), `harness.defineTool`, `harness.registerTool`, `btoa`, `atob`, `TextEncoder`, `TextDecoder`. Node APIs are DISABLED — do filesystem/network/timer work through the cordis services, never Node built-ins: `require`, `setTimeout`/`setInterval`, and `fetch` throw redirect errors; `process` and `Buffer` are undefined. Instead use inject: ['fs'] + ctx.fs for files, inject: ['web'] + ctx.web for HTTP, inject: ['bash'] + ctx.bash for processes, and inject: ['timer'] + ctx.setTimeout/ctx.setInterval for timing (fiber effects, auto-cleaned on unmount) — cordis_inspect what:"api" shows what THIS runtime provides. Write PLAIN JavaScript, not TypeScript (no `as`, no type annotations). Cautions: (1) waterfall events (e.g. tools/pre-execute) hand the listener a trailing `next` callback which MUST be called — returning without `next()` VETOES the call; prefer plain notification events unless you intend to intercept. (2) Never await something that only resolves after the current turn (your code runs INSIDE a tool call of that turn — it would deadlock). (3) Your `ctx` is a restricted façade: you can register tools, observe events, provide/consume services, and use timers, but framework internals (ctx.root, ctx.fiber, ctx.extend, ctx.plugin, …) are withheld. It is not a security boundary though — the services you inject (e.g. ctx.bash) reach the real runtime. +Mount a NEW cordis plugin into the live runtime that is running THIS agent (self-modification). `code` runs as the body of an async JavaScript function in an isolated sandbox and MUST `return` a plugin. Two forms: FUNCTION form `return (ctx) => { … }` — declares no inject, so it can register tools, listen to events, and provide services, but reaching ANY service (e.g. ctx.bash) throws; use it only when you need no services. OBJECT form `return { name?, inject: ['bash', 'llm', …], apply(ctx) { … } }` — declares dependencies, and cordis activates the plugin only after the services exist; PREFER this form. You may reach ONLY the services you list in inject: an undeclared service throws even if it exists, because an undeclared dependency would not be cleaned up if its provider is unmounted. BEFORE calling a service from your code, read cordis_inspect what:"api" — it lists method signatures AND the type shapes of their arguments/returns (do not guess a field's type; e.g. a bash run's stdout is an object, not a string). Inside `apply`, use the standard cordis API: `ctx.on(event, listener)` to observe events (see cordis_inspect what:"events"), or call `harness.registerTool(ctx, harness.defineTool({ name, description, parameters: { text: { type: 'string', required: true } }, async execute(args) { … } }))` to give yourself a new tool — it becomes callable on your NEXT step. Tool parameters: each key IS a property — { type: 'string'|'number'|'boolean'|'object'|'array', required?: true, description?, enum?, items?, properties? }; a JSON-Schema-style { type: 'object', properties, required: […] } wrapper and type 'integer' are also accepted and normalized. A tool's `execute` MUST return an ARRAY of content blocks, e.g. `return [{ type: 'text', text: someString }]` — never a bare string. Mounts can COMPOSE: one plugin may `ctx.provide('name', value)` a service and another may declare `inject: ['name']` to consume it — the consumer stays pending until the provider exists and returns to pending when the provider is unmounted. Everything registered inside `apply` is cleaned up automatically on unmount. Sandbox globals: `console` (tagged `[cordis:]`, writes through to the harness terminal), `harness.defineTool`, `harness.registerTool`, `btoa`, `atob`, `TextEncoder`, `TextDecoder`. Node APIs are DISABLED — do filesystem/network/timer work through the cordis services, never Node built-ins: `require`, `setTimeout`/`setInterval`, and `fetch` throw redirect errors; `process` and `Buffer` are undefined. Instead use inject: ['fs'] + ctx.fs for files, inject: ['web'] + ctx.web for HTTP, inject: ['bash'] + ctx.bash for processes, and inject: ['timer'] + ctx.setTimeout/ctx.setInterval for timing (fiber effects, auto-cleaned on unmount) — cordis_inspect what:"api" shows what THIS runtime provides. Write PLAIN JavaScript, not TypeScript (no `as`, no type annotations). Cautions: (1) waterfall events (e.g. tools/pre-execute) hand the listener a trailing `next` callback which MUST be called — returning without `next()` VETOES the call; prefer plain notification events unless you intend to intercept. (2) Never await something that only resolves after the current turn (your code runs INSIDE a tool call of that turn — it would deadlock). (3) Your `ctx` is a restricted façade: you can register tools, observe events, provide/consume services, and use timers, but framework internals (ctx.root, ctx.fiber, ctx.extend, ctx.plugin, …) are withheld. It is not a security boundary though — the services you inject (e.g. ctx.bash) reach the real runtime. ```json { diff --git a/packages/cordis/tool-cordis/src/guard.ts b/packages/cordis/tool-cordis/src/guard.ts index 07cd0f1df3..b124f6781f 100644 --- a/packages/cordis/tool-cordis/src/guard.ts +++ b/packages/cordis/tool-cordis/src/guard.ts @@ -185,15 +185,19 @@ export function sandboxRegisterTool(ctx: Context, tool: unknown): () => void { const CTX_VERBS = new Set(['on', 'once', 'provide', 'timeout', 'interval', 'setTimeout', 'setInterval', 'throttle', 'debounce']) /** - * The tool-registry façade: only `register` (marker-guarded), plus the - * read-only `schemas` / `get` a mount may legitimately want. No other registry - * method (nothing that could re-enter the raw context) is exposed. + * The tool-registry façade: `register` (marker-guarded) plus READ-ONLY + * metadata (`schemas`, and `get` returning a schema view, never the live + * `ToolDefinition`). Exposing the raw definition would hand mount code the + * tool's `execute` function, letting it call another tool directly and bypass + * `ToolRegistry.execute` — the pre/post-execute waterfall (permission gates, + * accounting) and result normalization. So `get` returns the same + * name/description/parameters view as `schemas()`, and nothing invocable. */ function sandboxTools(ctx: Context): Record { return { register: (tool: unknown): (() => void) => sandboxRegisterTool(ctx, tool), schemas: () => ctx.tools.schemas(), - get: (name: string) => ctx.tools.get(name), + get: (name: string) => ctx.tools.schemas().find(schema => schema.name === name), } } @@ -233,53 +237,85 @@ function guardedService(service: object, name: string): unknown { }) } +/** + * The service names a plugin declared in `inject`, as a lookup set. Whatever + * declaration style the plugin used — an `inject: ['bash', 'tools']` array or + * the `{ required, optional }` object form — cordis resolves it into a single + * name-keyed map on the fiber before `apply` runs (`{ bash: null, tools: null }`), + * so the gate just reads that map's keys. A mount may reach only the services + * it declared — that is what lets cordis park the mount when a declared + * provider unmounts. + */ +function declaredInjects(ctx: Context): Set { + return new Set(Object.keys(ctx.fiber.inject)) +} + /** * The sandbox context façade handed to a mounted plugin's `apply` in place of * the real `ctx`. A whitelist (see the module doc): the registration/eventing * verbs, the timer helpers, a guarded `tools`, and injected services resolved - * through a guarded `get` / property access. Every framework-plumbing member - * is denied with a teaching error; there is no context-valued member to reach. + * through a guarded `get` / property access. A service is reachable only if the + * plugin DECLARED it in `inject` — an undeclared service is denied even when a + * global provider exists, so cordis's activation/unload semantics (park the + * mount when a declared provider goes away) actually bind. Every + * framework-plumbing member is denied with a teaching error; there is no + * context-valued member to reach. */ function sandboxContext(ctx: Context): Context { const tools = sandboxTools(ctx) - // Resolve a named service to a guarded wrapper, or undefined when absent. - const resolveService = (name: string): unknown => { - if (name === 'tools') return tools - const service: unknown = ctx.get(name) - return service === undefined ? undefined : guardedService(service as object, name) + const declared = declaredInjects(ctx) + // A framework member or an undeclared service — distinguish the two so the + // error teaches the right fix (declare it in inject vs it is withheld). + const denyRead = (prop: string): never => { + if (ctx.get(prop) !== undefined) { + throw new Error( + `service "${prop}" is not injected. Declare it: inject: ['${prop}', …] on your plugin, ` + + 'so cordis parks this mount if the provider is later unmounted.', + ) + } + throw new Error( + `sandbox ctx does not expose "${prop}". Available: ctx.tools.register / ctx.on / ctx.provide / ` + + 'the timer helpers (ctx.setTimeout, ctx.interval, …) and any service you declared in inject. ' + + 'Framework internals (root, fiber, registry, extend, plugin, …) are withheld by design.', + ) } - const get = (name: string): unknown => resolveService(name) + // Read a service for either access path (property or `get`). `tools` is the + // façade's own surface. An UNDECLARED name is denied with the teaching + // error; a DECLARED one resolves to the guarded service. A declared inject + // is required in cordis (the fiber only activates once every declared + // service is live), so at `apply`/`execute` time `ctx.get(name)` is present + // for a declared name — no undefined case to handle here. + const readService = (name: string): unknown => { + if (name === 'tools') return tools + if (!declared.has(name)) return denyRead(name) + return guardedService(ctx.get(name) as object, name) + } + const get = (name: string): unknown => readService(name) return new Proxy({}, { get(_target, prop) { if (prop === 'tools') return tools if (prop === 'get') return get if (typeof prop !== 'string') return undefined // Lazy verb forwarder — reads `ctx[verb]` only when called, so a plugin - // that never uses a timer never triggers the timer mixin's inject check. + // that never uses a timer never triggers the timer mixin's inject check + // (cordis raises its own "without inject" error there for undeclared timer use). if (CTX_VERBS.has(prop)) { return (...args: unknown[]): unknown => { const method = ctx[prop as keyof Context] return Reflect.apply(method as (...a: unknown[]) => unknown, ctx, args) } } - // A declared-and-injected service reads as a ctx property; resolve it - // through the same guard. Absent → the deny path (framework plumbing, - // an un-injected service, or a typo) with one teaching error. - const service = resolveService(prop) - if (service !== undefined) return service - throw new Error( - `sandbox ctx does not expose "${prop}". Available: ctx.tools.register / ctx.on / ctx.provide / ` - + 'the timer helpers (ctx.setTimeout, ctx.interval, …) and any service you declared in inject. ' - + 'Framework internals (root, fiber, registry, extend, plugin, …) are withheld by design.', - ) + return readService(prop) }, // A façade is not the real ctx; block writes rather than let mount code // stash state on a throwaway object and think it persisted. set(_target, prop) { throw new Error(`sandbox ctx is read-only; cannot assign "${String(prop)}"`) }, + // `in` reflects reachability: the façade surface plus DECLARED services + // (whether or not currently live). Does not resolve/wrap — no throw. has: (_target, prop) => prop === 'tools' || prop === 'get' - || (typeof prop === 'string' && (CTX_VERBS.has(prop) || resolveService(prop) !== undefined)), + || (typeof prop === 'string' && (CTX_VERBS.has(prop) || declared.has(prop))), }) as unknown as Context } diff --git a/packages/cordis/tool-cordis/src/index.ts b/packages/cordis/tool-cordis/src/index.ts index f7d1958625..836d516120 100644 --- a/packages/cordis/tool-cordis/src/index.ts +++ b/packages/cordis/tool-cordis/src/index.ts @@ -125,12 +125,14 @@ export function apply(ctx: Context, config: Config): void { 'Mount a NEW cordis plugin into the live runtime that is running THIS agent ' + '(self-modification). `code` runs as the body of an async JavaScript function ' + 'in an isolated sandbox and MUST `return` a plugin. Two forms: ' - + 'FUNCTION form `return (ctx) => { … }` — cannot declare inject, uses whatever ' - + 'services are on the parent context, and accessing a service without inject ' - + '(e.g. ctx.bash) throws; use it only when you need no injected services. ' + + 'FUNCTION form `return (ctx) => { … }` — declares no inject, so it can register ' + + 'tools, listen to events, and provide services, but reaching ANY service (e.g. ' + + 'ctx.bash) throws; use it only when you need no services. ' + 'OBJECT form `return { name?, inject: [\'bash\', \'llm\', …], apply(ctx) { … } }` ' + '— declares dependencies, and cordis activates the plugin only after the ' - + 'services exist; PREFER this form for any plugin that needs bash, llm, sessions, etc. ' + + 'services exist; PREFER this form. You may reach ONLY the services you list in ' + + 'inject: an undeclared service throws even if it exists, because an undeclared ' + + 'dependency would not be cleaned up if its provider is unmounted. ' + 'BEFORE calling a service from your code, read cordis_inspect what:"api" — it lists ' + 'method signatures AND the type shapes of their arguments/returns (do not guess a ' + 'field\'s type; e.g. a bash run\'s stdout is an object, not a string). ' diff --git a/packages/cordis/tool-cordis/tests/mount.spec.ts b/packages/cordis/tool-cordis/tests/mount.spec.ts index d0db8d7efa..7ee266ce30 100644 --- a/packages/cordis/tool-cordis/tests/mount.spec.ts +++ b/packages/cordis/tool-cordis/tests/mount.spec.ts @@ -220,8 +220,6 @@ describe('cordis_mount', () => { return { name: 'raw-register-get', apply(ctx) { - const sp = ctx.get('systemPrompt') - console.log('systemPrompt is', typeof sp) ctx.get('tools').register({ name: 'raw_via_get', description: 'raw', parameters: {}, async execute() { return [] } }) }, } diff --git a/packages/cordis/tool-cordis/tests/sandbox-context.spec.ts b/packages/cordis/tool-cordis/tests/sandbox-context.spec.ts index 50f5b441a2..d3ade92572 100644 --- a/packages/cordis/tool-cordis/tests/sandbox-context.spec.ts +++ b/packages/cordis/tool-cordis/tests/sandbox-context.spec.ts @@ -154,3 +154,142 @@ describe('sandbox context façade — escape surface is closed', () => { expect(result.isError).toBe(false) }) }) + +describe('sandbox context façade — inject gate on services', () => { + it('denies an undeclared live service (property access), naming the inject fix', async () => { + // `systemPrompt` is a live global service in the setup harness, but this + // mount does not declare it — reaching it would let the mount depend on a + // provider cordis does not know about, so it is refused. + const ctx = await setup() + const result = await call(ctx, 'cordis_mount', { + code: 'return { name: \'undeclared\', inject: [\'tools\'], apply(ctx) { const s = ctx.systemPrompt } }', + }) + expect(result.isError).toBe(true) + expect(text(result)).toContain('service "systemPrompt" is not injected') + expect(text(result)).toContain('inject: [\'systemPrompt\', …]') + }) + + it('denies an undeclared live service reached through ctx.get too', async () => { + const ctx = await setup() + const result = await call(ctx, 'cordis_mount', { + code: 'return { name: \'undeclared-get\', inject: [\'tools\'], apply(ctx) { ctx.get(\'systemPrompt\') } }', + }) + expect(result.isError).toBe(true) + expect(text(result)).toContain('service "systemPrompt" is not injected') + }) + + it('allows a service the mount DID declare in inject', async () => { + const ctx = await setup() + const result = await call(ctx, 'cordis_mount', { + code: ` + return { + name: 'declared', + inject: ['systemPrompt', 'tools'], + apply(ctx) { console.log('has systemPrompt:', typeof ctx.systemPrompt) } + } + `, + }) + expect(result.isError).toBe(false) + expect(text(result)).toContain('state: active') + }) + + it('a cross-mount consumer must declare the provider — the undeclared path is refused, not left as a zombie tool', async () => { + // The finding's scenario: a consumer registers a tool built on a provider's + // service WITHOUT declaring inject. cordis would then never park the + // consumer when the provider unmounts, leaving a tool that fails only at + // execution. The gate refuses the undeclared access up front, so the + // dependency is always visible to cordis. + const ctx = await setup() + await call(ctx, 'cordis_mount', { + code: 'return { name: \'greeter-provider\', apply(ctx) { ctx.provide(\'greeter\', { greet: (n) => \'hi \' + n }) } }', + }) + const undeclared = await call(ctx, 'cordis_mount', { + code: ` + return { + name: 'sloppy-consumer', + inject: ['tools'], + apply(ctx) { + harness.registerTool(ctx, harness.defineTool({ + name: 'greet_undeclared', + description: 'uses greeter without declaring it', + parameters: { n: { type: 'string', required: true } }, + async execute(args) { return [{ type: 'text', text: ctx.greeter.greet(args.n) }] }, + })) + }, + } + `, + }) + // The tool registers (its execute is lazy), but calling it hits the gate: + // `ctx.greeter` is undeclared, so it fails with the teaching error rather + // than silently working and later stranding. + expect(undeclared.isError).toBe(false) + const called = await call(ctx, 'greet_undeclared', { n: 'x' }) + expect(called.isError).toBe(true) + expect(text(called)).toContain('service "greeter" is not injected') + }) +}) + +describe('sandbox tools façade — get is a read-only schema view', () => { + it('ctx.tools.get returns a schema, not the live ToolDefinition with execute', async () => { + // The finding: returning the raw ToolDefinition hands mount code the + // tool's execute function, letting it bypass ToolRegistry.execute (and its + // pre/post hooks). get now returns the same name/description/parameters + // view as schemas(), with no execute. Asserted via a self-made tool that + // reports the shape it saw — world-checked, not self-reported. + const ctx = await setup() + await call(ctx, 'cordis_mount', { + code: ` + return { + name: 'reporter', + inject: ['tools'], + apply(ctx) { + harness.registerTool(ctx, harness.defineTool({ + name: 'report_view', + description: 'reports the shape of a tool view', + parameters: {}, + async execute() { + const view = ctx.tools.get('cordis_mount') + return [{ type: 'text', text: JSON.stringify({ + hasExecute: 'execute' in view, + hasPresentCall: 'presentCall' in view, + name: view.name, + keys: Object.keys(view).sort(), + }) }] + }, + })) + }, + } + `, + }) + const reported = await call(ctx, 'report_view', {}) + expect(reported.isError).toBe(false) + const shape = JSON.parse(text(reported)) as { hasExecute: boolean; hasPresentCall: boolean; name: string; keys: string[] } + expect(shape.hasExecute).toBe(false) + expect(shape.hasPresentCall).toBe(false) + expect(shape.name).toBe('cordis_mount') + expect(shape.keys).toEqual(['description', 'name', 'parameters']) + }) + + it('ctx.tools.get returns undefined for an unknown tool', async () => { + const ctx = await setup() + await call(ctx, 'cordis_mount', { + code: ` + return { + name: 'unknown-probe', + inject: ['tools'], + apply(ctx) { + harness.registerTool(ctx, harness.defineTool({ + name: 'probe_unknown', + description: 'reports whether an unknown tool resolves', + parameters: {}, + async execute() { + return [{ type: 'text', text: String(ctx.tools.get('no_such_tool') === undefined) }] + }, + })) + }, + } + `, + }) + expect(text(await call(ctx, 'probe_unknown', {}))).toBe('true') + }) +}) From db857f62c08404e6767917163a191cdfdba29b1d Mon Sep 17 00:00:00 2001 From: imccyu <276526105+imccyu@users.noreply.github.com> Date: Thu, 9 Jul 2026 18:51:44 +0800 Subject: [PATCH 13/15] docs(tool-cordis): state the sandbox stance as steering, not containment MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The sandbox docs overclaimed a containment contract the design never makes: "capability access is routed through cordis services, never Node built-ins, so everything a mounted plugin does stays inspectable and disposable". The host-realm helpers on the sandbox global (harness, console, btoa) are reachable functions, so mount code that goes looking can reach the host realm through one of them — accepted under the trust stance, because the ctx a mount ultimately receives is fully privileged anyway. Reword the sandbox module doc, the README trust stance, and the RFC sandbox-semantics section to say exactly that: the traps and small global surface STEER honest code onto the cordis services; they are not a security boundary. --- .../2026-07-08-self-referential-cordis-toolset.md | 2 +- packages/cordis/tool-cordis/README.md | 2 +- packages/cordis/tool-cordis/src/sandbox.ts | 13 ++++++++----- 3 files changed, 10 insertions(+), 7 deletions(-) diff --git a/docs/rfc/implemented/feature/2026-07-08-self-referential-cordis-toolset.md b/docs/rfc/implemented/feature/2026-07-08-self-referential-cordis-toolset.md index fff36fee91..8a43c271c3 100644 --- a/docs/rfc/implemented/feature/2026-07-08-self-referential-cordis-toolset.md +++ b/docs/rfc/implemented/feature/2026-07-08-self-referential-cordis-toolset.md @@ -26,7 +26,7 @@ The trust stance, stated once and threaded through the rest: the `node:vm` sandb ### Sandbox semantics -Mount code runs via `vm.createContext` + `runInContext`, wrapped as the body of an async function under a per-mount filename (`cordis-mount-.js`). The vm gives the code a fresh realm: writes to `globalThis` stay inside the sandbox, and no Node API is provided — capability access is routed through the cordis services (`ctx.fs` for files, `ctx.web` for HTTP, `ctx.bash` for processes, the `ctx.timer` helpers for timing), never Node built-ins, so everything a mounted plugin does stays inspectable through `cordis_inspect` and disposable with its fiber. The `vmTimeoutMs` config bounds only the synchronous portion of evaluation; an async body escapes the bound (acceptable under the trust stance above). +Mount code runs via `vm.createContext` + `runInContext`, wrapped as the body of an async function under a per-mount filename (`cordis-mount-.js`). The vm gives the code a fresh realm: writes to `globalThis` stay inside the sandbox, and no Node API is handed in — capability access is *steered* toward the cordis services (`ctx.fs` for files, `ctx.web` for HTTP, `ctx.bash` for processes, the `ctx.timer` helpers for timing) rather than Node built-ins, so a well-behaved mount stays inspectable through `cordis_inspect` and disposable with its fiber. This is steering, not containment: consistent with the trust stance above, the small global surface keeps *honest* code on the cordis services but is not a security boundary — the host-realm helpers it exposes (`harness`, `console`, `btoa`) are reachable functions, so mount code that goes looking (through such a helper's `.constructor`, say) can still reach the host realm and Node itself, which is accepted because the `ctx` a mount ultimately receives is fully privileged anyway. The `vmTimeoutMs` config bounds only the synchronous portion of evaluation; an async body escapes the bound (also acceptable under the trust stance). Sandbox globals are deliberately small: a tagged write-through `console` (`[cordis:] …` on the host stdout/stderr, so a listener that fires long after the mount call still lands somewhere the user sees), the `harness.defineTool` / `harness.registerTool` registration pair, the encoding primitives fresh vm contexts lack (`btoa`/`atob` as host closures over `Buffer` — a sanctioned exception, `Buffer` itself is never exposed — plus `TextEncoder`/`TextDecoder`), and callable traps over the withheld Node APIs (`require`, `setTimeout`/`setInterval`/`setImmediate`/`clearTimeout`/`clearInterval`, `fetch`) that throw a redirect naming the cordis alternative. Only function-shaped globals are trapped; `process` and `Buffer` stay `undefined` so a `typeof` feature probe stays inert rather than detonating a throwing accessor. diff --git a/packages/cordis/tool-cordis/README.md b/packages/cordis/tool-cordis/README.md index 651f3273d9..c4f3cf11b9 100644 --- a/packages/cordis/tool-cordis/README.md +++ b/packages/cordis/tool-cordis/README.md @@ -12,7 +12,7 @@ Exact model-facing schemas: [the generated tool catalog](../../../docs/tool-cata ## Trust stance -The sandbox isolates the global context only — it is not a security boundary. No Node API is provided: `require`, the timers, and `fetch` are callable traps that throw a redirect to the cordis alternative (`ctx.fs` / `ctx.web` / `ctx.bash` / `inject: ['timer']` + `ctx.setTimeout`); `process` and `Buffer` are `undefined`; `globalThis` writes stay inside. The `ctx` a mounted plugin's `apply` receives is a whitelist façade — register tools, observe events, provide/consume services, use timers; framework internals (`ctx.root`, `ctx.fiber`, `ctx.extend`, `ctx.plugin`, …) are withheld — but the capabilities it does expose reach the real runtime, so load this plugin as deliberately as you would grant a bash tool. +The sandbox isolates the global context only — it is not a security boundary. No Node API is provided: `require`, the timers, and `fetch` are callable traps that throw a redirect to the cordis alternative (`ctx.fs` / `ctx.web` / `ctx.bash` / `inject: ['timer']` + `ctx.setTimeout`); `process` and `Buffer` are `undefined`; `globalThis` writes stay inside. These traps steer honest code onto the cordis services; they do not contain a mount that goes looking — the host-realm helpers on the sandbox global (`harness`, `console`, `btoa`) are reachable functions, so mount code can reach the host realm and Node through one of them, which is fine because `ctx` is fully privileged anyway. The `ctx` a mounted plugin's `apply` receives is a whitelist façade — register tools, observe events, provide/consume services, use timers; framework internals (`ctx.root`, `ctx.fiber`, `ctx.extend`, `ctx.plugin`, …) are withheld — but the capabilities it does expose reach the real runtime, so load this plugin as deliberately as you would grant a bash tool. ## Config diff --git a/packages/cordis/tool-cordis/src/sandbox.ts b/packages/cordis/tool-cordis/src/sandbox.ts index add858f3ce..5ed6b52b50 100644 --- a/packages/cordis/tool-cordis/src/sandbox.ts +++ b/packages/cordis/tool-cordis/src/sandbox.ts @@ -6,11 +6,14 @@ * routed through cordis services, never Node built-ins: filesystem work goes * through `ctx.fs`, network through `ctx.web`, processes through `ctx.bash`, * timers through the `ctx.timer` helpers (fiber effects, unwound on unmount) - * — so everything a mounted plugin does stays inspectable and disposable. The - * sandbox guards against ACCIDENTAL global pollution only — it is not a - * security boundary; the `ctx` a mounted plugin's `apply` later receives is - * the real, fully privileged runtime handle, and that is the point of the - * toolset. + * — so a well-behaved mount stays inspectable and disposable. That routing is + * STEERING toward the cordis services, not containment: the sandbox guards + * against ACCIDENTAL global pollution, and it is not a security boundary. The + * host-realm helpers on the sandbox global (`harness`, `console`, `btoa`) are + * reachable functions, so a mount that goes looking — e.g. through such a + * helper's `.constructor` — can still reach the host realm; that is accepted, + * because the `ctx` a mounted plugin's `apply` later receives is the real, + * fully privileged runtime handle, and that is the point of the toolset. * * @module @deepseek-ai/dsh-tool-cordis/sandbox */ From f1e54d737b9efc44216020942d468683ac9ebf63 Mon Sep 17 00:00:00 2001 From: imccyu <276526105+imccyu@users.noreply.github.com> Date: Thu, 9 Jul 2026 19:30:49 +0800 Subject: [PATCH 14/15] =?UTF-8?q?fix(tool-cordis):=20pass=20primitive=20pr?= =?UTF-8?q?ovided=20service=20values=20through=20the=20fa=C3=A7ade?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit cordis provide() accepts any value and cross-mount composition advertises ctx.provide('name', value), but the façade's readService unconditionally proxied every declared service — new Proxy('42') throws "Cannot create proxy with a non-object as target or handler", so a consumer of a primitive-valued service crashed on first read with an error naming neither the service nor the fix. A primitive or null value now passes through unwrapped (after the denyContext check); only object- and function-valued services are proxied — a primitive has no method that could hand back a Context, so nothing is lost. New cross-mount spec pins both read paths (ctx. and ctx.get) for a number and a null provided value. --- packages/cordis/tool-cordis/src/guard.ts | 15 ++++++-- .../tool-cordis/tests/cross-mount.spec.ts | 38 +++++++++++++++++++ 2 files changed, 49 insertions(+), 4 deletions(-) diff --git a/packages/cordis/tool-cordis/src/guard.ts b/packages/cordis/tool-cordis/src/guard.ts index b124f6781f..90eaaec41b 100644 --- a/packages/cordis/tool-cordis/src/guard.ts +++ b/packages/cordis/tool-cordis/src/guard.ts @@ -9,8 +9,9 @@ * The façade is a WHITELIST, not a pass-through proxy. Mount code needs to do * exactly four things — register a tool, listen to an event, provide a service, * call an injected service (timers included) — so the façade exposes only those - * verbs and the injected services, each individually wrapped. Every framework - * plumbing member (`root`, `parent`, `scope`, `fiber`, `reflect`, `registry`, + * verbs and the injected services, each object-valued service individually + * wrapped (a primitive provided value passes through as-is — see + * {@link sandboxContext}). Every framework plumbing member (`root`, `parent`, `scope`, `fiber`, `reflect`, `registry`, * `events`, `extend`, `isolate`, `intercept`, `plugin`, `set`, `mixin`, …) is * DENIED with a teaching error rather than passed through. This closes an * entire escape class at once: a pass-through proxy that only special-cased @@ -284,11 +285,17 @@ function sandboxContext(ctx: Context): Context { // error; a DECLARED one resolves to the guarded service. A declared inject // is required in cordis (the fiber only activates once every declared // service is live), so at `apply`/`execute` time `ctx.get(name)` is present - // for a declared name — no undefined case to handle here. + // for a declared name — no undefined case to handle here. `provide()` + // accepts ANY value though (cross-mount composition advertises + // `ctx.provide('name', value)`), so a primitive or null value passes + // through unwrapped: Proxy throws on a non-object target, and only an + // object can carry a method that hands back a Context. const readService = (name: string): unknown => { if (name === 'tools') return tools if (!declared.has(name)) return denyRead(name) - return guardedService(ctx.get(name) as object, name) + const service = denyContext(ctx.get(name), name) + if (service === null || (typeof service !== 'object' && typeof service !== 'function')) return service + return guardedService(service, name) } const get = (name: string): unknown => readService(name) return new Proxy({}, { diff --git a/packages/cordis/tool-cordis/tests/cross-mount.spec.ts b/packages/cordis/tool-cordis/tests/cross-mount.spec.ts index f68eaef639..dcfdb815c4 100644 --- a/packages/cordis/tool-cordis/tests/cross-mount.spec.ts +++ b/packages/cordis/tool-cordis/tests/cross-mount.spec.ts @@ -91,6 +91,44 @@ describe('cross-mount provide/inject', () => { expect(api).toContain('- greeter (provided by greeter-provider, no catalog entry)') }) + it('a primitive (or null) provided value passes through the façade unwrapped, on both read paths', async () => { + const ctx = await setup() + const provider = await call(ctx, 'cordis_mount', { + code: ` + return { + name: 'answer-provider', + apply(ctx) { + ctx.provide('answer', 42) + ctx.provide('nothing', null) + }, + } + `, + }) + expect(provider.isError).toBe(false) + + const consumer = await call(ctx, 'cordis_mount', { + code: ` + return { + name: 'answer-consumer', + inject: ['answer', 'nothing', 'tools'], + apply(ctx) { + harness.registerTool(ctx, harness.defineTool({ + name: 'answer', + description: 'Read the provided primitive services.', + parameters: {}, + async execute() { + return [{ type: 'text', text: ctx.answer + '/' + ctx.get('answer') + '/' + ctx.nothing }] + }, + })) + }, + } + `, + }) + expect(consumer.isError).toBe(false) + expect(text(consumer)).toContain('state: active') + expect(text(await call(ctx, 'answer', {}))).toBe('42/42/null') + }) + it('unmounting the consumer leaves the provider and its service intact', async () => { const ctx = await setup() await call(ctx, 'cordis_mount', { code: PROVIDER_CODE }) // dyn-1 From fe4da9244f53cdbf66bcd9ce3cdaa6fc09dca362 Mon Sep 17 00:00:00 2001 From: imccyu <276526105+imccyu@users.noreply.github.com> Date: Thu, 9 Jul 2026 22:12:30 +0800 Subject: [PATCH 15/15] fix(tool-cordis): validate a dynamic tool's execute return shape after the realm round-trip MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The sandbox execute wrapper JSON round-tripped the return and blindly cast it to ToolExecuteReturn. A JSON-valid but wrong-shape return — a bare string, { content: 'ok' }, blocks without a type tag — sailed through: the registry spreads result.content, so { content: 'ok' } became ['o','k'], passed the session log's isJsonValue gate, and the DeepSeek serializer then flattened it to '(no output)' — silent corruption of the next model request and every replay, instead of a contained tool error. The round-tripped value is now shape-checked against the two ToolExecuteReturn forms (array of content blocks, or { content: blocks, meta? }); block checks are structural only (plain object + string type tag) because the ContentBlock union is merge-extensible. A wrong shape — and the formerly cryptic forgot-return/bare-string cases — fails that one call with a teaching error echoing a truncated preview of what was returned and the two valid forms. New specs pin the object-form pass-through (meta included), six rejection shapes, and the preview truncation; per-file 100% coverage holds. --- ...6-07-08-self-referential-cordis-toolset.md | 2 +- packages/cordis/tool-cordis/src/guard.ts | 74 +++++++++++++-- .../cordis/tool-cordis/tests/mount.spec.ts | 89 +++++++++++++++++++ 3 files changed, 158 insertions(+), 7 deletions(-) diff --git a/docs/rfc/implemented/feature/2026-07-08-self-referential-cordis-toolset.md b/docs/rfc/implemented/feature/2026-07-08-self-referential-cordis-toolset.md index 8a43c271c3..3ec6c75cbc 100644 --- a/docs/rfc/implemented/feature/2026-07-08-self-referential-cordis-toolset.md +++ b/docs/rfc/implemented/feature/2026-07-08-self-referential-cordis-toolset.md @@ -30,7 +30,7 @@ Mount code runs via `vm.createContext` + `runInContext`, wrapped as the body of Sandbox globals are deliberately small: a tagged write-through `console` (`[cordis:] …` on the host stdout/stderr, so a listener that fires long after the mount call still lands somewhere the user sees), the `harness.defineTool` / `harness.registerTool` registration pair, the encoding primitives fresh vm contexts lack (`btoa`/`atob` as host closures over `Buffer` — a sanctioned exception, `Buffer` itself is never exposed — plus `TextEncoder`/`TextDecoder`), and callable traps over the withheld Node APIs (`require`, `setTimeout`/`setInterval`/`setImmediate`/`clearTimeout`/`clearInterval`, `fetch`) that throw a redirect naming the cordis alternative. Only function-shaped globals are trapped; `process` and `Buffer` stay `undefined` so a `typeof` feature probe stays inert rather than detonating a throwing accessor. -Three boundary mechanisms make model-written code behave correctly across the realm seam. **Dual-realm `instanceof`**: most objects sandbox code touches are host-realm (tool `args`, event payloads, service returns), so a plain `x instanceof Array` in the vm would silently be false — a per-sandbox prelude gives the vm realm's own constructors a `Symbol.hasInstance` that checks both the vm constructor and its host counterpart, patching only vm-realm globals. **Realm normalization of tool results**: objects built inside the vm carry the vm realm's `Object.prototype`, which the session log's append-time plainness check (`isJsonValue` in `dsh-session`, a prototype-identity comparison) rejects, so the sandbox's `harness.defineTool` JSON round-trips every `execute` return into the host realm — which also projects it onto exactly what the log durably stores. **A whitelist context façade**: the `ctx` a mounted plugin's `apply` receives is NOT the real context nor a pass-through proxy over it — it is a façade exposing only what a mount legitimately needs (`tools.register` marker-guarded, a read-only `tools.get`/`schemas`, `on`/`once`, `provide`, the timer helpers, and the services the plugin DECLARED in `inject`), with every framework-plumbing member (`root`, `parent`, `fiber`, `reflect`, `registry`, `extend`, `isolate`, `intercept`, `plugin`, `set`, `mixin`, …) denied with a teaching error. This closes an escape *class* rather than a single hole: a proxy that merely special-cased `ctx.tools` still handed back the raw context through `ctx.root`, `ctx.extend()`, or a service instance's `.ctx`, and mount code could then `ctx.root.tools.register({…})` to bypass the marker check and realm normalization — a raw vm-realm result then errors a real agent turn at the plainness check. The façade has no context-valued member to reach, and the one indirect leak (an injected-service method returning a `Context`) is rejected on the way back to sandbox code. Two narrower rules complete the surface. First, **service access requires an `inject` declaration**: reaching a service the mount did not declare is refused even when a global provider is live — otherwise a mount could depend on a provider cordis never sees, and unmounting that provider would neither park the consumer nor unwind the tools it registered, leaving a model-visible tool that fails only at execution time. Because the read is gated on the declaration, cross-mount `provide`/`inject` keeps its lifecycle guarantees (the plugin's own `inject` and the fiber's pending/active gating drive activation and unload); only the `apply`-time `ctx` surface is narrowed. Second, **`ctx.tools.get` returns a read-only schema view** (name/description/parameters), never the live `ToolDefinition` — handing back the definition would expose its `execute`, letting mount code call another tool directly and bypass `ToolRegistry.execute` and its pre/post-execute hooks and accounting; a mount that wants to invoke a tool must go through the registry, and one that wants to introspect gets the same view `schemas()` returns. +Three boundary mechanisms make model-written code behave correctly across the realm seam. **Dual-realm `instanceof`**: most objects sandbox code touches are host-realm (tool `args`, event payloads, service returns), so a plain `x instanceof Array` in the vm would silently be false — a per-sandbox prelude gives the vm realm's own constructors a `Symbol.hasInstance` that checks both the vm constructor and its host counterpart, patching only vm-realm globals. **Realm normalization of tool results**: objects built inside the vm carry the vm realm's `Object.prototype`, which the session log's append-time plainness check (`isJsonValue` in `dsh-session`, a prototype-identity comparison) rejects, so the sandbox's `harness.defineTool` JSON round-trips every `execute` return into the host realm — which also projects it onto exactly what the log durably stores — and then shape-checks it against the two `ToolExecuteReturn` forms, so a JSON-valid but wrong-shape return (a bare string, `{ content: 'ok' }`) fails that one call with a teaching error instead of entering the log as corrupt tool-result content. **A whitelist context façade**: the `ctx` a mounted plugin's `apply` receives is NOT the real context nor a pass-through proxy over it — it is a façade exposing only what a mount legitimately needs (`tools.register` marker-guarded, a read-only `tools.get`/`schemas`, `on`/`once`, `provide`, the timer helpers, and the services the plugin DECLARED in `inject`), with every framework-plumbing member (`root`, `parent`, `fiber`, `reflect`, `registry`, `extend`, `isolate`, `intercept`, `plugin`, `set`, `mixin`, …) denied with a teaching error. This closes an escape *class* rather than a single hole: a proxy that merely special-cased `ctx.tools` still handed back the raw context through `ctx.root`, `ctx.extend()`, or a service instance's `.ctx`, and mount code could then `ctx.root.tools.register({…})` to bypass the marker check and realm normalization — a raw vm-realm result then errors a real agent turn at the plainness check. The façade has no context-valued member to reach, and the one indirect leak (an injected-service method returning a `Context`) is rejected on the way back to sandbox code. Two narrower rules complete the surface. First, **service access requires an `inject` declaration**: reaching a service the mount did not declare is refused even when a global provider is live — otherwise a mount could depend on a provider cordis never sees, and unmounting that provider would neither park the consumer nor unwind the tools it registered, leaving a model-visible tool that fails only at execution time. Because the read is gated on the declaration, cross-mount `provide`/`inject` keeps its lifecycle guarantees (the plugin's own `inject` and the fiber's pending/active gating drive activation and unload); only the `apply`-time `ctx` surface is narrowed. Second, **`ctx.tools.get` returns a read-only schema view** (name/description/parameters), never the live `ToolDefinition` — handing back the definition would expose its `execute`, letting mount code call another tool directly and bypass `ToolRegistry.execute` and its pre/post-execute hooks and accounting; a mount that wants to invoke a tool must go through the registry, and one that wants to introspect gets the same view `schemas()` returns. Boundary errors are written around the mistakes models actually make (see [Consequences](#consequences) for how each was found), and the boundary normalizes rather than lectures wherever the input has exactly one meaning: schema `parameters` accept the JSON-Schema dialect models write by strong prior — the `{ type: 'object', properties, required: […] }` wrapper unwraps to the SchemaSpec DSL (the `required` array becoming per-property flags, at any nesting level), `type: 'integer'` maps to `number`, and `required: false` reads as optional — while genuinely meaningless input is rejected with the vocabulary enumerated (an unknown type lists the five valid ones; a non-boolean `required` names the rule). The remaining teaching errors: an unbalanced `});` closing gets the vm's offending source line plus a "code is a function body" reminder; TypeScript syntax gets the remove-annotations fix (detected on the failing line only, so an ` as ` inside a description string does not misfire); a forgotten `return` gets the two valid plugin forms; a Node built-in call gets the redirect to its cordis service; a tool-name collision on re-mount gets the unmount-first-then-remount recipe. diff --git a/packages/cordis/tool-cordis/src/guard.ts b/packages/cordis/tool-cordis/src/guard.ts index 90eaaec41b..f51faeb42e 100644 --- a/packages/cordis/tool-cordis/src/guard.ts +++ b/packages/cordis/tool-cordis/src/guard.ts @@ -27,8 +27,12 @@ * realm's `Object.prototype`, and the session log's append-time plainness check * (`dsh-session`'s `isJsonValue`, a prototype-identity comparison) rejects * foreign-realm data — so every dynamic tool's `execute` return is JSON - * round-tripped into the host realm before it reaches the registry, and the - * schema itself is rebuilt as fresh host-realm objects. And a malformed tool + * round-tripped into the host realm and shape-checked against the two + * `ToolExecuteReturn` forms before it reaches the registry (the registry + * trusts the shape blindly — it spreads `result.content`, so an unvalidated + * `{ content: 'ok' }` would enter the session log as `['o','k']` and silently + * corrupt the next model request), and the schema itself is rebuilt as fresh + * host-realm objects. And a malformed tool * schema must fail at REGISTRATION, not when a later request assembles it — so * dynamic tool registration accepts only definitions produced by the sandbox's * `harness.defineTool`, which normalizes `parameters` up front. @@ -137,14 +141,67 @@ function assertDynamicTool(tool: unknown): asserts tool is DynamicToolDefinition } } +/** + * Structurally a content block, checked AFTER the JSON round-trip: a plain + * object carrying a string `type` tag. Deliberately nothing deeper — the + * ContentBlock union is merge-extensible (an unknown tag must pass), and every + * downstream consumer dispatches on `type` and falls through unknowns. + */ +function isContentBlockShape(value: unknown): boolean { + return isPlainRecord(value) && typeof value.type === 'string' +} + +/** + * How much of an invalid execute return the teaching error echoes back — a + * huge blob would burn the model turn the error is trying to save. + */ +const RETURN_PREVIEW_LIMIT = 120 + +/** + * Compact JSON preview of an invalid execute return for the teaching error + * (`String(…)` for the un-stringifiable undefined case), truncated to + * {@link RETURN_PREVIEW_LIMIT}. + */ +function describeReturn(value: unknown): string { + // JSON.stringify is TYPED as always returning string, but it yields + // undefined for an undefined input (the routed forgot-return case) — the + // assertion widens the type back to the runtime truth. + const json = JSON.stringify(value) as string | undefined + if (json === undefined) return String(value) + return json.length > RETURN_PREVIEW_LIMIT ? `${json.slice(0, RETURN_PREVIEW_LIMIT)}…` : json +} + +/** + * Validate a round-tripped `execute` return against the two shapes + * {@link ToolExecuteReturn} allows: an ARRAY of content blocks, or + * `{ content: blocks, meta? }`. The registry trusts the shape blindly — it + * spreads `result.content`, so an unvalidated `{ content: 'ok' }` would enter + * the session log as `['o','k']` and silently corrupt the next model request — + * so a wrong shape fails THIS call with a teaching error instead. + */ +function assertExecuteReturn(value: unknown): ToolExecuteReturn { + if (Array.isArray(value) && value.every(isContentBlockShape)) { + return value as ToolExecuteReturn + } + if (isPlainRecord(value) && Array.isArray(value.content) && value.content.every(isContentBlockShape)) { + return value as ToolExecuteReturn + } + throw new Error( + `execute returned ${describeReturn(value)} — a tool's execute must return an ARRAY of content blocks, never a bare string:\n` + + ' ✓ return [{ type: \'text\', text: someString }]\n' + + ' ✓ return { content: [{ type: \'text\', text: someString }], meta: anyJsonValue }', + ) +} + /** * The `harness.defineTool` handed into the sandbox: the real DSL, with * `parameters` normalized into a fresh host-realm SchemaSpec (JSON-Schema * wrapper unwrapped, `integer` mapped, `required: false` dropped) and the * tool's `execute` return normalized into the host realm via a JSON round-trip - * (see the module doc). The round-trip also projects the return onto exactly - * what the log would durably store, so a non-JSON-serializable return surfaces - * as that one call's error instead of poisoning the turn. + * (see the module doc). The round-trip projects the return onto exactly what + * the log would durably store, and {@link assertExecuteReturn} then vets that + * projection — so a non-JSON-serializable OR wrong-shape return surfaces as + * that one call's teaching error instead of poisoning the turn. * @param options - the standard `defineTool` options; `parameters` may be the SchemaSpec DSL or a JSON-Schema-style wrapper. * @returns the marker-tagged definition `harness.registerTool` (and the guarded `ctx.tools.register`) accepts. */ @@ -155,7 +212,12 @@ export function sandboxDefineTool(options: Parameters[0]): To return markDynamicTool({ ...tool, async execute(args, exec) { - return JSON.parse(JSON.stringify(await execute(args, exec))) as ToolExecuteReturn + // JSON.stringify yields NO JSON for an undefined (or function/symbol) + // return despite its string-typed signature — route that into + // assertExecuteReturn's teaching error rather than letting JSON.parse + // throw its cryptic '"undefined" is not valid JSON'. + const json = JSON.stringify(await execute(args, exec)) as string | undefined + return assertExecuteReturn(json === undefined ? undefined : JSON.parse(json) as unknown) }, }) } diff --git a/packages/cordis/tool-cordis/tests/mount.spec.ts b/packages/cordis/tool-cordis/tests/mount.spec.ts index 7ee266ce30..fc29eeb2a0 100644 --- a/packages/cordis/tool-cordis/tests/mount.spec.ts +++ b/packages/cordis/tool-cordis/tests/mount.spec.ts @@ -60,6 +60,95 @@ describe('cordis_mount', () => { expect(isJsonValue({ content: reversed.content, isError: reversed.isError })).toBe(true) }) + it('threads the { content, meta } object return form through to the registry result', async () => { + const ctx = await setup() + await call(ctx, 'cordis_mount', { + code: ` + return { + name: 'meta-return', + inject: ['tools'], + apply(ctx) { + harness.registerTool(ctx, harness.defineTool({ + name: 'meta_tool', + description: 'attaches a private presentation payload', + parameters: {}, + async execute() { + return { content: [{ type: 'text', text: 'ok' }], meta: { kind: 'demo' } } + }, + })) + }, + } + `, + }) + const result = await call(ctx, 'meta_tool', {}) + expect(result.isError).toBe(false) + expect(text(result)).toBe('ok') + expect(result.meta).toEqual({ kind: 'demo' }) + }) + + it.each([ + ['a bare string', 'return \'ok\'', '"ok"'], + ['an object whose content is a string', 'return { content: \'ok\' }', '{"content":"ok"}'], + ['an array of non-objects', 'return [\'ok\']', '["ok"]'], + ['blocks missing the type tag', 'return [{ text: \'hi\' }]', '[{"text":"hi"}]'], + ['object-form blocks missing the type tag', 'return { content: [{ text: \'hi\' }] }', '{"content":[{"text":"hi"}]}'], + ['undefined — a forgotten return', 'return undefined', 'undefined'], + ])('rejects an execute return of %s as that one call\'s teaching error', async (_label, returnStatement, preview) => { + // The failure this prevents: the registry trusts the return shape + // (postExecute spreads result.content), so an unvalidated { content: 'ok' } + // would enter the session log as ['o','k'] and silently corrupt the next + // model request. The shape check turns it into THIS call's error instead — + // one well-formed text block the log and the model can digest. + const ctx = await setup() + await call(ctx, 'cordis_mount', { + code: ` + return { + name: 'bad-return', + inject: ['tools'], + apply(ctx) { + harness.registerTool(ctx, harness.defineTool({ + name: 'bad_return_tool', + description: 'returns a wrong shape', + parameters: {}, + async execute() { ${returnStatement} }, + })) + }, + } + `, + }) + const result = await call(ctx, 'bad_return_tool', {}) + expect(result.isError).toBe(true) + expect(result.content).toHaveLength(1) + expect(result.content[0]!.type).toBe('text') + expect(text(result)).toContain(`execute returned ${preview}`) + expect(text(result)).toContain('must return an ARRAY of content blocks') + expect(text(result)).toContain('✓ return { content: [{ type: \'text\', text: someString }], meta: anyJsonValue }') + }) + + it('truncates a huge invalid execute return in the teaching error', async () => { + const ctx = await setup() + await call(ctx, 'cordis_mount', { + code: ` + return { + name: 'huge-return', + inject: ['tools'], + apply(ctx) { + harness.registerTool(ctx, harness.defineTool({ + name: 'huge_return_tool', + description: 'returns a huge wrong shape', + parameters: {}, + async execute() { return 'x'.repeat(500) }, + })) + }, + } + `, + }) + const result = await call(ctx, 'huge_return_tool', {}) + expect(result.isError).toBe(true) + expect(text(result)).toContain('…') + expect(text(result)).not.toContain('x'.repeat(200)) + }) + it('accepts a JSON-Schema-style parameters wrapper and normalizes it to the DSL', async () => { // The dialect models write by strong prior: the { type:'object', // properties, required: […] } wrapper, `type: 'integer'`, and