Turtle
cd6b4ee3c9
dsh --profile <name> replaces the fixed entry modes: --config and -p are removed, --patch adds overlays over the composed profile, a positional task selects one-shot mode (requires the headless-runner row), and dsh web stays as the alias for --profile web carrying the Web flag family as patches. dsh plugin --profile <name> forwards verbatim to pnpm in the profile directory, initializes on first use, and reconciles the dsh.plugins layer list after add/remove (patch-less packages warn and stay plain dependencies). Config dumps and the keyless web e2e scaffold compose the same bundle layers over the same empty root as the boot.
1366 lines
60 KiB
TypeScript
1366 lines
60 KiB
TypeScript
/**
|
|
* Generate the relationship layer above the module, Cordis, and tool catalogs.
|
|
* Enumerable facts come from source; hybrid graphs add manifests for policy the
|
|
* source cannot infer, while curated graphs explain flow and ownership.
|
|
* `--check` verifies the generated set.
|
|
*/
|
|
|
|
import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs'
|
|
import { dirname, relative, resolve } from 'node:path'
|
|
import ts from 'typescript'
|
|
import { projectCordisCatalog } from '@deepseek-ai/dsh-typert-generator'
|
|
import { CORDIS_CATALOG_POLICY } from './gen-cordis-catalog.ts'
|
|
import type { EventEntry, ServiceEntry } from '@deepseek-ai/dsh-typert-generator'
|
|
import {
|
|
collectPackageGraph,
|
|
escapeMermaidLabel as escLabel,
|
|
graphNodeId as nodeId,
|
|
type PackageGraphNode,
|
|
} from './package-graph.ts'
|
|
import { TypeScriptProject } from './ts-project.ts'
|
|
|
|
const root = resolve(import.meta.dirname, '..')
|
|
type Pkg = PackageGraphNode
|
|
|
|
interface GraphDoc {
|
|
rel: string
|
|
content: string
|
|
}
|
|
|
|
interface ServiceRole {
|
|
key: string
|
|
pkg: string
|
|
title: string
|
|
mode: 'core' | 'seam' | 'bundle'
|
|
implementations?: string[]
|
|
consumers?: string[]
|
|
companions?: string[]
|
|
note: string
|
|
}
|
|
|
|
interface ExamplePlugin {
|
|
id: string
|
|
name: string
|
|
}
|
|
|
|
interface EventRelation {
|
|
dispatchers: Map<string, Set<string>>
|
|
listeners: Set<string>
|
|
}
|
|
|
|
/** One scanned package source file and its owning package short name. */
|
|
export interface PackageSource {
|
|
/** Repository-relative path. */
|
|
rel: string
|
|
/** Package short name from the `packages/<group>/<pkg>/src` path. */
|
|
pkg: string
|
|
/** The bound program source file. */
|
|
sourceFile: ts.SourceFile
|
|
}
|
|
|
|
type EventReceiverKind = 'context' | 'agent-dispatch' | 'events-service'
|
|
|
|
const GROUP_ORDER = [
|
|
'util',
|
|
'llm',
|
|
'core',
|
|
'typert',
|
|
'goal',
|
|
'process',
|
|
'bash',
|
|
'pty',
|
|
'sandbox',
|
|
'fs',
|
|
'skill',
|
|
'compact',
|
|
'subagent',
|
|
'tasks',
|
|
'workflow',
|
|
'web',
|
|
'spill',
|
|
'todo',
|
|
'plan',
|
|
'cordis',
|
|
'hooks',
|
|
'session-persistence',
|
|
'session-query',
|
|
'session-title',
|
|
'telemetry',
|
|
'storage',
|
|
'workspace',
|
|
'support',
|
|
'acp',
|
|
'ui',
|
|
]
|
|
|
|
const SERVICE_ROLES: ServiceRole[] = [
|
|
{
|
|
key: 'llm',
|
|
pkg: 'llm',
|
|
title: 'LLM adapter registry',
|
|
mode: 'seam',
|
|
implementations: ['llm-deepseek', 'llm-pi-ai', 'llm-replay'],
|
|
consumers: ['agent-loop', 'compact-basic'],
|
|
note: 'Adapters register provider implementations; the loop and compaction call the provider-neutral stream service.',
|
|
},
|
|
{
|
|
key: 'tokenMeter',
|
|
pkg: 'token-meter',
|
|
title: 'Replay token measurement',
|
|
mode: 'core',
|
|
consumers: ['compact-basic'],
|
|
note: 'Owns isolated per-session replay folds; pressure consumers share immutable revisioned measurements.',
|
|
},
|
|
{
|
|
key: 'toolResultPrune',
|
|
pkg: 'compact-tool-result-prune',
|
|
title: 'Model-free tool-result pruning',
|
|
mode: 'core',
|
|
consumers: ['compact-basic'],
|
|
note: 'Rewrites oversized current tool results through replayable single-node surface replacements before summary compaction.',
|
|
},
|
|
{
|
|
key: 'sessions',
|
|
pkg: 'session',
|
|
title: 'In-memory session store',
|
|
mode: 'core',
|
|
consumers: ['agent-loop', 'agent', 'cli-demo', 'session-persistence', 'session-query', 'session-query-sqlite', 'subagent-inprocess', 'invariants'],
|
|
note: 'Owns append-only Session instances and emits the durable session event feed.',
|
|
},
|
|
{
|
|
key: 'invariants',
|
|
pkg: 'invariants',
|
|
title: 'Package-owned invariant registry',
|
|
mode: 'core',
|
|
consumers: ['session', 'agent', 'scope', 'agent-loop'],
|
|
note: 'Companion subpaths register owner-local checks; the service owns selection, uniqueness, child fibers, and package-attributed failures.',
|
|
},
|
|
{
|
|
key: 'typert',
|
|
pkg: 'typert-registry',
|
|
title: 'Runtime type registry',
|
|
mode: 'core',
|
|
consumers: ['typert-loader'],
|
|
note: 'Plugins register live zod contributions directly or through dsh-typert-loader; runtime consumers query schemas and reflection metadata at their own edges.',
|
|
},
|
|
{
|
|
key: 'sessionPersistence',
|
|
pkg: 'session-persistence',
|
|
title: 'Durable session persistence seam',
|
|
mode: 'seam',
|
|
implementations: ['session-persistence-jsonl', 'session-persistence-sqlite'],
|
|
consumers: ['agent-loop', 'tool-bash', 'hooks-claude', 'hooks-codex', 'session-query', 'session-query-sqlite'],
|
|
note: 'Backends persist the same SessionEvent vocabulary; apps choose a backend at composition time.',
|
|
},
|
|
{
|
|
key: 'settings',
|
|
pkg: 'settings',
|
|
title: 'User-settings seam',
|
|
mode: 'seam',
|
|
implementations: ['settings-local'],
|
|
consumers: ['llm-deepseek', 'llm-pi-ai', 'apiproxy'],
|
|
note: 'Plugins register namespace schemas and resolve layered values; providers store the raw document. The LLM adapters register their entry config as the composition base under the user section; the web gateway serves redacted layered descriptors and writes the user layer.',
|
|
},
|
|
{
|
|
key: 'credentials',
|
|
pkg: 'credentials',
|
|
title: 'Credential seam',
|
|
mode: 'seam',
|
|
implementations: ['credentials-local'],
|
|
consumers: ['llm-deepseek', 'llm-pi-ai', 'apiproxy'],
|
|
note: 'Configuration carries references to secrets; providers own the values. Consumers resolve per operation, so a rotated credential reaches the very next request; the web gateway exposes value-free views and write-only storage.',
|
|
},
|
|
{
|
|
key: 'telemetry',
|
|
pkg: 'session-telemetry',
|
|
title: 'Session telemetry seam',
|
|
mode: 'seam',
|
|
implementations: ['session-telemetry-otel'],
|
|
consumers: [],
|
|
note: 'The seam captures, redacts, and hands session records to one backend; nothing else consumes the service — its output leaves the process.',
|
|
},
|
|
{
|
|
key: 'storage',
|
|
pkg: 'storage',
|
|
title: 'Non-session storage hub',
|
|
mode: 'seam',
|
|
implementations: ['storage-json', 'storage-sqlite'],
|
|
consumers: ['storage-domain'],
|
|
note: 'Backends register side by side under names; data forms (domain first) mount on the hub and translate typed operations into opaque KV-unit primitives.',
|
|
},
|
|
{
|
|
key: 'storageDomain',
|
|
pkg: 'storage-domain',
|
|
title: 'Domain data facility',
|
|
mode: 'core',
|
|
consumers: ['workspace'],
|
|
note: 'Waits for every configured backend, then publishes the domain form as one lifecycle-bound service for typed durable state.',
|
|
},
|
|
{
|
|
key: 'workspace',
|
|
pkg: 'workspace',
|
|
title: 'Workspace entity registry',
|
|
mode: 'core',
|
|
consumers: ['apiproxy'],
|
|
note: 'Owns WorkspaceId-branded records over the domain facility; stable sessionIds accounts drive Host RPC and GUI projections.',
|
|
},
|
|
{
|
|
key: 'sessionQuery',
|
|
pkg: 'session-query',
|
|
title: 'Session reads, traces, filters, and search',
|
|
mode: 'seam',
|
|
implementations: ['session-query-sqlite'],
|
|
consumers: ['session-reference', 'tool-session-query'],
|
|
note: 'The interface supplies exact reads, filters, and traces; its concrete backend adds full-text reconciliation, ranking, snippets, and cursor generations, while the model consumer owns workspace authority and cursor-free rendering.',
|
|
},
|
|
{
|
|
key: 'sessionReferences',
|
|
pkg: 'session-reference',
|
|
title: 'Cross-session snapshot preparation',
|
|
mode: 'core',
|
|
note: 'Projects bounded current-surface conversation snapshots into durable untrusted message context; host adapters own mention syntax.',
|
|
},
|
|
{
|
|
key: 'sessionTitle',
|
|
pkg: 'session-title',
|
|
title: 'Log-backed session titles',
|
|
mode: 'seam',
|
|
implementations: ['session-title-first-message-llm', 'session-title-all-messages-llm'],
|
|
note: 'Owns the deterministic fallback, latest-title fold, and sole optional asynchronous provider registration.',
|
|
},
|
|
{
|
|
key: 'systemPrompt',
|
|
pkg: 'system-prompt',
|
|
title: 'System prompt assembly registry',
|
|
mode: 'core',
|
|
consumers: ['agent-loop', 'tools', 'tool-fs', 'tool-pty', 'tool-web'],
|
|
note: 'Collects prompt sections and model-facing tool schemas for each step.',
|
|
},
|
|
{
|
|
key: 'tools',
|
|
pkg: 'tools',
|
|
title: 'Tool registry and guarded execution pipeline',
|
|
mode: 'core',
|
|
consumers: ['agent-loop', 'tool-ask-user', 'tool-bash', 'tool-cordis', 'tool-fs', 'tool-pty', 'tool-skill', 'tool-subagent', 'tool-todo', 'tool-web'],
|
|
note: 'Registers capabilities, owns Code Mode transport, and routes calls through pre-policy, monotonic guards, around dispatch, post-policy, and final-result observation.',
|
|
},
|
|
{
|
|
key: 'userInteraction',
|
|
pkg: 'user-interaction',
|
|
title: 'Human question/answer seam',
|
|
mode: 'seam',
|
|
consumers: ['tool-ask-user'],
|
|
note: 'UI front doors provide the active human-answer provider; tool-ask-user pauses a tool call on the provider-neutral ask() promise.',
|
|
},
|
|
{
|
|
key: 'planMode',
|
|
pkg: 'plan-mode',
|
|
title: 'Plan collaboration state',
|
|
mode: 'core',
|
|
note: 'Folds logged plan/mode state, flushes user selections at turn boundaries, renders deployment-owned guidance, registers /plan, and keeps the plan-exit schema stable across transitions.',
|
|
},
|
|
{
|
|
key: 'commands',
|
|
pkg: 'commands',
|
|
title: 'Human command registry',
|
|
mode: 'core',
|
|
note: 'Plugins register direct human commands without sending invocations to the model.',
|
|
},
|
|
{
|
|
key: 'sessionProjections',
|
|
pkg: 'session-projection',
|
|
title: 'Session projection units',
|
|
mode: 'core',
|
|
consumers: ['tool-todo', 'session-title', 'host-apiproxy'],
|
|
note: 'Domains register state-driven fold units; the eager drive keeps per-session watermark states and api-proxy serves baselines and pushes changed values.',
|
|
},
|
|
{
|
|
key: 'sessionProjectionCache',
|
|
pkg: 'session-projection-cache',
|
|
title: 'Persisted projection cache',
|
|
mode: 'core',
|
|
consumers: ['host-apiproxy'],
|
|
note: 'Durably checkpoints projection unit states per session (throttled + turn/end/detach mandatory points) and serves the cold-read ladder: cache row + persistence tail replay, so listings never load full logs.',
|
|
},
|
|
{
|
|
key: 'skills',
|
|
pkg: 'skill',
|
|
title: 'Skill provider registry',
|
|
mode: 'seam',
|
|
implementations: ['skill-local'],
|
|
consumers: ['tool-skill'],
|
|
note: 'Merges provider skill catalogs; tool-skill renders the session-prefix catalog and loads complete skill bodies.',
|
|
},
|
|
{
|
|
key: 'agents',
|
|
pkg: 'agent',
|
|
title: 'Agent service',
|
|
mode: 'core',
|
|
consumers: ['agent-loop', 'acp', 'cli-demo', 'subagent-inprocess'],
|
|
note: 'Owns live Agent handles, the create/resume factory seam, and process-local initiator propagation.',
|
|
},
|
|
{
|
|
key: 'agentLoop',
|
|
pkg: 'agent-loop',
|
|
title: 'Concrete loop driver',
|
|
mode: 'bundle',
|
|
consumers: ['agent-spine-demo'],
|
|
note: 'The one concrete loop plugin; extension packages depend on dsh-agent events and services, not on this package.',
|
|
},
|
|
{
|
|
key: 'goals',
|
|
pkg: 'goal',
|
|
title: 'Same-session goal domain',
|
|
mode: 'core',
|
|
note: 'Folds revisioned objective state from the session log and keeps live continuation activation process-local.',
|
|
},
|
|
{
|
|
key: 'subprocess',
|
|
pkg: 'subprocess',
|
|
title: 'Subprocess seam',
|
|
mode: 'seam',
|
|
implementations: ['subprocess-local'],
|
|
consumers: ['bash-local', 'bash-sandbox', 'lsp-local', 'subagent-acp'],
|
|
note: 'The bash executors, the LSP host, and the ACP subagent backend spawn their children through ctx.subprocess; the service owns tree lifetime, stdio dispositions (pipes, inherit, bounded spill-backed collection), and kill escalation.',
|
|
},
|
|
{
|
|
key: 'bash',
|
|
pkg: 'bash',
|
|
title: 'Bash executor seam',
|
|
mode: 'seam',
|
|
implementations: ['bash-local', 'bash-sandbox', 'pwsh-local'],
|
|
consumers: ['tool-bash', 'tool-pwsh', 'hooks-claude', 'hooks-codex'],
|
|
note: 'The model-facing shell tools and hook bridges consume this seam; sandboxed, remote, or PowerShell executors replace bash-local without touching them.',
|
|
},
|
|
{
|
|
key: 'bashEnv',
|
|
pkg: 'bash-env',
|
|
title: 'Managed bash environment registry',
|
|
mode: 'core',
|
|
consumers: ['tool-bash', 'tool-pwsh'],
|
|
note: 'Plugins declare effect-scoped DSH_* facts; each shell tool collects one trusted snapshot per execution and its executor rebuilds the namespace.',
|
|
},
|
|
{
|
|
key: 'pty',
|
|
pkg: 'pty',
|
|
title: 'Persistent PTY session registry',
|
|
mode: 'seam',
|
|
implementations: ['pty-local'],
|
|
consumers: ['tool-pty'],
|
|
note: 'The registry owns exact-Agent session identity and cleanup; backends own terminal mechanics, while tool-pty exposes the owner-scoped model surface.',
|
|
},
|
|
{
|
|
key: 'sandbox',
|
|
pkg: 'sandbox',
|
|
title: 'Process-sandbox seam',
|
|
mode: 'seam',
|
|
implementations: ['sandbox-local'],
|
|
consumers: ['bash-sandbox', 'pty-local'],
|
|
note: 'Consumers hand over the exact argv they are about to spawn; same-world backends wrap it under a per-call policy and report enforcement.',
|
|
},
|
|
{
|
|
key: 'sandboxPolicy',
|
|
pkg: 'sandbox-policy',
|
|
title: 'Sandbox policy home',
|
|
mode: 'core',
|
|
implementations: [],
|
|
consumers: ['bash-sandbox', 'fs-sandbox', 'pty-local'],
|
|
note: 'The one home for the deployment default mode + workspace root; only the sandboxed executor and provider read the service (the tool layers use the pure `sandbox/mode` fold it also exports). Both enforcing families read it so bash and fs cannot confine to different roots.',
|
|
},
|
|
{
|
|
key: 'approval',
|
|
pkg: 'approval',
|
|
title: 'Approval seam',
|
|
mode: 'seam',
|
|
implementations: ['acp'],
|
|
consumers: ['tools', 'tool-bash'],
|
|
note: 'One-shot permission decisions dispatched over the `approval/request` waterfall; answerers are listeners (the ACP bridge for its own agents), absence fails closed to `unavailable`.',
|
|
},
|
|
{
|
|
key: 'permission',
|
|
pkg: 'permission',
|
|
title: 'Permission presets',
|
|
mode: 'core',
|
|
implementations: [],
|
|
note: 'User-facing preset table (`workspace-write`/`danger-full-access`) bundling the sandbox-mode and approval-policy knobs; a switch writes one `permission/preset` event through to both knob events.',
|
|
},
|
|
{
|
|
key: 'codeRuntime',
|
|
pkg: 'code-runtime',
|
|
title: 'Code-execution seam',
|
|
mode: 'seam',
|
|
implementations: ['code-runtime-worker'],
|
|
consumers: ['tools'],
|
|
note: 'Runs one model-written program against host-provided async bindings; backends differ by substrate and language (the tool registry consumes it for Code Mode).',
|
|
},
|
|
{
|
|
key: 'fs',
|
|
pkg: 'fs',
|
|
title: 'Filesystem provider seam',
|
|
mode: 'seam',
|
|
implementations: ['fs-local', 'fs-sandbox'],
|
|
consumers: ['tool-fs'],
|
|
companions: ['fs-policy'],
|
|
note: 'tool-fs executes read/write/edit through ctx.fs; fs-sandbox fences mutations by the shared sandbox mode; fs-policy contributes observed-state checks through the fs/* event gate.',
|
|
},
|
|
{
|
|
key: 'compact',
|
|
pkg: 'compact',
|
|
title: 'Compaction seam',
|
|
mode: 'seam',
|
|
implementations: ['compact-basic'],
|
|
consumers: ['compact-basic'],
|
|
note: 'The basic backend consumes post-step pressure and request-error recovery events; a model-facing compact tool remains deferred.',
|
|
},
|
|
{
|
|
key: 'subagents',
|
|
pkg: 'subagent',
|
|
title: 'Subagent provider and continuation service',
|
|
mode: 'seam',
|
|
implementations: ['subagent-spawn', 'subagent-fork', 'subagent-acp'],
|
|
consumers: ['tool-subagent', 'tool-subagent-control', 'tool-ralph'],
|
|
note: 'Providers implement transports; the service also owns optional Activation-based continuation orchestration, tool-subagent selects one-shot or continuable delegation, tool-subagent-control delivers follow-ups, and tool-ralph requires one fresh structured-output route.',
|
|
},
|
|
{
|
|
key: 'tasks',
|
|
pkg: 'tasks',
|
|
title: 'Background task registry',
|
|
mode: 'seam',
|
|
implementations: ['tasks-local'],
|
|
consumers: ['tool-bash', 'tool-pty', 'tool-subagent', 'tool-tasks'],
|
|
note: 'Producers (background bash, PTY sends, and subagent delegations) register running work; tool-tasks is the model-facing control surface that reads, lists, and kills it; tasks-local is the process-local registry.',
|
|
},
|
|
{
|
|
key: 'web',
|
|
pkg: 'web',
|
|
title: 'Web access provider registry',
|
|
mode: 'seam',
|
|
implementations: ['web-search-exa', 'web-search-perplexity', 'web-search-deepseek', 'web-fetch-local'],
|
|
consumers: ['tool-web'],
|
|
note: 'Search and fetch providers register into one ctx.web seam; tool-web owns the stable model-facing names.',
|
|
},
|
|
{
|
|
key: 'spillStore',
|
|
pkg: 'spill',
|
|
title: 'Spill storage seam',
|
|
mode: 'seam',
|
|
implementations: ['spill-local'],
|
|
consumers: ['spill-policy'],
|
|
note: 'The backend saves oversized tool text and returns a model-facing locator plus retrieval hint; spill-policy is the tools/post-execute consumer that decides when to spill.',
|
|
},
|
|
{
|
|
key: 'directoryPicker',
|
|
pkg: 'directory-picker',
|
|
title: 'Workspace-directory picking seam',
|
|
mode: 'seam',
|
|
implementations: ['directory-picker-native', 'directory-picker-browse'],
|
|
consumers: ['apiproxy'],
|
|
note: 'Discriminated interaction capability: the native backend opens one OS chooser on the host display, the browse backend serves listing/creation primitives for the in-app browser; dual-face backends fill ui-workspace directory-flow slots from their browser halves (no wire advertisement).',
|
|
},
|
|
{
|
|
key: 'httpServer',
|
|
pkg: 'webserver',
|
|
title: 'HTTP route registration',
|
|
mode: 'core',
|
|
consumers: ['connection', 'modules', 'hmr'],
|
|
note: 'Plain node:http carrier: named-route registry, index transform taps, and the static dist fallback; web-transport plugins register their own routes.',
|
|
},
|
|
{
|
|
key: 'clientModuleHost',
|
|
pkg: 'modules',
|
|
title: 'Client plugin graph host',
|
|
mode: 'core',
|
|
consumers: ['hmr'],
|
|
note: 'Composes the __DSH_BOOT__ entry graph from an incremental dshClient scan, serves plugin bundles, and notifies rebuilt/graph-changed subscribers.',
|
|
},
|
|
{
|
|
key: 'workflows',
|
|
pkg: 'workflow',
|
|
title: 'Workflow script engine',
|
|
mode: 'seam',
|
|
implementations: ['workflow-workerthread'],
|
|
consumers: ['tool-workflow', 'tool-ralph'],
|
|
note: 'One engine per context (bash shape, no named-provider registry); the general workflow and fixed Ralph consumers start runs whose agent() calls fan out through ctx.subagents.',
|
|
},
|
|
]
|
|
|
|
function generatedHeader(title: string): string[] {
|
|
return [
|
|
'<!-- Generated by scripts/gen-doc-graphs.ts - do not edit by hand.',
|
|
' Run `pnpm run gen-doc-graphs` to regenerate. -->',
|
|
'',
|
|
`# ${title}`,
|
|
'',
|
|
]
|
|
}
|
|
|
|
function maintenanceFooter(source: string): string[] {
|
|
return [`Maintenance mode: ${source}.`, '']
|
|
}
|
|
|
|
function graphIndexLink(rel: string): string {
|
|
return relative('docs', rel).replaceAll('\\', '/')
|
|
}
|
|
|
|
function linkFromDoc(docRel: string, targetRel: string): string {
|
|
return relative(dirname(docRel), targetRel).replaceAll('\\', '/')
|
|
}
|
|
|
|
function mermaidCode(value: string): string {
|
|
return `<code>${value.replace(/&/g, '&').replace(/</g, '<').replace(/>/g, '>')}</code>`
|
|
}
|
|
|
|
function repoLink(path: string, label: string, up = '..'): string {
|
|
return `[${label}](${up}/${path})`
|
|
}
|
|
|
|
function sourceLink(source: string, up = '..'): string {
|
|
return repoLink(source.split(':')[0] ?? source, `\`${source}\``, up)
|
|
}
|
|
|
|
function pkgLink(pkg: Pkg | undefined, fallback: string, up = '..'): string {
|
|
return pkg ? repoLink(pkg.rel, `\`${pkg.short}\``, up) : `\`${fallback}\``
|
|
}
|
|
|
|
function pkgList(names: string[] | undefined, pkgsByShort: Map<string, Pkg>): string {
|
|
if (!names || names.length === 0) return '-'
|
|
return names.map(name => pkgLink(pkgsByShort.get(name), name)).join(', ')
|
|
}
|
|
|
|
function tableCell(value: string): string {
|
|
return value.replace(/\|/g, '\\|').replace(/\n/g, '<br>')
|
|
}
|
|
|
|
function assertServiceRolesComplete(services: readonly ServiceEntry[]): void {
|
|
const discovered = new Set(services.map(service => service.key))
|
|
const classified = new Set(SERVICE_ROLES.map(role => role.key))
|
|
const missing = [...discovered].filter(key => !classified.has(key)).sort()
|
|
const stale = [...classified].filter(key => !discovered.has(key)).sort()
|
|
if (missing.length || stale.length) {
|
|
throw new Error([
|
|
missing.length ? `missing service role classification: ${missing.join(', ')}` : '',
|
|
stale.length ? `stale service role classification: ${stale.join(', ')}` : '',
|
|
].filter(Boolean).join('; '))
|
|
}
|
|
}
|
|
|
|
function renderCapabilitySeams(pkgs: Pkg[], services: readonly ServiceEntry[]): string {
|
|
assertServiceRolesComplete(services)
|
|
const pkgsByShort = new Map(pkgs.map(pkg => [pkg.short, pkg]))
|
|
const maintenance = 'hybrid: services are discovered from Cordis declarations; interface/implementation/consumer roles are classified in `scripts/gen-doc-graphs.ts` with a completeness guard'
|
|
const nodes = new Map<string, string>()
|
|
const edges = new Set<string>()
|
|
const companionEdges = new Set<string>()
|
|
const addNode = (id: string, label: string): void => {
|
|
if (!nodes.has(id)) nodes.set(id, ` ${id}["${escLabel(label)}"]`)
|
|
}
|
|
const addEdge = (from: string, to: string): void => { edges.add(` ${from} --> ${to}`) }
|
|
const lines = generatedHeader('Capability Seams And Core Services')
|
|
lines.push(
|
|
'A service can be a core spine service, a swappable capability seam, or a bundle/composition point. The graph shows the package that owns the service declaration, known implementation packages, and packages that consume the service directly.',
|
|
'',
|
|
'```mermaid',
|
|
'flowchart LR',
|
|
)
|
|
for (const role of SERVICE_ROLES) {
|
|
const svc = nodeId('svc', role.key)
|
|
const owner = nodeId('pkg', role.pkg)
|
|
addNode(owner, role.pkg)
|
|
addNode(svc, `ctx.${role.key}<br/>${role.title}`)
|
|
addEdge(owner, svc)
|
|
for (const impl of role.implementations ?? []) {
|
|
addNode(nodeId('pkg', impl), impl)
|
|
addEdge(nodeId('pkg', impl), svc)
|
|
}
|
|
for (const consumer of role.consumers ?? []) {
|
|
addNode(nodeId('pkg', consumer), consumer)
|
|
addEdge(svc, nodeId('pkg', consumer))
|
|
}
|
|
for (const companion of role.companions ?? []) {
|
|
addNode(nodeId('pkg', companion), companion)
|
|
companionEdges.add(` ${svc} -. event gate .-> ${nodeId('pkg', companion)}`)
|
|
}
|
|
}
|
|
lines.push(...nodes.values(), ...[...edges].sort(), ...[...companionEdges].sort())
|
|
lines.push('```', '', '| ctx key | Role | Owner | Implementations | Direct consumers | Companion plugins | Note |', '| --- | --- | --- | --- | --- | --- | --- |')
|
|
for (const role of SERVICE_ROLES) {
|
|
lines.push(`| \`ctx.${role.key}\` | \`${role.mode}\` | ${pkgLink(pkgsByShort.get(role.pkg), role.pkg)} | ${pkgList(role.implementations, pkgsByShort)} | ${pkgList(role.consumers, pkgsByShort)} | ${pkgList(role.companions, pkgsByShort)} | ${tableCell(role.note)} |`)
|
|
}
|
|
lines.push('', ...maintenanceFooter(maintenance))
|
|
return lines.join('\n')
|
|
}
|
|
|
|
function parseExampleCordis(rel: string): ExamplePlugin[] {
|
|
const text = readFileSync(resolve(root, rel), 'utf8')
|
|
const plugins: ExamplePlugin[] = []
|
|
let current: { id: string; name?: string } | null = null
|
|
const flush = (): void => {
|
|
if (current?.name) plugins.push({ id: current.id, name: current.name })
|
|
}
|
|
for (const line of text.split('\n')) {
|
|
// Top-level rows (`- id:`) and bundle-patch insert rows (` - id:`).
|
|
const id = /^\s*-\s+id:\s+(.+?)\s*$/.exec(line)
|
|
if (id?.[1] !== undefined) {
|
|
flush()
|
|
current = { id: stripYamlScalar(id[1]) }
|
|
continue
|
|
}
|
|
const name = /^\s+name:\s+(.+?)\s*$/.exec(line)
|
|
if (name?.[1] !== undefined && current) current.name = stripYamlScalar(name[1])
|
|
}
|
|
flush()
|
|
return plugins
|
|
}
|
|
|
|
function stripYamlScalar(value: string): string {
|
|
return value.trim().replace(/^['"]|['"]$/g, '')
|
|
}
|
|
|
|
const APP_EXAMPLES = [
|
|
{
|
|
id: 'dsh_base',
|
|
rel: 'apps/cli/composition.md',
|
|
title: 'DSH Base Composition',
|
|
label: 'packages/bundle/base/cordis.patch.yml',
|
|
config: 'packages/bundle/base/cordis.patch.yml',
|
|
summary: 'The dsh-base bundle patch every profile applies first; mode bundles (dsh-web-app, dsh-headless) and the user\'s profile layer patch over it.',
|
|
},
|
|
{
|
|
id: 'headless',
|
|
rel: 'examples/headless-agent/composition.md',
|
|
title: 'Headless Agent App Composition',
|
|
label: 'examples/headless-agent',
|
|
config: 'examples/headless-agent/cordis.yml',
|
|
summary: 'The headless demo combines the real DeepSeek adapter and coding capabilities with the one-shot app package, format-pure stdout, and one fresh persisted top-level session.',
|
|
},
|
|
{
|
|
id: 'acp',
|
|
rel: 'examples/acp-agent/composition.md',
|
|
title: 'ACP Automation App Composition',
|
|
label: 'examples/acp-agent',
|
|
config: 'examples/acp-agent/cordis.yml',
|
|
summary: 'The ACP demo exposes fresh baseline-prompt agent sessions to programmatic clients over JSON-RPC stdio, with no stdout logger, human UI, or pre-created agent.',
|
|
},
|
|
]
|
|
|
|
type AppExample = typeof APP_EXAMPLES[number]
|
|
|
|
function renderAppExpansion(lines: string[], appNode: string, pluginName: string): void {
|
|
const agentCore = nodeId('bundle', 'agent_core')
|
|
const jsonl = nodeId('bundle', 'jsonl')
|
|
lines.push(` ${appNode} --> ${agentCore}["@deepseek-ai/dsh-agent-spine-demo"]`)
|
|
lines.push(` ${appNode} --> ${jsonl}["@deepseek-ai/dsh-session-persistence-jsonl"]`)
|
|
if (pluginName === '@deepseek-ai/dsh-cli-demo') {
|
|
lines.push(` ${appNode} --> ${nodeId('frontdoor', 'cli')}["one-shot driver<br/>format-pure stdout<br/>fresh top-level agent"]`)
|
|
} else if (pluginName === '@deepseek-ai/dsh-acp-demo') {
|
|
lines.push(` ${appNode} --> ${nodeId('frontdoor', 'acp')}["@deepseek-ai/dsh-acp<br/>automation-only JSON-RPC stdio<br/>fresh sessions created by client"]`)
|
|
}
|
|
lines.push(
|
|
` ${agentCore} --> ${nodeId('spine', 'llm')}["ctx.llm"]`,
|
|
` ${agentCore} --> ${nodeId('spine', 'sessions')}["ctx.sessions"]`,
|
|
` ${agentCore} --> ${nodeId('spine', 'tools')}["ctx.tools + tool-bash"]`,
|
|
` ${agentCore} --> ${nodeId('spine', 'loop')}["ctx.agents + ctx.agentLoop"]`,
|
|
)
|
|
}
|
|
|
|
function renderAppComposition(example: AppExample): string {
|
|
const plugins = parseExampleCordis(example.config)
|
|
const maintenance = 'hybrid: the leaf plugin list is parsed from its `cordis.yml`; app package expansion is curated from package source'
|
|
const lines = generatedHeader(example.title)
|
|
lines.push(
|
|
example.summary,
|
|
'',
|
|
'```mermaid',
|
|
'flowchart LR',
|
|
` cfg["${escLabel(example.label)}<br/>cordis.yml"]`,
|
|
)
|
|
for (const plugin of plugins) {
|
|
const pluginNode = nodeId(`plugin_${example.id}`, plugin.id)
|
|
lines.push(` ${pluginNode}["${escLabel(plugin.id)}<br/>${escLabel(plugin.name)}"]`)
|
|
lines.push(` cfg --> ${pluginNode}`)
|
|
if (plugin.name === '@deepseek-ai/dsh-cli-demo' || plugin.name === '@deepseek-ai/dsh-acp-demo') {
|
|
renderAppExpansion(lines, pluginNode, plugin.name)
|
|
}
|
|
}
|
|
lines.push(
|
|
'```',
|
|
'',
|
|
'| Plugin id | Package / module |',
|
|
'| --- | --- |',
|
|
...plugins.map(plugin => `| \`${plugin.id}\` | \`${plugin.name}\` |`),
|
|
'',
|
|
`Source config: [\`${example.config}\`](${linkFromDoc(example.rel, example.config)}).`,
|
|
)
|
|
lines.push('', ...maintenanceFooter(maintenance))
|
|
return lines.join('\n')
|
|
}
|
|
|
|
type CallSiteIndex = Map<ts.SignatureDeclaration | ts.JSDocSignature, ts.CallExpression[]>
|
|
|
|
/**
|
|
* The only method names visitSource classifies; receiver typing runs on these
|
|
* alone. Obligation: every method name matched by a branch inside visitSource
|
|
* must appear here — the prefilter drops non-members before any branch runs,
|
|
* so a branch for an unlisted name is silently dead.
|
|
*/
|
|
const EVENT_API_METHODS = new Set(['on', 'once', 'emit', 'parallel', 'serial', 'waterfall', 'dispatch'])
|
|
|
|
/** Collect event dispatch/listener relations from real cross-file receiver types. */
|
|
export class EventRelationCollector {
|
|
private readonly relations = new Map<string, EventRelation>()
|
|
private readonly fileCallSites = new Map<ts.SourceFile, CallSiteIndex>()
|
|
private readonly localCalleeProofs = new Map<ts.FunctionDeclaration, boolean>()
|
|
private globalCallSites: CallSiteIndex | null = null
|
|
private readonly contextType: ts.Type
|
|
private readonly agentDispatchType: ts.Type
|
|
private readonly eventsServiceType: ts.Type
|
|
private readonly packageSourceFiles: ReadonlySet<ts.SourceFile>
|
|
|
|
constructor(
|
|
private readonly project: TypeScriptProject,
|
|
private readonly sources: readonly PackageSource[],
|
|
) {
|
|
this.contextType = this.declaredType('vendor/cordis/src/context.ts', 'Context')
|
|
this.agentDispatchType = this.declaredType('packages/core/agent/src/dispatch.ts', 'AgentEventDispatch')
|
|
this.eventsServiceType = this.declaredType('vendor/cordis/src/events.ts', 'EventsService')
|
|
this.packageSourceFiles = new Set(sources.map(source => source.sourceFile))
|
|
}
|
|
|
|
/** Return all event relations discovered from the Program. */
|
|
collect(): Map<string, EventRelation> {
|
|
for (const source of this.sources) this.visitSource(source)
|
|
return this.relations
|
|
}
|
|
|
|
/** Resolve one named class/interface declaration to its merged instance type. */
|
|
private declaredType(relativePath: string, name: string): ts.Type {
|
|
const sourceFile = this.project.sourceFile(relativePath)
|
|
const declaration = sourceFile.statements.find((statement): statement is ts.ClassDeclaration | ts.InterfaceDeclaration => {
|
|
return (ts.isClassDeclaration(statement) || ts.isInterfaceDeclaration(statement)) && statement.name?.text === name
|
|
})
|
|
const symbol = declaration?.name && this.project.checker.getSymbolAtLocation(declaration.name)
|
|
if (!symbol) throw new Error(`cannot resolve TypeScript type ${name} from ${relativePath}`)
|
|
return this.project.checker.getDeclaredTypeOfSymbol(symbol)
|
|
}
|
|
|
|
/** Index resolved function calls in the given files for narrow argument-flow recovery. */
|
|
private buildCallSiteIndex(files: Iterable<ts.SourceFile>): CallSiteIndex {
|
|
const index: CallSiteIndex = new Map()
|
|
const visit = (node: ts.Node): void => {
|
|
if (ts.isCallExpression(node)) {
|
|
const declaration = this.project.checker.getResolvedSignature(node)?.declaration
|
|
if (declaration) {
|
|
const calls = index.get(declaration) ?? []
|
|
calls.push(node)
|
|
index.set(declaration, calls)
|
|
}
|
|
}
|
|
ts.forEachChild(node, visit)
|
|
}
|
|
for (const file of files) visit(file)
|
|
return index
|
|
}
|
|
|
|
/**
|
|
* Return every indexed call resolving to one local helper declaration.
|
|
* Fast path: when every same-file reference to the non-exported helper is
|
|
* provably a direct callee, module scoping confines all of its calls to that
|
|
* file, so only that file is indexed. Any other reference shape may alias
|
|
* the function value outward, so the original full package-source index
|
|
* decides instead.
|
|
*/
|
|
private callSitesFor(owner: ts.FunctionDeclaration): ts.CallExpression[] {
|
|
if (!this.globalCallSites && !this.provenLocalCallee(owner)) {
|
|
this.globalCallSites = this.buildCallSiteIndex(this.packageSourceFiles)
|
|
}
|
|
if (this.globalCallSites) return this.globalCallSites.get(owner) ?? []
|
|
const file = owner.getSourceFile()
|
|
let index = this.fileCallSites.get(file)
|
|
if (!index) {
|
|
index = this.buildCallSiteIndex([file])
|
|
this.fileCallSites.set(file, index)
|
|
}
|
|
return index.get(owner) ?? []
|
|
}
|
|
|
|
/**
|
|
* Prove every same-file reference to one helper is a direct callee. The
|
|
* proof owns its premises: an exported helper or a helper in a global
|
|
* script file (no import/export means program-wide scope, callable from
|
|
* another file with no same-file reference at all) fails immediately.
|
|
* Alias escapes (re-export statements, default exports, value reads)
|
|
* resolve back to the owner symbol at a non-callee position and fail the
|
|
* proof, as does anything the scan cannot positively classify.
|
|
*/
|
|
private provenLocalCallee(owner: ts.FunctionDeclaration): boolean {
|
|
const cached = this.localCalleeProofs.get(owner)
|
|
if (cached !== undefined) return cached
|
|
if (hasExportModifier(owner) || !ts.isExternalModule(owner.getSourceFile())) {
|
|
this.localCalleeProofs.set(owner, false)
|
|
return false
|
|
}
|
|
const name = owner.name
|
|
const ownerSymbol = name && this.project.checker.getSymbolAtLocation(name)
|
|
let proven = !!ownerSymbol
|
|
const refersToOwner = (identifier: ts.Identifier): boolean => {
|
|
// Shorthand properties resolve to the property symbol; ask for the value side.
|
|
const local = ts.isShorthandPropertyAssignment(identifier.parent)
|
|
? this.project.checker.getShorthandAssignmentValueSymbol(identifier.parent)
|
|
: this.project.checker.getSymbolAtLocation(identifier)
|
|
if (!local) return false
|
|
const symbol = local.flags & ts.SymbolFlags.Alias
|
|
? this.project.checker.getAliasedSymbol(local)
|
|
: local
|
|
return symbol === ownerSymbol
|
|
}
|
|
const visit = (node: ts.Node): void => {
|
|
if (!proven) return
|
|
if (ts.isIdentifier(node) && node !== name && node.text === name?.text
|
|
&& !isDirectCallee(node) && refersToOwner(node)) {
|
|
proven = false
|
|
return
|
|
}
|
|
ts.forEachChild(node, visit)
|
|
}
|
|
visit(owner.getSourceFile())
|
|
this.localCalleeProofs.set(owner, proven)
|
|
return proven
|
|
}
|
|
|
|
/** Walk one package source file and classify event API calls by receiver type. */
|
|
private visitSource(source: PackageSource): void {
|
|
const visit = (node: ts.Node): void => {
|
|
if (ts.isCallExpression(node)) {
|
|
if (this.isAgentEventEmitter(node.expression)) {
|
|
const event = node.arguments[2]
|
|
if (event) {
|
|
for (const name of this.finiteStringValues(event) ?? []) {
|
|
this.addDispatcher(name, source.pkg, 'emitAgentEvent')
|
|
}
|
|
}
|
|
} else if (ts.isPropertyAccessExpression(node.expression) && EVENT_API_METHODS.has(node.expression.name.text)) {
|
|
const receiverKind = this.receiverKind(node.expression.expression)
|
|
const method = node.expression.name.text
|
|
if (receiverKind === 'events-service' && method === 'dispatch') {
|
|
const argumentList = node.arguments[1]
|
|
if (argumentList) {
|
|
for (const event of this.eventNamesFromArgumentList(argumentList, new Set())) {
|
|
this.addDispatcher(event, source.pkg, 'events.dispatch')
|
|
}
|
|
}
|
|
} else if (receiverKind === 'context' || receiverKind === 'agent-dispatch') {
|
|
const eventNames = this.eventNamesFromCall(node, receiverKind)
|
|
if (method === 'on' || method === 'once') {
|
|
for (const event of eventNames) this.ensure(event).listeners.add(source.pkg)
|
|
} else if (method === 'emit' || method === 'parallel' || method === 'serial' || method === 'waterfall') {
|
|
for (const event of eventNames) this.addDispatcher(event, source.pkg, method)
|
|
}
|
|
}
|
|
}
|
|
}
|
|
ts.forEachChild(node, visit)
|
|
}
|
|
visit(source.sourceFile)
|
|
}
|
|
|
|
/** Match the exported contained-notification helper by declaration identity. */
|
|
private isAgentEventEmitter(expression: ts.Expression): boolean {
|
|
if (!ts.isIdentifier(expression)) return false
|
|
const local = this.project.checker.getSymbolAtLocation(expression)
|
|
if (!local) return false
|
|
const symbol = local.flags & ts.SymbolFlags.Alias
|
|
? this.project.checker.getAliasedSymbol(local)
|
|
: local
|
|
const declarations = symbol.declarations ?? []
|
|
return declarations.some((declaration) => {
|
|
return ts.isFunctionDeclaration(declaration)
|
|
&& declaration.name?.text === 'emitAgentEvent'
|
|
&& this.project.relativePath(declaration.getSourceFile()) === 'packages/core/agent/src/dispatch.ts'
|
|
})
|
|
}
|
|
|
|
/** Classify a receiver using assignability to the repository's actual event API types. */
|
|
private receiverKind(receiver: ts.Expression): EventReceiverKind | undefined {
|
|
const type = this.project.checker.getTypeAtLocation(receiver)
|
|
if (type.flags & (ts.TypeFlags.Any | ts.TypeFlags.Unknown | ts.TypeFlags.Never)) return undefined
|
|
if (this.project.checker.isTypeAssignableTo(type, this.eventsServiceType)) return 'events-service'
|
|
if (this.project.checker.isTypeAssignableTo(type, this.contextType)) return 'context'
|
|
if (this.project.checker.isTypeAssignableTo(type, this.agentDispatchType)) return 'agent-dispatch'
|
|
return undefined
|
|
}
|
|
|
|
/** Resolve the event-name argument for Context and fused agent dispatch calls. */
|
|
private eventNamesFromCall(call: ts.CallExpression, receiverKind: Exclude<EventReceiverKind, 'events-service'>): Set<string> {
|
|
const candidates = receiverKind === 'context' ? call.arguments.slice(0, 2) : call.arguments.slice(0, 1)
|
|
for (const candidate of candidates) {
|
|
const values = this.finiteStringValues(candidate)
|
|
if (values) return values
|
|
}
|
|
return new Set()
|
|
}
|
|
|
|
/** Recover the event slot from the argument array handed to EventsService.dispatch(). */
|
|
private eventNamesFromArgumentList(expression: ts.Expression, seen: Set<ts.Node>): Set<string> {
|
|
const current = unwrapExpression(expression)
|
|
if (seen.has(current)) return new Set()
|
|
seen.add(current)
|
|
|
|
if (ts.isArrayLiteralExpression(current)) {
|
|
for (const element of current.elements.slice(0, 2)) {
|
|
if (ts.isOmittedExpression(element) || ts.isSpreadElement(element)) continue
|
|
const values = this.finiteStringValues(element)
|
|
if (values) return values
|
|
}
|
|
return new Set()
|
|
}
|
|
if (ts.isConditionalExpression(current)) {
|
|
return unionSets(
|
|
this.eventNamesFromArgumentList(current.whenTrue, new Set(seen)),
|
|
this.eventNamesFromArgumentList(current.whenFalse, new Set(seen)),
|
|
)
|
|
}
|
|
if (!ts.isIdentifier(current)) return new Set()
|
|
|
|
const symbol = this.project.checker.getSymbolAtLocation(current)
|
|
if (!symbol) return new Set()
|
|
const events = new Set<string>()
|
|
for (const declaration of symbol.declarations ?? []) {
|
|
if (ts.isVariableDeclaration(declaration) && declaration.initializer && isConstDeclaration(declaration)) {
|
|
addAll(events, this.eventNamesFromArgumentList(declaration.initializer, new Set(seen)))
|
|
} else if (ts.isParameter(declaration)) {
|
|
addAll(events, this.eventNamesFromParameter(declaration, seen))
|
|
}
|
|
}
|
|
return events
|
|
}
|
|
|
|
/** Follow a non-exported local helper parameter back to every resolved call site. */
|
|
private eventNamesFromParameter(parameter: ts.ParameterDeclaration, seen: Set<ts.Node>): Set<string> {
|
|
const owner = parameter.parent
|
|
if (!ts.isFunctionDeclaration(owner) || hasExportModifier(owner)) return new Set()
|
|
const index = owner.parameters.indexOf(parameter)
|
|
if (index < 0) return new Set()
|
|
const events = new Set<string>()
|
|
for (const call of this.callSitesFor(owner)) {
|
|
const argument = call.arguments[index]
|
|
if (argument) addAll(events, this.eventNamesFromArgumentList(argument, new Set(seen)))
|
|
}
|
|
return events
|
|
}
|
|
|
|
/** Return a finite string-literal value set, rejecting widened and generic strings. */
|
|
private finiteStringValues(expression: ts.Expression): Set<string> | undefined {
|
|
const current = unwrapExpression(expression)
|
|
if (ts.isStringLiteralLike(current)) return new Set([current.text])
|
|
if (this.isForwardedAgentEventParameter(current)) return undefined
|
|
return finiteStringTypeValues(this.project.checker.getTypeAtLocation(current))
|
|
}
|
|
|
|
/** Reject the contextual parameter inside the AgentEventDispatch forwarding object. */
|
|
private isForwardedAgentEventParameter(expression: ts.Expression): boolean {
|
|
if (!ts.isIdentifier(expression)) return false
|
|
const declarations = this.project.checker.getSymbolAtLocation(expression)?.declarations ?? []
|
|
return declarations.some((declaration) => {
|
|
if (!ts.isParameter(declaration)) return false
|
|
const method = declaration.parent
|
|
if (!ts.isMethodDeclaration(method) || !ts.isObjectLiteralExpression(method.parent)) return false
|
|
const contextualType = this.project.checker.getContextualType(method.parent)
|
|
return contextualType !== undefined
|
|
&& this.project.checker.isTypeAssignableTo(contextualType, this.agentDispatchType)
|
|
})
|
|
}
|
|
|
|
/** Get or create one relation row. */
|
|
private ensure(event: string): EventRelation {
|
|
const existing = this.relations.get(event)
|
|
if (existing) return existing
|
|
const relation = { dispatchers: new Map<string, Set<string>>(), listeners: new Set<string>() }
|
|
this.relations.set(event, relation)
|
|
return relation
|
|
}
|
|
|
|
/** Add one dispatcher method without duplicating package/method labels. */
|
|
private addDispatcher(event: string, pkg: string, method: string): void {
|
|
const relation = this.ensure(event)
|
|
const methods = relation.dispatchers.get(pkg) ?? new Set<string>()
|
|
methods.add(method)
|
|
relation.dispatchers.set(pkg, methods)
|
|
}
|
|
}
|
|
|
|
/** Return whether an identifier is the callee of a call, seen through value-preserving wrappers. */
|
|
function isDirectCallee(identifier: ts.Identifier): boolean {
|
|
let current: ts.Node = identifier
|
|
while (
|
|
ts.isParenthesizedExpression(current.parent)
|
|
|| ts.isAsExpression(current.parent)
|
|
|| ts.isTypeAssertionExpression(current.parent)
|
|
|| ts.isNonNullExpression(current.parent)
|
|
|| ts.isSatisfiesExpression(current.parent)
|
|
) {
|
|
current = current.parent
|
|
}
|
|
return ts.isCallExpression(current.parent) && current.parent.expression === current
|
|
}
|
|
|
|
/** Peel syntax-only wrappers that do not change an expression's runtime value. */
|
|
function unwrapExpression(expression: ts.Expression): ts.Expression {
|
|
let current = expression
|
|
while (
|
|
ts.isParenthesizedExpression(current)
|
|
|| ts.isAsExpression(current)
|
|
|| ts.isTypeAssertionExpression(current)
|
|
|| ts.isNonNullExpression(current)
|
|
|| ts.isSatisfiesExpression(current)
|
|
) {
|
|
current = current.expression
|
|
}
|
|
return current
|
|
}
|
|
|
|
/** Return every value only when a type is a closed string-literal union. */
|
|
function finiteStringTypeValues(type: ts.Type): Set<string> | undefined {
|
|
if (type.flags & ts.TypeFlags.StringLiteral) {
|
|
return new Set([(type as ts.StringLiteralType).value])
|
|
}
|
|
if (type.flags & ts.TypeFlags.Never) return new Set()
|
|
if (!type.isUnion()) return undefined
|
|
const values = new Set<string>()
|
|
for (const member of type.types) {
|
|
const memberValues = finiteStringTypeValues(member)
|
|
if (!memberValues) return undefined
|
|
addAll(values, memberValues)
|
|
}
|
|
return values
|
|
}
|
|
|
|
/** Return whether a variable declaration belongs to a const declaration list. */
|
|
function isConstDeclaration(declaration: ts.VariableDeclaration): boolean {
|
|
return (declaration.parent.flags & ts.NodeFlags.Const) !== 0
|
|
}
|
|
|
|
/** Return whether a declaration is visible to callers outside its source module. */
|
|
function hasExportModifier(node: ts.Node): boolean {
|
|
return ts.canHaveModifiers(node) && (ts.getModifiers(node)?.some((modifier) => {
|
|
return modifier.kind === ts.SyntaxKind.ExportKeyword || modifier.kind === ts.SyntaxKind.DefaultKeyword
|
|
}) ?? false)
|
|
}
|
|
|
|
/** Add every member of source to target. */
|
|
function addAll<T>(target: Set<T>, source: ReadonlySet<T>): void {
|
|
for (const value of source) target.add(value)
|
|
}
|
|
|
|
/** Return the union of two sets without mutating either input. */
|
|
function unionSets<T>(left: ReadonlySet<T>, right: ReadonlySet<T>): Set<T> {
|
|
const out = new Set(left)
|
|
addAll(out, right)
|
|
return out
|
|
}
|
|
|
|
/**
|
|
* Select the package source files of one project in deterministic order.
|
|
* @param project - the loaded repository TypeScript project.
|
|
* @returns `packages/<group>/<pkg>/src` files tagged with their package name.
|
|
*/
|
|
export function collectPackageSources(project: TypeScriptProject): PackageSource[] {
|
|
return project.sourceFiles().flatMap((sourceFile): PackageSource[] => {
|
|
const rel = project.relativePath(sourceFile)
|
|
const match = /^packages\/[^/]+\/([^/]+)\/src\/.+\.ts$/.exec(rel)
|
|
return match?.[1] ? [{ rel, pkg: match[1], sourceFile }] : []
|
|
}).sort((left, right) => left.rel.localeCompare(right.rel))
|
|
}
|
|
|
|
function collectEventRelations(): Map<string, EventRelation> {
|
|
const project = new TypeScriptProject(root)
|
|
return new EventRelationCollector(project, collectPackageSources(project)).collect()
|
|
}
|
|
|
|
function relationPackages(map: Map<string, Set<string>>, pkgsByShort: Map<string, Pkg>): string {
|
|
if (map.size === 0) return '-'
|
|
return [...map.entries()]
|
|
.sort(([a], [b]) => a.localeCompare(b))
|
|
.map(([pkg, methods]) => `${pkgLink(pkgsByShort.get(pkg), pkg)} (${[...methods].sort().map(m => `\`${m}\``).join(', ')})`)
|
|
.join(', ')
|
|
}
|
|
|
|
function listenerPackages(listeners: Set<string>, pkgsByShort: Map<string, Pkg>): string {
|
|
if (listeners.size === 0) return '-'
|
|
return [...listeners].sort().map(pkg => pkgLink(pkgsByShort.get(pkg), pkg)).join(', ')
|
|
}
|
|
|
|
function renderEventRelations(pkgs: Pkg[], events: readonly EventEntry[]): string {
|
|
const relations = collectEventRelations()
|
|
const pkgsByShort = new Map(pkgs.map(pkg => [pkg.short, pkg]))
|
|
const maintenance = 'generated: Cordis event declarations and producer/listener edges are resolved from the repository TypeScript Program'
|
|
const lines = generatedHeader('Event Producer And Consumer Matrix')
|
|
lines.push(
|
|
'This matrix shows which packages dispatch each harness-owned event and which packages listen to it. It is intentionally a table rather than one large graph: events are many-to-many, and dense relation data is easier to review in rows. Receiver and event-name types also cover contained dispatch sites that deliberately bypass `ctx.emit`, such as subagent lifecycle containment.',
|
|
'',
|
|
'| Event | Mode | Declared in | Dispatchers | Listeners |',
|
|
'| --- | --- | --- | --- | --- |',
|
|
)
|
|
for (const event of [...events].sort((a, b) => a.name.localeCompare(b.name))) {
|
|
const relation = relations.get(event.name) ?? { dispatchers: new Map<string, Set<string>>(), listeners: new Set<string>() }
|
|
lines.push(`| \`${event.name}\` | \`${event.mode}\` | ${sourceLink(event.source)} | ${relationPackages(relation.dispatchers, pkgsByShort)} | ${listenerPackages(relation.listeners, pkgsByShort)} |`)
|
|
}
|
|
// Every declared event needs a dispatcher: zero means dead vocabulary or an
|
|
// unrecognized semantic dispatch shape. Listener-free extension points remain
|
|
// valid. Client-declared events are exempt: the relation scan seeds the HOST
|
|
// aggregate program only (host+client cannot share one program — the cordis
|
|
// Context merges collide), so client dispatch sites are structurally
|
|
// invisible here; their rows stay in the table for the declarations' sake.
|
|
const undispatched = [...events]
|
|
.filter(event => !event.source.startsWith('packages/client/'))
|
|
.filter(event => (relations.get(event.name)?.dispatchers.size ?? 0) === 0)
|
|
.map(event => event.name)
|
|
.sort()
|
|
if (undispatched.length > 0) {
|
|
throw new Error(
|
|
`event-producer-consumer matrix: no dispatcher found for declared event${undispatched.length > 1 ? 's' : ''} `
|
|
+ `${undispatched.map(name => `"${name}"`).join(', ')} — dead vocabulary, or a dispatch shape the semantic scan misses `
|
|
+ '(teach scripts/gen-doc-graphs.ts the shape)',
|
|
)
|
|
}
|
|
const declared = new Set(events.map(event => event.name))
|
|
const extra = [...relations.keys()].filter(event => !declared.has(event)).sort()
|
|
if (extra.length > 0) {
|
|
lines.push('', '## Non-harness or undeclared event strings seen in package source', '', '| Event string | Dispatchers | Listeners |', '| --- | --- | --- |')
|
|
for (const event of extra) {
|
|
const relation = relations.get(event)
|
|
if (!relation) continue
|
|
lines.push(`| \`${event}\` | ${relationPackages(relation.dispatchers, pkgsByShort)} | ${listenerPackages(relation.listeners, pkgsByShort)} |`)
|
|
}
|
|
}
|
|
lines.push('', ...maintenanceFooter(maintenance))
|
|
return lines.join('\n')
|
|
}
|
|
|
|
function renderLifecycle(): string {
|
|
const maintenance = 'curated Mermaid sequence; exact event signatures live in the generated Cordis catalog'
|
|
return [
|
|
...generatedHeader('Agent Turn And Step Lifecycle'),
|
|
'This sequence is the visual companion to [architecture.md](architecture.md#loop-lifecycle-session--turn--step). It keeps durable replay facts on `session/event` and live control/status on `agent/*`.',
|
|
'',
|
|
'```mermaid',
|
|
'sequenceDiagram',
|
|
' participant User',
|
|
' participant Agent',
|
|
' participant Driver',
|
|
' participant Hooks as hook listeners',
|
|
' participant Prompt as ctx.systemPrompt',
|
|
' participant LLM as ctx.llm',
|
|
' participant Tools as ctx.tools',
|
|
' participant Session',
|
|
' participant SDK as UI or SDK listener',
|
|
' User->>Agent: followup(content)',
|
|
` Agent-->>SDK: ${mermaidCode('agent/inbox/enqueue')}`,
|
|
' Agent->>Driver: queued work wakes driver',
|
|
` Driver-->>SDK: ${mermaidCode('agent/status')} running`,
|
|
' Note over Agent,Driver: next-step acceptance window opens',
|
|
` Driver->>Hooks: ${mermaidCode('agent/prompt-submit')} waterfall`,
|
|
' Hooks-->>Driver: authoritative allow, block, or add context',
|
|
' alt prompt blocked or admission failed',
|
|
' Driver-->>Driver: append context-only batch or keep steering boundary pending',
|
|
' else prompt allowed',
|
|
` Driver->>Session: ${mermaidCode('turn/start')}`,
|
|
` Driver->>Session: ${mermaidCode('user/message')}`,
|
|
` Driver->>Prompt: ${mermaidCode('system-prompt/assemble')} waterfall`,
|
|
` Driver-->>Driver: ${mermaidCode('agent/step')} serial checkpoint`,
|
|
` Driver->>Session: ${mermaidCode('step/start')}`,
|
|
` Driver->>LLM: ${mermaidCode('agent/request')} waterfall, then ${mermaidCode('llm/stream')} waterfall`,
|
|
' LLM-->>Driver: StreamChunk*',
|
|
` Driver->>Session: ${mermaidCode('assistant/chunk')}*`,
|
|
` Session-->>SDK: ${mermaidCode('session/event')} ${mermaidCode('assistant/chunk')}*`,
|
|
' alt final adapter or terminal in-band request failure',
|
|
` Driver->>Session: ${mermaidCode('step/end')}`,
|
|
` Driver->>Hooks: ${mermaidCode('agent/request-error')} waterfall`,
|
|
' Hooks-->>Driver: return retry action or preserve the original error',
|
|
' else model request succeeded',
|
|
` Driver->>Session: ${mermaidCode('assistant/message')}`,
|
|
' Driver->>Tools: classify pending call by executionMode',
|
|
' loop barriers and bounded rolling pool, reclassify before start',
|
|
' opt call starts',
|
|
` Driver->>Session: ${mermaidCode('tool/call')}`,
|
|
' Driver->>Tools: ordered pre, concurrent execute',
|
|
' Tools-->>Session: tool-owned events when applicable',
|
|
' end',
|
|
' opt next model-order result ready',
|
|
' Driver->>Tools: ordered post',
|
|
` Driver->>Session: ${mermaidCode('tool/result')}`,
|
|
' end',
|
|
' end',
|
|
' Driver->>Session: post-tool context and steering (no prompt-submit)',
|
|
` Driver->>Session: ${mermaidCode('step/end')}`,
|
|
` Driver->>Hooks: ${mermaidCode('agent/turn-stopping')} serial terminal checkpoint`,
|
|
' end',
|
|
' Note over Agent,Driver: next-step acceptance window closes',
|
|
` Driver->>Session: ${mermaidCode('turn/end')}`,
|
|
' end',
|
|
` Driver-->>SDK: ${mermaidCode('agent/status')} idle`,
|
|
'```',
|
|
'',
|
|
'The `assistant/message` edge records every successful provider call, including content-less and `max-tokens` finishes. Empty content stays out of derived history while the durable anchor retains usage and exact chunk provenance, including an explicit empty source set.',
|
|
'',
|
|
'`dsh-compact-basic` uses `agent/step` for pressure before request derivation and `agent/request-error` only for canonical context overflow. Once either trigger qualifies, optional tool-result pruning runs before summary selection. Recovery works between the closed failed step and failed turn close, and opens a fresh retry turn only when pruning or summarization advances the surface replacement generation; otherwise the original request error remains authoritative.',
|
|
'',
|
|
'The returned `agent/prompt-submit` allow is authoritative; listeners wrapping `next()` preserve downstream content and additional contexts unless replacement is intentional. Steering bypasses that waterfall and joins at its durable checkpoint.',
|
|
'',
|
|
'SDK users that need replayable transcript data should consume `session/event`; `agent/*` is the live coordination surface for queue/status, prompt interception, request shaping, steering, continuation, and errors.',
|
|
'',
|
|
...maintenanceFooter(maintenance),
|
|
].join('\n')
|
|
}
|
|
|
|
function renderToolPipeline(): string {
|
|
const maintenance = 'curated Mermaid flow; exact tool schemas and event signatures live in generated catalogs'
|
|
return [
|
|
...generatedHeader('Tool Execution Pipeline'),
|
|
'This graph shows where policy, hooks, sandboxing, filesystem guards, result rewriting, final-outcome observation, and UI rendering fit without changing the loop. The transformable extension points are the `tools/pre-execute`, `tools/execute`, and `tools/post-execute` waterfalls; monotonic guards, definition-owned `finalizeContent`, and `tools/result` are the owner-enforced boundaries around them.',
|
|
'',
|
|
'```mermaid',
|
|
'flowchart TD',
|
|
' model["Assistant message contains tool-call block"]',
|
|
` toolCall["Session event: ${mermaidCode('tool/call')}<br/>logged before execution"]`,
|
|
' presentCall["UI pending card<br/>presentCall(args)"]',
|
|
` pre["${mermaidCode('tools/pre-execute')} waterfall<br/>hooks, permission, sandbox"]`,
|
|
' guards["Registered monotonic guards<br/>deny or abstain; identity protected"]',
|
|
' denied["denied or approval refused<br/>tool body skipped"]',
|
|
` approval["${mermaidCode('ctx.approval')} one-shot prompt<br/>absent or unanswerable: deny"]`,
|
|
` around["${mermaidCode('tools/execute')} waterfall<br/>timeout, retry, metrics (around dispatch)"]`,
|
|
' toolBody["Registered tool execute() body"]',
|
|
` fsGate["${mermaidCode('fs/write-intent')} or ${mermaidCode('fs/edit-intent')}<br/>tool-fs mutations only"]`,
|
|
` owned["Tool-owned session events<br/>${mermaidCode('todo/write')}, ${mermaidCode('fs/observed')}, ${mermaidCode('hook/invoked')}, ${mermaidCode('hook/result')}, ${mermaidCode('tool/code-dispatch')}"]`,
|
|
` post["${mermaidCode('tools/post-execute')} waterfall<br/>accept, block, replace, add context"]`,
|
|
' normalized["Registry outer normalization<br/>pipeline/result snapshot throws become isError"]',
|
|
' finalize["ToolDefinition.finalizeContent<br/>last content-only invariant"]',
|
|
` final["${mermaidCode('tools/result')} synchronous notification<br/>frozen authoritative outcome"]`,
|
|
' context["Active-batch additionalContexts FIFO<br/>injected user/message after recorded tool results"]',
|
|
` toolResult["Session event: ${mermaidCode('tool/result')}<br/>single model-facing outcome"]`,
|
|
' allResults["Tool batch settled<br/>recorded tool/result events complete"]',
|
|
' presentResult["UI completed card<br/>presentResult(args, result)"]',
|
|
' model --> toolCall',
|
|
' toolCall --> presentCall',
|
|
' toolCall --> pre',
|
|
' pre -->|allow| guards',
|
|
' guards -->|allow| around',
|
|
' guards -->|deny| denied',
|
|
' guards -.->|throw| normalized',
|
|
' around --> toolBody',
|
|
' pre -->|deny| denied',
|
|
' pre -->|ask| approval',
|
|
' approval -->|allowed-once| guards',
|
|
' approval -->|rejected, cancelled, unavailable| denied',
|
|
' approval -.->|throw| normalized',
|
|
' denied --> post',
|
|
' pre -.->|throw| normalized',
|
|
' toolBody --> fsGate',
|
|
' fsGate --> toolBody',
|
|
' toolBody --> owned',
|
|
' toolBody --> around',
|
|
' around --> post',
|
|
' around -.->|wrapper throws| normalized',
|
|
' post -.->|throw| normalized',
|
|
' post --> finalize',
|
|
' normalized --> finalize',
|
|
' finalize --> final',
|
|
' final --> toolResult',
|
|
' toolResult --> presentResult',
|
|
' toolResult --> allResults',
|
|
' allResults --> context',
|
|
'```',
|
|
'',
|
|
'Filesystem read-before-edit checks stay below `tool-fs` on `fs/*` events. Generic pre/post waterfalls host hooks and approval policy; `ctx.approval` resolves asks before monotonic guards, and owner policy that must not be reordered remains a registered guard. Around-dispatch concerns such as timeouts wrap `tools/execute`. The registry losslessly snapshots the candidate result and normalizes a snapshot failure before the visible definition\'s snapshotted `finalizeContent` callback enforces its synchronous content-only invariant. `tools/result` then observes the immutable, lossless-JSON outcome. This lets hooks span tool families without coupling the tools to one policy service. Code Mode sends both the reserved `run_code` transport and its serialized sub-calls through the pipeline; sub-calls carry the parent token, log `tool/code-dispatch`, surface denials as binding rejections, and omit `additionalContexts` to preserve call/result adjacency.',
|
|
'',
|
|
...maintenanceFooter(maintenance),
|
|
].join('\n')
|
|
}
|
|
|
|
function renderDocs(): GraphDoc[] {
|
|
const pkgs = collectPackageGraph(root, GROUP_ORDER, 'gen-doc-graphs')
|
|
const { model } = projectCordisCatalog(root, CORDIS_CATALOG_POLICY)
|
|
const docs: GraphDoc[] = [
|
|
{ rel: 'docs/capability-seams.md', content: renderCapabilitySeams(pkgs, model.services) },
|
|
...APP_EXAMPLES.map(example => ({ rel: example.rel, content: renderAppComposition(example) })),
|
|
{ rel: 'docs/event-producer-consumer.md', content: renderEventRelations(pkgs, model.events) },
|
|
{ rel: 'docs/agent-lifecycle.md', content: renderLifecycle() },
|
|
{ rel: 'docs/tool-execution-pipeline.md', content: renderToolPipeline() },
|
|
]
|
|
docs.unshift({ rel: 'docs/graph-atlas.md', content: renderIndex(docs) })
|
|
return docs
|
|
}
|
|
|
|
function renderIndex(docs: GraphDoc[]): string {
|
|
const labels: Record<string, string> = {
|
|
'docs/capability-seams.md': 'capability seams and core services',
|
|
'apps/cli/composition.md': 'dsh shared base composition',
|
|
'examples/headless-agent/composition.md': 'headless-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',
|
|
'docs/tool-execution-pipeline.md': 'tool execution pipeline',
|
|
}
|
|
const modes: Record<string, string> = {
|
|
'docs/capability-seams.md': 'hybrid generated',
|
|
'apps/cli/composition.md': 'hybrid generated',
|
|
'examples/headless-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',
|
|
'docs/tool-execution-pipeline.md': 'curated',
|
|
}
|
|
const rows = [
|
|
'| [module dependency graph](module-graph.md) | `generated` |',
|
|
'| [tool schema catalog and package map](tool-catalog.md) | `generated` |',
|
|
...docs.map((doc) => {
|
|
const link = graphIndexLink(doc.rel)
|
|
return `| [${labels[doc.rel] ?? link}](${link}) | \`${modes[doc.rel] ?? 'generated'}\` |`
|
|
}),
|
|
]
|
|
const maintenance = 'mixed: each linked page declares generated, hybrid, or curated mode'
|
|
return [
|
|
...generatedHeader('Documentation Graph Index'),
|
|
'These diagrams are the relationship layer above the generated catalogs. Use them to navigate package topology, capability seams, event flow, model-facing tools, app composition, and runtime lifecycle paths. Exact signatures and type shapes still live in the generated [events](cordis-catalog/events.md) / [services](cordis-catalog/services.md) catalogs, [tool-catalog.md](tool-catalog.md), and [core-data-structures/](core-data-structures/core.md).',
|
|
'',
|
|
'The process decision behind this index is recorded in [the documentation graph Agent Note](../.agents/notes/archived/process/2026-07-03-documentation-graph-atlas.md).',
|
|
'',
|
|
'| Graph | Mode |',
|
|
'| --- | --- |',
|
|
...rows,
|
|
'',
|
|
'Regenerate with `pnpm run gen-doc-graphs`; verify freshness with `pnpm run verify-doc-graphs`.',
|
|
'',
|
|
...maintenanceFooter(maintenance),
|
|
].join('\n')
|
|
}
|
|
|
|
function main(): void {
|
|
const docs = renderDocs()
|
|
if (process.argv.includes('--check')) {
|
|
const stale: string[] = []
|
|
for (const doc of docs) {
|
|
const abs = resolve(root, doc.rel)
|
|
const committed = existsSync(abs) ? readFileSync(abs, 'utf8') : null
|
|
if (committed !== doc.content) stale.push(doc.rel)
|
|
}
|
|
if (stale.length === 0) {
|
|
console.log(`gen-doc-graphs: ${docs.length} graph doc(s) are up to date.`)
|
|
return
|
|
}
|
|
console.error(`gen-doc-graphs: stale graph doc(s): ${stale.join(', ')}. Run \`pnpm run gen-doc-graphs\` and commit the result.`)
|
|
process.exit(1)
|
|
}
|
|
|
|
for (const doc of docs) {
|
|
mkdirSync(dirname(resolve(root, doc.rel)), { recursive: true })
|
|
writeFileSync(resolve(root, doc.rel), doc.content)
|
|
}
|
|
console.log(`gen-doc-graphs: wrote ${docs.length} graph doc(s).`)
|
|
}
|
|
|
|
if (process.argv[1] && import.meta.filename === resolve(process.argv[1])) {
|
|
main()
|
|
}
|