@openclaw/orchestration

Framework for coordinating multi-agent tasks with atomic claims, dependencies, retries, and markdown task visibility using a shared SQLite queue.

Security Scan

The package implements the claimed SQLite-backed orchestration features and matches its description, but the bundle has multiple correctness/robustness issues and an undeclared cross-skill dependency that make it risky to run without review and fixes.

Purpose & Capability

Name/description match the code: a SQLite-backed task queue with claiming, dependencies, retries, sweep, and markdown interchange generation. Declared dependencies (better-sqlite3, commander, uuid) and the CLI align with that purpose. Two concerns: (1) src/interchange.js imports '../../interchange/src/index.js' — a relative, out-of-package import that requires a sibling 'interchange' module to exist but is not declared in package.json; this is an implicit external dependency and brittle design. (2) package-lock includes native modules (better-sqlite3) which require native build/runtime support; that is expected but worth noting for deployment.

Instruction Scope

SKILL.md and the CLI instruct only local actions (npm install, run node src/cli.js commands). The code reads/writes a local DB (data/orchestration.db), writes .md interchange files, and exposes backup/restore that overwrite local DB files. There is no attempt to read environment secrets or contact external network endpoints in the provided source. However: the interchange import reaches outside the package (../../interchange/...), and refresh generates files in an 'interchange' tree — the SKILL.md does not call out that refresh will rely on an external sibling module, nor that files will be written to the repository filesystem. The CLI 'restore' and backup functions can overwrite the live DB file; the README/CLI warn about WAL but these operations still carry data-loss risk if misused.

Install Mechanism

There is no special install script in the skill registry; the SKILL.md recommends running 'npm install' which will fetch packages from the npm registry (better-sqlite3, commander, uuid). No downloads from arbitrary URLs or shorteners are used. Note: better-sqlite3 is a native module and may run build/install steps (prebuild-install) — this is normal but requires build toolchain on the host.

Credentials

The skill declares no required environment variables, no credentials, and no special config paths. The code operates on local filesystem paths under the skill (data/, interchange/) and uses no external API keys. This is proportionate to an on-disk orchestration tool.

Persistence & Privilege

The skill does not request always:true or any elevated platform privileges. It will run CLI commands and modify files under its data/interchange directories. One caveat: the source imports code via a relative path that crosses upward and into a sibling 'interchange' directory ('../../interchange/src/index.js'), which means at runtime it could execute code from other skill directories if those exist in the same filesystem — this is a design fragility that could lead to surprising cross-skill execution if the repository layout differs from expectations.

Scan Findings in Context

[CRITICAL-race-condition-claimTask] expected: A static CODEX_REVIEW flagged a critical race: reading task fields outside the transaction can yield stale dependency data. For a DB-backed orchestration skill, transaction correctness is expected, so this finding is directly relevant and should be fixed before production use.

[HIGH-non-transactional-mutations] expected: Multiple high findings note that createTask, completeTask, and failTask had multi-statement sequences that were not wrapped in transactions; this risks DB inconsistency on crashes. These are correctness/robustness issues aligned with the skill's purpose (DB mutations) but not unexpected in such code — still they should be remedied.

[MEDIUM-unenforced-max_concurrent] expected: The schema includes agent.max_concurrent and current_load, but claim logic does not enforce max_concurrent. This is a logical bug (limits not enforced) rather than a secret-exfiltration pattern.

[MEDIUM-interchange-files-accumulation] expected: interchange.generateTaskFiles never cleans stale .md files; for an interchange generator this is plausible but should be handled to avoid stale artifacts.

[LOW-uuid-truncation] expected: IDs are generated by uuidv4().slice(0,8) which reduces entropy and increases collision risk; relevant to correctness and long-term scaling but not malicious.

What to consider before installing

This skill appears to implement what it says (a local SQLite multi-agent queue) but it's not production-ready as-is. Before installing or running it: - Review and, if possible, run the included tests in an isolated environment (the repository includes tests). They exercise most critical paths. - Address the CODEX_REVIEW issues (wrap multi-statement DB changes in transactions, enforce agent max_concurrent, ensure backup/restore await/close DB properly). These are correctness and data-integrity fixes, not evidence of malicious behavior. - Be aware the code imports '../../interchange/src/index.js' — the skill expects a sibling 'interchange' module to be present; if you don't have that, refresh/CLI may fail or, if present, will execute that external code. Validate that path and ensure only trusted code exists there. - Because this uses better-sqlite3 (native module), install/build may require a C++ toolchain or prebuilt binaries; test installation in your target environment first. - Run the CLI commands (claim/complete/sweep/refresh/backup/restore) in a controlled environment and back up any important data — restore can overwrite the live DB file and sweep/complete mutate state. If you need to use this skill in production, require the maintainer to fix the high/critical issues and either declare a dependency on @openclaw/interchange or vendor the required interchange functions to avoid cross-directory imports. If you lack the capability to audit or patch these issues, treat this package as untrusted for production workloads.

Orchestration Skill

Multi-agent task orchestration framework. Agents delegate tasks via a shared SQLite queue, with .md interchange files for visibility.

Quick Start

cd skills/orchestration
npm install
node src/cli.js agent register my-agent --capabilities "coding,research"
node src/cli.js task create "Build feature X" --desc "..." --priority high
node src/cli.js task claim <task-id> --agent my-agent
node src/cli.js task complete <task-id> --summary "Done"
node src/cli.js refresh

Design

• DB is source of truth — .md files are read-only projections
• Atomic claims — only one agent can claim a pending task
• Dependencies — tasks can depend on other tasks
• Timeout + retry — sweep handles stale tasks
• Interchange — refresh generates .md files via @openclaw/interchange