Require meaningful slugs for spawned workers (#4621)

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:

```ts
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

```bash
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.

Author: KyleAMathews

.changeset/meaningful-worker-slugs.md

@@ -0,0 +1,5 @@
+---
+'@electric-ax/agents': patch
+---
+
+Require meaningful slugs when spawning workers and append a random suffix so worker URLs are easier to identify while remaining generally unique.

packages/agents/src/agents/horton.ts

@@ -333,7 +333,7 @@ Dispatch a worker when:
 - The subtask is independent and can run in parallel with other work.
 - You need an isolated context (e.g., focused coding on one file without pulling its full content into our chat).
 
-When you spawn a worker, write its system prompt the way you'd brief a colleague who just walked in: include file paths, line numbers, what specifically to do, and what form of answer you want back. The system prompt sets the worker's persona and constraints; the required initialMessage is the concrete task you're handing off — that's what kicks the worker off, so without it the worker sits idle.
+When you spawn a worker, provide a short meaningful slug for the worker path (for example, \`auth-audit\` or \`api-test-fix\`) and write its system prompt the way you'd brief a colleague who just walked in: include file paths, line numbers, what specifically to do, and what form of answer you want back. The system prompt sets the worker's persona and constraints; the required initialMessage is the concrete task you're handing off — that's what kicks the worker off, so without it the worker sits idle.
 
 After spawning, end your turn (optionally with a brief "I've dispatched a worker for X; I'll respond when it finishes"). When the worker finishes, you'll receive a message describing which worker completed and what it returned. Multiple workers may finish at different times — check the message for the worker URL to know which one you're hearing about.
 

packages/agents/src/tools/fork.ts

@@ -23,7 +23,7 @@ Omit 'entityUrl' to fork your own session. Pass a different session's URL to for
       ),
       id: Type.Optional(
         Type.String({
-          description: `Instance id for the new fork (the \`<id>\` in \`/horton/<id>\`). Mirrors spawn_worker's id parameter. Omit to let the server assign one.`,
+          description: `Instance id for the new fork (the \`<id>\` in \`/horton/<id>\`). Omit to let the server assign one.`,
         })
       ),
       initialMessage: Type.Optional(
@@ -52,8 +52,7 @@ Omit 'entityUrl' to fork your own session. Pass a different session's URL to for
         // The library API (`ctx.fork` / `ctx.forkSelf`) requires an id
         // — same shape as `ctx.spawn(type, id, ...)`. The model layer
         // doesn't need to know this; we generate one via nanoid when
-        // it's not supplied (same pattern `createSpawnWorkerTool` uses
-        // for the worker's id).
+        // it's not supplied.
         const forkId = id ?? `fork-${nanoid(10)}`
         const handle =
           entityUrl !== undefined

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

@@ -1,5 +1,5 @@
 import { Type } from '@sinclair/typebox'
-import { nanoid } from 'nanoid'
+import { randomBytes } from 'node:crypto'
 import { serverLog } from '../log'
 import type { BuiltinAgentModelConfig } from '../model-catalog'
 import type { AgentTool } from '@mariozechner/pi-agent-core'
@@ -18,15 +18,33 @@ export const WORKER_TOOL_NAMES = [
 
 export type WorkerToolName = (typeof WORKER_TOOL_NAMES)[number]
 
+const MAX_WORKER_SLUG_LENGTH = 48
+
+function normalizeWorkerSlug(slug: unknown): string {
+  if (typeof slug !== `string`) return ``
+
+  return slug
+    .trim()
+    .toLowerCase()
+    .replace(/[^a-z0-9._-]+/g, `-`)
+    .replace(/-+/g, `-`)
+    .replace(/^-+|-+$/g, ``)
+    .slice(0, MAX_WORKER_SLUG_LENGTH)
+    .replace(/^-+|-+$/g, ``)
+}
+
 export function createSpawnWorkerTool(
   ctx: HandlerContext,
   modelConfig?: BuiltinAgentModelConfig
 ): AgentTool {
   return {
     name: `spawn_worker`,
     label: `Spawn Worker`,
-    description: `Dispatch a subagent (worker) to perform an isolated subtask. Provide a brief system prompt to give it its role and then a detailed initialMessage which briefs the worker like a colleague who just walked into the room (file paths, line numbers, what specifically to do, what form of answer you want back) and pick the subset of tools the worker needs.`,
+    description: `Dispatch a subagent (worker) to perform an isolated subtask. Provide a meaningful slug for the worker path, a brief system prompt to give it its role, then a detailed initialMessage which briefs the worker like a colleague who just walked into the room (file paths, line numbers, what specifically to do, what form of answer you want back), and pick the subset of tools the worker needs. The slug is normalized and a few random bytes are appended to keep the worker path unique.`,
     parameters: Type.Object({
+      slug: Type.String({
+        description: `Short, meaningful slug for this worker, used as the start of its path. Use lowercase words separated by hyphens, e.g. "audit-auth-flow". A random suffix is added automatically for uniqueness.`,
+      }),
       systemPrompt: Type.String({
         description: `System prompt for the worker.`,
       }),
@@ -41,11 +59,25 @@ export function createSpawnWorkerTool(
       }),
     }),
     execute: async (_toolCallId, params) => {
-      const { systemPrompt, tools, initialMessage } = params as {
+      const { slug, systemPrompt, tools, initialMessage } = params as {
+        slug: string
         systemPrompt: string
         tools: Array<WorkerToolName>
         initialMessage: string
       }
+      const normalizedSlug = normalizeWorkerSlug(slug)
+      if (normalizedSlug.length === 0 || !/[a-z0-9]/.test(normalizedSlug)) {
+        return {
+          content: [
+            {
+              type: `text` as const,
+              text: `Error: slug is required and must contain at least one letter or number.`,
+            },
+          ],
+          details: { spawned: false },
+        }
+      }
+
       if (!Array.isArray(tools) || tools.length === 0) {
         return {
           content: [
@@ -69,7 +101,7 @@ export function createSpawnWorkerTool(
         }
       }
 
-      const id = nanoid(10)
+      const id = `${normalizedSlug}-${randomBytes(3).toString(`hex`)}`
       const workerModelArgs = modelConfig
         ? {
             provider: modelConfig.provider,

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

@@ -11,6 +11,7 @@ describe(`spawn_worker tool`, () => {
     const ctx = { spawn } as any
     const tool = createSpawnWorkerTool(ctx)
     const result = await tool.execute(`call-1`, {
+      slug: `file-size-check`,
       systemPrompt: `Read /tmp/foo and report its size`,
       tools: [`read`, `bash`],
       initialMessage: `Please check the size of /tmp/foo and report back`,
@@ -21,7 +22,7 @@ describe(`spawn_worker tool`, () => {
     const [type, id, args, opts] = call as Array<any>
     expect(type).toBe(`worker`)
     expect(typeof id).toBe(`string`)
-    expect(id.length).toBeGreaterThanOrEqual(10)
+    expect(id).toMatch(/^file-size-check-[0-9a-f]{6}$/)
     expect(args).toEqual({
       systemPrompt: `Read /tmp/foo and report its size`,
       tools: [`read`, `bash`],
@@ -52,6 +53,7 @@ describe(`spawn_worker tool`, () => {
     })
 
     await tool.execute(`call-model`, {
+      slug: `model-worker`,
       systemPrompt: `Do a thing`,
       tools: [`read`],
       initialMessage: `Please do it`,
@@ -67,11 +69,70 @@ describe(`spawn_worker tool`, () => {
     })
   })
 
+  it(`normalizes the slug before appending a random suffix`, async () => {
+    const spawn = vi.fn(async (type, id) => ({
+      entityUrl: `/${type}/${id}`,
+      writeToken: `tok`,
+      txid: 1,
+    }))
+    const ctx = { spawn } as any
+    const tool = createSpawnWorkerTool(ctx)
+
+    await tool.execute(`call-slug`, {
+      slug: `  Audit Auth Flow!!  `,
+      systemPrompt: `Do a thing`,
+      tools: [`read`],
+      initialMessage: `Please do it`,
+    })
+
+    const [, id] = spawn.mock.calls[0]! as Array<any>
+    expect(id).toMatch(/^audit-auth-flow-[0-9a-f]{6}$/)
+  })
+
+  it(`caps the normalized slug before appending a random suffix`, async () => {
+    const spawn = vi.fn(async (type, id) => ({
+      entityUrl: `/${type}/${id}`,
+      writeToken: `tok`,
+      txid: 1,
+    }))
+    const ctx = { spawn } as any
+    const tool = createSpawnWorkerTool(ctx)
+
+    await tool.execute(`call-long-slug`, {
+      slug: `this is a very long worker slug that should be capped before it reaches the worker path`,
+      systemPrompt: `Do a thing`,
+      tools: [`read`],
+      initialMessage: `Please do it`,
+    })
+
+    const [, id] = spawn.mock.calls[0]! as Array<any>
+    expect(id).toMatch(
+      /^this-is-a-very-long-worker-slug-that-should-be-c-[0-9a-f]{6}$/
+    )
+  })
+
+  it(`rejects when slug is missing or empty after normalization`, async () => {
+    const spawn = vi.fn()
+    const ctx = { spawn } as any
+    const tool = createSpawnWorkerTool(ctx)
+    const result = await tool.execute(`call-no-slug`, {
+      slug: `!!!`,
+      systemPrompt: `do something`,
+      tools: [`bash`],
+      initialMessage: `go`,
+    })
+    expect((result.content[0] as { text: string }).text).toMatch(
+      /slug is required/i
+    )
+    expect(spawn).not.toHaveBeenCalled()
+  })
+
   it(`rejects when tools is empty`, async () => {
     const spawn = vi.fn()
     const ctx = { spawn } as any
     const tool = createSpawnWorkerTool(ctx)
     const result = await tool.execute(`call-2`, {
+      slug: `empty-tools`,
       systemPrompt: `do something`,
       tools: [],
       initialMessage: `go`,
@@ -87,13 +148,15 @@ describe(`spawn_worker tool`, () => {
     const ctx = { spawn } as any
     const tool = createSpawnWorkerTool(ctx)
     const missing = await tool.execute(`call-3`, {
+      slug: `missing-message`,
       systemPrompt: `do something`,
       tools: [`bash`],
     } as any)
     expect((missing.content[0] as { text: string }).text).toMatch(
       /initialMessage is required/i
     )
     const empty = await tool.execute(`call-4`, {
+      slug: `empty-message`,
       systemPrompt: `do something`,
       tools: [`bash`],
       initialMessage: ``,