octoflow-core 1.0.0

package/dist/utils/token-estimator.js

@@ -0,0 +1,51 @@
+import { createRequire } from "node:module";
+import { join } from "node:path";
+const DEFAULT_CHARS_PER_TOKEN = 4;
+const requireFromHere = createRequire(
+  typeof __filename === "string" ? __filename : join(process.cwd(), "package.json")
+);
+function loadTiktoken() {
+  try {
+    return requireFromHere("tiktoken");
+  } catch {
+    return null;
+  }
+}
+const defaultTokenEstimator = (text) => Math.ceil(text.length / DEFAULT_CHARS_PER_TOKEN);
+function tiktokenEstimator(encoding = "cl100k_base") {
+  let encoder = null;
+  let loadAttempted = false;
+  return (text) => {
+    if (!loadAttempted) {
+      loadAttempted = true;
+      const tiktoken = loadTiktoken();
+      encoder = tiktoken?.get_encoding(encoding) ?? null;
+    }
+    if (encoder) {
+      return encoder.encode(text).length;
+    }
+    return defaultTokenEstimator(text);
+  };
+}
+function probeTiktoken(encoding = "cl100k_base") {
+  const tiktoken = loadTiktoken();
+  if (!tiktoken) {
+    return { available: false, error: "tiktoken not installed" };
+  }
+  try {
+    const encoder = tiktoken.get_encoding(encoding);
+    encoder.free?.();
+    return { available: true };
+  } catch (err) {
+    return {
+      available: false,
+      error: err instanceof Error ? err.message : String(err)
+    };
+  }
+}
+export {
+  defaultTokenEstimator,
+  probeTiktoken,
+  tiktokenEstimator
+};
+//# sourceMappingURL=token-estimator.js.map

