@opengroundplan/core 0.1.1

package/templates/architectures/multi-agent/files/src/__solutionName.snake__/agents/orchestrator/budget.py

@@ -0,0 +1,45 @@
+"""Per-run token ledger.
+
+Budget is reserved before dispatch and reconciled after, because refusing one spawn is far
+cheaper than discovering the overrun once five workers have already spent it.
+"""
+
+from __future__ import annotations
+
+from ..contracts import TokenUsage
+
+
+class BudgetExceededError(RuntimeError):
+    def __init__(self, requested: int, remaining: int) -> None:
+        super().__init__(f"Run token budget exhausted: needed {requested}, {remaining} remaining")
+        self.requested = requested
+        self.remaining = remaining
+
+
+class RunBudget:
+    __slots__ = ("_limit", "_reserved", "_spent")
+
+    def __init__(self, limit: int) -> None:
+        self._limit = limit
+        self._reserved = 0
+        self._spent = 0
+
+    @property
+    def spent(self) -> int:
+        return self._spent
+
+    @property
+    def remaining(self) -> int:
+        """Reservations and actuals overlap, so the larger of the two is what is committed."""
+        return self._limit - max(self._reserved, self._spent)
+
+    def reserve(self, tokens: int) -> None:
+        if tokens > self.remaining:
+            raise BudgetExceededError(tokens, self.remaining)
+        self._reserved += tokens
+
+    def release(self, tokens: int) -> None:
+        self._reserved = max(0, self._reserved - tokens)
+
+    def record(self, usage: TokenUsage) -> None:
+        self._spent += usage.total

package/templates/architectures/multi-agent/files/src/__solutionName.snake__/agents/orchestrator/fanout.py

@@ -0,0 +1,63 @@
+"""The only path to a worker.
+
+Cap first, budget second, concurrency third — an orchestrator that plans twenty workers must
+fail loudly rather than quietly cost twenty times as much.
+"""
+
+from __future__ import annotations
+
+import asyncio
+from collections.abc import Awaitable, Callable, Sequence
+from typing import Any
+
+from ..config import AgentConfig, agent_config
+from ..contracts import WorkerResult, WorkerTask, condense
+from .budget import BudgetExceededError, RunBudget
+
+Dispatch = Callable[[WorkerTask], Awaitable[dict[str, Any]]]
+
+
+class FanOutCapExceededError(RuntimeError):
+    def __init__(self, planned: int, cap: int) -> None:
+        super().__init__(
+            f"Planned {planned} workers, cap is {cap} — narrow the plan or raise the cap in config"
+        )
+
+
+async def fan_out(
+    tasks: Sequence[WorkerTask],
+    dispatch: Dispatch,
+    budget: RunBudget,
+    config: AgentConfig | None = None,
+) -> list[WorkerResult]:
+    config = config or agent_config()
+    if len(tasks) > config.fan_out_cap:
+        raise FanOutCapExceededError(len(tasks), config.fan_out_cap)
+
+    gate = asyncio.Semaphore(max(1, config.worker_concurrency))
+
+    async def guarded(task: WorkerTask) -> WorkerResult:
+        async with gate:
+            return await _dispatch_one(task, dispatch, budget, config)
+
+    return list(await asyncio.gather(*(guarded(task) for task in tasks)))
+
+
+async def _dispatch_one(
+    task: WorkerTask, dispatch: Dispatch, budget: RunBudget, config: AgentConfig
+) -> WorkerResult:
+    reservation = min(task.token_budget, config.worker_token_budget)
+    try:
+        budget.reserve(reservation)
+    except BudgetExceededError as error:
+        # A starved worker degrades the answer; aborting the run throws away what already cost money.
+        return condense(task, {"summary": str(error), "status": "budget-exceeded"}, config.summary_char_limit)
+
+    try:
+        result = condense(task, await dispatch(task), config.summary_char_limit)
+        budget.record(result.usage)
+        return result
+    except Exception as error:  # one worker failing must not abort the whole fan-out
+        return condense(task, {"summary": str(error), "status": "failed"}, config.summary_char_limit)
+    finally:
+        budget.release(reservation)

