Add `electric agents run` using spawn-and-claim
Nobody has claimed this yet.
Assessment
- Difficulty
- 5/5
- Estimated time
- Over a week
- Newbie friendliness
- 35/100
- Issue type
- Feature
- Clarity
- Mostly clear
- Activity status
- Quiet
- Tech stack
- typescript
- Domain
- backend-api-design, cli
Research direction
Start by reading the existing spawn and claim/callback machinery in packages/agents-server and packages/agents-runtime, then identify the CLI entry point for agent commands. The issue describes the required spawn-and-claim endpoint, local registry loading, handler execution, heartbeat, streaming, and claim completion or failure; done means these pieces work together with tests for success and error paths.
Written by the indexing model from the issue text.
Description
Summary
Add a Docker-style electric agents run command for one-shot local/CI agent execution.
The command should spawn an existing Electric Agent entity type, immediately claim the resulting wake for the current process using an API token, run the normal entity handler locally, stream progress, complete/fail the claim, and exit.
This gives us an imperative “run this agent” workflow without changing how entities are defined.
Motivation
Our entity definition model is already good:
defineEntity(`horton`, {
async handler(ctx, wake) {
ctx.useAgent(...)
await ctx.agent.run()
},
})
What’s missing is a simple way to run an existing entity directly from the CLI or CI, similar to how Flue supports one-shot agent invocation.
The command can be implemented as a small runner wrapper around primitives we already have:
- spawn entity
- claim wake
- execute handler
- heartbeat claim
- complete/fail claim
This fits naturally with the existing Docker-inspired CLI model:
electric agents run horton task-123 "Fix the failing tests"
Relationship to electric agents spawn
run is the attached execution form of spawn.
electric agents spawn should stay control-plane only: it creates the durable entity, optionally enqueues an initial message/wake, returns entity details, and exits. It does not need the entity implementation locally and it does not run anything in the CLI process. A separate long-running worker/runtime can pick up the wake later.
electric agents run does more: it requires the runner process to have the entity code/registry available locally, because that same process immediately claims the wake and executes the normal entity handler. It blocks until the claimed run completes and exits with the handler status.
In short:
spawn = create/enqueue durable work, no local code required
run = create/enqueue + claim + execute here, local registry required
exec = send/enqueue to existing entity + claim + execute here, local registry required
This is why run needs a server-side spawn-and-claim operation rather than just composing existing spawn behavior client-side: the claim should be assigned to the runner before another worker can pick up the wake.
Local registry discovery
Unlike electric agents spawn, electric agents run executes entity code in the CLI process. Therefore the CLI must load a local entity registry that contains the requested type.
There is no server-side or built-in fallback for execution. If the registry cannot be found, or the requested type is not registered, run should fail before claiming work.
Proposed resolution order:
--registry <path>- package config, e.g.
package.json - convention file such as
electric.agent-registry.ts - error
Example registry module:
// electric.agent-registry.ts
import { createEntityRegistry } from '@electric-ax/agents-runtime'
import { registerHorton } from '@electric-ax/agents'
import { registerReviewer } from './src/agents/reviewer'
export default async function createAgentRegistry(options: {
workingDirectory: string
}) {
const registry = createEntityRegistry()
registerHorton(registry, {
workingDirectory: options.workingDirectory,
})
registerReviewer(registry)
return registry
}
The module can export either an EntityRegistry or a factory returning one. The CLI should verify the requested entity type is registered before calling spawn-and-claim.
Proposed UX
Canonical form:
electric agents run [--registry <path>] <type> [id] [message]
The examples below assume a registry is discoverable via electric.agent-registry.ts, package config, or --registry.
Examples:
electric agents run horton "Summarize the latest project status"
Auto-generate an entity id.
electric agents run horton project-status \
"Summarize the latest project status and list any open questions"
Explicit entity id.
electric agents run --registry ./electric.agent-registry.ts worker worker-1 \
--args '{"workingDirectory":"/Users/kylemathews/programs/electric"}' \
--message "Run tests and report failures"
Structured spawn args + explicit message.
electric agents run horton bugfix-42 \
-m "Fix the failing typecheck" \
--cwd /Users/kylemathews/programs/electric \
--tag repo=electric \
--tag source=cli
Proposed flags
MVP flags:
--server, -H Agents server URL
--token Runner/API token
--registry Local entity registry module
--args JSON spawn args
--message, -m Initial message
--tag, -t Repeatable key=value tag
--cwd Convenience for built-in agents / working directory
--json Machine-readable output
Environment fallbacks:
ELECTRIC_AGENTS_SERVER_URL
ELECTRIC_AGENTS_RUNNER_TOKEN
Potential future flags:
--name Docker-style alias for explicit id
--detach, -d Spawn without attached local execution
--rm Delete entity after successful run
--if-exists reuse | fail | replace
Server API
Add a server endpoint:
POST /_electric/runner/spawn-and-claim
Authorization: Bearer <token>
Content-Type: application/json
Request:
{
"type": "horton",
"id": "task-123",
"args": {},
"initialMessage": "Fix the failing tests",
"tags": {
"runner": "cli"
},
"consumerId": "runner-local-abc123"
}
Response:
{
"entity": {
"url": "/horton/task-123",
"type": "horton",
"streams": {
"main": "/horton/task-123/main"
}
},
"claim": {
"consumerId": "runner-local-abc123",
"primaryStream": "/horton/task-123/main",
"writeToken": "..."
},
"wake": {
"...": "same enriched payload the runtime handler expects"
}
}
The exact claim shape can follow the existing claim/callback machinery. The important property is that the runner receives everything needed to run the entity handler immediately and write stream events under the active claim.
Programmatic API
Expose the same runner flow as a small TypeScript API so apps, tests, and CI scripts can run entities without shelling out to the CLI.
Basic example:
import { createEntityRegistry } from '@electric-ax/agents-runtime'
import { runEntityOnce } from '@electric-ax/agents/runner'
import { registerHorton } from '@electric-ax/agents'
const registry = createEntityRegistry()
registerHorton(registry, { workingDirectory: process.cwd() })
await runEntityOnce({
serverUrl: process.env.ELECTRIC_AGENTS_SERVER_URL!,
token: process.env.ELECTRIC_AGENTS_RUNNER_TOKEN!,
registry,
type: `horton`,
id: `task-123`,
args: {
workingDirectory: `/Users/kylemathews/programs/electric`,
},
initialMessage: `Fix the failing tests`,
tags: {
runner: `script`,
repo: `electric`,
},
})
With multiple/custom entity types:
import { createEntityRegistry } from '@electric-ax/agents-runtime'
import { runEntityOnce } from '@electric-ax/agents/runner'
import { registerHorton, registerWorker } from '@electric-ax/agents'
const registry = createEntityRegistry()
registerHorton(registry, {
workingDirectory: process.cwd(),
})
registerWorker(registry, {
workingDirectory: process.cwd(),
})
await runEntityOnce({
serverUrl: process.env.ELECTRIC_AGENTS_SERVER_URL!,
token: process.env.ELECTRIC_AGENTS_RUNNER_TOKEN!,
registry,
type: `horton`,
id: `task-123`,
args: {},
initialMessage: `Summarize the latest project status and list any open questions`,
})
Proposed API shape:
export interface RunEntityOnceOptions {
serverUrl: string
token: string
type: string
id?: string
args?: Record<string, unknown>
initialMessage?: unknown
tags?: Record<string, string>
/**
* Local registry containing the requested entity type.
*/
registry: EntityRegistry
/**
* Optional working directory convenience for built-in agents.
*/
workingDirectory?: string
/**
* Optional stable consumer id. If omitted, generate one.
*/
consumerId?: string
/**
* Optional lifecycle hooks for logs/events/claim state.
*/
onEvent?: (event: RunnerEvent) => void
signal?: AbortSignal
}
export interface RunEntityOnceResult {
entityUrl: string
entityType: string
streamPath: string
id: string
status: `completed` | `failed`
}
Lower-level API for callers that want to own execution:
import { createRuntimeServerClient } from '@electric-ax/agents-runtime'
const client = createRuntimeServerClient({
baseUrl: process.env.ELECTRIC_AGENTS_SERVER_URL!,
token: process.env.ELECTRIC_AGENTS_RUNNER_TOKEN!,
})
const { entity, claim, wake } = await client.spawnAndClaimEntity({
type: `horton`,
id: `task-123`,
args: {},
initialMessage: `Fix the failing tests`,
tags: { runner: `script` },
})
try {
await runLocalHandler({ entity, claim, wake })
await client.completeClaim(claim)
} catch (error) {
await client.failClaim(claim, {
error: error instanceof Error ? error.message : String(error),
})
throw error
}
Potential follow-up API for exec:
await execEntityOnce({
serverUrl,
token,
entityUrl: `/horton/task-123`,
message: `Continue investigating the failing tests`,
})
And the lower-level client equivalent:
const { entity, claim, wake } = await client.sendAndClaimEntity({
entityUrl: `/horton/task-123`,
payload: `Continue investigating the failing tests`,
type: `message`,
})
Server behavior
spawn-and-claim should:
- authenticate the runner token
- spawn the requested entity type/id using existing manager logic
- include spawn args, tags, and optional initial message
- handle spawn conflicts consistently with current spawn behavior
- immediately create/assign a claim for the entity’s primary stream
- mark the entity as
running - return the enriched wake payload expected by the runtime handler
- rely on existing claim heartbeat / stale claim / done semantics
This should be a thin composition of existing capabilities, not a new execution system.
Runner behavior
electric agents run should:
- load config/env
- ensure it has server URL and runner token
- load the local entity registry from
--registry, package config, or convention - verify the requested entity type is registered locally
- initialize the local runtime with that registry
- call
spawn-and-claim - start claim heartbeat using existing claim mechanisms
- execute the normal entity handler locally with the returned wake payload
- stream progress/events to stdout/stderr
- complete the claim on success
- fail the claim on error
- exit with a meaningful status code
Default mode should be attached: the command runs until the entity handler completes.
Follow-up: electric agents exec
Once spawn-and-claim exists, we should also add a Docker-style exec path for existing entities:
electric agents exec horton/task-123 "Continue investigating the failing tests"
or:
electric agents exec /horton/task-123 \
--message "Summarize what you have learned so far"
Semantically, exec would:
- target an existing entity
- send a new message/wake
- immediately claim that wake for the current process
- run the normal handler locally
- heartbeat and complete/fail the claim as usual
So run is:
spawn + claim + execute
and exec is:
send + claim + execute
This would make it easy to attach local one-shot work to an existing durable agent without creating a new entity.
Implementation notes
Likely package touchpoints:
-
packages/agents-server- add
POST /_electric/runner/spawn-and-claim - add runner token auth
- compose existing spawn + claim + payload enrichment logic
- add
-
packages/agents-runtime- add runtime server client method, e.g.:
spawnAndClaimEntity(...) - optionally expose helpers for claim completion/heartbeat if not already public
- add runtime server client method, e.g.:
-
packages/agents- export
runEntityOncefrom@electric-ax/agents/runner - later export
execEntityOnce - add
electric agents run - load local entity registry via
--registry, package config, orelectric.agent-registry.ts - fail before claiming if the registry is missing or the requested type is not registered
- parse Docker-style flags
- call spawn-and-claim and run handler
- export
Non-goals
- Do not change
defineEntity - Do not introduce a new session abstraction
- Do not bypass durable entity streams
- Do not create a separate persistence model
- Do not replace normal webhook/long-running worker execution
- Do not reimplement existing CLI commands like
ps/inspect
This is just an imperative runner path for existing entity types.
Why this is useful
This unlocks:
- local one-shot agent runs
- CI workflows
- scripted issue triage
- local coding/research agents
- easier demos
- easier onboarding
- later
electric agents execsupport for existing entities - imperative “run this agent” ergonomics
while preserving all Electric Agents semantics:
- same entity definitions
- same timelines
- same durable streams
- same status transitions
- same claim lifecycle
- same UI visibility
- same tools/spawn/observe behavior
Acceptance criteria
electric agents run horton <id> "message"spawns and runs Horton locally- command authenticates using
ELECTRIC_AGENTS_RUNNER_TOKENor--token - command requires a local entity registry via
--registry, package config, or convention discovery - command fails before claiming work if no registry is found
- command fails before claiming work if the requested entity type is not registered locally
- server exposes
POST /_electric/runner/spawn-and-claim - spawned entity appears in the existing Agents UI
- timeline/events are written to the entity stream as usual
- claim heartbeat works during execution
- claim is completed on success
- claim is failed/released on error
- command exits non-zero on execution failure
runEntityOnce(...)exposes the same behavior programmatically without invoking the CLIrunEntityOnce(...)requires anEntityRegistryrunis documented as the attached execution form ofspawnrunrequires the runner process to have the entity code/registry available locally- no changes are required to existing entity definitions
- Dominant language
- TypeScript
- Stars
- 10.4k
- Forks
- 399
- PR merge metrics
- No merged PRs in 30d
Getting set up
- No Dockerfile or Docker Compose file
- No pull request template
- Read the contributing guide
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
More from electric-sql/electric
-
camelToSnake and snakeCamelMapper() drop the underscore when a digit precedes a camelCase boundaryOpen
Difficulty 2/5 1-3 hours Newbie friendliness 85/100
electric-sql/electric#4855 ·
-
ShapeStream does not notify subscribers when it gives up on a non-Error valuePossibly taken @Tyagiquamar claimed this 19 days ago. Open
Difficulty 2/5 1-3 hours Newbie friendliness 72/100
electric-sql/electric#4830 ·
-
@electric-sql/client throws SecurityError on import when the browser blocks site storage (typeof localStorage outside try)Possibly taken @mohanedmoh claimed this 37 days ago. Open
Difficulty 2/5 1-3 hours Newbie friendliness 72/100
electric-sql/electric#4826 · 1 comment ·
-
agents-chat-starter: spawn PUT goes to the durable-streams proxy, so no entity is created and agents never wakePossibly taken @adityavkk claimed this 133 days ago. Open
Difficulty 2/5 1-3 hours Newbie friendliness 78/100
electric-sql/electric#4687 ·
-
Listen IP addressOpenfeature request triage
Difficulty 2/5 1-3 hours Newbie friendliness 68/100
electric-sql/electric#4150 · 1 comment ·
All issues in electric-sql/electric
Similar issues
-
area:cli area:security bug priority:medium
Difficulty 2/5 1-3 hours Newbie friendliness 82/100
Maintainers usually reply within 1 day
-
"code source" and "numerique.gouv" links: "new window" mention duplicated in the accessible nameOpenaccessibility
Difficulty 2/5 1-3 hours Newbie friendliness 72/100
numerique-gouv/lasuite-landingpage#315 ·
Maintainers usually reply within 1 day
-
needs:triage
Difficulty 1/5 Under an hour Newbie friendliness 92/100
Maintainers usually reply within 1 day
-
Difficulty 1/5 Under an hour Newbie friendliness 72/100
HyeokjaeChoi/vaultme#585 ·
Maintainers usually reply within 1 day
-
enhancement priority/P2
Difficulty 2/5 1-3 hours Newbie friendliness 72/100
beettlle/pi-smart-router#200 ·