CONFIGURATION.md

Configuration reference

All keys are optional. Defaults are resolved by the plugin's Schemastery config before the service starts.

Key	Default	Purpose
projectDirectory	.dsh/workflows	Project capsule/trusted-local catalog, relative to session cwd.
personalDirectory	workflows	Personal catalog, relative to $DSH_HOME (or ~/.dsh).
runDirectory	.dsh/workflow-runs	Per-project durable run store. Absolute paths are additionally partitioned by cwd hash.
listToolName	workflow_list	Model-facing discovery tool name.
runToolName	run_workflow	Model-facing execution/authoring tool name.
manageToolName	workflow_manage	Model-facing lifecycle tool name.
maxCapsuleBytes	512000	Per workflow file admission limit.
maxCatalogEntries	200	Maximum catalog rows returned to callers.
maxAgents	64	Deployment ceiling per run. A manifest may select a lower cap.
maxConcurrency	8	Deployment concurrent-child ceiling shared across every project and run in this plugin instance.
maxResultChars	50000	Durable/rendered result-summary limit; full JSON result remains in run.json.
scriptSyncTimeoutMs	10000	VM synchronous slice limit.
scriptWallTimeoutMs	3600000	Whole restricted-script wall-clock limit.
defaultProvider	spawn	Fallback DSH subagent provider.
synthesisProvider	spawn	DSH subagent transport selected by wf.synthesize.
fastProvider/ModelProvider/Model/MaxTokens	spawn / unset / unset / 4096	Fast tier: subagent transport plus optional DSH LLM provider/model route.
balancedProvider/ModelProvider/Model/MaxTokens	spawn / unset / unset / 8192	Balanced/default tier: subagent transport plus optional DSH LLM provider/model route.
deepProvider/ModelProvider/Model/MaxTokens	spawn / unset / unset / 16384	Deep tier: subagent transport plus optional DSH LLM provider/model route.
readOnlyAllowedTools	read, read_image, glob, grep, lsp, skill, web_search	Trusted read-only candidates. Each child receives only names also visible in its parent's live DSH catalog.
readOnlyDeniedTools	[]	Deprecated extra subtraction from the allow-list; never forwarded as an unvalidated deny-list.
approvalMode	generated-and-local	never, generated/trusted-local only, or always.
availableTools	[]	Deployment capability inventory used by capsule preflight.
availableMcp	[]	Available MCP server inventory used by preflight.
availableSkills	[]	Available skill inventory used by preflight.
maxRetainedRuns	500	Newest terminal runs retained automatically. Live runs are never pruned.

Example:

- id: dsh-external-workflow
  name: '@dsh-external/workflow'
  config:
    approvalMode: generated-and-local
    maxAgents: 32
    maxConcurrency: 6
    availableTools: [read, search]
    availableMcp: [github]
    availableSkills: [code-review]
    fastProvider: spawn
    fastModelProvider: deepseek-official
    fastModel: fast-model
    deepProvider: spawn
    deepModelProvider: deepseek-official
    deepModel: reasoning-model

fastProvider/balancedProvider/deepProvider name a provider registered on ctx.subagents (for example spawn, fork, acp). The corresponding *ModelProvider values name DSH LLM provider routes passed in AgentOptions. They are deliberately separate; a subagent transport name is never sent to the model router.

Deployment adapters

Register these before the first workflow operation in a project context:

ctx.dynamicWorkflows.registerIsolationAdapter({
  name: 'deployment-worktree',
  async prepare({ runId, taskId, cwd, parent }) {
    // Create a contained worktree and a DSH parent Agent whose cwd points at it.
    return { cwd: isolatedCwd, parent: isolatedParent, async dispose() { /* cleanup */ } }
  },
})

ctx.dynamicWorkflows.registerVerificationAdapter({
  async preflight(cwd, policy) { /* capture an authoritative workspace baseline */ return { ok: true, reasons: [] } },
  async verify(cwd, task, result) { /* add git/diff evidence */ return { ok: true, reasons: [], changedPaths: [] } },
})

ctx.dynamicWorkflows.registerDispatchAdapter({
  async start({ target, effort, provider, request, subagents }) {
    // Route target/effort through a deployment-specific continuable-agent or model seam.
    const run = await deploymentDispatch({ target, effort, provider, request, subagents })
    return {
      run,
      telemetry: {
        provider: 'resolved-provider', model: 'resolved-model', resolvedEffort: effort,
        // Optional measured usage, fallbackReason, iterations, and durationMs belong here.
      },
    }
  },
})

Adapters are single registrations because isolation and verification are policy authorities. Registration after an engine has started is rejected to prevent different runs in one project from receiving different semantics.

Dispatch adapters may return a bare SubagentRun or { run, telemetry }. The latter is the authority for final provider/model/effort, fallback and remote usage facts; the plugin never fabricates unknown remote token counts.

Budget semantics

For a token-budgeted workflow, every possible model tier needs maxTokens. Before a child starts, its allocation is reserved atomically against the run budget. Local DSH children reconcile the reservation from Session usage; remote providers without local usage are conservatively charged the allocation.