package/templates/architectures/multi-agent/files/src/__solutionName.snake__/agents/orchestrator/lead.py

@@ -0,0 +1,92 @@
+"""The lead agent: plan, fan out, synthesize from summaries only."""
+
+from __future__ import annotations
+
+import json
+from dataclasses import dataclass
+from typing import Any
+
+from ..config import agent_config
+from ..contracts import WorkerResult, WorkerTask
+from ..runtime import RunnerRequest, get_runner
+from ..workers import dispatch_to_worker, known_workers
+from .budget import RunBudget
+from .fanout import fan_out
+
+# Effort is scaled to the query, not fixed: a lookup wants one worker, a comparison two to four.
+# Over-fanning a simple question is the most expensive mistake this architecture makes.
+_PLANNER_SYSTEM = "\n".join(
+    [
+        "You are the lead agent. Break the query into independent worker briefs and return JSON only:",
+        "an array of objects with keys objective, outputFormat, tools, boundaries, workerId.",
+        "Every brief needs all of them — underspecified briefs make workers duplicate each other.",
+        "Briefs must not overlap; workers cannot see each other or ask you questions mid-run.",
+        "Scale effort to the query: one brief for a simple lookup, two to four for a comparison.",
+        "Available workers: {workers}. Never plan more than {cap} briefs.",
+    ]
+)
+
+
+@dataclass(frozen=True, slots=True)
+class RunOutcome:
+    answer: str
+    workers: tuple[WorkerResult, ...]
+    tokens_spent: int
+
+
+async def run_lead(query: str) -> RunOutcome:
+    config = agent_config()
+    budget = RunBudget(config.run_token_budget)
+    runner = get_runner()
+
+    plan = await runner.run(
+        RunnerRequest(
+            role="lead-planner",
+            system=_PLANNER_SYSTEM.format(workers=", ".join(known_workers()), cap=config.fan_out_cap),
+            prompt=query,
+            max_output_tokens=config.worker_token_budget,
+        )
+    )
+    budget.record(plan.usage)
+
+    tasks = _parse_plan(plan.text, config.worker_token_budget)[: config.fan_out_cap]
+    results = await fan_out(tasks, dispatch_to_worker, budget, config)
+
+    # The lead synthesizes from summaries only; this is where the context stays small.
+    answer = await runner.run(
+        RunnerRequest(
+            role="lead-synthesizer",
+            system="Answer the query using only the worker summaries below. Cite the sources they give.",
+            prompt=query + "\n\n" + "\n\n".join(_render(r) for r in results),
+            max_output_tokens=config.worker_token_budget,
+        )
+    )
+    budget.record(answer.usage)
+
+    return RunOutcome(answer=answer.text, workers=tuple(results), tokens_spent=budget.spent)
+
+
+def _render(result: WorkerResult) -> str:
+    return f"[{result.worker_id} {result.status}] {result.summary}\nSources: {', '.join(result.citations)}"
+
+
+def _parse_plan(text: str, token_budget: int) -> list[WorkerTask]:
+    """Models wrap JSON in prose often enough that slicing to the outermost array is the safe read."""
+    start, end = text.find("["), text.rfind("]")
+    if start == -1 or end <= start:
+        return []
+
+    briefs: list[dict[str, Any]] = json.loads(text[start : end + 1])
+    fallback = known_workers()[0]
+    return [
+        WorkerTask(
+            id=f"task-{index + 1}",
+            worker_id=str(brief.get("workerId")) if brief.get("workerId") in known_workers() else fallback,
+            objective=str(brief.get("objective", "")),
+            output_format=str(brief.get("outputFormat", "A short prose summary with sources.")),
+            tools=tuple(str(t) for t in brief.get("tools", ())),
+            boundaries=tuple(str(b) for b in brief.get("boundaries", ())),
+            token_budget=token_budget,
+        )
+        for index, brief in enumerate(briefs)
+    ]

