@flower-f/afk-node

Node.js agent runtime integration, workspace management, config, auth, doctor checks, plugin support, and workflow orchestration for afk-dev.

Most users should install @flower-f/afk-cli instead.

Agent Runtimes

afk-node provides built-in agent runtimes for OpenCode and Codex. The default runtime is Codex. Runtime implementations register through a common factory interface so callers can add runtimes without changing core logic.

afk config setup --runtime opencode --model deepseek/deepseek-chat
afk run "Refactor auth" --runtime codex --model openai/gpt-5.5

For OpenCode runs, AFK uses shell or .env credentials first, then AFK auth, then OpenCode's native auth store. For Codex runs, AFK uses CODEX_API_KEY, maps OPENAI_API_KEY or AFK openai auth to CODEX_API_KEY, and otherwise lets Codex use its native auth.

Config loading

Config priority is CLI flags, then project afk-dev.config.json, then global config, then AFK defaults. afk run loads .env from the current directory first, then from the resolved workspace directory; existing shell environment variables win.

OpenCode plugin assets installed by AFK are tracked under .afk-dev/plugins/. AFK may clean previously managed assets on reinstall, but it does not scan or delete user-owned .opencode/ files.

Plugin discovery

Plugins are discovered from:

• built-in plugin names resolved through @flower-f/afk-plugins-official
• custom plugin paths in afk-dev.config.json, resolved relative to the config file

Each plugin provides an afk-dev.plugin.json manifest plus optional agents/, skills/, prompts/, and pipeline modules. Plugin-contributed pipelines are registered alongside the built-in pipelines before workflow selection, doctor validation, and execution.

Doctor

afk doctor runs diagnostics for config, git state, workspace lock, runtime command, credentials, plugins, workflow readiness, and runtime-specific skills. Doctor delegates runtime-specific checks (credentials, asset targets, diagnostics) to the selected runtime implementation.

afk doctor --json
afk doctor --workspace . --runtime opencode --runtime-command /path/to/opencode

Sessions and artifacts

AFK stores session metadata, default artifacts, turn snapshots, locks, cache files, and runtime temp state in a global workspace store by default. The workspace identity is the real path of the workspace hashed into a stable directory name.

$XDG_DATA_HOME/afk-dev/workspaces/<workspace-hash>/
  afk.sqlite
  run.lock
  artifacts/
    <safe-session-key>/
      runs/
        <run-id>/
          report.json
          summary.md
          trace.json
  blobs/
    <hash-prefix>/
      <hash>
  turn-snapshots/

$XDG_CACHE_HOME/afk-dev/workspaces/<workspace-hash>/
  runtime/
    npmrc/

$TMPDIR/afk-dev/<workspace-hash>/
  agent-tools/

report.json is compact and machine-readable. summary.md is the human-readable run summary. trace.json keeps full raw agent and check detail when enabled or when a run fails. Flow workflows can declare additional artifact projections such as plan.md or questions.md; afk status lists the files recorded for each run. A custom artifactDir still resolves from the workspace for explicit export behavior; the default artifact directory is redirected to the global store.

Programmatic API

import { builtInWorkflowPipelines, runAfkWorkflow, runDoctor } from "@flower-f/afk-node";
import { createWorkflowPipelineRegistry } from "@flower-f/afk-core";

const workflowPipelineRegistry = createWorkflowPipelineRegistry(builtInWorkflowPipelines);

await runDoctor({ workflowPipelineRegistry });
await runAfkWorkflow({ task, overrides, workflowPipelineRegistry });

Plugin-declared pipelines are merged into the registry before workflow selection when using the CLI; Node callers can inject their own registry the same way.

Tests

pnpm --filter @flower-f/afk-node test

Optional real adapter smoke tests:

AFK_E2E_OPENCODE=1 pnpm --filter @flower-f/afk-node test:e2e:opencode
AFK_E2E_CODEX=1 pnpm --filter @flower-f/afk-node test:e2e:codex

Optional live native MCP routing smokes exercise AFK's required control-plane tools through the full runtime adapter path:

pnpm smoke:mcp:codex:turn
pnpm smoke:mcp:codex:flow
pnpm smoke:mcp:opencode:turn
pnpm smoke:mcp:opencode:flow

These commands are intentionally not part of pnpm verify. They require local Codex/OpenCode auth or provider credentials. For OpenCode, the default smoke model is deepseek/deepseek-v4-pro; set AFK_MCP_SMOKE_MODEL or AFK_E2E_MODEL to override it. For Codex, set AFK_E2E_CODEX_MODEL or AFK_MCP_SMOKE_MODEL when the runtime should not use its configured default model. The smoke script creates a temporary writable Codex/OpenCode home and copies only the local auth/config files required for that run. This avoids failures when an outer sandbox blocks writes to ~/.codex, ~/.local/share/opencode, or related XDG directories. The temporary runtime home is removed even when the smoke workspace is kept for debugging.