tiny-orchestrator 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Dan Korotenko
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,73 @@
+# tiny-orchestrator
+
+A tiny TypeScript multi-agent runner with sane defaults, templates, and traces.
+
+## Goals
+
+- **Small surface area**: `new Orchestrator({ llm }).run({ goal })`
+- **Code-driven orchestration**: budgets/policy live in code; the model is a worker.
+- **Bring your own LLM**: minimal `LLM` interface (OpenAI/Anthropic/local).
+- **Traces**: every run returns a trace you can persist.
+
+## Install (core + provider)
+
+```bash
+# npm (recommended)
+npm i tiny-orchestrator @tiny-orchestrator/openrouter
+
+# bun
+bun add tiny-orchestrator @tiny-orchestrator/openrouter
+```
+
+## Usage
+
+```ts
+import { Orchestrator } from "tiny-orchestrator";
+import { OpenRouterChatLLM } from "@tiny-orchestrator/openrouter";
+
+const llm = new OpenRouterChatLLM({
+  // Or just set OPENROUTER_API_KEY / OPENROUTER_MODEL in env.
+  apiKey: process.env.OPENROUTER_API_KEY,
+  model: process.env.OPENROUTER_MODEL ?? "openai/gpt-4o-mini",
+});
+
+const tools = [
+  {
+    name: "add",
+    description: "Add two numbers",
+    async run(args: { a: number; b: number }) {
+      return args.a + args.b;
+    },
+  },
+];
+
+const orch = new Orchestrator({ llm, tools, budgets: { maxSteps: 10, timeMs: 30_000 } });
+const out = await orch.run({ goal: "Use the add tool to compute 2 + 2, then explain." });
+
+console.log(out.summary);
+```
+
+## Tool calling protocol
+
+The model must output **one JSON object** per step:
+
+- Tool request:
+  - `{ "type": "tool", "name": "add", "args": { "a": 2, "b": 2 } }`
+- Final answer:
+  - `{ "type": "final", "content": "..." }`
+
+## Templates
+
+```ts
+import { researcher, reviewer, writer } from "tiny-orchestrator/templates";
+
+console.log(researcher(), reviewer(), writer());
+```
+
+## Runtime
+
+This package is **Node 18+** compatible. You can run scripts with **bun** or **node**.
+
+## License
+
+MIT

package/dist/index.d.ts

@@ -0,0 +1,106 @@
+type LLMMessage = {
+    role: "system" | "user" | "assistant";
+    content: string;
+};
+type LLMInput = {
+    system?: string;
+    messages: LLMMessage[];
+    signal?: AbortSignal;
+};
+type LLMResponse = {
+    content: string;
+    raw?: unknown;
+};
+/**
+ * Minimal interface: bring your own provider (OpenAI, Anthropic, local, etc.).
+ */
+interface LLM {
+    complete(input: LLMInput): Promise<LLMResponse>;
+}
+
+type TraceEvent = {
+    t: "run.start";
+    runId: string;
+    goal: string;
+    at: number;
+} | {
+    t: "run.end";
+    runId: string;
+    at: number;
+    summary: string;
+} | {
+    t: "tool.call";
+    runId: string;
+    at: number;
+    tool: string;
+    args: unknown;
+} | {
+    t: "tool.result";
+    runId: string;
+    at: number;
+    tool: string;
+    ok: boolean;
+    result?: unknown;
+    error?: string;
+} | {
+    t: "agent.spawn";
+    runId: string;
+    at: number;
+    agent: string;
+    task: string;
+} | {
+    t: "agent.result";
+    runId: string;
+    at: number;
+    agent: string;
+    output: string;
+};
+type ToolContext = {
+    runId: string;
+    signal: AbortSignal;
+    trace: (event: TraceEvent) => void;
+};
+type ToolResult<TResult = unknown> = {
+    ok: true;
+    result: TResult;
+} | {
+    ok: false;
+    error: string;
+};
+type Tool<TArgs = unknown, TResult = unknown> = {
+    name: string;
+    description?: string;
+    /** Optional schema (zod/jsonschema/typebox). Treated as metadata by core. */
+    schema?: unknown;
+    run: (args: TArgs, ctx: ToolContext) => Promise<TResult>;
+};
+type OrchestratorOptions = {
+    llm: LLM;
+    tools?: Tool[];
+    budgets?: {
+        timeMs?: number;
+        /** Max LLM steps (each step may be a tool call or final response). */
+        maxSteps?: number;
+        maxSpawns?: number;
+    };
+};
+type RunInput = {
+    goal: string;
+    context?: Record<string, unknown>;
+};
+type RunResult = {
+    runId: string;
+    summary: string;
+    trace: TraceEvent[];
+};
+
+declare class Orchestrator {
+    private llm;
+    private tools;
+    private budgets;
+    private completeJSON;
+    constructor(opts: OrchestratorOptions);
+    run(input: RunInput): Promise<RunResult>;
+}
+
+export { type LLM, type LLMInput, type LLMMessage, type LLMResponse, Orchestrator, type OrchestratorOptions, type RunInput, type RunResult, type Tool, type ToolContext, type ToolResult, type TraceEvent };

