dsh-graph-runtime

English | 中文

Graph runtime capabilities for the DeepSeek Harness (DSH), published as a standalone Cordis plugin/bundle.

Current capabilities:

• Graph definition and auto-mounting: define an "extended StateGraph" with defineGraph — a graph factory plus a registration declaration (whether it becomes a DSH tool, whether it joins the registry) plus a tool-argument validation hook. Loading the module completes registration: at plugin startup the already-defined graphs auto-mount, and later definitions mount immediately; developers make no service calls at all. Tool name/description are auto-discovered (compile({ name, description }) or structural synthesis), compilation is lazy and memoized (the registration path has zero compile side effects), and parameter validation, cancellation forwarding, and result rendering are all owned by this plugin.
• GraphRoutingAgent: a graph-driven routing agent. It hands the graphTools registry (optionally filtered) to the LLM and requires a tool to be chosen; the returned tool call goes through existence, JSON, schema, and author validate checks, retrying with the rejection reason on failure (default 3, configurable); once it passes, the corresponding graph executes. Every chosen-tool execution is wrapped by the graphTools/pre-execute / graphTools/post-execute waterfall extension points (gating, auditing, result transforms).

Installation and wiring

# After publishing
npm install dsh-graph-runtime
# Or from a local path (e.g. inside the yolo-agent repo)
npm install file:../dsh-graph-runtime

Wiring follows the same steps as any other DSH bundle, either or both:

