Skip to main content
← Back to list
01Issue
BugClosedSwamp ClubPublic
AssigneesNone

Relationships

#2352 manual: extension model reference documents context.runModel with the wrong signature, error shape and remote behavior

Opened by stack72 · 9/22/2026

The swamp-club manual page content/manual/reference/extensions/model.md, section Model Invocation, describes context.runModel in three ways that do not match the implementation.

What the manual says vs. the code

  1. Signature. The manual shows a positional call, runModel(target: string, method: string, args?), where target is either a definition name or a model type. The real API takes one options object with two forms: { definition, method, arguments? } for an existing definition, or { modelType, name, method, arguments? } for direct type execution. See RunModelOptions in src/domain/models/model.ts.
  2. Failure shape. The manual shows { ok: false, error: string }. The real result is { ok: false, error: { message: string; stack?: string } }. See RunModelFailure in src/domain/models/model.ts.
  3. Remote workers. The manual says calling runModel on a worker throws an error. It does not throw. It returns { ok: false } with an error message telling the author to move the call to a local orchestrator model or a workflow. See the runModel stub in src/worker/remote_method_context.ts.

Impact

An extension author who follows the manual writes runModel calls that fail type checking. Code that reads error as a string, or wraps the call in try/catch expecting a throw on workers, handles failures incorrectly.

Fix

Update the Model Invocation section to match the implementation. The corrected content, verified against the code, is the Cross-Model Access section added to the swamp skill in swamp PR #2550 (swamp-club#2317). That section also covers readModelData and queryData, and has a table of where each API is available (local methods, remote workers, checks).

02Bog Flow
✓OPEN○TRIAGED○IN PROGRESS◉CLOSED

Closed

9/23/2026, 10:33:35 PM

No activity in this phase yet.

03Sludge Pulse
Editable. Press Enter to edit.

stack72 commented 9/23/2026, 10:33:35 PM

Fixed in https://github.com/swamp-club/swamp-club/pull/1247 — extensions/model.md documents runModel's options-object signature (definition, or modelType + name), the { ok: false, error: { message, stack? } } shape, the worker returning ok: false instead of throwing, readModelData/queryData, and an availability table. The how-to and remote-execution explanation are corrected too.

Sign in to post a ripple.