18fe174897
A preset is a directory holding one `agent.cordis.yml`. Mounting it under an agent's scope context during `setup(agentCtx)` gives that one session its own tools and prompt sections while every other live session keeps its own. No registry gains a tier. `dsh-tools` and `dsh-system-prompt` already file registrations into the calling context's scope layer, and entry contexts chain to the context a subtree was plugged into, so a composition mounted under `agent.ctx` is that agent's alone and unwinds with it. The mount audits itself because a directly-plugged subtree is absent from `ctx.loader.entries()` and no boot audit covers it. It rejects an unscoped target, a row that never became usable, and a row that published a service into the root service realm — that last one is process-global rather than per-session, and its collision with the next session surfaces as an unhandled rejection `setup` never observes, leaving a half-composed agent that looks healthy. The package invariant re-checks that rule on every service notification, since a row publishing from a timer would escape a one-shot audit. Raises the `packages/README.md` word ceiling from 920 to 980: the group table must enumerate every group, and the new `preset/` row is necessary content. Design: .agents/notes/implemented/architecture/2026-08-03-per-session-agent-presets.md
76 lines
2.7 KiB
TypeScript
76 lines
2.7 KiB
TypeScript
/**
|
|
* Filesystem discovery of agent presets. A preset is a directory holding
|
|
* {@link COMPOSITION_FILE}; the directory name is the preset id. Discovery
|
|
* re-reads the roots on every call so a preset authored while the process is
|
|
* running is visible without a restart.
|
|
* @module @deepseek-ai/dsh-agent-presets/discovery
|
|
*/
|
|
|
|
import { readdir, stat } from 'node:fs/promises'
|
|
import { join, resolve } from 'node:path'
|
|
import { expandHomePath } from '@deepseek-ai/dsh-paths'
|
|
import type { AgentPreset, PresetRoot } from './types.ts'
|
|
|
|
/** The composition file that makes a directory a preset. */
|
|
export const COMPOSITION_FILE = 'agent.cordis.yml'
|
|
|
|
/**
|
|
* Whether `path` names an existing regular file.
|
|
* @param path - absolute path to test.
|
|
* @returns true when the path resolves to a file.
|
|
*/
|
|
async function isFile(path: string): Promise<boolean> {
|
|
try {
|
|
return (await stat(path)).isFile()
|
|
} catch {
|
|
// Any stat failure — absent, unreadable, a dangling link — means this
|
|
// directory does not present a composition, which is not an error: the
|
|
// directory simply is not a preset.
|
|
return false
|
|
}
|
|
}
|
|
|
|
/**
|
|
* Scan one root for preset directories.
|
|
*
|
|
* An absent root yields no presets rather than throwing: the user root does
|
|
* not exist until the first locally authored preset, and naming a default
|
|
* that no root supplies already fails loud at resolution.
|
|
* @param root - the directory and the trust its presets inherit.
|
|
* @returns the root's presets ordered by id.
|
|
*/
|
|
export async function scanRoot(root: PresetRoot): Promise<AgentPreset[]> {
|
|
const dir = resolve(expandHomePath(root.path))
|
|
let children
|
|
try {
|
|
children = await readdir(dir, { withFileTypes: true })
|
|
} catch (error) {
|
|
if ((error as NodeJS.ErrnoException).code === 'ENOENT') return []
|
|
throw new Error(`agent-presets: cannot read preset root ${dir}: ${String(error)}`, { cause: error })
|
|
}
|
|
const found: AgentPreset[] = []
|
|
for (const child of children) {
|
|
if (!child.isDirectory()) continue
|
|
const path = join(dir, child.name, COMPOSITION_FILE)
|
|
if (!await isFile(path)) continue
|
|
found.push({ id: child.name, trust: root.trust, path })
|
|
}
|
|
return found.sort((left, right) => left.id.localeCompare(right.id))
|
|
}
|
|
|
|
/**
|
|
* Scan every root in precedence order.
|
|
* @param roots - roots in precedence order; an earlier root wins a duplicate id.
|
|
* @returns every discovered preset, first-root-wins per id.
|
|
*/
|
|
export async function discoverPresets(roots: readonly PresetRoot[]): Promise<AgentPreset[]> {
|
|
const byId = new Map<string, AgentPreset>()
|
|
for (const root of roots) {
|
|
for (const preset of await scanRoot(root)) {
|
|
if (byId.has(preset.id)) continue
|
|
byId.set(preset.id, preset)
|
|
}
|
|
}
|
|
return [...byId.values()]
|
|
}
|