agent-accelerator 0.5.9 → 0.6.5

package/src/prompts/architecture.md

@@ -0,0 +1,19 @@
+# src/prompts/
+
+The prompts the SDK itself puts in front of the model, as plain `.md` files, so they can be read, copied and replaced.
+
+| File                                                                                                                        | What it is                                                                                                                                                                         |
+| :-------------------------------------------------------------------------------------------------------------------------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `prompts.ts`                                                                                                                | `DEFAULT_PROMPTS` (the shipped text, read once at load, final newline removed), `resolvePrompts` (defaults + `AgentConfig.prompts`, validated), `fillPrompt` (`{{name}}` markers). |
+| `reasoning-directive.md`, `structured-output.md`, `additional-context.md`, `tool-bridge.md`                                 | Text added to the system prompt, a user turn or a history gap.                                                                                                                     |
+| `tool-truncated-arguments.md`, `tool-not-found.md`, `tool-schema-error.md`, `tool-repeat-blocked.md`, `tool-interrupted.md` | The refusals the executor and the loop send back as tool results.                                                                                                                  |
+| `worker-replied.md`, `worker-failed.md`                                                                                     | The header of a `subagents` answer.                                                                                                                                                |
+| `subagents-tool.md`, `scheduled-actions-tool.md`                                                                            | The manuals that are the descriptions of the `subagents` and `scheduled_actions` tools.                                                                                            |
+
+## Invariants
+
+- One file per prompt; the name in `FILES` (`prompts.ts`) is the public name. Add a prompt by adding a file, a `FILES` entry, its use, a row in `docs/guides/prompts.md` and a pinned-text assertion in `test/prompts.test.ts`.
+- The default text is pinned exactly by a test: reflowing a file (an editor or formatter) changes what the model sees and the prompt cache, so the test must fail.
+- Every user of a prompt reads it from the Agent's resolved prompts (`agent.prompts`, `loop` config `prompts`, `ProviderRequestOptions.prompts`, executor `prompts`), never from `DEFAULT_PROMPTS` directly, except as the default of an optional parameter.
+- Machine-readable parts stay in code: the `repeat_blocked` `errorCode`, the `[Structured Output]` marker line.
+- The system prompt carries no delegation text (cache-stable): tool manuals are tool descriptions.

package/src/prompts/prompts.ts

