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] =?UTF-8?q?examples:=20cordis-agent=20=E2=80=94=20the=20se?= =?UTF-8?q?lf-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" },