package/dist/index.js

@@ -0,0 +1,193 @@
+import crypto from 'crypto';
+
+// src/orchestrator.ts
+
+// src/prompts.ts
+function buildDefaultSystemPrompt(params) {
+  const toolList = params.tools.length ? params.tools.map((t) => `- ${t.name}${t.description ? `: ${t.description}` : ""}`).join("\n") : "- (no tools registered)";
+  return [
+    "You are Tiny Orchestrator.",
+    "You are allowed to call developer-provided tools.",
+    "",
+    "Rules:",
+    "- Be direct.",
+    "- Prefer concrete steps and checklists.",
+    "- If information is missing, call tools (if available) or ask exactly what you need.",
+    "",
+    "Tool calling protocol (IMPORTANT):",
+    "- You MUST respond with a single JSON object, and NOTHING else.",
+    "- Either request a tool:",
+    '  { "type": "tool", "name": "toolName", "args": { ... } }',
+    "- Or finish with a final answer:",
+    '  { "type": "final", "content": "..." }',
+    "- After you request a tool, you will receive a user message of the form:",
+    '  { "type": "tool_result", "name": "toolName", "ok": true|false, "result": ..., "error": "..." }',
+    "- Do not wrap JSON in markdown. Do not include explanations outside JSON.",
+    "",
+    "Registered tools:",
+    toolList
+  ].join("\n");
+}
+
+// src/orchestrator.ts
+var Orchestrator = class {
+  llm;
+  tools;
+  budgets;
+  async completeJSON(input) {
+    const out1 = await this.llm.complete(input);
+    const t1 = out1.content.trim();
+    if (safeParseJSONLoose(t1)) return t1;
+    const retryMessages = [
+      ...input.messages,
+      {
+        role: "user",
+        content: "Your previous response was not valid JSON. Reply again with ONLY a single JSON object that follows the protocol. No markdown. No extra text."
+      }
+    ];
+    const out2 = await this.llm.complete({ ...input, messages: retryMessages });
+    return out2.content.trim();
+  }
+  constructor(opts) {
+    this.llm = opts.llm;
+    this.tools = opts.tools ?? [];
+    this.budgets = {
+      timeMs: opts.budgets?.timeMs ?? 6e4,
+      maxSteps: opts.budgets?.maxSteps ?? 20,
+      maxSpawns: opts.budgets?.maxSpawns ?? 4
+    };
+  }
+  async run(input) {
+    const runId = `to_${crypto.randomUUID()}`;
+    const trace = [];
+    const tracePush = (event) => trace.push(event);
+    const abort = new AbortController();
+    const timer = setTimeout(() => abort.abort(new Error("time budget exceeded")), this.budgets.timeMs);
+    const ctx = {
+      runId,
+      signal: abort.signal,
+      trace: tracePush
+    };
+    tracePush({ t: "run.start", runId, goal: input.goal, at: Date.now() });
+    const system = buildDefaultSystemPrompt({ tools: this.tools });
+    const toolMap = new Map(this.tools.map((t) => [t.name, t]));
+    const messages = [
+      {
+        role: "user",
+        content: JSON.stringify(
+          {
+            goal: input.goal,
+            context: input.context ?? {}
+          },
+          null,
+          2
+        )
+      }
+    ];
+    for (let step = 0; step < this.budgets.maxSteps; step++) {
+      const text = await this.completeJSON({ system, messages, signal: abort.signal });
+      messages.push({ role: "assistant", content: text });
+      const parsed = safeParseJSONLoose(text);
+      if (!parsed || typeof parsed !== "object") {
+        clearTimeout(timer);
+        tracePush({ t: "run.end", runId, at: Date.now(), summary: text });
+        return { runId, summary: text, trace };
+      }
+      const type = parsed.type;
+      if (type === "final") {
+        const summary2 = String(parsed.content ?? "").trim();
+        clearTimeout(timer);
+        tracePush({ t: "run.end", runId, at: Date.now(), summary: summary2 });
+        return { runId, summary: summary2, trace };
+      }
+      if (type !== "tool") {
+        clearTimeout(timer);
+        tracePush({ t: "run.end", runId, at: Date.now(), summary: text });
+        return { runId, summary: text, trace };
+      }
+      const toolName = String(parsed.name ?? "");
+      const args = parsed.args ?? {};
+      tracePush({ t: "tool.call", runId, at: Date.now(), tool: toolName, args });
+      const tool = toolMap.get(toolName);
+      if (!tool) {
+        const error = `unknown tool: ${toolName}`;
+        tracePush({ t: "tool.result", runId, at: Date.now(), tool: toolName, ok: false, error });
+        messages.push({
+          role: "user",
+          content: JSON.stringify({ type: "tool_result", name: toolName, ok: false, error }, null, 2)
+        });
+        continue;
+      }
+      try {
+        const result = await tool.run(args, ctx);
+        tracePush({ t: "tool.result", runId, at: Date.now(), tool: toolName, ok: true, result });
+        messages.push({
+          role: "user",
+          content: JSON.stringify({ type: "tool_result", name: toolName, ok: true, result }, null, 2)
+        });
+      } catch (e) {
+        const error = e instanceof Error ? e.message : String(e);
+        tracePush({ t: "tool.result", runId, at: Date.now(), tool: toolName, ok: false, error });
+        messages.push({
+          role: "user",
+          content: JSON.stringify({ type: "tool_result", name: toolName, ok: false, error }, null, 2)
+        });
+      }
+    }
+    clearTimeout(timer);
+    const summary = `maxSteps exceeded (${this.budgets.maxSteps})`;
+    tracePush({ t: "run.end", runId, at: Date.now(), summary });
+    return { runId, summary, trace };
+  }
+};
+function safeParseJSONLoose(text) {
+  try {
+    return JSON.parse(text);
+  } catch {
+  }
+  const extracted = extractFirstJSONObject(text);
+  if (!extracted) return null;
+  try {
+    return JSON.parse(extracted);
+  } catch {
+    return null;
+  }
+}
+function extractFirstJSONObject(text) {
+  const start = text.indexOf("{");
+  if (start < 0) return null;
+  let depth = 0;
+  let inString = false;
+  let escape = false;
+  for (let i = start; i < text.length; i++) {
+    const ch = text[i];
+    if (inString) {
+      if (escape) {
+        escape = false;
+        continue;
+      }
+      if (ch === "\\") {
+        escape = true;
+        continue;
+      }
+      if (ch === '"') {
+        inString = false;
+      }
+      continue;
+    }
+    if (ch === '"') {
+      inString = true;
+      continue;
+    }
+    if (ch === "{") depth++;
+    if (ch === "}") depth--;
+    if (depth === 0) {
+      return text.slice(start, i + 1);
+    }
+  }
+  return null;
+}
+
+export { Orchestrator };
+//# sourceMappingURL=index.js.map
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/prompts.ts","../src/orchestrator.ts"],"names":["summary"],"mappings":"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","file":"index.js","sourcesContent":["import type { Tool } from \"./types\";\n\nexport function buildDefaultSystemPrompt(params: { tools: Tool[] }) {\n  const toolList = params.tools.length\n    ? params.tools.map((t) => `- ${t.name}${t.description ? `: ${t.description}` : \"\"}`).join(\"\\n\")\n    : \"- (no tools registered)\";\n\n  return [\n    \"You are Tiny Orchestrator.\",\n    \"You are allowed to call developer-provided tools.\",\n    \"\",\n    \"Rules:\",\n    \"- Be direct.\",\n    \"- Prefer concrete steps and checklists.\",\n    \"- If information is missing, call tools (if available) or ask exactly what you need.\",\n    \"\",\n    \"Tool calling protocol (IMPORTANT):\",\n    \"- You MUST respond with a single JSON object, and NOTHING else.\",\n    \"- Either request a tool:\",\n    \"  { \\\"type\\\": \\\"tool\\\", \\\"name\\\": \\\"toolName\\\", \\\"args\\\": { ... } }\",\n    \"- Or finish with a final answer:\",\n    \"  { \\\"type\\\": \\\"final\\\", \\\"content\\\": \\\"...\\\" }\",\n    \"- After you request a tool, you will receive a user message of the form:\",\n    \"  { \\\"type\\\": \\\"tool_result\\\", \\\"name\\\": \\\"toolName\\\", \\\"ok\\\": true|false, \\\"result\\\": ..., \\\"error\\\": \\\"...\\\" }\",\n    \"- Do not wrap JSON in markdown. Do not include explanations outside JSON.\",\n    \"\",\n    \"Registered tools:\",\n    toolList,\n  ].join(\"\\n\");\n}\n","import crypto from \"node:crypto\";\nimport { buildDefaultSystemPrompt } from \"./prompts\";\nimport type { LLMMessage } from \"./llm\";\nimport type { OrchestratorOptions, RunInput, RunResult, Tool, ToolContext, TraceEvent } from \"./types\";\n\nexport class Orchestrator {\n  private llm: OrchestratorOptions[\"llm\"];\n  private tools: Tool[];\n  private budgets: Required<NonNullable<OrchestratorOptions[\"budgets\"]>>;\n\n  private async completeJSON(input: Parameters<OrchestratorOptions[\"llm\"][\"complete\"]>[0]): Promise<string> {\n    const out1 = await this.llm.complete(input);\n    const t1 = out1.content.trim();\n    if (safeParseJSONLoose(t1)) return t1;\n\n    // One corrective retry. This is the common failure mode: the model adds prose.\n    const retryMessages: LLMMessage[] = [\n      ...input.messages,\n      {\n        role: \"user\",\n        content:\n          \"Your previous response was not valid JSON. Reply again with ONLY a single JSON object that follows the protocol. No markdown. No extra text.\",\n      },\n    ];\n\n    const out2 = await this.llm.complete({ ...input, messages: retryMessages });\n    return out2.content.trim();\n  }\n\n  constructor(opts: OrchestratorOptions) {\n    this.llm = opts.llm;\n    this.tools = opts.tools ?? [];\n    this.budgets = {\n      timeMs: opts.budgets?.timeMs ?? 60_000,\n      maxSteps: opts.budgets?.maxSteps ?? 20,\n      maxSpawns: opts.budgets?.maxSpawns ?? 4,\n    };\n  }\n\n  async run(input: RunInput): Promise<RunResult> {\n    const runId = `to_${crypto.randomUUID()}`;\n    const trace: TraceEvent[] = [];\n    const tracePush = (event: TraceEvent) => trace.push(event);\n\n    const abort = new AbortController();\n    const timer = setTimeout(() => abort.abort(new Error(\"time budget exceeded\")), this.budgets.timeMs);\n\n    const ctx: ToolContext = {\n      runId,\n      signal: abort.signal,\n      trace: tracePush,\n    };\n\n    tracePush({ t: \"run.start\", runId, goal: input.goal, at: Date.now() });\n\n    const system = buildDefaultSystemPrompt({ tools: this.tools });\n\n    const toolMap = new Map(this.tools.map((t) => [t.name, t] as const));\n\n    const messages: LLMMessage[] = [\n      {\n        role: \"user\",\n        content: JSON.stringify(\n          {\n            goal: input.goal,\n            context: input.context ?? {},\n          },\n          null,\n          2,\n        ),\n      },\n    ];\n\n    for (let step = 0; step < this.budgets.maxSteps; step++) {\n      const text = await this.completeJSON({ system, messages, signal: abort.signal });\n\n      // Always record model output in the conversation.\n      messages.push({ role: \"assistant\", content: text });\n\n      const parsed = safeParseJSONLoose(text);\n      if (!parsed || typeof parsed !== \"object\") {\n        clearTimeout(timer);\n        tracePush({ t: \"run.end\", runId, at: Date.now(), summary: text });\n        return { runId, summary: text, trace };\n      }\n\n      const type = (parsed as any).type;\n      if (type === \"final\") {\n        const summary = String((parsed as any).content ?? \"\").trim();\n        clearTimeout(timer);\n        tracePush({ t: \"run.end\", runId, at: Date.now(), summary });\n        return { runId, summary, trace };\n      }\n\n      if (type !== \"tool\") {\n        // Unknown protocol → treat as final.\n        clearTimeout(timer);\n        tracePush({ t: \"run.end\", runId, at: Date.now(), summary: text });\n        return { runId, summary: text, trace };\n      }\n\n      const toolName = String((parsed as any).name ?? \"\");\n      const args = (parsed as any).args ?? {};\n      tracePush({ t: \"tool.call\", runId, at: Date.now(), tool: toolName, args });\n\n      const tool = toolMap.get(toolName);\n      if (!tool) {\n        const error = `unknown tool: ${toolName}`;\n        tracePush({ t: \"tool.result\", runId, at: Date.now(), tool: toolName, ok: false, error });\n        messages.push({\n          role: \"user\",\n          content: JSON.stringify({ type: \"tool_result\", name: toolName, ok: false, error }, null, 2),\n        });\n        continue;\n      }\n\n      try {\n        const result = await tool.run(args, ctx);\n        tracePush({ t: \"tool.result\", runId, at: Date.now(), tool: toolName, ok: true, result });\n        messages.push({\n          role: \"user\",\n          content: JSON.stringify({ type: \"tool_result\", name: toolName, ok: true, result }, null, 2),\n        });\n      } catch (e) {\n        const error = e instanceof Error ? e.message : String(e);\n        tracePush({ t: \"tool.result\", runId, at: Date.now(), tool: toolName, ok: false, error });\n        messages.push({\n          role: \"user\",\n          content: JSON.stringify({ type: \"tool_result\", name: toolName, ok: false, error }, null, 2),\n        });\n      }\n    }\n\n    clearTimeout(timer);\n    const summary = `maxSteps exceeded (${this.budgets.maxSteps})`;\n    tracePush({ t: \"run.end\", runId, at: Date.now(), summary });\n    return { runId, summary, trace };\n  }\n}\n\nfunction safeParseJSONLoose(text: string): unknown | null {\n  // Strict first.\n  try {\n    return JSON.parse(text);\n  } catch {\n    // Fall through.\n  }\n\n  // Then try to extract the first JSON object from messy output.\n  const extracted = extractFirstJSONObject(text);\n  if (!extracted) return null;\n\n  try {\n    return JSON.parse(extracted);\n  } catch {\n    return null;\n  }\n}\n\nfunction extractFirstJSONObject(text: string): string | null {\n  const start = text.indexOf(\"{\");\n  if (start < 0) return null;\n\n  let depth = 0;\n  let inString = false;\n  let escape = false;\n\n  for (let i = start; i < text.length; i++) {\n    const ch = text[i];\n\n    if (inString) {\n      if (escape) {\n        escape = false;\n        continue;\n      }\n      if (ch === \"\\\\\") {\n        escape = true;\n        continue;\n      }\n      if (ch === \"\\\"\") {\n        inString = false;\n      }\n      continue;\n    }\n\n    if (ch === \"\\\"\") {\n      inString = true;\n      continue;\n    }\n\n    if (ch === \"{\") depth++;\n    if (ch === \"}\") depth--;\n\n    if (depth === 0) {\n      return text.slice(start, i + 1);\n    }\n  }\n\n  return null;\n}\n\n"]}

