Preamble

In environments such as DeepSeek Harness (DSH) or Codex, Agents often invoke Tools or Skills in a discrete manner. Without structure, these invocations are difficult to save, validate, or resume. @gm-hz/agent-dag-workflow provides a solution: it allows Codex, DSH, or other Agents to reuse existing Tools, Skills, and MCP, and organizes discrete invocations into WorkflowTemplate JSON that can be saved, validated, resumed, audited, and replayed.

What Is This

This is a Host-neutral DAG Workflow Runtime, maintained by GM-HZ. It is not another Coze or Dify platform, and it does not include model Providers, a credential center, or a Tool marketplace. The Host continues to manage its existing Agent/Tool/Skill/MCP ecosystem; this project only turns discrete capabilities into stable workflows.

Core Features

  • Host-neutral DAG Workflow Runtime: supports Codex, DSH, and embedded Hosts.
  • CLI-native access: provides the shorthand adw and the full command agent-workflow, with support for local database storage.
  • Fixed MCP Gateway: provides a fixed MCP Tool gateway.
  • On-demand Skills: supports activating Skills on demand.
  • Triggers: supports Cron, Webhook, and Channel triggers.
  • Replay and Trace support: supports execution tracing and replay.
  • Visual Canvas: provides visual Canvas design capabilities.
  • WorkflowTemplate JSON: uses a single JSON definition, supporting Schema validation, auditing, and replay.
  • Journal and Checkpointing: supports Journal and Checkpointing for persistent state.
  • Multi-host support: supports multi-Host environments.

Installation and Enablement

Before running, ensure that your Node.js version is 22.19 or higher.

npm install @gm-hz/agent-dag-workflow

The package is published as a single module, and specific features can be imported on demand via subpath imports:

import { WorkflowRuntime } from '@gm-hz/agent-dag-workflow'
import { SqliteWorkflowRunStore } from '@gm-hz/agent-dag-workflow/sqlite'
import { createMcpGateway } from '@gm-hz/agent-dag-workflow/mcp'
import * as DshWorkflow from '@gm-hz/agent-dag-workflow/dsh'

Typical Usage

CLI Operations

The CLI provides the shorthand adw and the full command agent-workflow; the two are fully equivalent. By default, the CLI uses .agent-dag-workflow.db in the current directory, or you can specify a SQLite file with --db.

adw validate examples/script-transform.workflow.
adw draft put examples/script-transform.workflow. --db workflows.db
adw publish script-transform-demo --expected 1 --db workflows.db
adw run script-transform-demo@1 --input input. --db workflows.db
adw trace <runId> --events --db workflows.db
adw replay <runId> --mode recorded --db workflows.db

SDK Integration

SDK usage example (minimal, performing only deterministic JSON transformation):

import {
  InMemoryWorkflowCatalogRepository,
  InMemoryWorkflowRunStore,
  WorkflowNodeRegistry,
  WorkflowRuntime,
  WorkflowTemplateCatalog,
  registerCoreNodes,
} from '@gm-hz/agent-dag-workflow'

const nodes = new WorkflowNodeRegistry()
registerCoreNodes(nodes)

const catalog = new WorkflowTemplateCatalog(
  new InMemoryWorkflowCatalogRepository(),
  nodes,
)

const runtime = new WorkflowRuntime({
  nodes,
  catalog,
  runStore: new InMemoryWorkflowRunStore(),
})

const template = {
  apiVersion: 'workflow.gm-hz.dev/v1',
  kind: 'WorkflowTemplate',
  metadata: { id: 'hello', name: 'Hello' },
  spec: {
    inputSchema: {
      type: 'object',
      required: ['name'],
      properties: { name: { type: 'string' } },
    },
    outputSchema: {
      type: 'object',
      required: ['message'],
      properties: { message: { type: 'string' } },
    },
    requires: [{ kind: 'script-runtime', uses: 'json.expr@1' }],
    nodes: [
      { id: 'start', uses: 'core.start@1', with: {}, inputs: {} },
      {
        id: 'format',
        uses: 'core.script@1',
        with: { language: 'json.expr@1', source: '{ message: "Hello, " + input.name }' },
        inputs: { name: { input: { path: ['name'] } } },
      },
      {
        id: 'end',
        uses: 'core.end@1',
        with: {},
        inputs: { message: { output: { nodeId: 'format', path: ['message'] } } },
      },
    ],
    edges: [
      { id: 'start-format', source: 'start', target: 'format' },
      { id: 'format-end', source: 'format', target: 'end' },
    ],
    outputs: { message: { output: { nodeId: 'end', path: ['message'] } } },
  },
}

const handle = await runtime.launch({
  target: { type: 'inline', template },
  inputs: { name: 'Workflow' },
  authorityRef: 'sdk:local',
  authority: {},
  origin: { type: 'sdk' },
})

console.log(await handle.result)

Use Cases and Notes

Use cases: Agent development that requires organizing discrete Tool invocations into structured, persistent workflows with validation, auditing, and replay capabilities.

Notes:
* Host responsibility: This plugin does not provide built-in model Providers, a credential center, or a Tool marketplace. The Host is responsible for maintaining the Agent/Tool/Skill/MCP ecosystem.
* Pure JSON Scripts: Scripts contain pure JSON only and do not support network requests, file read/write, environment variables, secrets, or dynamic code execution (eval). Loops with external side effects must use core.foreach@1.
* Permission narrowing: Permissions follow the narrowing logic of Template requires -> Node uses -> Host Policy.
* Trigger logic: Triggers such as Cron, Webhook, and Channel only produce a trusted Envelope and do not directly enter the DAG; they must start a published revision through a fixed Binding.
* Dependency adapters: Queue/Runner are optional adapters; by default, the current Agent, CLI, or Host invokes the Runtime directly.

Summary

@gm-hz/agent-dag-workflow provides a Host-neutral DAG workflow runtime that connects Tools, Skills, and MCP through a single JSON definition. It supports validation, auditing, recovery, and replay, and is suitable for developers who need to build deterministic workflows in environments such as DeepSeek Harness or Codex.