Workflow Self-Recursive — Execution System

English | 中文

Turn every agent conversation into an auditable, recoverable, version-bound delivery.

The Execution System is the host-neutral execution boundary of workflow-self-recursive: it resolves and validates one exact Workflow Package, binds it in an immutable Delivery Manifest, coordinates the Delivery inside an isolated Runner-owned execution context, recovers from the last durable boundary after crashes, and emits bounded observations over OTLP — observation never controls execution.

Delivery forms (交付形态)

The Execution System is a host-neutral product, not a plugin. DSH is one entry point among several:

Form	Package	Audience
Embedded library	wsr-execution	Host-neutral embedding — import ExecutionApplicationFactory and bootstrap with create(configFile, dependencies)
DSH plugin entry	wsr-dsh-intake	DeepSeek Harness users — run workflows from chat and sidebar tabs
CLI	execution-config (in wsr-execution)	Configuration init / copy / validate / dump-effective

The DSH plugin is the first product entry; every admitted Workflow Action runs in a Runner-owned, isolated DSH execution context (DSH-E), never in the Intake context (DSH-I).

Why it exists

Bare agent chat	What actually happens	Execution System
Execution is a black box	What the model did, and with which workflow definition, cannot be audited afterwards	Every Delivery binds one exact version + SHA-256 into an immutable Manifest
Interruptions lose state	After a crash or restart there is nowhere to look	Manifest/current-slot persist; /wsr recover resumes from the last durable boundary
Version drift	The same request can execute different definitions at different times	Exact/latest selectors with a local READY store that stays authoritative
Observation couples to execution	A telemetry outage can take the run down with it	One-way, best-effort OTLP; Execution continues when Evidence or telemetry is unavailable

How it works

Three modules carry the responsibility:

• Delivery Binding resolves one exact, locally READY Workflow Package (selector → validation → local MISSING/STAGING/READY store) and constructs the Manifest content.
• Runtime Interaction owns canonical worktree exclusivity, the current Delivery slot, Manifest persistence, Runtime invocation, recovery, and final handling.
• Delivery Observation maps outbound bounded facts to a one-way, best-effort OTLP profile without controlling execution.

The default Source is the configured firestige/workflow-package GitHub Release. implementation-workflow@0.3.0 and system-design-workflow@0.3.0 are downloaded, validated, and published to the local READY store; neither is embedded in an Execution artifact.

Install (DSH entry, one command)

# 1. Approve the better-sqlite3 native build once (pnpm 11)
dsh plugin --profile web config set --location=project --json allowBuilds '{"better-sqlite3":true}'
# 2. Install the Intake entry — the engine (wsr-execution) comes as its dependency
dsh plugin --profile web add wsr-dsh-intake

Requires Node `>=24.12 /wsr recover [delivery-id] /wsr status [delivery-id] /wsr action finish /wsr abandon

The explicit first-party skill `/workflow-execution` performs exactly one closed operation through the DSH-I-only `workflow_execution_intake` tool.

## Compatibility

| Dimension | Requirement |
|---|---|
| Node.js | `>=24.12.0 <25` |
| DeepSeek Harness | `0.1.1-rc.2` (`@deepseek-ai/dsh`) |
| Workflow Package contract | `agentops.workflow-dsl@1.1.0` |
| Observation contract | `agentops.observation@1.0.0` |
| Checkpoint store | `better-sqlite3` (native build, approved via `allowBuilds`) |

## Known Limitations and Deferred Work

- **Developer preview** — version `0.1.x` is an MVP candidate for trusted local use by individuals and small teams; compatibility-breaking changes are possible.
- **Conversation workspace as provisional worktree** — until [#94](https://github.com/firestige/workflow-self-recursive/issues/94), an operation that must select a worktree uses the invoking conversation's registered workspace; authority is invocation-scoped and exact.
- **Observation disabled by default** — set `observation.enabled: true` with a loopback OTLP base `endpoint` to enable the non-controlling exporter.
- **DSH-only interactive surface** — the shipped `web` profile is the reference assembly; a custom profile contains only `dsh-base` and is not an interactive Intake surface.

## For maintainers

- **Release qualification** — see [the release process](https://github.com/firestige/workflow-self-recursive/blob/main/docs/guides/execution-release-process.md). `pnpm quickstart:prepare` builds and verifies both artifacts and initializes local E2E configuration in one operation.
- **Changelog** — generated from git history by `pnpm changelog:generate`; `pnpm changelog:check` (CI-gated) rejects hand-edited drift.
- **Local pre-release E2E** — [guide](https://github.com/firestige/workflow-self-recursive/blob/main/docs/guides/dsh-execution-local-e2e.md); final [DSH quickstart](https://github.com/firestige/workflow-self-recursive/blob/main/docs/guides/dsh-execution-quickstart.md); [configuration reference](https://github.com/firestige/workflow-self-recursive/blob/main/docs/reference/execution-configuration.md); [DSH Intake package reference](https://github.com/firestige/execution-system/blob/a1ab8c2f8cd853b7dc7d79b0bb5e2ec474f0853f/packages/dsh-intake/README.md).

### Direct embedding

For host-neutral embedding, import `ExecutionApplicationFactory`, `DefaultExecutionApplicationFactory`, `ExecutionRequest`, `TaskPrompt`, and the configuration types from the package root. Calling the default factory's `create(configFile, dependencies)` is the single production bootstrap path. The exact DSH runtime is an optional peer: package-root import/type consumers need not install it, while executing the current `dsh` Provider requires the embedding profile to provide `@deepseek-ai/dsh@0.1.1-rc.2`. The release includes `config/schema/execution.config.schema.json`, versioned defaults/examples, compiled TypeScript declarations, and `execution-config init|copy|validate|dump-effective`.

## Get the source

This repository is normally consumed as a submodule of [workflow-self-recursive](https://github.com/firestige/workflow-self-recursive):

```sh
git clone --recurse-submodules https://github.com/firestige/workflow-self-recursive.git

To clone it standalone:

git clone https://github.com/firestige/execution-system.git

Documentation

• Execution System design
• Conceptual architecture
• Workflow composition model
• Execution–Evidence interaction contract
• Planned first-party LangGraph runtime profile

License

Apache-2.0