@@ -0,0 +1,81 @@
+/**
+ * The prompts the SDK itself puts in front of the model, kept as `.md` files in this folder so they can be read,
+ * copied and replaced. `DEFAULT_PROMPTS` holds the shipped text; `AgentConfig.prompts` overrides single entries per
+ * Agent. Keeping the original is recommended: it is what the SDK was tested with, and a good starting point (and the
+ * reference) for writing your own. `{{name}}` marks a value the SDK fills in at use time.
+ */
+import { readFileSync } from "node:fs";
+import { ConfigError } from "../types/errors.ts";
+
+/** One entry per prompt file: its public name and the file that holds the default text. */
+const FILES = {
+  reasoningDirective: "reasoning-directive.md",
+  structuredOutput: "structured-output.md",
+  additionalContext: "additional-context.md",
+  toolBridge: "tool-bridge.md",
+  toolTruncatedArguments: "tool-truncated-arguments.md",
+  toolNotFound: "tool-not-found.md",
+  toolSchemaError: "tool-schema-error.md",
+  toolRepeatBlocked: "tool-repeat-blocked.md",
+  toolInterrupted: "tool-interrupted.md",
+  workerReplied: "worker-replied.md",
+  workerFailed: "worker-failed.md",
+  subagentsTool: "subagents-tool.md",
+  scheduledActionsTool: "scheduled-actions-tool.md",
+} as const;
+
+/** The name of one SDK prompt (see `DEFAULT_PROMPTS`). */
+export type PromptName = keyof typeof FILES;
+
+/** The text of every prompt, by name. */
+export type Prompts = Record<PromptName, string>;
+
+/** Per-Agent replacements for single prompts (`AgentConfig.prompts`); every other prompt keeps its default. */
+export type PromptOverrides = Partial<Prompts>;
+
+// Reads one prompt file without its final newline; in: DEFAULT_PROMPTS at load, out: the default text.
+function readPrompt(file: string): string {
+  return readFileSync(new URL(`./${file}`, import.meta.url), "utf8").replace(/\n$/, "");
+}
+
+/**
+ * The prompts as shipped. Placeholders (`{{name}}`) are filled in by the SDK: `reasoningDirective` none;
+ * `structuredOutput` `{{schema}}`; `additionalContext` `{{context}}`; `toolTruncatedArguments`, `toolRepeatBlocked`
+ * `{{tool}}`; `toolNotFound` `{{tool}}`, `{{suggestion}}`; `toolSchemaError` `{{tool}}`, `{{detail}}`, `{{keys}}`,
+ * `{{expected}}`; `toolInterrupted` `{{tool}}`, `{{id}}`; `workerReplied` `{{id}}`, `{{text}}`; `workerFailed` `{{id}}`,
+ * `{{reason}}`; `subagentsTool` `{{TOOLS}}`, `{{LIMIT}}`; `scheduledActionsTool` `{{TOOLS}}`.
+ */
+export const DEFAULT_PROMPTS: Readonly<Prompts> = Object.freeze(
+  Object.fromEntries(Object.entries(FILES).map(([name, file]) => [name, readPrompt(file)])) as Prompts
+);
+
+/** Defaults with `overrides` applied. Throws a `ConfigError` for an unknown name or an empty or non-string text. */
+export function resolvePrompts(overrides?: PromptOverrides): Prompts {
+  const out: Prompts = { ...DEFAULT_PROMPTS };
+  if (overrides === undefined) return out;
+  if (!overrides || typeof overrides !== "object" || Array.isArray(overrides)) {
+    throw new ConfigError(
+      '[Agent Accelerator] Invalid prompts: expected an object like { reasoningDirective: "..." } (see DEFAULT_PROMPTS for the names).'
+    );
+  }
+  for (const [name, text] of Object.entries(overrides)) {
+    if (text === undefined) continue;
+    if (!Object.hasOwn(FILES, name)) {
+      throw new ConfigError(
+        `[Agent Accelerator] Unknown prompt "${name}". Valid names: ${Object.keys(FILES).join(", ")}.`
+      );
+    }
+    if (typeof text !== "string" || !text.trim()) {
+      throw new ConfigError(`[Agent Accelerator] Invalid prompt "${name}": expected a non-empty string.`);
+    }
+    out[name as PromptName] = text;
+  }
+  return out;
+}
+
+/** Fills `{{name}}` markers in a prompt from `values`; a marker with no value is left as written. */
+export function fillPrompt(template: string, values: Record<string, string | number>): string {
+  return template.replace(/\{\{(\w+)\}\}/g, (whole, key: string) =>
+    Object.hasOwn(values, key) ? String(values[key]) : whole
+  );
+}

package/src/prompts/reasoning-directive.md

@@ -0,0 +1,5 @@
+[Reasoning Directive]
+
+1. Use internal reasoning strictly for private planning and step-by-step thinking.
+2. Never attempt to execute tools or output final user deliverables inside reasoning.
+3. Once your reasoning is complete, output your final response or function calls directly in the standard response output.

package/src/{scheduler/scheduled-actions.md → prompts/scheduled-actions-tool.md}

@@ -3,6 +3,7 @@ Schedules a sub-agent (a "scheduled action") to run LATER, once or on repeat, on
 Call get_datetime first whenever you create or reschedule, then pick DD from today's date.
 
 COMMANDS (one tool, the `command` field)
+
 - create: schedule a new action. Needs instructions, task and scheduled_action.{name, id, timeToDeliver, meridiem, startCookingInAdvance}. Optional: role, tools, timeoutMs, scheduled_action.repeatEvery, scheduled_action.retries, scheduled_action.onMissed.
 - list: every action with its metadata and state (waiting, cooking, missed, done).
 - get: one action by `id`, with its latest run result.
@@ -12,6 +13,7 @@ COMMANDS (one tool, the `command` field)
 - skip: ignore a missed run of `id` and wait for the next scheduled time.
 
 SCHEDULED_ACTION FIELDS