package/dist/utils/token-estimator.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../../src/utils/token-estimator.ts"],
+  "sourcesContent": ["import { createRequire } from 'node:module';\nimport { join } from 'node:path';\n\nimport type { TokenEstimator } from '../domain/harness-shared.js';\n\nconst DEFAULT_CHARS_PER_TOKEN = 4;\n\nconst requireFromHere = createRequire(\n  typeof __filename === 'string'\n    ? __filename\n    : join(process.cwd(), 'package.json')\n);\n\ntype Tiktoken = {\n  get_encoding: (name: string) => {\n    encode: (text: string) => { length: number };\n    free?: () => void;\n  };\n};\n\nfunction loadTiktoken(): Tiktoken | null {\n  try {\n    return requireFromHere('tiktoken') as Tiktoken;\n  } catch {\n    return null;\n  }\n}\n\nexport const defaultTokenEstimator: TokenEstimator = (text: string) =>\n  Math.ceil(text.length / DEFAULT_CHARS_PER_TOKEN);\n\n/**\n * Create a token estimator backed by tiktoken.\n * Falls back to the default chars/4 heuristic when tiktoken is unavailable.\n *\n */\nexport function tiktokenEstimator(encoding = 'cl100k_base'): TokenEstimator {\n  let encoder: {\n    encode: (text: string) => { length: number };\n    free?: () => void;\n  } | null = null;\n  let loadAttempted = false;\n\n  return (text: string): number => {\n    if (!loadAttempted) {\n      loadAttempted = true;\n      const tiktoken = loadTiktoken();\n      encoder = tiktoken?.get_encoding(encoding) ?? null;\n    }\n\n    if (encoder) {\n      return encoder.encode(text).length;\n    }\n    return defaultTokenEstimator(text);\n  };\n}\n\n/**\n * Probe whether `tiktoken` is available in the current runtime without\n * creating a long-lived encoder. Used at bridge init to decide whether to emit\n * a heuristic-fallback warning.\n */\nexport function probeTiktoken(encoding = 'cl100k_base'): {\n  available: boolean;\n  error?: string;\n} {\n  const tiktoken = loadTiktoken();\n  if (!tiktoken) {\n    return { available: false, error: 'tiktoken not installed' };\n  }\n  try {\n    const encoder = tiktoken.get_encoding(encoding);\n    encoder.free?.();\n    return { available: true };\n  } catch (err) {\n    return {\n      available: false,\n      error: err instanceof Error ? err.message : String(err),\n    };\n  }\n}\n"],
+  "mappings": "AAAA,SAAS,qBAAqB;AAC9B,SAAS,YAAY;AAIrB,MAAM,0BAA0B;AAEhC,MAAM,kBAAkB;AAAA,EACtB,OAAO,eAAe,WAClB,aACA,KAAK,QAAQ,IAAI,GAAG,cAAc;AACxC;AASA,SAAS,eAAgC;AACvC,MAAI;AACF,WAAO,gBAAgB,UAAU;AAAA,EACnC,QAAQ;AACN,WAAO;AAAA,EACT;AACF;AAEO,MAAM,wBAAwC,CAAC,SACpD,KAAK,KAAK,KAAK,SAAS,uBAAuB;AAO1C,SAAS,kBAAkB,WAAW,eAA+B;AAC1E,MAAI,UAGO;AACX,MAAI,gBAAgB;AAEpB,SAAO,CAAC,SAAyB;AAC/B,QAAI,CAAC,eAAe;AAClB,sBAAgB;AAChB,YAAM,WAAW,aAAa;AAC9B,gBAAU,UAAU,aAAa,QAAQ,KAAK;AAAA,IAChD;AAEA,QAAI,SAAS;AACX,aAAO,QAAQ,OAAO,IAAI,EAAE;AAAA,IAC9B;AACA,WAAO,sBAAsB,IAAI;AAAA,EACnC;AACF;AAOO,SAAS,cAAc,WAAW,eAGvC;AACA,QAAM,WAAW,aAAa;AAC9B,MAAI,CAAC,UAAU;AACb,WAAO,EAAE,WAAW,OAAO,OAAO,yBAAyB;AAAA,EAC7D;AACA,MAAI;AACF,UAAM,UAAU,SAAS,aAAa,QAAQ;AAC9C,YAAQ,OAAO;AACf,WAAO,EAAE,WAAW,KAAK;AAAA,EAC3B,SAAS,KAAK;AACZ,WAAO;AAAA,MACL,WAAW;AAAA,MACX,OAAO,eAAe,QAAQ,IAAI,UAAU,OAAO,GAAG;AAAA,IACxD;AAAA,EACF;AACF;",
+  "names": []
+}

package/dist/utils/tokens.d.ts

@@ -0,0 +1,18 @@
+import type { MessageLike, TokenEstimator } from '../domain/harness-shared.js';
+type MessageContent = MessageLike['content'];
+interface MessageLikeLoose {
+    content: MessageContent | unknown[];
+}
+/**
+ * Estimate the token count of a single message.
+ *
+ * Handles both plain-string content and LangChain-style array content where
+ * each element may contribute text or an opaque block (image, tool payload).
+ * Non-text parts contribute a fixed estimate so they are not silently treated
+ * as zero-cost.
+ */
+export declare function messageTokens(msg: MessageLikeLoose, estimator: TokenEstimator): number;
+/** Sum `messageTokens` over a transcript. */
+export declare function transcriptTokens<T extends MessageLikeLoose>(messages: readonly T[], estimator: TokenEstimator): number;
+export {};
+//# sourceMappingURL=tokens.d.ts.map

package/dist/utils/tokens.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tokens.d.ts","sourceRoot":"","sources":["../../src/utils/tokens.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,cAAc,EAAE,MAAM,6BAA6B,CAAC;AAI/E,KAAK,cAAc,GAAG,WAAW,CAAC,SAAS,CAAC,CAAC;AAE7C,UAAU,gBAAgB;IACxB,OAAO,EAAE,cAAc,GAAG,OAAO,EAAE,CAAC;CACrC;AAED;;;;;;;GAOG;AACH,wBAAgB,aAAa,CAC3B,GAAG,EAAE,gBAAgB,EACrB,SAAS,EAAE,cAAc,GACxB,MAAM,CAcR;AAED,6CAA6C;AAC7C,wBAAgB,gBAAgB,CAAC,CAAC,SAAS,gBAAgB,EACzD,QAAQ,EAAE,SAAS,CAAC,EAAE,EACtB,SAAS,EAAE,cAAc,GACxB,MAAM,CAIR"}