package/templates/architectures/multi-agent/files/src/__solutionName.snake__/agents/runtime/__init__.py

@@ -0,0 +1,5 @@
+"""The only package permitted to import a model SDK; everything else goes through AgentRunner."""
+
+from .runner import AgentRunner, RunnerRequest, RunnerResponse, get_runner, set_runner
+
+__all__ = ["AgentRunner", "RunnerRequest", "RunnerResponse", "get_runner", "set_runner"]

package/templates/architectures/multi-agent/files/src/__solutionName.snake__/agents/runtime/runner.py

@@ -0,0 +1,48 @@
+"""The single seam to the model provider.
+
+Only this package may talk to an SDK, which is what makes the run ledger complete — one
+unmetered call somewhere else silently invalidates the budget.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Protocol
+
+from ..contracts import TokenUsage
+
+
+@dataclass(frozen=True, slots=True)
+class RunnerRequest:
+    #: Purpose, not model id — the binding resolves the model from this.
+    role: str
+    system: str
+    prompt: str
+    max_output_tokens: int
+
+
+@dataclass(frozen=True, slots=True)
+class RunnerResponse:
+    text: str
+    usage: TokenUsage
+
+
+class AgentRunner(Protocol):
+    """Implementations are shared across concurrent workers and must be concurrency-safe."""
+
+    async def run(self, request: RunnerRequest) -> RunnerResponse: ...
+
+
+_bound: AgentRunner | None = None
+
+
+def set_runner(runner: AgentRunner) -> None:
+    """Bind at startup, next to wherever the app builds its LLM client."""
+    global _bound
+    _bound = runner
+
+
+def get_runner() -> AgentRunner:
+    if _bound is None:
+        raise RuntimeError("No AgentRunner bound — call set_runner() at startup. See docs/architecture/.")
+    return _bound

package/templates/architectures/multi-agent/files/src/__solutionName.snake__/agents/workers/__init__.py

@@ -0,0 +1,27 @@
+"""Worker registry, so the lead names a worker instead of importing one.
+
+One sub-package per worker, each running in its own context. Copy
+``{{ workerName | snake }}/`` to add another and register it below. A worker may import
+``..contracts``, ``..runtime`` and ``..config``, and nothing else under ``agents``.
+"""
+
+from collections.abc import Awaitable, Callable
+from typing import Any
+
+from ..contracts import WorkerTask
+from .{{ workerName | snake }}.worker import run_{{ workerName | snake }}
+
+_WORKERS: dict[str, Callable[[WorkerTask], Awaitable[dict[str, Any]]]] = {
+    "{{ workerName | kebab }}": run_{{ workerName | snake }},
+}
+
+
+def known_workers() -> list[str]:
+    return list(_WORKERS)
+
+
+async def dispatch_to_worker(task: WorkerTask) -> dict[str, Any]:
+    worker = _WORKERS.get(task.worker_id)
+    if worker is None:
+        raise KeyError(f"Unknown worker {task.worker_id!r}. Known: {', '.join(known_workers())}")
+    return await worker(task)

package/templates/architectures/multi-agent/files/src/__solutionName.snake__/agents/workers/__workerName.snake__/__init__.py

@@ -0,0 +1,9 @@
+"""{{ workerName | title }} worker — one isolated context, one specialization.
+
+Two workers with overlapping objectives pay twice for one answer, which is the failure mode
+this architecture is most prone to.
+"""
+
+from .worker import run_{{ workerName | snake }}
+
+__all__ = ["run_{{ workerName | snake }}"]

package/templates/architectures/multi-agent/files/src/__solutionName.snake__/agents/workers/__workerName.snake__/prompt.py

@@ -0,0 +1,31 @@
+"""A worker's entire context is this brief plus what its own tools return.
+
+It never sees the lead's history, so anything missing here is missing for good.
+"""
+
+from __future__ import annotations
+
+import re
+
+from ...contracts import WorkerTask
+
+_URL = re.compile(r"https?://\S+")
+
+
+def brief(task: WorkerTask, max_steps: int) -> str:
+    return "\n".join(
+        [
+            "You are a {{ workerName | title }} worker running in isolation.",
+            f"Objective: {task.objective}",
+            f"Output format: {task.output_format}",
+            f"Tools you may use: {', '.join(task.tools) or 'none'}",
+            f"Out of scope: {'; '.join(task.boundaries) or 'nothing specified'}",
+            f"Stop after at most {max_steps} tool calls and report what you have.",
+            'Return a condensed summary, not a transcript. End with a line "Sources:" listing every URL.',
+        ]
+    )
+
+
+def citations_of(text: str) -> tuple[str, ...]:
+    """The lead only sees what the worker kept, so citations must be machine-readable."""
+    return tuple(dict.fromkeys(_URL.findall(text)))

package/templates/architectures/multi-agent/files/src/__solutionName.snake__/agents/workers/__workerName.snake__/worker.py

@@ -0,0 +1,28 @@
+"""One worker, one isolated context: it receives a brief and returns a summary, never its run."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from ...config import agent_config
+from ...contracts import WorkerTask
+from ...runtime import RunnerRequest, get_runner
+from .prompt import brief, citations_of
+
+
+async def run_{{ workerName | snake }}(task: WorkerTask) -> dict[str, Any]:
+    config = agent_config()
+    response = await get_runner().run(
+        RunnerRequest(
+            role="{{ workerName | kebab }}-worker",
+            system=brief(task, config.worker_max_steps),
+            prompt=task.objective,
+            max_output_tokens=min(task.token_budget, config.worker_token_budget),
+        )
+    )
+    return {
+        "summary": response.text,
+        "citations": citations_of(response.text),
+        "usage": response.usage,
+        "status": "ok",
+    }

