orchajs 0.14.0 → 0.15.1

package/dist-cjs/cli-agents-template.js

@@ -0,0 +1,1090 @@
+"use strict"; const __orchaImportMetaUrl = require("node:url").pathToFileURL(__filename).href;
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+var cli_agents_template_exports = {};
+__export(cli_agents_template_exports, {
+  AGENTS_MD: () => AGENTS_MD
+});
+module.exports = __toCommonJS(cli_agents_template_exports);
+const AGENTS_MD = `# Orcha project guide
+
+This repository uses OrchaJS, a filesystem-convention framework for durable
+AI agents. Treat the \`orcha/\` directory as source code. Do not edit generated
+files under \`.orcha/\`.
+
+## Commands
+
+- \`orcha init\` creates the initial Orcha files without overwriting files.
+- \`orcha dev\` validates agent source and watches \`orcha/**\` for changes.
+- \`orcha playground\` opens the built-in local UI and hot reloads agent source.
+- \`orcha run <agent> --input "\u2026"\` executes one registered agent.
+- \`orcha run <agent> --input-file request.json\` accepts structured input.
+- \`orcha run <agent> --session <id> --input "\u2026"\` continues a session.
+- \`orcha run <agent> --session <id> --tool-results results.json\` submits
+  pending client-action results.
+- \`orcha test\` runs every enabled discovered agent test.
+- \`orcha test <agent>\` or \`orcha test <agent>/<case>\` narrows the run.
+- \`orcha migrate-storage --to sqlite|node-jsonl\` copies all session histories
+  between local stores without deleting the source.
+- \`orcha export-session <agent> <sessionId> [--output <path>]\` exports one
+  session from the active store as JSONL.
+- \`orcha build\` creates the production Orcha bundle without calling models.
+- Add \`--json\` to \`run\` and \`test\` for machine-readable output.
+
+\`run\`, \`test\`, and playground executions use real providers and require
+credentials. \`dev\` and \`build\` are offline. Sessions use JSONL by default
+under \`.orcha/sessions/<agentName>/\`; opt-in SQLite stores all agents in
+\`.orcha/sessions/orcha-sqlite.db\`.
+
+## Registry
+
+\`orcha/index.ts\` initializes providers and explicitly registers agents:
+
+\`\`\`ts
+import { orcha } from "orchajs";
+
+orcha.init({
+  providers: {
+    anthropic: process.env.ANTHROPIC_API_KEY ?? "",
+    openai: process.env.OPENAI_API_KEY ?? "",
+  },
+  agents: {
+    supportBot: "./supportBot",
+  },
+});
+\`\`\`
+
+Only registered agents are compiled. Agent keys become runtime properties
+such as \`orcha.supportBot\`. Local actions use the native Node.js runtime by
+default. Set \`actions.runtime: "sandbox"\` only when isolated execution is
+required.
+
+\`orcha.init()\` fields:
+
+- \`providers\` (required): provider configurations keyed by built-in provider
+  name.
+- \`agents\` (required): runtime property names mapped to folders relative to
+  \`orcha/\`. At least one agent is required.
+- \`actions\` (optional): overrides the native local-action runtime or configures
+  its environment and sandbox settings.
+- \`storage.strategy\` (optional): \`"node-jsonl"\` (default) or \`"sqlite"\`.
+  The SQLite driver ships as an internal optional Orcha dependency.
+- \`storage.directory\` (optional): session directory relative to project
+  root; defaults to \`.orcha/sessions\`.
+- \`root\` (optional): absolute or working-directory-relative project root;
+  defaults to \`ORCHA_PROJECT_ROOT\` and then \`process.cwd()\`.
+
+The Orcha library reads the host application's existing \`process.env\`.
+Standalone Orcha CLI commands also load \`.env\` from the project root without
+overriding environment variables already in the process.
+
+Provider configuration shapes:
+
+\`\`\`ts
+providers: {
+  anthropic: process.env.ANTHROPIC_API_KEY ?? "",
+  deepseek: process.env.DEEPSEEK_API_KEY ?? "",
+  googlegenai: process.env.GOOGLE_API_KEY ?? "",
+  openai: {
+    apiKey: process.env.OPENAI_API_KEY ?? "",
+    baseUrl: "https://api.openai.com/v1", // optional override
+  },
+  vertexai: {
+    project: process.env.GOOGLE_CLOUD_PROJECT ?? "",
+    location: process.env.GOOGLE_CLOUD_LOCATION ?? "us-central1",
+    // credentials is optional; omit it to use Google ADC.
+    credentials: {
+      clientEmail: process.env.GOOGLE_CLIENT_EMAIL ?? "",
+      privateKey: process.env.GOOGLE_PRIVATE_KEY ?? "",
+    },
+    baseUrl: undefined, // optional override
+  },
+  bedrock: {
+    region: process.env.AWS_REGION ?? "us-east-1",
+    // credentials is optional; omit it to use the AWS credential chain.
+    credentials: {
+      accessKeyId: process.env.AWS_ACCESS_KEY_ID ?? "",
+      secretAccessKey: process.env.AWS_SECRET_ACCESS_KEY ?? "",
+      sessionToken: process.env.AWS_SESSION_TOKEN,
+    },
+    baseUrl: undefined, // optional override
+  },
+}
+\`\`\`
+
+API-key providers accept either a string shorthand or
+\`{ apiKey, baseUrl? }\`. Vertex AI requires \`project\` and \`location\`;
+explicit service-account credentials are optional. Bedrock requires \`region\`;
+explicit AWS credentials are optional. Never place credentials in
+\`index.json\`, instructions, tests, session metadata, or committed files.
+
+## Agent folders
+
+\`\`\`text
+orcha/
+  index.ts
+  supportBot/
+    index.json
+    instructions.md
+    actions/
+    skills/
+    tests/
+    evaluations/
+\`\`\`
+
+\`index.json\` selects the model:
+
+\`\`\`json
+{
+  "name": "Support Agent",
+  "description": "Resolve customer support questions using confirmed account data.",
+  "provider": "anthropic",
+  "model": "claude-sonnet-4-6",
+  "region": "provider_managed",
+  "maxTokens": 10240,
+  "outputType": "text"
+}
+\`\`\`
+
+Optional fields include \`reasoningLevel\`, \`outputType: "json"\`, and an
+\`outputSchema\` JSON Schema. Provider-specific reasoning values are forwarded
+without translation. Put the agent's stable role, boundaries, and operating
+instructions in \`instructions.md\`.
+
+Agent \`index.json\` fields:
+
+- \`name\` (required): concise human-readable agent name.
+- \`description\` (optional): what the agent does and when it should be used.
+- \`provider\` (required): \`"anthropic"\`, \`"bedrock"\`, \`"deepseek"\`,
+  \`"openai"\`, \`"googlegenai"\`, or \`"vertexai"\`.
+- \`model\` (required): exact provider model identifier.
+- \`region\` (optional): provider/model routing hint; defaults in durable
+  metadata to \`"provider_managed"\`.
+- \`maxTokens\` (optional): positive integer. If omitted, the provider adapter
+  chooses its default.
+- \`reasoningLevel\` (optional): non-empty provider-native string. Orcha does
+  not translate values between providers.
+- \`outputType\` (optional): \`"text"\` (default) or \`"json"\`. Image and
+  audio are reserved but not implemented.
+- \`outputSchema\` (required for JSON output): JSON Schema used for provider
+  structured output and final validation.
+
+\`instructions.md\` is required and cannot be empty. At compile time it becomes
+the base system prompt. Orcha appends the compact available-skill catalog and
+the full instructions for skills already loaded in this durable session.
+
+## Subagents
+
+Register private subagents alongside a parent in \`orcha/index.ts\`:
+
+\`\`\`js
+agents: {
+  coordinator: {
+    path: "./coordinator",
+    subagents: {
+      researcher: "./researcher",
+    },
+  },
+  researcher: "./researcher",
+}
+\`\`\`
+
+Only top-level keys become \`orcha.<agentName>\`. In this example the
+researcher is both directly accessible and available to the coordinator.
+Remove its top-level entry to make it private.
+
+A parent may configure delegation limits in its \`index.json\`:
+
+\`\`\`json
+{
+  "subagents": {
+    "maxPerRun": 3
+  }
+}
+\`\`\`
+
+\`maxPerRun\` limits newly created child sessions in one parent run and
+defaults to 10.
+
+The parent receives a compact catalog containing each subagent's registered
+name and optional description. Internal \`run_agent\`, \`resume_agent\`,
+\`inspect_agent\` tools let it start, continue, and inspect only child sessions
+initiated by its current session. A delegated agent cannot delegate again.
+
+Subagent calls are synchronous. The parent becomes
+\`waiting_for_subagent\` while the child runs, then receives the child's text,
+pause state, client-action request, failure, or completion as a normal tool
+result. The parent and child keep separate linked JSONL sessions.
+
+## Core execution model
+
+An **agent** is the compiled definition: model settings, instructions, actions,
+skills, and evaluations. An agent can create many independent sessions.
+
+A **session** is one durable conversation owned by one agent. It has one
+\`sessionId\`, optional name and metadata, fixed prompt variables, and one
+append-only JSONL timeline. Completing one response does not close the
+session\u2014the application can resume it later. A session cannot be transferred
+to another registered agent, but later runs may use a different provider or
+model if that same agent's configuration changes.
+
+A **run** is one attempt to advance a session. \`run()\` creates a session and
+its first run. A conversational \`resume(sessionId, { content })\` creates the
+next numbered run in that session. Each run accumulates its own model usage and
+ends in exactly one of these states:
+
+- \`completed\`: the model produced final output.
+- \`waiting_for_subagent\`: the parent is waiting for a synchronous child
+  response and continues automatically when it arrives.
+- \`waiting_for_client_action\`: the model requested work that only the
+  application can perform. The run is paused, not completed.
+- \`paused\`: active provider work was aborted, streamed output was preserved,
+  and a later \`resume()\` starts a new run.
+- \`failed\`: validation, provider, storage, or execution failed. The durable
+  events remain available for diagnosis.
+
+An **execution** is the in-process handle returned by one call to \`run()\` or
+\`resume()\`. It exposes a cumulative output stream, latest snapshot, final
+result promise, and evaluation promise. An execution ends when that invocation
+completes, pauses, or fails; the durable session may continue through another
+execution.
+
+A **model round** is one provider request inside a run. One run may contain
+several rounds:
+
+\`\`\`text
+user input
+  \u2192 model round
+  \u2192 tool calls
+  \u2192 tool results
+  \u2192 another model round
+  \u2192 final answer
+\`\`\`
+
+Local actions and skill loads are handled automatically inside the same
+execution. Their results are sent back to the model and the model loop
+continues without application involvement.
+
+A **client action** deliberately crosses the application boundary. Orcha can
+describe the tool to the model but cannot execute it because the operation
+belongs to a browser, mobile app, approval system, or other caller-owned
+environment. The complete pause/continue flow is:
+
+\`\`\`text
+1. Application calls agent.run(...) or agent.resume(...content).
+2. Model requests one or more client actions.
+3. Orcha stores client_action.requested and run.paused.
+4. execution.result resolves with:
+   {
+     status: "waiting_for_client_action",
+     sessionId,
+     clientToolCalls: [{ callId, name, arguments }]
+   }
+5. Application executes every requested action.
+6. Application calls agent.resume(sessionId, {
+     toolResults: [{ callId, output, isError? }]
+   }).
+7. Orcha validates every callId and output, stores the results, and continues
+   the same paused run from its prior model context.
+8. The resumed execution either completes, requests more client actions, or
+   fails.
+\`\`\`
+
+Every pending call must be resolved exactly once in one resume operation.
+\`callId\` links the submitted result to the model's request; the action name
+must not be substituted for it. Re-submitting the identical resolved result is
+idempotent and returns the prior completed result. Submitting different data
+for an already-resolved call fails with \`action_result_conflict\`.
+
+\`clientCapabilities\` is supplied per invocation because different callers
+may support different client actions. Orcha exposes only declared client
+actions to that model round. Local actions are always available when compiled.
+
+Only one execution may mutate a session at a time. Concurrent calls for the
+same \`sessionId\` return \`session_busy\`; different sessions can run
+independently.
+
+## Running and resuming
+
+\`\`\`ts
+const execution = orcha.supportBot.run({
+  content: "Check subscription sub_123.",
+  name: "Subscription check",
+  metadata: { accountId: "acct_123" },
+  clientCapabilities: ["request_human_approval"],
+});
+
+for await (const snapshot of execution.stream) {
+  console.log(snapshot);
+}
+
+const result = await execution.result;
+const evaluations = await execution.evaluations;
+\`\`\`
+
+\`run()\` input fields:
+
+- \`content\` (required): a non-empty string, one content item, or an array.
+  Use \`{ filePath: "./document.pdf" }\` for a local file or
+  \`{ url: "https://example.com/document.pdf" }\` for a remote file.
+  \`mimeType\` is optional when it can be inferred from the extension. Durable
+  events store local paths and MIME types, never encoded file bytes.
+- \`name\` (optional): trimmed session label from 1 through 200 characters.
+- \`metadata\` (optional): at most 50 fields with non-empty keys and finite
+  string, number, boolean, or null values. Metadata is durable and available
+  to local action context; never place secrets in it.
+- \`variables\` (optional): at most 50 string values whose keys are JavaScript
+  identifiers. They replace \`{{ variableName }}\` placeholders in
+  \`instructions.md\`, are fixed when the session is created, and are reused
+  by later resumes. A missing referenced variable fails the run.
+- \`clientCapabilities\` (optional): action names the current caller can
+  execute. Client actions not declared here are withheld from the model.
+
+\`run()\` always creates a new durable session. Continue one with:
+
+\`\`\`ts
+const execution = orcha.supportBot.resume(sessionId, {
+  content: "Continue with the confirmed account.",
+});
+\`\`\`
+
+If a result has \`status: "waiting_for_client_action"\`, execute the requested
+client actions in the application and submit every result:
+
+\`\`\`ts
+orcha.supportBot.resume(sessionId, {
+  toolResults: [
+    { callId: "call_123", output: { approved: true } }
+  ],
+});
+\`\`\`
+
+Never invent call IDs. Use the IDs returned in \`clientToolCalls\`.
+
+## Actions
+
+Each action has metadata and, for local actions, executable code:
+
+\`\`\`text
+actions/
+  lookupAccount/
+    index.json
+    index.js
+\`\`\`
+
+\`\`\`json
+{
+  "name": "lookup_account",
+  "description": "Look up one account.",
+  "parameters": {
+    "type": "object",
+    "properties": {
+      "accountId": { "type": "string" }
+    },
+    "required": ["accountId"],
+    "additionalProperties": false
+  },
+  "outputSchema": {
+    "type": "object",
+    "properties": {
+      "status": { "type": "string" }
+    },
+    "required": ["status"],
+    "additionalProperties": false
+  }
+}
+\`\`\`
+
+\`\`\`js
+export default async function lookupAccount({ accountId }) {
+  return { status: "active" };
+}
+\`\`\`
+
+Action entrypoints can use ordinary relative project imports, TypeScript
+modules, npm packages, transitive dependencies, and standard exports. Orcha
+bundles the complete import graph for development and production.
+
+Client actions use \`"execution": "client"\` and do not include executable
+code. Orcha pauses until the caller submits their results. Keep action names,
+descriptions, schemas, and implementations aligned.
+
+Action \`index.json\` fields:
+
+- \`name\` (required): model-facing tool name, 1\u201364 letters, numbers,
+  underscores, or hyphens. \`load_skill\` is reserved.
+- \`description\` (required): tells the model when and why to call the action.
+- \`enabled\` (optional): defaults to \`true\`. Set to \`false\` to keep a WIP
+  action inactive without deleting its folder.
+- \`execution\` (optional): defaults to \`"local"\`, which executes \`index.js\`.
+  Set to \`"client"\` to pause and delegate execution to the application.
+- \`parameters\` (required): JSON Schema for model-generated arguments.
+- \`outputSchema\` (optional): JSON Schema validated against local or submitted
+  client output before the model receives it.
+- \`timeoutMs\` (optional): integer from 1 through 120000; defaults to 10000.
+- \`permissions.env\` (optional): names copied from \`orcha.init().actions.env\`
+  into the action context.
+- \`permissions.network\` (optional): exact hosts or wildcard subdomains such
+  as \`"api.example.com"\` or \`"*.example.com"\` allowed through
+  \`context.fetch\`. Redirects are rejected.
+- \`sideEffect\` (optional): descriptive metadata for whether the operation
+  mutates external state. It does not currently change execution behavior.
+
+\`orcha.init().actions.runtime\` and an action's \`execution\` solve different
+problems:
+
+- \`execution: "client"\`: Orcha never executes code for this action.
+- \`execution: "local"\` + \`runtime: "sandbox"\`: compiled code runs in a
+  QuickJS isolate with JSON-only inputs/outputs, default 32 MB memory, default
+  512 KB stack, interruptible timeout, declared environment values, and
+  allowlisted network access through the provided context.
+- \`execution: "local"\` + \`runtime: "native"\`: code runs in the host Node.js
+  process. It can use host privileges directly. The timeout rejects slow
+  asynchronous work but cannot interrupt synchronous blocking code.
+
+Global local-action configuration:
+
+\`\`\`ts
+actions: {
+  runtime: "sandbox", // optional; native is the default
+  env: {
+    BILLING_API_TOKEN: process.env.BILLING_API_TOKEN,
+  },
+  sandbox: {
+    memoryLimitMb: 32,
+    stackLimitKb: 512,
+  },
+}
+\`\`\`
+
+The local action signature is
+\`(parameters, context) => output | Promise<output>\`. Context contains
+\`sessionId\`, immutable session \`metadata\`, a stable \`idempotencyKey\`,
+allowlisted \`env\`, guarded \`fetch\`, and prefixed \`log\`.
+
+## Skills
+
+Skills are lazy-loaded procedural instructions. Direct child folders under
+\`skills/\` are discovered automatically. Each folder contains \`index.json\`
+metadata and \`instructions.md\`.
+The model receives a compact catalog and can call the internal \`load_skill\`
+tool. Loaded instructions remain active for the durable session. Lifecycle
+events are \`skill.requested\`, \`skill.loaded\`, and \`skill.failed\`.
+
+Skill \`index.json\` fields:
+
+- \`name\` (required): model-facing name, 1\u201364 letters, numbers, underscores,
+  or hyphens; unique within the agent.
+- \`description\` (required): compact catalog description shown before loading.
+- \`enabled\` (optional): defaults to \`true\`. Set to \`false\` to keep a WIP
+  skill inactive.
+- \`triggers\` (optional): non-empty array of non-empty situations describing
+  when the model should load the skill.
+
+\`instructions.md\` is required and cannot be empty for enabled skills.
+\`index.json.name\` is the name used by the model and durable events.
+
+## Tests
+
+Direct child folders under \`tests/\` are discovered automatically. Each
+case's \`index.json\` defines \`input\`, optional mocked action responses, and
+\`expect\`. Tests run the real compiled agent and provider. Actions listed
+under \`actions\` are mocked; unlisted local actions execute live. Orcha reports
+live action use in the terminal, test report, and session trace.
+Client actions must always be mocked because no application client is attached
+to the test runner.
+
+\`\`\`json
+{
+  "input": { "content": "Check account acct_123." },
+  "actions": {
+    "lookup_account": {
+      "responses": [
+        { "output": { "status": "active" } }
+      ]
+    }
+  },
+  "expect": {
+    "status": "completed",
+    "text": { "contains": ["active"] },
+    "actions": [
+      {
+        "name": "lookup_account",
+        "arguments": { "equals": { "accountId": "acct_123" } }
+      }
+    ]
+  }
+}
+\`\`\`
+
+Test sessions use the \`ses_test_<timestamp>_<uuid>\` format and end with a \`test.completed\`
+event. Prefer semantic output assertions; verify exact identifiers and values
+through action-argument assertions.
+
+Test \`index.json\` fields:
+
+- \`name\` (optional): friendly display name. The folder name remains the CLI
+  selector.
+- \`description\` (optional): human-readable purpose.
+- \`enabled\` (optional): defaults to \`true\`. Set to \`false\` to keep a WIP test
+  inactive.
+- \`input\` (required): an inline agent input object or a path to a JSON file
+  containing that object. Relative paths resolve from the test case directory.
+- \`input.content\` (required for inline input): string or multimodal content
+  array.
+- \`input.variables\` (optional): string map available to the session.
+- \`input.metadata\` (optional): string, number, boolean, or null values.
+- \`actions\` (optional): mocked actions keyed by compiled action name. Unlisted
+  local actions execute live and may cause side effects. Unknown action names
+  are rejected, and unlisted client actions are rejected. Every \`responses\`
+  array is consumed in call order.
+- \`responses[].output\` (required): mocked action result.
+- \`responses[].isError\` (optional): marks the mocked result as an error.
+- \`expect.status\` (optional): \`"completed"\` or \`"failed"\`; defaults to
+  \`"completed"\`.
+- \`expect.output.equals\` / \`partial\` (optional): exact or recursive partial
+  comparison against structured output.
+- \`expect.text.contains\` / \`excludes\` (optional): case-sensitive semantic
+  text checks.
+- \`expect.actions\` (optional): ordered expected calls. Each may assert
+  \`arguments.equals\` or \`arguments.partial\`.
+
+The test folder name is the selector used by \`orcha test agent/testName\`.
+
+## Evaluations
+
+Evaluations are asynchronous LLM judges discovered from direct child folders
+under \`evaluations/\`. Each folder's \`index.json\` defines its provider, model,
+metrics, and thresholds:
+
+\`\`\`json
+{
+  "name": "response_quality",
+  "description": "Grounding of agent responses.",
+  "instructions": "Judge the complete response using only confirmed evidence recorded in the session.",
+  "enabled": true,
+  "provider": "openai",
+  "model": "gpt-5-mini",
+  "metrics": [
+    {
+      "name": "groundedness",
+      "description": "The answer relies on confirmed session evidence.",
+      "threshold": 0.8
+    }
+  ]
+}
+\`\`\`
+
+\`execution.result\` does not wait for judges. Await
+\`execution.evaluations\` when results must finish before process exit.
+Evaluations always finish during \`orcha test\`; judge errors and missed
+thresholds fail the test. Lifecycle events are \`evaluation.requested\`,
+\`evaluation.completed\`, and \`evaluation.failed\`.
+
+Evaluation \`index.json\` fields:
+
+- \`name\` (required): durable model-facing identifier, 1\u201364 letters, numbers,
+  underscores, or hyphens; unique within the agent.
+- \`description\` (optional): short human-facing summary of the evaluator.
+- \`instructions\` (optional): detailed prompt supplied to the judge. When
+  omitted, \`description\` is used for backward compatibility.
+- \`enabled\` (optional): defaults to \`true\`. Disabled evaluations are ignored
+  by compilation and runtime.
+- \`provider\` and \`model\` (required): independently select the judge. The
+  provider must also exist in \`orcha.init().providers\`.
+- \`maxTokens\` (optional): positive integer; defaults to 2000 for judges.
+- \`reasoningLevel\` (optional): non-empty provider-native string forwarded
+  without translation.
+- \`metrics\` (required): non-empty array with unique metric names.
+- \`metrics[].name\`: 1\u201364 letters, numbers, underscores, or hyphens.
+- \`metrics[].description\`: exact criterion supplied to the judge.
+- \`metrics[].threshold\`: inclusive number from 0 to 1. A metric passes when
+  the returned score is greater than or equal to this threshold.
+
+The judge sees a sanitized transcript of user/assistant messages, action
+requests and outcomes, client-action activity, and loaded skill names. It does
+not receive internal reasoning blocks, replay metadata, previous evaluation
+results, or test assertions. It must return exactly one score, reasoning
+string, and non-empty evidence array for every configured metric.
+
+## Sessions and logs
+
+The configured session store is the durable source of truth. JSONL stores one
+complete event object per line; SQLite stores one event per row. Events are
+append-only and ordered by \`sequence\`.
+
+All events use this envelope:
+
+\`\`\`ts
+type SessionEvent<T> = {
+  sequence: number;       // starts at 1 and increases across the whole session
+  type: SessionEventType;
+  timestamp: string;      // ISO-8601 UTC timestamp
+  run?: number;           // present for run-scoped events
+  data: T;
+};
+\`\`\`
+
+Session-scoped events omit \`run\`. Optional properties whose values are
+\`undefined\` are omitted from serialized JSON.
+
+Shared stored structures:
+
+\`\`\`ts
+type Usage = {
+  inputTokens: number;
+  outputTokens: number;
+  reasoningTokens: number | null;
+  cacheReadTokens: number;
+  cacheWriteTokens: number;
+};
+
+type ErrorData = {
+  code: string;
+  message: string;
+  retryable?: boolean;
+};
+
+type UserContent =
+  | { type: "text"; text: string }
+  | { type: "file"; filePath: string; mimeType: string }
+  | {
+      type: "image" | "video" | "audio" | "url";
+      mimeType: string;
+      fileUri: string;
+    };
+
+type AssistantContent =
+  | { type: "text"; text: string }
+  | {
+      type: "reasoning";
+      text: string;
+      replay?: { providerId?: string; opaqueData?: string };
+    }
+  | {
+      type: "tool_call";
+      callId: string;
+      name: string;
+      arguments: Record<string, unknown>;
+      replay?: { providerId?: string; opaqueData?: string };
+    };
+
+type ToolResult = {
+  callId: string;
+  output: unknown;
+  isError?: boolean;
+};
+\`\`\`
+
+Exact event payloads:
+
+\`\`\`ts
+type SessionCreated = SessionEvent<{
+  schemaVersion: 1;
+  sessionId: string;
+  agent: string;
+  status: "active";
+  name?: string;
+  metadata: Record<string, string | number | boolean | null>;
+  variables: Record<string, string>;
+  lineage?: {
+    origin: "delegated";
+    parentAgent: string;
+    parentSessionId: string;
+    parentCallId: string;
+  };
+}>; // type "session.created", no run
+
+type SessionUpdated = SessionEvent<{
+  name?: string;
+  metadata?: Record<string, string | number | boolean | null>;
+}>; // type "session.updated", no run
+
+type RunStarted = SessionEvent<{
+  status: "running";
+  agent: string;
+  provider: string;
+  model: string;
+  region: string;
+  reasoningLevel?: string;
+  outputType: "text" | "json";
+  clientCapabilities: string[];
+}>; // type "run.started"
+
+type UserMessageCreated = SessionEvent<{
+  role: "user";
+  content: UserContent[];
+}>; // type "message.created"
+
+type AssistantMessageCreated = SessionEvent<{
+  status: "completed" | "incomplete";
+  provider: string;
+  model: string;
+  responseId?: string;
+  stopReason?: "end_turn" | "tool_call" | "max_tokens" |
+    "content_filter" | "unknown";
+  role: "assistant";
+  content: AssistantContent[];
+  parsedOutput?: unknown; // final JSON output only
+  usage: Usage;
+  durationMs: number;
+}>; // type "message.created"
+
+type ToolMessageCreated = SessionEvent<{
+  role: "tool";
+  content: ToolResult[];
+}>; // type "message.created"
+
+type ActionRequested = SessionEvent<{
+  callId: string;
+  name: string;
+  arguments: Record<string, unknown>;
+  sourceHash?: string;
+  idempotencyKey: string; // sessionId:callId
+}>; // type "action.requested"
+
+type ActionCompleted = SessionEvent<{
+  callId: string;
+  name: string;
+  output: unknown;
+  sourceHash?: string;
+  durationMs: number;
+}>; // type "action.completed"
+
+type ActionFailed = SessionEvent<{
+  callId: string;
+  name: string;
+  sourceHash?: string;
+  durationMs: number;
+  error: {
+    code: "action_execution_failed";
+    message: string;
+  };
+}>; // type "action.failed"
+
+type ClientActionRequested = SessionEvent<{
+  status: "waiting";
+  calls: Array<{
+    callId: string;
+    name: string;
+    arguments: Record<string, unknown>;
+  }>;
+  localResults: ToolResult[];
+  toolCallOrder: string[];
+}>; // type "client_action.requested"
+
+type ClientActionResolved = SessionEvent<{
+  status: "completed";
+  results: ToolResult[];
+}>; // type "client_action.resolved"
+
+type SkillRequested = SessionEvent<{
+  callId: string;
+  name: unknown;
+}>; // type "skill.requested"
+
+type SkillLoaded = SessionEvent<{
+  callId: string;
+  name: string;
+  alreadyLoaded: boolean;
+}>; // type "skill.loaded", no run
+
+type SkillFailed = SessionEvent<{
+  callId: string;
+  name: unknown;
+  error: {
+    code: "skill_not_found";
+    message: string;
+  };
+}>; // type "skill.failed"
+
+type EvaluationRequested = SessionEvent<{
+  name: string;
+  provider: string;
+  model: string;
+  evaluatedThroughSequence: number;
+}>; // type "evaluation.requested"
+
+type EvaluationMetric = {
+  name: string;
+  score: number;
+  threshold: number;
+  passed: boolean;
+  reasoning: string;
+  evidence: string[];
+};
+
+type EvaluationCompleted = SessionEvent<{
+  name: string;
+  status: "passed" | "failed";
+  metrics: EvaluationMetric[];
+  usage?: Usage;
+  durationMs: number;
+  provider: string;
+  model: string;
+  evaluatedThroughSequence: number;
+}>; // type "evaluation.completed"
+
+type EvaluationFailed = SessionEvent<{
+  name: string;
+  status: "error";
+  metrics: [];
+  durationMs: number;
+  error: { message: string };
+  provider: string;
+  model: string;
+  evaluatedThroughSequence: number;
+}>; // type "evaluation.failed"
+
+type SubagentInitiated = SessionEvent<{
+  callId: string;
+  agent: string;
+  sessionId: string;
+  status: "running";
+}>; // type "subagent.initiated"
+
+type SubagentResumed = SessionEvent<{
+  callId: string;
+  agent: string;
+  sessionId: string;
+  status: "running";
+}>; // type "subagent.resumed"
+
+type SubagentCompletedOrPausedOrFailed = SessionEvent<{
+  callId: string;
+  agent: string;
+  sessionId: string;
+  status:
+    | "completed"
+    | "waiting_for_client_action"
+    | "paused"
+    | "failed";
+  output?: unknown;
+  usage?: Usage;
+  clientToolCalls?: Array<{
+    callId: string;
+    name: string;
+    arguments: Record<string, unknown>;
+  }>;
+  error?: ErrorData;
+}>; // type "subagent.completed" | "subagent.paused" | "subagent.failed"
+
+type RunPaused = SessionEvent<{
+  status: "waiting_for_client_action" | "paused";
+  clientToolCalls?: Array<{
+    callId: string;
+    name: string;
+    arguments: Record<string, unknown>;
+  }>;
+  usage?: Usage;
+  output?: unknown;
+  durationMs?: number;
+}>; // type "run.paused"
+
+type RunCompleted = SessionEvent<{
+  status: "completed";
+  durationMs: number;
+  usage: Usage;
+}>; // type "run.completed"
+
+type RunFailed = SessionEvent<{
+  status: "failed";
+  durationMs: number;
+  usage?: Usage;
+  error: ErrorData;
+}>; // type "run.failed"
+
+type SessionPaused = SessionEvent<{
+  status: "paused";
+}>; // type "session.paused", no run
+
+type SessionResumed = SessionEvent<{
+  status: "active";
+}>; // type "session.resumed", no run
+
+type TestCompleted = SessionEvent<{
+  suiteId: string;
+  agent: string;
+  test: string;
+  status: "passed" | "failed";
+  durationMs: number;
+  assertions: Array<{
+    path: string;
+    passed: boolean;
+    message: string;
+    expected?: unknown;
+    actual?: unknown;
+  }>;
+  usage?: Usage;
+  evaluations?: Array<{
+    name: string;
+    status: "passed" | "failed" | "error";
+    metrics: EvaluationMetric[];
+    usage?: Usage;
+    durationMs: number;
+    error?: { message: string };
+  }>;
+  warnings?: Array<{
+    code: "live_actions";
+    message: string;
+    actions: string[];
+  }>;
+  error?: ErrorData;
+}>; // type "test.completed", no run
+
+type TestWarning = SessionEvent<{
+  code: "live_actions";
+  message: string;
+  actions: string[];
+}>; // type "test.warning", no run
+\`\`\`
+
+Typical event order:
+
+\`\`\`text
+session.created
+run.started
+message.created (user)
+message.created (assistant, possibly with tool_call)
+action.requested \u2192 action.completed|action.failed       # local action
+subagent.initiated
+...child session advances independently...
+subagent.paused
+subagent.resumed
+...child session advances independently...
+subagent.completed|subagent.paused|subagent.failed
+message.created (tool)
+...additional model/action rounds...
+message.created (assistant final)
+run.completed
+evaluation.requested
+evaluation.completed|evaluation.failed
+\`\`\`
+
+For client actions, \`client_action.requested\` and \`run.paused\` replace the
+immediate tool message. A later \`resume(...toolResults)\` appends
+\`client_action.resolved\`, the tool message, and continues the same run
+number. A conversational \`resume(...content)\` starts a new run number.
+
+## How Orcha works behind the scenes
+
+### Compilation
+
+1. \`orcha/index.ts\` calls \`orcha.init()\` with explicit agent paths.
+2. The compiler reads each registered agent's \`index.json\` and
+   \`instructions.md\`.
+3. Direct child folders under \`actions/\`, \`skills/\`, \`tests/\`, and
+   \`evaluations/\` are discovered automatically. Items with \`"enabled": false\`
+   remain inactive.
+4. Local action source is bundled and SHA-256 hashed. Production bundles keep
+   only provider adapters required by agents and enabled evaluations.
+5. Invalid paths, duplicate model-facing names, missing files, unsupported
+   configuration values, and missing schema objects fail before execution.
+   Concrete action arguments and outputs are validated against their schemas
+   when the action is used.
+
+\`orcha dev\` repeats validation when files change. \`orcha build\` performs
+offline production compilation. Neither command invokes a provider.
+
+### Run lifecycle
+
+1. \`run()\` creates a \`ses_<timestamp>_<uuid>\`, acquires the per-session execution lock,
+   appends \`session.created\`, then starts run 1.
+2. \`resume()\` reads and validates the existing session. Message continuation
+   starts a new run; submitted client results continue the paused run.
+3. The provider receives the base instructions, available-skill catalog,
+   loaded skill instructions, normalized conversation messages, action
+   schemas, model settings, and current client capabilities.
+4. Provider-specific responses are normalized into text, reasoning, and tool
+   call blocks. Opaque replay metadata is stored only when a provider needs it
+   to replay its own prior block correctly.
+5. Tool calls are checked against compiled actions and declared client
+   capabilities. Arguments and outputs are validated against JSON Schema.
+6. \`load_skill\` updates durable session instructions. Local actions execute
+   through the configured runtime. Client actions pause safely. Tool results
+   are reordered to match the model's original call order.
+7. Internal agent tools start or continue linked child sessions. A
+   \`run_agent\` input accepts the same text or multimodal content shape as a
+   normal run. Local file paths resolve from the configured Orcha project root.
+   The parent reports \`waiting_for_subagent\` until each synchronous child
+   call returns.
+8. The model loop continues until final output, failure, a pause, or the
+   maximum of 10 action rounds.
+9. Usage is normalized and aggregated across every model call in the run.
+10. After \`run.completed\`, enabled evaluations start in the background.
+   \`execution.result\` is already available; \`execution.evaluations\` waits
+   for judge completion and durable persistence.
+
+The per-session lock prevents two model executions from mutating one session
+at once. Background evaluation writes queue behind active runs so they cannot
+cause \`resume()\` to fail spuriously or reuse sequence numbers.
+
+### Replay and context
+
+Orcha does not send raw stored events back to the model. It projects them
+into provider-neutral conversation messages. Completed and explicitly paused
+conversational runs become user, assistant, and tool messages, so a new run
+sees incomplete assistant text preserved by \`pause()\`. Lifecycle bookkeeping
+such as durations, test assertions, and evaluation events is excluded from
+model context. Reasoning text and provider replay metadata are retained where
+needed for faithful continuation but are omitted from evaluation transcripts.
+
+### Reading sessions
+
+- \`agent.get(sessionId)\` projects the latest status, pending client actions,
+  last output, metadata, and aggregate usage.
+- \`agent.history(sessionId, { page, pageSize })\` returns a safe user-facing
+  timeline rather than raw provider bookkeeping.
+- \`agent.events(sessionId, { page, pageSize })\` returns the canonical durable
+  event records for observability, audit, and debugging tools. For subsequent
+  pages of a changing session, pass the first response's \`throughSequence\`
+  back in the options to keep pagination on a stable event boundary.
+- \`agent.list({ page, pageSize, status, metadata })\` lists projected session
+  snapshots.
+- \`agent.subagentHistory(childSessionId, { page, pageSize })\` returns the
+  projected history of a child owned by this parent agent. Lineage checks
+  prevent access through unrelated agents.
+- \`agent.subagentEvents(childSessionId, { page, pageSize })\` returns that
+  owned child's canonical events for full transcript and debugging interfaces.
+- \`agent.pause(sessionId)\` aborts active provider work for the session and
+  active children, preserving streamed text as an incomplete assistant
+  message. \`agent.resume(sessionId)\` starts a new run with \`"Continue."\`;
+  pass content to give different instructions. Pending client actions still
+  require their exact tool results.
+- Never read storage files directly. Use these methods so applications remain
+  compatible with JSONL, SQLite, IndexedDB, remote, and future storage adapters.
+
+## Change rules
+
+- Register every new agent and subagent explicitly. Agent-owned actions, skills,
+  tests, and evaluations are auto-discovered; use \`"enabled": false\` for WIP.
+- Keep runtime behavior provider-neutral.
+- Mock actions when tests must avoid side effects; document intentional live
+  action coverage.
+- Do not commit \`.orcha/\`; it contains generated output and session data.
+- Run \`orcha dev\` after filesystem changes and \`orcha test\` when behavior
+  changes.
+- Do not weaken assertions to match incorrect behavior. Remove an assertion
+  only when it is stricter than the documented agent contract.
+`;
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  AGENTS_MD
+});
+//# sourceMappingURL=cli-agents-template.js.map