Require meaningful slugs for spawned workers

[KyleAMathews]

Require spawn_worker calls to include a meaningful slug, then append a short random suffix so spawned worker URLs are readable and generally unique. This makes child worker paths easier to identify in wake messages, logs, and the UI.

Root Cause

Workers previously used an opaque nanoid(10) id, so spawned worker URLs were unique but not meaningful. When multiple workers were dispatched, agents and humans had to infer purpose from surrounding context instead of the worker path itself.

Approach

• Add a required slug parameter to the spawn_worker tool schema.
• Normalize the slug into a safe path prefix:
  • trim whitespace
  • lowercase
  • replace unsupported characters with -
  • collapse repeated hyphens
  • trim leading/trailing hyphens
  • cap at 48 characters
• Append a short random hex suffix to avoid routine collisions:

const id = `${normalizedSlug}-${randomBytes(3).toString(`hex`)}`

• Reject slugs that normalize to no meaningful letter/number content before spawning.
• Update Horton’s worker-spawning instructions to tell it to provide short meaningful slugs.
• Remove stale fork-tool wording that said fork ids mirror the old spawn_worker id parameter.
• Add a changeset for @electric-ax/agents.

Key Invariants

• Every spawned worker id starts with a meaningful slug.
• Worker ids remain generally unique via the random suffix.
• Invalid slugs do not call ctx.spawn.
• Existing worker behavior remains otherwise unchanged:
  • selected tools are forwarded
  • model config is forwarded
  • initial message is forwarded
  • runFinished wake with response remains enabled
  • sandbox inheritance remains enabled

Non-goals

• This does not require globally collision-proof worker ids. If an unlikely slug/suffix collision occurs, spawning fails and the agent can retry.
• This does not restrict slugs to hyphen-only text; dots and underscores remain allowed because worker ids become URLs and can be encoded.
• This does not change the fork id generation behavior beyond removing stale documentation.

Trade-offs

The implementation uses a small random suffix rather than UUID/nanoid-level entropy to keep worker URLs compact. That preserves readability while still avoiding collisions in normal use. Slugs are capped at 48 characters to avoid unwieldy URLs, at the cost of truncating very long model-provided labels.

Verification

pnpm --filter @electric-ax/agents typecheck
pnpm --filter @electric-ax/agents exec vitest run test/spawn-worker-tool.test.ts
GITHUB_BASE_REF=main node scripts/check-changeset.mjs

Files changed

• .changeset/meaningful-worker-slugs.md

  • Adds a patch changeset for @electric-ax/agents.

• packages/agents/src/tools/spawn-worker.ts

  • Requires slug.
  • Normalizes and caps slug values.
  • Appends a random hex suffix to form the worker id.
  • Rejects non-meaningful slugs before spawning.

• packages/agents/test/spawn-worker-tool.test.ts

  • Updates existing spawn-worker tests to pass slugs.
  • Adds coverage for slug normalization, slug length capping, and invalid slug rejection.

• packages/agents/src/agents/horton.ts

  • Updates Horton’s instructions to provide meaningful slugs when spawning workers.

• packages/agents/src/tools/fork.ts

  • Removes stale wording tying fork ids to spawn_worker id behavior.

[github-actions]

Electric Agents Desktop Builds

Build artifacts for commit a20bc8e.

Platform	Status	Artifact
macOS Apple Silicon	Passed	DMG
macOS Intel	Passed	DMG
Windows x64	Passed	Installer
Linux x64	Passed	AppImage / deb

Workflow run

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 71.70%. Comparing base (16c8339) to head (a20bc8e).
✅ All tests successful. No failed tests found.

Additional details and impacted files

@@            Coverage Diff             @@
##             main    #4621      +/-   ##
==========================================
+ Coverage   71.68%   71.70%   +0.01%     
==========================================
  Files          84       84              
  Lines       10155    10162       +7     
  Branches     3252     3254       +2     
==========================================
+ Hits         7280     7287       +7     
  Misses       2855     2855              
  Partials       20       20              

Flag	Coverage Δ
packages/agents	72.74% <100.00%> (+0.12%)	⬆️
packages/agents-server	75.32% <ø> (ø)
packages/electric-ax	47.62% <ø> (ø)
typescript	71.70% <100.00%> (+0.01%)	⬆️
unit-tests	71.70% <100.00%> (+0.01%)	⬆️

Flags with carried forward coverage won't be shown. Click here to find out more.

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

[github-actions]

Electric Agents Mobile Build

Local mobile checks ran for commit 2f86849.

The EAS Android preview build was skipped because the mobile-eas-build label is not present.
Add the mobile-eas-build label to this PR to produce an installable preview build.

Workflow run

[samwillis]

LGTM