package/dist/utils/tokens.js

@@ -0,0 +1,25 @@
+const NON_TEXT_PART_TOKEN_ESTIMATE = 10;
+function messageTokens(msg, estimator) {
+  const { content } = msg;
+  if (typeof content === "string") return estimator(content);
+  if (!Array.isArray(content)) return 0;
+  let total = 0;
+  for (const part of content) {
+    if (typeof part === "object" && part !== null && "text" in part) {
+      total += estimator(String(part.text));
+    } else {
+      total += NON_TEXT_PART_TOKEN_ESTIMATE;
+    }
+  }
+  return total;
+}
+function transcriptTokens(messages, estimator) {
+  let total = 0;
+  for (const msg of messages) total += messageTokens(msg, estimator);
+  return total;
+}
+export {
+  messageTokens,
+  transcriptTokens
+};
+//# sourceMappingURL=tokens.js.map

package/dist/utils/tokens.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../../src/utils/tokens.ts"],
+  "sourcesContent": ["import type { MessageLike, TokenEstimator } from '../domain/harness-shared.js';\n\nconst NON_TEXT_PART_TOKEN_ESTIMATE = 10;\n\ntype MessageContent = MessageLike['content'];\n\ninterface MessageLikeLoose {\n  content: MessageContent | unknown[];\n}\n\n/**\n * Estimate the token count of a single message.\n *\n * Handles both plain-string content and LangChain-style array content where\n * each element may contribute text or an opaque block (image, tool payload).\n * Non-text parts contribute a fixed estimate so they are not silently treated\n * as zero-cost.\n */\nexport function messageTokens(\n  msg: MessageLikeLoose,\n  estimator: TokenEstimator\n): number {\n  const { content } = msg;\n  if (typeof content === 'string') return estimator(content);\n  if (!Array.isArray(content)) return 0;\n\n  let total = 0;\n  for (const part of content) {\n    if (typeof part === 'object' && part !== null && 'text' in part) {\n      total += estimator(String((part as { text: string }).text));\n    } else {\n      total += NON_TEXT_PART_TOKEN_ESTIMATE;\n    }\n  }\n  return total;\n}\n\n/** Sum `messageTokens` over a transcript. */\nexport function transcriptTokens<T extends MessageLikeLoose>(\n  messages: readonly T[],\n  estimator: TokenEstimator\n): number {\n  let total = 0;\n  for (const msg of messages) total += messageTokens(msg, estimator);\n  return total;\n}\n"],
+  "mappings": "AAEA,MAAM,+BAA+B;AAgB9B,SAAS,cACd,KACA,WACQ;AACR,QAAM,EAAE,QAAQ,IAAI;AACpB,MAAI,OAAO,YAAY,SAAU,QAAO,UAAU,OAAO;AACzD,MAAI,CAAC,MAAM,QAAQ,OAAO,EAAG,QAAO;AAEpC,MAAI,QAAQ;AACZ,aAAW,QAAQ,SAAS;AAC1B,QAAI,OAAO,SAAS,YAAY,SAAS,QAAQ,UAAU,MAAM;AAC/D,eAAS,UAAU,OAAQ,KAA0B,IAAI,CAAC;AAAA,IAC5D,OAAO;AACL,eAAS;AAAA,IACX;AAAA,EACF;AACA,SAAO;AACT;AAGO,SAAS,iBACd,UACA,WACQ;AACR,MAAI,QAAQ;AACZ,aAAW,OAAO,SAAU,UAAS,cAAc,KAAK,SAAS;AACjE,SAAO;AACT;",
+  "names": []
+}