+
 - name: human label.
 - id: lowercase kebab-case, at most 48 characters, e.g. "daily-ai-brief". The SDK appends 6 characters ("daily-ai-brief-d64aj2"); use that full id in every later command.
 - timeToDeliver: "DD:HH:MM". DD = days from today (00 today, 01 tomorrow, 55 = 55 days ahead). HH:MM = clock time on a 12-hour clock, HH 01-12.
@@ -30,12 +32,14 @@ Weekly report, every Monday at 9:00 AM (use get_datetime to count the days to th
 {"command":"create","instructions":"You review a codebase and report its health.","task":"Report test health, open risks and notable changes this week.","scheduled_action":{"name":"Weekly Codebase Health Report","id":"weekly-code-health","timeToDeliver":"03:09:00","meridiem":"AM","startCookingInAdvance":"00:02:00","repeatEvery":"07:00:00"}}
 
 TIMING ADVICE (do not guess; talk to the user)
+
 - A run must finish before the next one is due, so startCookingInAdvance must be shorter than repeatEvery.
 - Pick the lead time from the job: a quick lookup fits the 10-minute lead ("00:00:10"); research with many tools needs much more.
 - If the job looks too heavy for the gap the user asked for, do not schedule it blindly. Say so and suggest a wider gap, an earlier start, or a lighter task.
 - A run still cooking when the next one is due is skipped, never stacked, so a gap that is too small means lost runs.
 
 RULES
+
 - Each run starts blank and remembers nothing from earlier runs: put everything the worker needs in instructions and task.
 - Results go to files, not into this chat. Tell the user the action is scheduled and when it will be delivered.
 - Never put secrets in instructions or task: they are stored as plain text.

package/src/prompts/structured-output.md

@@ -0,0 +1,2 @@
+Return ONLY valid JSON matching this JSON Schema, with no markdown fences, no commentary, no extra text.
+Schema: {{schema}}

package/src/{agent/subagents.md → prompts/subagents-tool.md}

@@ -1,12 +1,14 @@
 Starts helpers ("workers") that work on a task for you and can be asked again later. A worker is a separate agent with its own instructions, its own tools and its own memory: it knows only what you give it (plus the earlier conversation you choose to copy). Use workers for parallel research, a second opinion, or a long side task you do not want in your own context.
 
 COMMANDS (one tool, the `command` field)
+
 - spawn: start a worker. Needs `name` and `task`. Optional: `instructions` (the worker's own system prompt), `role`, `tools`, `history`. It waits for the worker's first reply and gives you the worker's `id`.
 - message: send `task` to the open worker `id`. The worker remembers everything said to it before. It waits for the reply.
 - close: end the worker `id` when you no longer need it. A closed worker cannot be messaged again.
 - list: your open workers, plus the numbered turns of this conversation that `history` can copy.
 
 FIELDS
+
 - name: a short label such as "researcher". The SDK adds a suffix; use the full `id` it returns ("researcher-1a2b3c4d") in message and close.
 - instructions: the worker's own system prompt: its role, rules and the format you want back.
 - task: for spawn, the first assignment; for message, the next message to that worker.
@@ -23,6 +25,7 @@ Ask it a follow-up:
 {"command":"message","id":"researcher-1a2b3c4d","task":"Now focus on write-heavy workloads."}
 
 RULES
+
 - Several workers at once: make several spawn calls in the same turn. They run in parallel.
 - A worker handles one call at a time. Wait for its reply before messaging it again.
 - {{LIMIT}}

package/src/prompts/tool-bridge.md

@@ -0,0 +1 @@
+I have processed the tool results.

package/src/prompts/tool-interrupted.md

@@ -0,0 +1 @@
+Error: tool_call '{{tool}}' ({{id}}) has no result because the run was interrupted before it completed (recovered by ensureToolPairing). It may have partially executed: check the tool trace before repeating side-effecting work.

package/src/prompts/tool-not-found.md

@@ -0,0 +1 @@
+Error: Tool '{{tool}}' not found.{{suggestion}}

package/src/prompts/tool-repeat-blocked.md

@@ -0,0 +1 @@
+repeat_blocked: Tool '{{tool}}' was called again with identical arguments. The previous result is already available; reuse it or call the tool with different arguments.

package/src/prompts/tool-schema-error.md

@@ -0,0 +1 @@
+Schema validation error for tool '{{tool}}': {{detail}} Received argument keys: [{{keys}}].{{expected}} Fix the arguments and call the tool again with corrected JSON. Do not explain the error, just retry the call.

package/src/prompts/tool-truncated-arguments.md

@@ -0,0 +1 @@
+Error: Tool '{{tool}}' arguments are truncated or incomplete and could not be parsed. Call the tool again with the complete JSON arguments. Do not explain the error, just retry the call.

package/src/prompts/worker-failed.md

@@ -0,0 +1 @@
+[worker {{id}}] failed: {{reason}}

package/src/prompts/worker-replied.md

@@ -0,0 +1,2 @@
+[worker {{id}}] replied:
+{{text}}

package/src/providers/architecture.md

@@ -2,19 +2,21 @@
 
 All HTTP and wire parsing. Canonical mappers (thinking, cache, tool choice, structured output) live in `../providers.ts`, never here.
 
-| File | Wire | Notes |
-| :-- | :-- | :-- |
-| `google.ts` | Google Interactions | Stateful chaining (TTL gate, self-heal on `not_found`), exact replay of raw `steps`, media consts at the top, Gemini 4 long decode as background interactions. |
-| `openai.ts` | OpenAI Responses | Stateless (`store:false`), full history every turn. |
-| `openrouter.ts` | OpenRouter Chat Completions | Every request streams (so it can be cancelled); `generate()` collects its own stream. |
-| `openai-compat.ts` | OpenAI-compatible Chat Completions | Serves every custom prefix; strict subset of fields; no default base URL. |
-| `registry.ts` | - | Routes `provider/model` to an adapter; the registry is immutable; `ModelProvider` helpers. |
-| `shared.ts` | - | Helpers every adapter uses: signals and timers, error payloads, ids, retry-after, SSE scaffold (`linkStreamAbort`, `withAbortTimer`, `readSseData`, `incompleteStreamCheck`, `failStream`). |
+| File               | Wire                               | Notes                                                                                                                                                                                                                                                                                                                                                                                                                              |
+| :----------------- | :--------------------------------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `google.ts`        | Google Interactions                | Stateful chaining (TTL gate, self-heal on `not_found`), exact replay of raw `steps`, media consts at the top, Gemini 4 long decode as background interactions. The inline size checks (`assertGoogleInlineSizes`) exist but are not called yet. A video part's `processing` (`static`/`agentic`) is sent as the block's `processing` field.                                                                                        |
+| `openai.ts`        | OpenAI Responses                   | Stateless (`store:false`), full history every turn.                                                                                                                                                                                                                                                                                                                                                                                |
+| `openrouter.ts`    | OpenRouter Chat Completions        | Every request streams (so it can be cancelled); `generate()` collects its own stream. A turn's `reasoning_details` blocks are kept as `providerSteps` and sent back verbatim on the next request; parsed-PDF `file` annotations travel the same way, so a PDF is not parsed twice. Routing, `parallel_tool_calls`, `reasoning.exclude` and `user` come from `OPENROUTER_*` env vars (see the file header), never from AgentConfig. |
+| `openai-compat.ts` | OpenAI-compatible Chat Completions | Serves every custom prefix; strict subset of fields; no default base URL.                                                                                                                                                                                                                                                                                                                                                          |
+| `registry.ts`      | -                                  | Routes `provider/model` to an adapter; the registry is immutable; `ModelProvider` helpers.                                                                                                                                                                                                                                                                                                                                         |
+| `shared.ts`        | -                                  | Helpers every adapter uses: signals and timers, error payloads, ids, retry-after, SSE scaffold (`linkStreamAbort`, `withAbortTimer`, `readSseData`, `incompleteStreamCheck`, `failStream`).                                                                                                                                                                                                                                        |
 
 ## Contract (`Provider`, in `../types/model.ts`)
+
 `generate(model, context, options)` returns a `ProviderGenerateResult`; `stream(...)` returns an `AssistantMessageEventStream` that ends with an `AgentResponse`; optional `isLongRunning()` tells the loop to skip its whole-call timeouts.
 
 ## Invariants
+
 - Fix shared streaming behaviour in `shared.ts`, never per adapter. Event parsing and request building stay in each adapter.
 - OpenRouter and compat chat chunk handlers are deliberately not merged.
 - A custom prefix never gets another provider's key or base URL.