Add `electric agents run` using spawn-and-claim
Nessuno ha ancora preso questa issue.
Valutazione
- Difficoltà
- 5/5
- Tempo stimato
- Più di una settimana
- Idoneità per principianti
- 35/100
- Tipo di issue
- Funzionalità
- Chiarezza
- Abbastanza chiara
- Stato di attività
- Tranquilla
- Stack tecnologico
- typescript
- Ambito
- backend-api-design, cli
Direzione di ricerca
Inizia leggendo la logica esistente di spawn e claim/callback in packages/agents-server e packages/agents-runtime, quindi individua l'entry point della CLI per i comandi degli agenti. L'issue descrive l'endpoint di spawn-and-claim richiesto, il caricamento del registry locale, l'esecuzione dell'handler, l'heartbeat, lo streaming e il completamento o il fallimento del claim; il lavoro è completo quando questi elementi funzionano insieme con test per i percorsi di successo e di errore.
Scritto dal modello di indicizzazione a partire dal testo della issue.
Descrizione
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
- Lingua principale
- TypeScript
- Stelle
- 10.4k
- Fork
- 399
- Metriche di merge delle PR
- Nessuna PR unita negli ultimi 30g
Preparare l'ambiente
- Nessun Dockerfile né file Docker Compose
- Nessun modello di pull request
- Leggi la guida per i contributori
Come iniziare
- Leggi tutta la issue e poi la guida ai contributi del progetto.
- Commenta sulla issue per dire che te ne occupi tu — evita che due persone facciano lo stesso lavoro.
- Fai un fork del repository e lavora su un branch.
- Apri una pull request che faccia riferimento al numero della issue.
Altre issue di electric-sql/electric
-
camelToSnake and snakeCamelMapper() drop the underscore when a digit precedes a camelCase boundaryAperta
Difficoltà 2/5 1-3 ore Idoneità per principianti 85/100
electric-sql/electric#4855 ·
-
ShapeStream does not notify subscribers when it gives up on a non-Error valueForse già presa @Tyagiquamar l’ha presa 19 giorni fa. Aperta
Difficoltà 2/5 1-3 ore Idoneità per principianti 72/100
electric-sql/electric#4830 ·
-
@electric-sql/client throws SecurityError on import when the browser blocks site storage (typeof localStorage outside try)Forse già presa @mohanedmoh l’ha presa 37 giorni fa. Aperta
Difficoltà 2/5 1-3 ore Idoneità per principianti 72/100
electric-sql/electric#4826 · 1 commento ·
-
agents-chat-starter: spawn PUT goes to the durable-streams proxy, so no entity is created and agents never wakeForse già presa @adityavkk l’ha presa 133 giorni fa. Aperta
Difficoltà 2/5 1-3 ore Idoneità per principianti 78/100
electric-sql/electric#4687 ·
-
Listen IP addressApertafeature request triage
Difficoltà 2/5 1-3 ore Idoneità per principianti 68/100
electric-sql/electric#4150 · 1 commento ·
Tutte le issue di electric-sql/electric
Issue simili
-
clawsweeper:fix-shape-clear clawsweeper:queueable-fix clawsweeper:source-repro impact:ux-friction issue-rating: 🦞 diamond lobster no-stale P2
Difficoltà 2/5 1-3 ore Idoneità per principianti 68/100
openclaw/openclaw#199885 · 2 commenti · 1 reazione ·
I maintainer di solito rispondono entro 1 giorno
-
Difficoltà 2/5 1-3 ore Idoneità per principianti 88/100
-
feature needs-triage
Difficoltà 2/5 1-3 ore Idoneità per principianti 78/100
BoardGamesEmpire/board-games-empire-backend#1306 ·
I maintainer di solito rispondono entro 1 giorno
-
Difficoltà 2/5 1-3 ore Idoneità per principianti 80/100
sequant-io/sequant#1689 ·
I maintainer di solito rispondono entro 1 giorno
-
Difficoltà 2/5 1-3 ore Idoneità per principianti 80/100