Merge remote-tracking branch 'origin/master' into cross-family-fs-sandbox

# Conflicts: # .agents/notes/implemented/feature/2026-07-14-cross-family-fs-sandbox.i18n.yaml # .agents/notes/implemented/feature/2026-07-14-cross-family-fs-sandbox.md # .agents/notes/implemented/feature/2026-07-14-cross-family-fs-sandbox.zh.md # docs/capability-seams.md # docs/cordis-catalog/events.md # docs/cordis-catalog/services.md # docs/event-producer-consumer.md # docs/module-graph.md # docs/persistence-catalog.md # docs/rfc/INDEX.md # examples/acp-agent/README.md # examples/acp-agent/fs.cordis.snapshot.yml # examples/acp-agent/fs.cordis.yml # examples/acp-agent/tests/snapshots/escalation-approved/session.jsonl # examples/acp-agent/tests/snapshots/escalation-rejected/session.jsonl # examples/acp-agent/tests/snapshots/hook-cc-pretool-ask/session.jsonl # examples/acp-agent/tests/snapshots/permission-switching/session.jsonl # examples/acp-agent/tests/snapshots/workspace-context/system-prompt.expected.md # examples/acp-agent/tests/snapshots/workspace-context/tool-schemas.expected.json # examples/acp-agent/tests/snapshots/workspace-edit/system-prompt.expected.md # examples/acp-agent/tests/snapshots/workspace-edit/tool-schemas.expected.json # packages/bash/bash/src/index.ts # packages/bash/tool-bash/package.json # packages/bash/tool-bash/src/index.ts # packages/bash/tool-bash/tests/tools.spec.ts # packages/cordis/tool-cordis/src/api-catalog.ts # packages/fs/README.md # packages/fs/tool-fs/src/edit.ts # packages/fs/tool-fs/src/write.ts # packages/sandbox/README.md # pnpm-lock.yaml
2026-07-20 11:40:29 +08:00
parent 9a2ef4e229 023bed1a83
commit 2e7cdddb89
1293 changed files with 74019 additions and 16297 deletions
--- a/packages/cordis/tool-cordis/src/api-catalog.ts
+++ b/packages/cordis/tool-cordis/src/api-catalog.ts
--- a/packages/cordis/tool-cordis/src/index.ts
+++ b/packages/cordis/tool-cordis/src/index.ts
@@ -12,9 +12,9 @@ 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 { EVENT_API, INHERITED_CTX_API, SERVICE_API, TYPE_API } from './api-catalog.ts'
 import { describeApi, describeDynamic, describeEvents, describePlugins, describeServices, describeTools } from './inspect.ts'
-import { missingServices, mountDynamic } from './mount.ts'
-import type { DynamicMount } from './mount.ts'
+import { missingServices, mountDynamic, type DynamicMount } from './mount.ts'
 import { presentInspectCall, presentMountCall, presentUnmountCall } from './present.ts'
 import { createSandbox, evaluateMountCode } from './sandbox.ts'

@@ -26,7 +26,7 @@ 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.
+   * bound — see .agents/notes/implemented/feature/2026-07-08-self-referential-cordis-toolset.md for the trust stance.
   */
  vmTimeoutMs?: number
 }