package/templates/architectures/multi-agent/files/src/agents/config.ts

@@ -0,0 +1,46 @@
+/**
+ * Every agent-runtime limit lives here. No other module reads the environment or names a number.
+ * Overridable at runtime with `{{ solutionName | upperSnake }}_AGENTS_*`.
+ */
+
+// Read through globalThis so this compiles with or without @types/node present.
+const env =
+  (globalThis as { process?: { env?: Record<string, string | undefined> } }).process?.env ?? {};
+
+const PREFIX = '{{ solutionName | upperSnake }}_AGENTS_';
+
+function positiveInt(name: string, fallback: number): number {
+  const parsed = Number(env[PREFIX + name]);
+  return Number.isFinite(parsed) && parsed > 0 ? Math.floor(parsed) : fallback;
+}
+
+export interface AgentConfig {
+  /** Hard ceiling on workers dispatched in one fan-out. */
+  readonly fanOutCap: number;
+  /** How many of those actually run at once. */
+  readonly workerConcurrency: number;
+  /**
+   * Whole-run token ceiling, orchestrator included. Anthropic measured multi-agent systems at
+   * ~15x the tokens of a chat interaction, so this is a budget the run is held to, not a
+   * number it reports afterwards.
+   */
+  readonly runTokenBudget: number;
+  /** A single worker may never eat the whole run. */
+  readonly workerTokenBudget: number;
+  /** Tool calls a worker may make before it must report back. */
+  readonly workerMaxSteps: number;
+  /** Condensation is the whole point — a "summary" longer than this is a transcript. */
+  readonly summaryCharLimit: number;
+}
+
+export function agentConfig(): AgentConfig {
+  const runTokenBudget = positiveInt('RUN_TOKEN_BUDGET', {{ runTokenBudget }});
+  return {
+    fanOutCap: positiveInt('FAN_OUT_CAP', {{ fanOutCap }}),
+    workerConcurrency: positiveInt('WORKER_CONCURRENCY', 3),
+    runTokenBudget,
+    workerTokenBudget: positiveInt('WORKER_TOKEN_BUDGET', Math.floor(runTokenBudget / 5)),
+    workerMaxSteps: positiveInt('WORKER_MAX_STEPS', 15),
+    summaryCharLimit: positiveInt('SUMMARY_CHAR_LIMIT', 4000),
+  };
+}