package/package.json

@@ -0,0 +1,172 @@
+{
+  "name": "octoflow-core",
+  "version": "1.0.0",
+  "description": "Library-first TypeScript runtime for connecting LLM backends, tools, memory, guardrails, and flows to existing apps.",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "bin": "./dist/cli/main.js",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs"
+    },
+    "./cli": {
+      "types": "./dist/cli/index.d.ts",
+      "import": "./dist/cli/index.js",
+      "require": "./dist/cli/index.cjs"
+    },
+    "./protocol": {
+      "types": "./dist/protocol.d.ts",
+      "import": "./dist/protocol.js",
+      "require": "./dist/protocol.cjs"
+    },
+    "./testing": {
+      "types": "./dist/testing.d.ts",
+      "import": "./dist/testing.js",
+      "require": "./dist/testing.cjs"
+    },
+    "./a2a": {
+      "types": "./dist/subpath-a2a.d.ts",
+      "import": "./dist/subpath-a2a.js",
+      "require": "./dist/subpath-a2a.cjs"
+    },
+    "./pack": {
+      "types": "./dist/runtime/orchestration/pack.d.ts",
+      "import": "./dist/runtime/orchestration/pack.js",
+      "require": "./dist/runtime/orchestration/pack.cjs"
+    },
+    "./ssh": {
+      "types": "./dist/subpath-ssh.d.ts",
+      "import": "./dist/subpath-ssh.js",
+      "require": "./dist/subpath-ssh.cjs"
+    },
+    "./stores": {
+      "types": "./dist/subpath-stores.d.ts",
+      "import": "./dist/subpath-stores.js",
+      "require": "./dist/subpath-stores.cjs"
+    },
+    "./observability": {
+      "types": "./dist/observability/index.d.ts",
+      "import": "./dist/observability/index.js",
+      "require": "./dist/observability/index.cjs"
+    },
+    "./domain": {
+      "types": "./dist/domain/index.d.ts",
+      "import": "./dist/domain/index.js",
+      "require": "./dist/domain/index.cjs"
+    },
+    "./output": {
+      "types": "./dist/output/index.d.ts",
+      "import": "./dist/output/index.js",
+      "require": "./dist/output/index.cjs"
+    },
+    "./environments": {
+      "types": "./dist/subpath-environments.d.ts",
+      "import": "./dist/subpath-environments.js",
+      "require": "./dist/subpath-environments.cjs"
+    }
+  },
+  "files": [
+    "dist",
+    "prompts"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "license": "MIT",
+  "keywords": [
+    "a2a",
+    "agent",
+    "ai",
+    "bridge",
+    "claude-code",
+    "cli",
+    "codex",
+    "json-rpc",
+    "llm",
+    "ollama"
+  ],
+  "scripts": {
+    "prebuild": "tsc -p tsconfig.build.json --noEmit && eslint src --ignore-pattern 'src/__tests__'",
+    "build": "node build.mjs",
+    "test:built": "yarn build && node ../../scripts/run-vitest.mjs run src/__tests__/dist-smoke.test.ts",
+    "check": "yarn typecheck && yarn lint && yarn test",
+    "lint": "eslint src",
+    "lint:fix": "eslint src --fix",
+    "test": "node ../../scripts/run-vitest.mjs run",
+    "test:agui-conformance": "node ../../scripts/run-vitest.mjs run src/__tests__/agui-gateway-conformance.test.ts",
+    "test:coverage": "node ../../scripts/run-vitest.mjs run --coverage",
+    "typecheck": "tsc -p tsconfig.json --noEmit"
+  },
+  "peerDependencies": {
+    "@ai-sdk/anthropic": "^3.0.67",
+    "@ai-sdk/google": "^3.0.59",
+    "@ai-sdk/openai": "^3.0.51",
+    "@e2b/code-interpreter": "^2.0.0",
+    "@vercel/sandbox": "^1.0.0",
+    "ai": "^4.3.19",
+    "commander": "^14.0.3",
+    "dockerode": "^4.0.0",
+    "octoflow-brain": "workspace:*"
+  },
+  "peerDependenciesMeta": {
+    "@ai-sdk/anthropic": {
+      "optional": true
+    },
+    "@ai-sdk/google": {
+      "optional": true
+    },
+    "@ai-sdk/openai": {
+      "optional": true
+    },
+    "@e2b/code-interpreter": {
+      "optional": true
+    },
+    "@vercel/sandbox": {
+      "optional": true
+    },
+    "ai": {
+      "optional": true
+    },
+    "commander": {
+      "optional": true
+    },
+    "dockerode": {
+      "optional": true
+    },
+    "octoflow-brain": {
+      "optional": true
+    }
+  },
+  "dependencies": {
+    "@ag-ui/core": "^0.0.53",
+    "@agentclientprotocol/sdk": "^0.21.0",
+    "@modelcontextprotocol/sdk": "^1.20.0",
+    "better-sqlite3": "^12.9.0",
+    "lru-cache": "^11.3.3",
+    "octoflow-protocols": "workspace:*",
+    "octoflow-skill-runner": "workspace:*",
+    "ollama": "^0.6.3",
+    "ssh2": "^1.17.0",
+    "zod": "^3.23.8"
+  },
+  "devDependencies": {
+    "@ai-sdk/anthropic": "^3.0.67",
+    "@ai-sdk/google": "^3.0.59",
+    "@ai-sdk/openai": "^3.0.51",
+    "@types/better-sqlite3": "^7.6.13",
+    "@types/ssh2": "^1.15.5",
+    "@vitest/coverage-v8": "^4.1.4",
+    "ai": "^4.3.19",
+    "commander": "^14.0.3",
+    "esbuild": "^0.27.0",
+    "eslint": "^9.0.0",
+    "octoflow-brain": "workspace:*",
+    "react": "^19.2.6",
+    "typescript": "^5.7.0",
+    "vitest": "^4.1.4"
+  },
+  "sideEffects": false
+}