@@ -63,15 +63,23 @@ export function apply(ctx: Context, config: Config): void {
      + '`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.',
+      + 'Omit `what` to get all six sections. With `what:"api"` or `what:"events"`, pass an exact `name` '
+      + 'to narrow to one service/event and include its original source JSDoc.',
    parameters: {
      what: {
        type: 'string',
        enum: ['services', 'plugins', 'tools', 'dynamic', 'api', 'events'],
        description: 'Limit the report to one section. Omit for all sections.',
      },
+      name: {
+        type: 'string',
+        description: 'Exact service key or event name whose original JSDoc to include; valid only with what:"api" or what:"events".',
+      },
    },
    execute(args, exec): Promise<{ type: 'text'; text: string }[]> {
+      if (args.name !== undefined && args.what !== 'api' && args.what !== 'events') {
+        throw new Error('name is valid only with what:"api" or what:"events"')
+      }
      const sections: [heading: string, body: () => string[]][] = [
        ['services', () => describeServices(ctx)],
        ['plugins', () => describePlugins(ctx)],
@@ -79,8 +87,8 @@ export function apply(ctx: Context, config: Config): void {
        // globals absent — "what you can call", not the global registry.
        ['tools', () => describeTools(ctx, exec.agent)],
        ['dynamic', () => describeDynamic(ctx, mounts)],
-        ['api', () => describeApi(ctx)],
-        ['events', () => describeEvents()],
+        ['api', () => describeApi(ctx, SERVICE_API, INHERITED_CTX_API, TYPE_API, args.name)],
+        ['events', () => describeEvents(EVENT_API, args.name)],
      ]
      const selected = sections.filter(([heading]) => args.what === undefined || args.what === heading)
      const text = selected
--- a/packages/cordis/tool-cordis/src/inspect.ts
+++ b/packages/cordis/tool-cordis/src/inspect.ts
@@ -1,7 +1,8 @@
 /**
 * Read-only renderers over the live runtime for `cordis_inspect`: the service list, the flat
 * plugin list, the registered tools, the dynamic-mount table (with per-mount provides/waits),
- * and the catalog-backed `api` / `events` sections.
+ * and the catalog-backed `api` / `events` sections. Exact-name lookups add the
+ * original source JSDoc without inflating the default reports.
 * @module @deepseek-ai/dsh-tool-cordis/inspect
 */

@@ -126,6 +127,18 @@ function typeClosure(seeds: string[], types: readonly TypeApiEntry[]): TypeApiEn
  return [...included.values()].sort((a, b) => a.name.localeCompare(b.name))
 }

+/** Render one catalogued service, optionally including source-owned method JSDoc. */
+function serviceLines(entry: ServiceApiEntry, detailed: boolean): string[] {
+  const lines = [`- ${entry.key} — ${entry.summary}`]
+  for (const method of entry.methods) {
+    if (detailed) {
+      for (const docLine of method.jsDoc.split('\n')) lines.push(`    ${docLine}`)
+    }
+    lines.push(`    ${method.signature}`)
+  }
+  return lines
+}
+
 /**
 * Render the generated catalog against the live runtime: live catalogued services with methods,
 * uncatalogued live services with owners, absent loadable services, referenced type shapes, and
@@ -134,6 +147,7 @@ function typeClosure(seeds: string[], types: readonly TypeApiEntry[]): TypeApiEn
 * @param api - generated service entries, replaceable in tests.
 * @param inherited - inherited `ctx` entries, replaceable in tests.
 * @param types - public type shapes, replaceable in tests.
+ * @param name - exact live service key whose methods should include original JSDoc; omitted for the compact catalog.
 * @returns the section lines.
 */
 export function describeApi(
@@ -141,25 +155,33 @@ export function describeApi(
  api: readonly ServiceApiEntry[] = SERVICE_API,
  inherited: readonly InheritedApiEntry[] = INHERITED_CTX_API,
  types: readonly TypeApiEntry[] = TYPE_API,
+  name?: string,
 ): string[] {
  const live = new Map<string, string>()
  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}`)
+  let selected = api.filter(entry => live.has(entry.key))
+  if (name !== undefined) {
+    const entry = api.find(candidate => candidate.key === name)
+    if (!entry) throw new Error(`no catalogued service named "${name}"`)
+    if (!live.has(name)) throw new Error(`catalogued service "${name}" is not running`)
+    selected = [entry]
+  }
+  for (const entry of selected) {
+    lines.push(...serviceLines(entry, name !== undefined))
    for (const method of entry.methods) {
-      lines.push(`    ${method}`)
-      liveMethodTexts.push(method)
+      liveMethodTexts.push(method.signature)
    }
  }
-  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)`)
+  if (name === undefined) {
+    const catalogued = new Set(api.map(entry => entry.key))
+    for (const [liveName, fiber] of [...live].sort(([a], [b]) => a.localeCompare(b))) {
+      if (!catalogued.has(liveName)) lines.push(`- ${liveName} (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 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):')
@@ -167,8 +189,10 @@ export function describeApi(
      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}`)
+  if (name === undefined) {
+    lines.push('inherited ctx API:')
+    for (const entry of inherited) lines.push(`- ${entry.name} — ${entry.summary}`)
+  }
  return lines
 }

@@ -176,13 +200,24 @@ export function describeApi(
 * 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).
+ * @param name - exact event name whose signature should include original JSDoc; omitted for the compact catalog.
 * @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}`,
-  ])
+export function describeEvents(events: readonly EventApiEntry[] = EVENT_API, name?: string): string[] {
+  let selected = events
+  if (name !== undefined) {
+    const event = events.find(candidate => candidate.name === name)
+    if (!event) throw new Error(`no catalogued event named "${name}"`)
+    selected = [event]
+  }
+  const lines = selected.flatMap((event) => {
+    const entry = [`- ${event.name} [${event.mode}] — ${event.summary}`]
+    if (name !== undefined) {
+      for (const docLine of event.jsDoc.split('\n')) entry.push(`    ${docLine}`)
+    }
+    entry.push(`    ${event.signature}`)
+    return entry
+  })
  lines.push('waterfall listeners receive a trailing next() and MUST call it to delegate — returning without next() vetoes the chain.')
  return lines
 }
--- a/packages/cordis/tool-cordis/src/present.ts
+++ b/packages/cordis/tool-cordis/src/present.ts
@@ -15,11 +15,12 @@ import type { GenericCallView } from '@deepseek-ai/dsh-tools'
 * @param args - the validated call arguments.
 * @returns the generic card the ACP bridge renders.
 */
-export function presentInspectCall(args: { what?: string }): GenericCallView {
+export function presentInspectCall(args: { what?: string; name?: string }): GenericCallView {
+  const target = args.name === undefined ? args.what : `${args.what}: ${args.name}`
  return {
    card: 'generic',
    kind: 'read',
-    title: args.what === undefined ? 'Inspect cordis runtime' : `Inspect cordis runtime: ${args.what}`,
+    title: target === undefined ? 'Inspect cordis runtime' : `Inspect cordis runtime: ${target}`,
  }
 }