package/templates/architectures/multi-agent/files/src/agents/contracts/index.ts

@@ -0,0 +1,4 @@
+// The only types allowed to cross the orchestrator/worker seam. This folder imports nothing.
+export type { WorkerTask } from './task.js';
+export type { TokenUsage, WorkerResult, WorkerStatus } from './result.js';
+export { condense, totalTokens } from './result.js';

package/templates/architectures/multi-agent/files/src/agents/contracts/result.ts

@@ -0,0 +1,50 @@
+import type { WorkerTask } from './task.js';
+
+export interface TokenUsage {
+  readonly inputTokens: number;
+  readonly outputTokens: number;
+}
+
+export const totalTokens = (usage: TokenUsage): number => usage.inputTokens + usage.outputTokens;
+
+export type WorkerStatus = 'ok' | 'budget-exceeded' | 'failed';
+
+/**
+ * The worker -> orchestrator seam. There is deliberately no transcript, message list, or history
+ * field: the lead agent's context must grow by a summary, never by a worker's whole run. Adding
+ * one here is the change that turns this architecture back into a single shared context.
+ */
+export interface WorkerResult {
+  readonly taskId: string;
+  readonly workerId: string;
+  readonly summary: string;
+  readonly citations: readonly string[];
+  readonly usage: TokenUsage;
+  readonly status: WorkerStatus;
+}
+
+const STATUSES: readonly WorkerStatus[] = ['ok', 'budget-exceeded', 'failed'];
+
+/**
+ * Whitelist projection applied to every worker return value. A worker that hands back extra keys
+ * cannot leak them into the lead's context, because only these fields survive.
+ */
+export function condense(
+  task: WorkerTask,
+  raw: Record<string, unknown>,
+  summaryCharLimit: number,
+): WorkerResult {
+  const status = raw.status as WorkerStatus;
+  const usage = (raw.usage ?? {}) as Partial<TokenUsage>;
+  return {
+    taskId: task.id,
+    workerId: task.workerId,
+    summary: String(raw.summary ?? '').slice(0, summaryCharLimit),
+    citations: Array.isArray(raw.citations) ? raw.citations.map(String) : [],
+    usage: {
+      inputTokens: Number(usage.inputTokens ?? 0),
+      outputTokens: Number(usage.outputTokens ?? 0),
+    },
+    status: STATUSES.includes(status) ? status : 'failed',
+  };
+}

package/templates/architectures/multi-agent/files/src/agents/contracts/task.ts

@@ -0,0 +1,19 @@
+/**
+ * The orchestrator -> worker seam. A brief carries everything the worker needs and nothing about
+ * the run it came from; that omission is what keeps the contexts isolated.
+ */
+export interface WorkerTask {
+  readonly id: string;
+  /** Which worker in the registry handles this brief. */
+  readonly workerId: string;
+  /**
+   * The four fields a subagent brief must carry. Underspecified briefs are why workers
+   * duplicate each other's work and leave gaps — they are required, not decorative.
+   */
+  readonly objective: string;
+  readonly outputFormat: string;
+  readonly tools: readonly string[];
+  readonly boundaries: readonly string[];
+  /** Reserved against the run ledger before dispatch. */
+  readonly tokenBudget: number;
+}

package/templates/architectures/multi-agent/files/src/agents/orchestrator/budget.ts