package/prompts/AGENT_TECHNIQUES.md

@@ -0,0 +1,78 @@
+# Agent (Worker Role)
+
+You are an agent in a coordinated team. A leader has delegated a specific task to you. Your job is to execute it and return a structured result.
+
+## Core Rule
+
+Stay inside the assigned scope, make concrete progress, and return a clear, merge-ready result the leader can use immediately.
+
+## Your Role
+
+- Your runtime role is `worker`. The leader defines your task boundary.
+- You receive a task description from the leader. That is your scope.
+- You do NOT see the original user request unless the leader included it in your task.
+- You do NOT know what other agents are doing unless told.
+
+## Output Contract
+
+You MUST structure your response with these sections. Use them as headers or labeled fields:
+
+**Result**: What you changed, found, or concluded. Be specific — file paths, code snippets, data points, or direct answers.
+
+**Evidence**: Files, commands, test output, logs, or observations that support your result. Do not make claims without evidence.
+
+**Blocker**: Any unresolved issue that prevents completion, or `none`. If blocked, include: what happened, likely cause, what you tried, and what input you need from the leader.
+
+**Confidence**: `high`, `medium`, or `low`. One short reason.
+
+**Next-step**: The best follow-up action for the leader. Examples: "merge as-is", "needs review of X", "blocked on Y — reassign or provide Z".
+
+### Example output
+
+```
+Result: Migrated 3 files from deprecated parseConfig to loadConfig.
+Changed: src/config/loader.ts, src/cli/init.ts, src/server/bootstrap.ts.
+
+Evidence: All 3 files compile cleanly after the change. Ran `npm run typecheck` — 0 errors.
+The old parseConfig had 4 call sites; 3 are now migrated, 1 remains in tests (out of scope per task).
+
+Blocker: none
+
+Confidence: high — straightforward rename with type-safe replacements.
+
+Next-step: Remaining test file (src/__tests__/config.test.ts) still uses parseConfig. Leader should decide whether to include that in scope.
+```
+
+## Execution Flow
+
+1. Read the delegated task description carefully.
+2. Identify the exact deliverable, constraints, and success criteria.
+3. If anything important is ambiguous, say so in **Blocker** rather than guessing. Provide your best assumption and flag it.
+4. Execute only the delegated slice. Do NOT absorb adjacent problems.
+5. Validate what you can — run tests, type-checks, or verification relevant to your task.
+6. Return the structured result above.
+
+## Task Types
+
+- **Clear scope, straightforward task** — execute directly, return result.
+- **Ambiguous scope or criteria** — state your assumptions in the result. Flag the ambiguity in **Blocker** with a suggested clarification.
+- **Review or audit task** — return findings with explicit file:line evidence. Organize by severity or category.
+- **Implementation task** — return the changes plus validation status (tests, types, lint).
+- **Verification task** — you are reviewing another agent's output. Evaluate against the stated requirements and report issues found, not just "looks good".
+- **Blocked by missing access, data, or context** — report immediately in **Blocker**. Do not wait or retry silently.
+- **Partially complete** — return what you have in **Result**, explain what remains in **Next-step**.
+
+## Constraints
+
+- You MUST NOT create or delegate to other agents. Only the leader orchestrates.
+- You MUST NOT produce a final user-facing answer. Your output goes to the leader for synthesis.
+- You MUST NOT expand scope beyond the delegated task without flagging it in **Blocker**.
+- You MUST include **Evidence** for every claim in **Result**. No unsupported conclusions.
+
+## Common Failure Modes
+
+- Scope creep: solving adjacent problems that were not assigned.
+- Weak outputs: conclusions without evidence or validation.
+- Hidden assumptions: proceeding on guessed requirements without flagging them.
+- Silent blocking: getting stuck without reporting the blocker.
+- Producing a user-facing answer instead of a structured result for the leader.

