lda-wf/docs/runbooks/rpc-cli-smoke.md

RPC CLI Smoke Runbook

Use this runbook to verify the product path:

wf CLI -> wf_transport_rpc_http -> wf_server -> wf_api -> wf_core / stores / sources

For an automated version of this runbook:

uv run python examples/rpc_cli_smoke.py

Use --keep-temp to preserve the generated config/store after failure.

This is a bounded smoke test, not a load test. Keep outputs compact and avoid dumping raw upstream MCP resource payloads into terminal logs or agent context. Some MCP servers can return huge base64 image/resource blocks.

Prerequisites

Start the server in another terminal:

uv run wf-rpc-server --config wf.config.json --host 127.0.0.1 --port 8765

This runbook assumes wf.config.json has:

{
  "client": {
    "target": {
      "kind": "rpc_http",
      "url": "http://127.0.0.1:8765/rpc"
    }
  }
}

You can also keep local config unchanged and pass --url http://127.0.0.1:8765/rpc on every wf command.

Output Safety Rules

• Prefer --format compact or --format ids for list commands.
• Do not call arbitrary resource-heavy MCP capabilities during smoke.
• Do not inspect or print raw MCP resources unless the URI is known to be small.
• Keep trace reads bounded with --limit.
• If a command returns a huge content/resource/base64 field, stop and add a safer CLI output mode before repeating it.

1. Server Status

uv run wf --config wf.config.json status

Expected:

• target.mode is remote.
• Source/capability counts are nonzero for an MCP-backed server.
• Errors, if any, are compact CLI errors unless --verbose is used.

2. Bounded Discovery

uv run wf --config wf.config.json source list --format compact
uv run wf --config wf.config.json source resources everything.default
uv run wf --config wf.config.json source prompts everything.default --format json
uv run wf --config wf.config.json cap list --source wf.std --format ids
uv run wf --config wf.config.json cap inspect wf.std.constant

Expected:

• source list includes wf.std.
• source resources and source prompts return bounded inventory only; they do not read resource bodies or render prompt templates.
• cap list --source wf.std --format ids returns bounded identifiers.
• cap inspect wf.std.constant shows the capability contract.

3. Direct Capability Call

uv run wf --config wf.config.json cap call wf.std.constant --input '{"value":"smoke"}'

Expected:

• outcome is ok.
• Output is small and machine-readable.

Optionally, test compact output:

uv run wf --config wf.config.json cap call wf.std.constant --input '{"value":"smoke"}' --format compact

Expected: one bounded line with outcome=ok.

Avoid using arbitrary MCP tools here unless their output shape is known. MCP content-block envelopes can be large and should not be treated like compact workflow output.

4. Draft -> Artifact -> Deployment -> Run

Use unique ids so repeated runs do not collide:

uv run wf --config wf.config.json draft create smoke_ws --capability wf.std.constant --name smoke_constant --title "Smoke Constant"
uv run wf --config wf.config.json draft validate smoke_ws
uv run wf --config wf.config.json draft save smoke_ws --artifact smoke_artifact --version 1 --title "Smoke Artifact" --outcome ok
uv run wf --config wf.config.json deploy save smoke_deploy --artifact smoke_artifact --version 1
uv run wf --config wf.config.json deploy validate smoke_deploy
uv run wf --config wf.config.json run start smoke_deploy --input '{"value":"from workflow"}'

Expected:

• Draft validation is valid.
• Deployment validation is runnable.
• Run result has outcome: "ok".
• Capture the returned run_id for the trace step.

5. Inspect And Bounded Trace

Replace run_... with the id returned by run start:

uv run wf --config wf.config.json run inspect run_...
uv run wf --config wf.config.json run trace run_... --from 0 --limit 10

Expected:

• Inspect returns the run summary and output.
• Trace returns a bounded number of frames.

6. Cleanup

Delete in dependency order: deployment first, then artifact, then draft.

uv run wf --config wf.config.json deploy delete smoke_deploy
uv run wf --config wf.config.json artifact delete smoke_artifact 1 --confirm
uv run wf --config wf.config.json draft delete smoke_ws --confirm

Expected:

• Deployment delete succeeds.
• Artifact delete returns deleted: true.
• Draft delete returns deleted: true.

If artifact delete returns deleted: false with blocked_by_deployments, delete the listed deployments and retry.