• Add one entry to the root composition cordis.yml (this package ships its own cordis.patch.yml; adding the package name to the web profile's dsh.profile.bundles auto-mounts it the same way):

  - id: graph-runtime
    name: dsh-graph-runtime
  

Usage

Graph authors only need defineGraph — defining is registering; no mount or service call is required:

// graphs/echo.ts
import { defineGraph } from 'dsh-graph-runtime'
import { Annotation, END, START, StateGraph } from '@langchain/langgraph'

const State = Annotation.Root({
  topic: Annotation<string>,
  log: Annotation<string[]>({
    reducer: (left, right) => [...left, ...right],
    default: () => [],
  }),
})

export const echoGraph = defineGraph({
  name: 'echo_graph',
  description: 'Echo the given topic.',
  build: () =>
    new StateGraph(State)
      .addNode('echo', async (state) => ({ log: [`seen:${state.topic}`] }))
      .addEdge(START, 'echo')
      .addEdge('echo', END),
  asTool: true, // Declared as a model-visible DSH tool; default false
  // asGraphTool: true, // Also listed in the graphTools registry for discovery; default true, can be omitted
  // validate: (input) => Boolean((input as { topic?: string }).topic), // Argument-validation hook; defaults to always passing
})

The only wiring requirement: a graph module must be imported by some bundle entry (a single barrel line import './graphs' suffices). At plugin apply, every already-defined graph auto-mounts, and later definitions mount immediately; a single graph failing to mount (duplicate name, invalid declaration) warns and is skipped without blocking startup.

Tools declared asTool: true register at the plugin's global layer: visible to every agent (including the default agent). For scope-private or runtime-constructed cases, use the imperative entries below.

GraphRoutingAgent

Trimmed from dsh's ReactLoopAgent to a single routing step: one routing round = the LLM picks a tool → validation → (optional retry) → the graph executes.

import { GraphRoutingAgent } from 'dsh-graph-runtime'

const router = new GraphRoutingAgent(ctx, {
  provider: 'deepseek',
  model: 'deepseek-chat',
  filter: { allow: ['echo_graph', 'search_graph'] }, // allow/deny, same as tools.restrict
  maxRetries: 3, // Maximum LLM re-calls after a failed validation; default 3
  // fallback: myFallbackTool, // Optional: overrides the built-in fallback tool
})

const outcome = await router.route({ input: 'echo hello for me' })
// outcome: { tool: 'echo_graph', args: {...}, result: <the graph's final state> }

Behavior details:

• A tool must be chosen: dsh-llm's GenerateOptions has no toolChoice field, so the "required" semantics are enforced by the loop — when the model picks no tool (a plain-text reply) there is no retry; the fallback tool runs instead and the outcome is marked fallback: true. The default fallback is the built-in graph_routing_fallback (a no-op: empty input, returns {}); override it through fallback with a ToolDefinition or a GraphDefinition, and the overrider is responsible for keeping empty input {} valid under its schema (e.g. parameters: {}).
• The validation chain (any failure retries with the reason): the tool exists in the (filtered) registry; the arguments are valid JSON; execution-time schema validation (ToolArgsError); the author's validate hook (GraphValidationError, with context.request available during routing for semantic rejection). A graph's own runtime failure is not a routing failure and propagates as-is.
• Filtering: filter follows the same allow/deny semantics as tools.restrict (both may be given; they intersect); a list naming unknown tools or an empty result after filtering is a configuration error.
• Exhausted retries end with the last failure reason.

Routing extension points

Routed executions do not pass through dsh's ctx.tools pipeline (the registry there is a separate surface), so the pipeline-shaped extension points live on the routing loop itself as cordis waterfall events: every chosen-tool attempt traverses graphTools/pre-execute before the graph runs and graphTools/post-execute after it settles. Audit logging, metrics, policy gating, and result transforms all hang off them:

// Gate before execution: a deny feeds the reason back to the model for a
// retry, exactly like a validate rejection.
ctx.on('graphTools/pre-execute', async (execution, next) => {
  if (disabledTools.has(execution.tool)) {
    return { kind: 'deny', reason: `"${execution.tool}" is disabled by policy` }
  }
  return next()
})

// Observe or reshape the settled outcome; fires on successes and failures alike.
ctx.on('graphTools/post-execute', async (execution, outcome, next) => {
  if (execution.tool === 'search_graph' && !('error' in outcome)) {
    return { kind: 'accept', result: redact(outcome.result) } // replace the returned value
  }
  return next()
})

Semantics:

• execution carries tool / args / request (the original routing text) / signal; the same object reaches both events of one attempt.
• Waterfall order: listeners run in registration order; next() delegates, and answering without next() vetoes the rest — the first decision wins.
• deny (pre) and block (post) join the ordinary retry loop: the reason is fed back to the model and retries exhaust into the standard error. A block rejects any settled outcome — it can also convert a propagating graph error into a retried choice instead of an error.
• accept keeps the settled outcome; with result it replaces the value returned to the caller (listeners still observed the original).
• The fallback path (no tool chosen) traverses neither event; if you need hooks there, wrap your fallback tool's execute. A throwing listener propagates as-is. Listeners register with plain ctx.on like any cordis event; inside a listener, this is the agent's ctx.

Registration declaration

Field	Meaning
asTool	Whether to register as a model-visible DSH tool (ctx.tools). Default false; the auto-mount path registers at the plugin's global layer (visible to all agents), the imperative mount path registers at the layer of the ctx passed in.
asGraphTool	Whether to list in the graphTools registry for discovery (get/list, GraphRoutingAgent). Default true.

defineGraph fields

Field	Meaning
name	The graph name, which becomes the registered tool name; globally unique; the reserved name run_code is rejected.
description	Optional. The model-facing tool description; defaults to the description written by compile({ description }) on the build() product (when the author compiled it), or a structural description synthesized from nodes and state keys.
build	Graph factory: returns an uncompiled builder (the plugin plain-compile()s it at first invocation, passing no options), or an author-compiled instance. Checkpointer and all compile options belong entirely to the author — for state memory, return builder.compile({ checkpointer: new MemorySaver() }).
validate	Optional argument-validation hook: receives (input, context) before the graph runs; context.tool is the tool name, and when routed through GraphRoutingAgent context.request carries the original request text (absent on direct calls). Returning false or throwing rejects (a thrown message becomes the rejection reason); defaults to always passing. This enables "this request is not mine" semantic rejection, which the routing loop retries with the reason.
parameters	Optional DSH ParameterSchemaSpec. When provided, the whole argument object becomes the graph input; when omitted, the tool exposes a single required input JSON parameter (its description is appended with the discovered state key names, but the value itself stays opaque). Model-visible graphs should always declare it — see the next section.
threadId	Optional thread key; forwarded as-is into the graph config's thread_id. Whether it produces state memory is decided by the graph's own checkpointer (the plugin manages none).
configurable	Optional extra configurable keys forwarded as-is (thread_id is governed by threadId).
timeoutMs	Optional cooperative timeout budget; the graph must respond to the cancellation signal and converge.

Parameter schema quality (required reading for model-visible graphs)

parameters is forwarded as-is as a DSH ParameterSchemaSpec and enforced before execution (out-of-range enums, type mismatches, and missing requireds are all stopped by ToolArgsError). For graphs a model will see, keep every parameter explicitly typed, concretely described, and fully enumerated:

defineGraph({
  name: 'greet_graph',
  build: () => buildGreetGraph(),
  parameters: {
    name: { type: 'string', required: true, description: 'The name to greet.' },
    style: {
      type: 'string',
      required: true,
      enum: ['formal', 'casual'],
      description: 'Greeting style.',
    },
    times: { type: 'integer', description: 'Repeat count.', default: 1 },
    tags: { type: 'array', items: { type: 'string' }, description: 'Extra tags.' },
  },
})

Supported capabilities: type is one of string / number / integer / boolean / null / array / object / json, unions use oneOf; every key may carry description / title / default / examples; enums use an enum matching the type (e.g. a string array), single-value constraints use const; nested objects use object + properties + additionalProperties, arrays use items; mark required keys individually with required: true.

Why nothing is derived automatically: langgraph drops Annotation type information at compile time, leaving only key names and aggregation semantics in the runtime structure — a schema with fabricated types or requireds would mislead the model into assembling arguments the validation layer then rejects, which is worse than an honest input. So the fallback without declared parameters is a single required input (json), whose description carries the discovered state keys (e.g. Expected state keys: topic, log (accumulated).); when asTool: true and no parameters are declared, the mount path logs a warn through ctx.logger to nudge the author.

Imperative entries (dynamic / low-level scenarios)

// A runtime-constructed graph: createGraphDefinition constructs without
// publishing (defineGraph auto-mounts, so an explicit mount while the
// plugin is active would double-register), paired with an explicit mount;
// ctx is both the fiber owner and the ctx.tools registration target.
const dynamicGraph = createGraphDefinition({
  name: 'dynamic_flow',
  build: () => buildDynamicGraph(),
  asTool: true,
})
const mounted = ctx.graphTools.mount(dynamicGraph, ctx)

// Discovery side: ctx.graphTools.get('echo_graph') / ctx.graphTools.list()

// Already holding a compiled graph, or only want a one-off conversion:
const entry = ctx.graphTools.register(compiledGraph, ctx)
const tool = ctx.graphTools.create(compiledGraph)

import { createGraphTool } from 'dsh-graph-runtime' also does the pure conversion directly, with the same effect. Passing a graph definition to register fails with an error pointing at mount — graph definitions carry their own registration declaration. defineGraph targets graph authors (declare-and-publish, auto-mount); createGraphDefinition targets runtime-dynamic scenarios (construction stays construction, mounting stays mounting).

Behavior contract

• Defining is registering: defineGraph publishes the graph definition to a package-level static queue; at plugin apply the queue is taken over and drained, and later definitions mount immediately. A single graph failing to mount (duplicate name, invalid declaration) is skipped with a ctx.logger warning and never blocks startup; after the plugin disposes, defineGraph queues again and can remount with the next plugin load.
• Registration is only registration: defineGraph/mount/register never call langgraph's compile(); an uncompiled builder is plain-compile()d exactly once at the tool's first real invocation and memoized (structural discovery only reads the builder's nodes/channels and likewise never compiles).
• The checkpointer belongs to the graph: the plugin never injects or manages compile options; threadId is only a thread_id pass-through, and whether memory takes effect depends on the instance the author returns from build().
• Each tool call is one graph.invoke; tool arguments pass DSH parameter-schema validation and the author's validate hook before entering the graph, and the caller's AbortSignal is forwarded as-is.
• The graph's final state must be lossless JSON, or it is rejected with an explicit error; the tool result returns to the model as a pretty-printed JSON text block.
• Interaction with ctx.tools happens only when asTool: true is declared: the auto-mount path registers at the plugin's global layer (visible to every agent including the default agent); imperative mount(definition, ctx) registers at the layer of the passed ctx (on an agent-scoped ctx, visible only to that agent, shadowing a same-named global tool). The graphTools registry is separate state: listed names are unique, unregister is idempotent, and entries leave automatically with the disposing fiber of the mounting path.
• Limits of auto-discovery: Annotation type information and addNode descriptions are dropped when langgraph compiles, so a parameter schema cannot be derived automatically. Discovery degrades safely for a custom GraphInvocable missing runtime fields, but the name must be provided explicitly.