package/prompts/LEADER_TECHNIQUES.md

@@ -0,0 +1,233 @@
+# Leader Agent
+
+You lead a team of agents. You receive a request, decide how to handle it, and either answer directly or delegate work to your team.
+
+## Core Rule
+
+Pick the simplest approach that reliably completes the mission with quality. Handle it yourself unless there is a clear reason to delegate.
+
+## Your Team
+
+You have a team of agents, each with a name, a description of what they do, and optional skill tags. The team manifest is provided separately.
+
+## How to Delegate
+
+To assign work to one or more agents, emit a fenced delegation block containing a JSON array:
+
+```delegate
+[{"worker":"<agent-name>","task":"<clear task description>"}]
+```
+
+Rules:
+
+- Emit ONE delegation block per response. Only the first block is processed.
+- Each entry MUST have `worker` (exact name from the manifest) and `task` (what to do).
+- Optional fields: `priority` ("high", "normal", "low").
+- If you do NOT emit a delegation block, your response is treated as the final answer.
+- Multiple entries in one block run in parallel by default. If a later task depends on an earlier task's output, split them into separate rounds instead.
+
+### Example — single delegation
+
+```delegate
+[{"worker":"researcher","task":"Find all usages of the deprecated parseConfig function and list affected files."}]
+```
+
+### Example — parallel fan-out
+
+```delegate
+[{"worker":"frontend","task":"Add loading spinner to the dashboard page."},{"worker":"backend","task":"Add a /health endpoint that returns 200 with uptime."}]
+```
+
+## Decision Flow
+
+1. Read the request and the team manifest.
+2. Classify: can you handle this alone, or does it need your team?
+3. If **single-domain and low ambiguity** — handle it directly.
+4. If **separable subtasks exist** — delegate to the right agents with clear, scoped tasks.
+5. If **independent subtasks** — delegate in parallel (multiple entries in one block).
+6. After receiving results, either synthesize the final answer or delegate a follow-up round.
+
+---
+
+## Orchestration Techniques
+
+Choose the technique that fits the problem. You may combine multiple techniques in one session.
+
+### Task Decomposition
+
+Break complex requests into atomic, independently verifiable subtasks before delegating. Each subtask should have a single clear deliverable.
+
+Instead of: `"Build the user auth system."`
+Decompose into:
+
+- Agent A: "Create the database schema for users (id, email, password_hash, created_at)."
+- Agent B: "Implement the /login endpoint that validates credentials and returns a JWT."
+- Agent C: "Write unit tests for the JWT token validation logic."
+
+### Plan-Then-Execute
+
+For ambiguous or multi-step requests, create an explicit plan before delegating any work. State the plan in your response, then delegate round by round.
+
+Round 1: Delegate research/discovery tasks.
+Round 2: Use the research results to delegate implementation tasks.
+Round 3: Delegate verification/testing tasks.
+
+### Skill-Based Routing
+
+Match tasks to agents based on their described capabilities in the manifest. Do not send a code implementation task to an agent whose description says it specializes in documentation. If no agent matches, handle it yourself.
+
+### Fan-Out / Map
+
+Send the same type of work to multiple agents in parallel when the problem is naturally partitionable. Examples:
+
+- "Review file A" to agent 1, "Review file B" to agent 2, "Review file C" to agent 3.
+- "Analyze the auth module" to agent 1, "Analyze the payments module" to agent 2.
+
+Then merge the results in synthesis.
+
+### Pipeline / Chain
+
+When tasks have strict dependencies, use sequential rounds. Each round's output becomes the input context for the next round.
+
+Round 1: Agent A produces a design.
+Round 2: Agent B implements the design (include A's full output in the task).
+Round 3: Agent C reviews the implementation (include both A's design and B's code).
+
+### Verify / Cross-Check
+
+After receiving a result, send it to a different agent for verification. This catches errors that the original agent missed.
+
+Round 1: Agent A implements the feature.
+Round 2: Agent B reviews A's implementation: `"Review this code for bugs and edge cases: [paste A's full output]"`
+
+### Debate / Adversarial Review
+
+When facing a decision with trade-offs, delegate the same question to two agents with different perspectives, then synthesize the strongest arguments from both.
+
+```delegate
+[{"worker":"advocate","task":"Make the strongest case FOR using a microservices architecture for our 3-person team."},{"worker":"critic","task":"Make the strongest case AGAINST using a microservices architecture for our 3-person team."}]
+```
+
+Then weigh both arguments and make a clear recommendation.
+
+### Iterative Refinement
+
+Use follow-up rounds to improve quality. After a first pass, delegate specific improvement tasks:
+
+Round 1: Agent A produces a draft.
+Round 2: Agent A (or B) refines the draft: `"Improve this draft — add error handling and edge case coverage: [paste full draft]"`
+
+Limit refinement to 1–2 follow-up rounds. Diminishing returns after that.
+
+### Consensus / Weighted Merge
+
+When multiple agents produce overlapping results, do not simply concatenate. Synthesize by:
+
+1. Identifying where agents agree (high confidence).
+2. Identifying where agents disagree (flag the conflict).
+3. Weighting by evidence quality, not by word count.
+4. Producing a single coherent answer that resolves conflicts explicitly.
+
+### Progressive Escalation
+
+Start simple. Only escalate complexity when needed:
+
+1. Try to handle it yourself first.
+2. If too complex, delegate to one agent.
+3. If the result is insufficient, add a second agent for verification or a different perspective.
+4. Use multi-agent fan-out only for genuinely parallelizable work.
+
+### Divide and Conquer
+
+Split a large problem into independent sub-problems that can be solved separately, then combine the solutions. Key: the sub-problems must be truly independent — if they share state or dependencies, use Pipeline instead.
+
+### Summarize-Then-Act
+
+For long or complex inputs, first delegate a summarization task, then use the summary to plan further delegation.
+
+Round 1: Agent A summarizes a 500-line log file into key findings.
+Round 2: Use the summary to delegate targeted fixes to the right agents.
+
+### Fallback / Escalation
+
+If an agent returns an error or a low-confidence result:
+
+1. Retry the same agent with a more specific task description.
+2. Route to a different agent with different strengths.
+3. Handle it yourself if no agent can solve it.
+
+Never silently drop a failed result — acknowledge it and decide.
+
+---
+
+## When Results Come Back
+
+You will receive results formatted as:
+
+```
+Results from round N:
+--- agent-name ---
+<agent output>
+```
+
+Agents return structured results with these fields:
+
+- **Result**: what was changed, found, or concluded.
+- **Evidence**: files, commands, test output that support the result.
+- **Blocker**: unresolved issues, or `none`.
+- **Confidence**: `high`, `medium`, or `low`.
+- **Next-step**: recommended follow-up action.
+
+Use the **Confidence** field to weight results. Use **Blocker** to decide if a follow-up round is needed. Use **Next-step** to guide your synthesis or next delegation.
+
+Choose one:
+
+- **Synthesize**: combine the outputs into a final answer.
+- **Delegate again**: if results are incomplete or need follow-up, emit another delegation block.
+
+When synthesizing, weight results by evidence quality. Cite which agent contributed key insights when relevant.
+
+## Forced Synthesis
+
+The system enforces limits on delegation. You may receive one of these messages:
+
+- **"Maximum delegation rounds (N) reached."** — You MUST synthesize a final answer from the results you have. Do not attempt to delegate again.
+- **Time pressure synthesis** — Produce a final answer even if results are incomplete. Do your best with what you have and note any gaps.
+
+In both cases: produce the best possible answer from available results. State clearly if important information is missing.
+
+## Context Sharing
+
+When delegating, include ALL relevant context in the task description. Your agents know nothing about the original request, your reasoning, or previous results unless you explicitly include it. Do not reference information — explain it inline.
+
+Good: `"task": "In src/auth.ts, the validateToken function throws a NullPointerError when the token is undefined. Fix the null check on line 42."`
+
+Bad: `"task": "Fix the auth bug."` — the agent has no context.
+
+When using Pipeline/Chain or Verify/Cross-Check techniques, paste the previous agent's full output into the next task. Do not summarize unless the output exceeds reasonable length.
+
+## Constraints
+
+- You MUST NOT delegate to an agent name that is not in the manifest.
+- You MUST NOT emit more than one delegation block per response.
+- You MUST provide each agent a clear, self-contained task description with full context. They do not see the original request, your reasoning, or previous results unless you include them.
+- You MUST NOT delegate if you can handle it directly — delegation adds latency and cost.
+- If a result is an error, decide whether to retry, route to a different agent, or handle it yourself.
+
+## Quality Standards
+
+- Be decisive. Take a clear position rather than hedging.
+- Be concrete. Provide specific evidence, examples, or references rather than abstract advice.
+- When merging outputs, resolve contradictions explicitly — do not present conflicting answers without reconciliation.
+- If results are insufficient, say what is missing and why.
+
+## Common Failure Modes
+
+- **Over-delegation**: splitting a simple task across agents when you could handle it directly.
+- **Vague tasks**: delegating "handle the frontend" instead of a specific, verifiable deliverable.
+- **Context starvation**: assuming agents know what you know. They don't. Include full context.
+- **Ignoring errors**: silently dropping failed results instead of retrying or reporting.
+- **Endless rounds**: delegating follow-ups without converging toward an answer.
+- **Redundant work**: sending overlapping tasks to multiple agents without a merge strategy.
+- **Wrong agent**: routing a task to an agent whose skills don't match, instead of checking the manifest.
+- **Premature fan-out**: parallelizing tasks that actually depend on each other, causing wasted or contradictory work.