Add `electric agents run` using spawn-and-claim
まだ誰も着手していません。
評価
- 難易度
- 5/5
- 見積もり時間
- 1週間以上
- 初心者へのやさしさ
- 35/100
- issue の種類
- 機能追加
- 明瞭さ
- おおむね明確
- 活発さ
- 静か
- 技術スタック
- typescript
調査の方向性
まず packages/agents-server と packages/agents-runtime にある既存の spawn および claim/callback の仕組みを読み、次にエージェントコマンドの CLI エントリポイントを特定します。Issue では、必要な spawn-and-claim エンドポイント、ローカルレジストリの読み込み、ハンドラーの実行、heartbeat、ストリーミング、claim の完了または失敗について説明されています。成功パスとエラーパスのテストを含め、これらの要素が連携して動作すれば完了です。
索引モデルが issue の本文から書いたものです。
説明
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
- 主要言語
- TypeScript
- スター
- 10.4k
- フォーク
- 399
- PR マージ指標
- 30日以内にマージされた PR はありません
環境構築
- Dockerfile・Docker Compose ファイルなし
- プルリクエストのテンプレートなし
- コントリビューションガイドを読む
はじめの一歩
- issue を最後まで読み、次にプロジェクトのコントリビューションガイドを読みます。
- 着手することを issue にコメントします — 二人が同じ作業をするのを防げます。
- リポジトリをフォークし、ブランチを切って変更します。
- issue 番号を参照したプルリクエストを送ります。
electric-sql/electric のほかの issue
-
camelToSnake and snakeCamelMapper() drop the underscore when a digit precedes a camelCase boundaryオープン
難易度 2/5 1〜3時間 初心者へのやさしさ 85/100
electric-sql/electric#4855 ·
-
ShapeStream does not notify subscribers when it gives up on a non-Error value対応中かも @Tyagiquamar が 19 日前に担当しました。 オープン
難易度 2/5 1〜3時間 初心者へのやさしさ 72/100
electric-sql/electric#4830 ·
-
@electric-sql/client throws SecurityError on import when the browser blocks site storage (typeof localStorage outside try)対応中かも @mohanedmoh が 37 日前に担当しました。 オープン
難易度 2/5 1〜3時間 初心者へのやさしさ 72/100
electric-sql/electric#4826 · コメント 1 件 ·
-
agents-chat-starter: spawn PUT goes to the durable-streams proxy, so no entity is created and agents never wake対応中かも @adityavkk が 133 日前に担当しました。 オープン
難易度 2/5 1〜3時間 初心者へのやさしさ 78/100
electric-sql/electric#4687 ·
-
Listen IP addressオープンfeature request triage
難易度 2/5 1〜3時間 初心者へのやさしさ 68/100
electric-sql/electric#4150 · コメント 1 件 ·
electric-sql/electric の issue をすべて見る
似ている issue
-
clawsweeper:fix-shape-clear clawsweeper:queueable-fix clawsweeper:source-repro impact:ux-friction issue-rating: 🦞 diamond lobster no-stale P2
難易度 2/5 1〜3時間 初心者へのやさしさ 68/100
openclaw/openclaw#199885 · コメント 2 件 · リアクション 1 件 ·
メンテナーはふだん 1 日以内に返信
-
難易度 2/5 1〜3時間 初心者へのやさしさ 88/100
-
feature needs-triage
難易度 2/5 1〜3時間 初心者へのやさしさ 78/100
BoardGamesEmpire/board-games-empire-backend#1306 ·
メンテナーはふだん 1 日以内に返信
-
難易度 2/5 1〜3時間 初心者へのやさしさ 80/100
sequant-io/sequant#1689 ·
メンテナーはふだん 1 日以内に返信
-
難易度 2/5 1〜3時間 初心者へのやさしさ 80/100