Roadmap: run your org locally: the server's agent hierarchy as a swarm alongside you (opt-in)

Abierto
  • ¿Algo no está bien?
#438 4 comentarios 0 reacciones 0 asignados Ver en GitHub

Los mantenedores suelen responder en 1 día

Nadie ha tomado este issue todavía.

Evaluación

Dificultad
5/5
Tiempo estimado
Más de una semana
Aptitud para principiantes
5/100
Tipo de issue
Nueva funcionalidad
Claridad
Necesita aclaración
Estado de actividad
Activo
Stack tecnológico
electron, ollama, typescript
Área
ai-infra-agents

Línea de trabajo

This is an unscheduled roadmap, so there is no fixed task. The payload points at the local governance store, wake queue, coordinator and scheduler in Projects, and at the server's heartbeat and lease model. Starting here means agreeing the mode (A, B or C) and the lease design with maintainers before any code. Done means a written design and an approved scope, not a patch.

Escrito por el modelo de indexación a partir del texto del issue.

Descripción

area:projects p2 type:feature

Roadmap. Not scheduled yet.

Today Muster polls a snapshot of a Muster Server (Paperclip) org, and a person can check out one task to work on locally. The org's own architecture stays on the server: its roles, chain of command, wakes, delegation, review stages, budgets and routines. Users should be able to run their org locally with that same architecture, as a swarm of role agents working alongside them while they chat. Without that, working locally loses much of its point.

How the server orchestrates (from the Paperclip source)

  • Heartbeats, not long-running agents. Every trigger goes through heartbeat.wakeup(agentId, {source, reason, payload, idempotencyKey}). The sources are timer, assignment, on-demand and automation. Wakes also come from comments, resolved blockers, approvals and decisions (issue-*-wakeup.ts, decision-wakeup.ts). Wakes are coalesced and suppressed in heartbeat/queue.ts.
  • Each run:
    1. Read identity and chainOfCommand (the reportsTo walk).
    2. Pick from the inbox in this order: in progress, then in review if woken by a comment, then to do.
    3. Check out atomically (checkoutRunId/executionRunId). A 409 means never retry.
    4. Do the work, then leave an explicit disposition: done, blocked (with a routable wait) or in review.
    5. Compare-and-clear the locks. Recovery reclaims stale locks.
  • Delegation creates child issues and blockers. A parent wakes when its blockers resolve. Hiring goes through can_create_agents, optionally with an approval. The "CEO" is simply the agent with no reportsTo.
  • Review and approval stages live in executionPolicy.stages[]. Each participant's PATCH advances the stage or requests changes. Thread interactions are suggest_tasks, ask_user_questions, request_confirmation, checkbox, item verdicts and connection intent. Each carries a resolver and continuation policy.
  • Budgets are scoped by company, agent or project, in billed cents per month or lifetime, with incidents and daily run and cost caps. Routines cover cron, webhook and API triggers, with concurrency and catch-up policies.

What Muster already has locally

Projects already re-implements much of this. It has the governance store (wakes and runs, holds, execution-policy state, watchdogs, monitors, breakers), the wake queue, coordinator, review, watchdog and hire blocks with reportsTo, interactions, the scheduler (leases, concurrency, budgets), project governance timers and the mailbox.

What's missing

  1. A live two-way sync of roster, reportsTo, execution policy and budgets. Import is one-shot today.
  2. A mapping from server agents to local role agents: instruction bundle, adapter and model, permissions.
  3. Server-equivalent budget policies (agent and company scope, billed cents, incidents, daily caps).
  4. Routines as a local scheduler.
  5. Server review and approval stages mapped onto the local review flow, with write-back to the server.
  6. Chain-of-command context for role agents, and server-style routing of comments and mentions.

Stays on the server: the authoritative assignee and lock, the audit trail, approvals bound to real board users, secret grants, company-wide budget enforcement. Local agents act only through the existing API with the person's token.

Modes

  • A. One task locally. This is today's mode. It is safe because a human-assigned task never wakes a server agent.
  • B. Hybrid. Check out a subtree or a role. Local agents work that slice and the server keeps the rest. Needs a subtree lease.
  • C. Mirror the org. Local role agents act as the org's roles in a Project, with write-through sync to the server. Server agents for mirrored roles are paused, or the roles are explicitly taken over.

Opt-in, never automatic: a setting in Settings, or Muster asks the first time you work in an org or project how you want to use it (A, B or C) and why.

Risks

  • Double execution with server wakes: take roles over explicitly and verify the lease before every local start.
  • Leases: a lease per role, with expiry and renewal, and compare-and-clear like the server's.
  • Cost: report cost events up and enforce a local cap before each wake.
  • Secrets: references only, never values.
  • Sync conflicts: every write checks that the server still looks as expected.
  • Fan-out loops: keep the circuit breakers, concurrency cap and holds, and add a per-org daily run cap.

UI: a swarm with you, without clutter

Keep the current look and add no new top-level surfaces.

  • One chat. The person's conversation stays a single chat. Role agents appear as small chips (name and title) on task rows.
  • Agent-to-agent traffic collapses to one activity line per task ("CTO delegated 3 tasks · QA reviewing"). It expands to the mailbox thread.
  • Org strip. A collapsed strip shows live state dots (idle, running, waiting on you, blocked) and the reporting tree on hover. It is hosted in the existing Roster.
  • Needs-you items (questions, approvals, secret requests) go to the existing Inbox, not inline.
  • Status pill. A small pill ("Org local · 4 running · budget 62%") opens the strip and has Pause all.
  • No streaming by default. Events are grouped by wake reason and task. An agent's tokens stream only when you open its run.

The UI needs its own design pass with before and after screenshots before any build.

Related: #434 (full task context locally), #134 (local org onboarding), #168 (Huddle), #143 (remaining parity), #150 (circuit breaker), #151 (limit-aware scheduler).

Lenguaje dominante
TypeScript
Estrellas
3
Forks
0
Merge medio
17 h 33 min
PR fusionados (30 d)
163

Preparar el entorno

Primeros pasos

  1. Lee el issue completo y luego la guía de contribución del proyecto.
  2. Comenta en el issue que vas a ocuparte — evita que dos personas hagan lo mismo.
  3. Haz un fork del repositorio y trabaja en una rama.
  4. Abre un pull request que haga referencia al número del issue.

Más de musterhq/muster-code

Todos los issues de musterhq/muster-code

Issues similares

Más issues de TypeScript

Recibe los nuevos issues en tu correo

Un resumen breve de issues de GitHub para principiantes.