@@ -0,0 +1,51 @@
+import { totalTokens, type TokenUsage } from '../contracts/index.js';
+
+export class BudgetExceededError extends Error {
+  // Explicit fields, not parameter properties: bases compile with `erasableSyntaxOnly`.
+  readonly requested: number;
+  readonly remaining: number;
+
+  constructor(requested: number, remaining: number) {
+    super(`Run token budget exhausted: needed ${requested}, ${remaining} remaining`);
+    this.name = 'BudgetExceededError';
+    this.requested = requested;
+    this.remaining = remaining;
+  }
+}
+
+/**
+ * Per-run token ledger. Budget is reserved before dispatch and reconciled after, because
+ * refusing one spawn is far cheaper than discovering the overrun once five workers have
+ * already spent it.
+ */
+export class RunBudget {
+  #reserved = 0;
+  #spent = 0;
+  readonly #limit: number;
+
+  constructor(limit: number) {
+    this.#limit = limit;
+  }
+
+  get spent(): number {
+    return this.#spent;
+  }
+
+  /** Reservations and actuals overlap, so the larger of the two is what is committed. */
+  get remaining(): number {
+    return this.#limit - Math.max(this.#reserved, this.#spent);
+  }
+
+  reserve(tokens: number): void {
+    if (tokens > this.remaining) throw new BudgetExceededError(tokens, this.remaining);
+    this.#reserved += tokens;
+  }
+
+  release(tokens: number): void {
+    this.#reserved = Math.max(0, this.#reserved - tokens);
+  }
+
+  record(usage: TokenUsage): void {
+    this.#spent += totalTokens(usage);
+  }
+}

package/templates/architectures/multi-agent/files/src/agents/orchestrator/fanout.ts

@@ -0,0 +1,67 @@
+import { agentConfig, type AgentConfig } from '../config.js';
+import { condense, type WorkerResult, type WorkerTask } from '../contracts/index.js';
+import { BudgetExceededError, RunBudget } from './budget.js';
+
+export class FanOutCapExceededError extends Error {
+  constructor(planned: number, cap: number) {
+    super(`Planned ${planned} workers, cap is ${cap} — narrow the plan or raise the cap in config`);
+    this.name = 'FanOutCapExceededError';
+  }
+}
+
+/** A worker invocation. The returned object is projected through `condense`, never trusted. */
+export type Dispatch = (task: WorkerTask) => Promise<Record<string, unknown>>;
+
+/**
+ * The only path to a worker. Cap first, budget second, concurrency third — an orchestrator that
+ * plans twenty workers must fail loudly rather than quietly cost twenty times as much.
+ */
+export async function fanOut(
+  tasks: readonly WorkerTask[],
+  dispatch: Dispatch,
+  budget: RunBudget,
+  config: AgentConfig = agentConfig(),
+): Promise<WorkerResult[]> {
+  if (tasks.length > config.fanOutCap) {
+    throw new FanOutCapExceededError(tasks.length, config.fanOutCap);
+  }
+
+  const results: WorkerResult[] = [];
+  const queue = [...tasks];
+
+  const worker = async (): Promise<void> => {
+    for (let task = queue.shift(); task; task = queue.shift()) {
+      results.push(await dispatchOne(task, dispatch, budget, config));
+    }
+  };
+
+  const lanes = Math.max(1, Math.min(config.workerConcurrency, tasks.length));
+  await Promise.all(Array.from({ length: lanes }, worker));
+  return results;
+}
+
+async function dispatchOne(
+  task: WorkerTask,
+  dispatch: Dispatch,
+  budget: RunBudget,
+  config: AgentConfig,
+): Promise<WorkerResult> {
+  const reservation = Math.min(task.tokenBudget, config.workerTokenBudget);
+  try {
+    budget.reserve(reservation);
+  } catch (error) {
+    if (!(error instanceof BudgetExceededError)) throw error;
+    // A starved worker degrades the answer; aborting the run throws away what already cost money.
+    return condense(task, { summary: error.message, status: 'budget-exceeded' }, config.summaryCharLimit);
+  }
+
+  try {
+    const result = condense(task, await dispatch(task), config.summaryCharLimit);
+    budget.record(result.usage);
+    return result;
+  } catch (error) {
+    return condense(task, { summary: String(error), status: 'failed' }, config.summaryCharLimit);
+  } finally {
+    budget.release(reservation);
+  }
+}

package/templates/architectures/multi-agent/files/src/agents/orchestrator/index.ts

@@ -0,0 +1,4 @@
+// The orchestrator's public surface. `fanout` and `budget` stay private so the cap and the
+// ledger cannot be routed around — scripts/check-agent-boundaries.mjs enforces that.
+export type { RunOutcome } from './lead.js';
+export { runLead } from './lead.js';