package/dist/templates/index.d.ts

@@ -0,0 +1,9 @@
+type TemplateAgent = {
+    name: string;
+    system: string;
+};
+declare function researcher(): TemplateAgent;
+declare function reviewer(): TemplateAgent;
+declare function writer(): TemplateAgent;
+
+export { type TemplateAgent, researcher, reviewer, writer };

package/dist/templates/index.js

@@ -0,0 +1,39 @@
+// src/templates/index.ts
+function researcher() {
+  return {
+    name: "researcher",
+    system: [
+      "You are a research agent.",
+      "Return:",
+      "- bullet findings",
+      "- sources (URLs) when available",
+      "- uncertainties"
+    ].join("\n")
+  };
+}
+function reviewer() {
+  return {
+    name: "reviewer",
+    system: [
+      "You are a code reviewer.",
+      "Return:",
+      "- summary",
+      "- risks",
+      "- suggested changes",
+      "- tests to add"
+    ].join("\n")
+  };
+}
+function writer() {
+  return {
+    name: "writer",
+    system: [
+      "You are a technical writer.",
+      "Write a clean, concise draft."
+    ].join("\n")
+  };
+}
+
+export { researcher, reviewer, writer };
+//# sourceMappingURL=index.js.map
+//# sourceMappingURL=index.js.map

package/dist/templates/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/templates/index.ts"],"names":[],"mappings":";AAKO,SAAS,UAAA,GAA4B;AAC1C,EAAA,OAAO;AAAA,IACL,IAAA,EAAM,YAAA;AAAA,IACN,MAAA,EAAQ;AAAA,MACN,2BAAA;AAAA,MACA,SAAA;AAAA,MACA,mBAAA;AAAA,MACA,iCAAA;AAAA,MACA;AAAA,KACF,CAAE,KAAK,IAAI;AAAA,GACb;AACF;AAEO,SAAS,QAAA,GAA0B;AACxC,EAAA,OAAO;AAAA,IACL,IAAA,EAAM,UAAA;AAAA,IACN,MAAA,EAAQ;AAAA,MACN,0BAAA;AAAA,MACA,SAAA;AAAA,MACA,WAAA;AAAA,MACA,SAAA;AAAA,MACA,qBAAA;AAAA,MACA;AAAA,KACF,CAAE,KAAK,IAAI;AAAA,GACb;AACF;AAEO,SAAS,MAAA,GAAwB;AACtC,EAAA,OAAO;AAAA,IACL,IAAA,EAAM,QAAA;AAAA,IACN,MAAA,EAAQ;AAAA,MACN,6BAAA;AAAA,MACA;AAAA,KACF,CAAE,KAAK,IAAI;AAAA,GACb;AACF","file":"index.js","sourcesContent":["export type TemplateAgent = {\n  name: string;\n  system: string;\n};\n\nexport function researcher(): TemplateAgent {\n  return {\n    name: \"researcher\",\n    system: [\n      \"You are a research agent.\",\n      \"Return:\",\n      \"- bullet findings\",\n      \"- sources (URLs) when available\",\n      \"- uncertainties\",\n    ].join(\"\\n\"),\n  };\n}\n\nexport function reviewer(): TemplateAgent {\n  return {\n    name: \"reviewer\",\n    system: [\n      \"You are a code reviewer.\",\n      \"Return:\",\n      \"- summary\",\n      \"- risks\",\n      \"- suggested changes\",\n      \"- tests to add\",\n    ].join(\"\\n\"),\n  };\n}\n\nexport function writer(): TemplateAgent {\n  return {\n    name: \"writer\",\n    system: [\n      \"You are a technical writer.\",\n      \"Write a clean, concise draft.\",\n    ].join(\"\\n\"),\n  };\n}\n"]}

package/package.json

@@ -0,0 +1,39 @@
+{
+  "name": "tiny-orchestrator",
+  "version": "0.2.0",
+  "description": "A tiny TypeScript multi-agent runner with sane defaults, templates, and traces.",
+  "license": "MIT",
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./templates": {
+      "types": "./dist/templates/index.d.ts",
+      "import": "./dist/templates/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "sideEffects": false,
+  "engines": {
+    "node": ">=18"
+  },
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsup --watch",
+    "test": "vitest",
+    "test:node": "npm run build && node ./scripts/node-smoke-test.mjs",
+    "lint": "tsc -p tsconfig.json --noEmit",
+    "prepublishOnly": "npm run build && npm run lint && npm test"
+  },
+  "devDependencies": {
+    "@esbuild/darwin-arm64": "0.27.3",
+    "@types/node": "^20.19.0",
+    "tsup": "^8.5.0",
+    "typescript": "^5.9.3",
+    "vitest": "^3.2.4"
+  }
+}