@nhtio/adk 0.1.0-master-f0aa531d

package/skills/adk-assembly/references/executors-tools-pipelines-events.md

@@ -0,0 +1,113 @@
+# Executors, Tools, Pipelines, and Events
+
+The executor is the only primary reasoning loop. Pipelines prepare or inspect context. Events deliver output and telemetry.
+
+## Executor Contract
+
+`executorCallback` implements `DispatchExecutorFn`:
+
+```ts
+const executor = async (ctx, helpers) => {
+  try {
+    // call model, stream output, execute tools, persist state
+    ctx.ack()
+  } catch (error) {
+    ctx.nack(error instanceof Error ? error : new Error(String(error)))
+  }
+}
+```
+
+The executor must eventually call exactly one terminal signal per invocation:
+
+- `ctx.ack()` for successful completion.
+- `ctx.nack(error)` for failure.
+
+Failing to signal can leave the dispatch loop running until an abort or middleware intervention. Double signaling throws.
+
+For battery executors, use `autoAck: true` for simple one-shot turns that should finish after a tool-call-free response. Omit it only when the application owns a later quality gate or terminal signal.
+
+## Executor Responsibilities
+
+A custom executor owns:
+
+1. Formatting ADK primitives into provider requests.
+2. Calling the model/provider or custom decision runtime.
+3. Streaming functional output through `helpers.reportMessage`, `helpers.reportThought`, and `helpers.reportToolCall`.
+4. Executing requested tools inline with `tool.executor(ctx)(args)`.
+5. Persisting messages, thoughts, and tool calls through `ctx.store*` / `ctx.mutate*`.
+6. Enforcing provider retry, timeout, and loop policies.
+7. Finalizing with `ack()` or `nack()`.
+
+Reporting is not persistence. Use both `helpers.report*` for live output and `ctx.store*` for durable state.
+
+## Tool Wiring
+
+Define tools with `Tool`. The `inputSchema` is both runtime argument validation and the model-visible schema.
+
+Register tools through:
+
+- `tools: [toolA, toolB]` for baseline tools available each turn.
+- `fetchToolsCallback` plus middleware registration for dynamic tools.
+- `new ToolRegistry([...])` or `ToolRegistry.merge(...)` when manually combining registries.
+
+Do not look for `ToolRegistry.fromTools`; construct a registry directly.
+
+Trust rules:
+
+- `trusted: false` is the safe default for inline textual/spooled tool results.
+- Set `trusted: true` only for developer-controlled or explicitly user-authorized output.
+- `Media.trustTier` controls media trust, not `Tool.trusted`.
+
+Tool handler returns are raw. Executors or batteries decide whether to wrap strings/bytes in `SpooledArtifact`, spool bytes, or persist `Media` handles directly.
+
+## Pipeline Placement
+
+ADK has four optional middleware arrays:
+
+- `turnInputPipeline`: once before dispatch. Use for hydration, retrieval, memory loading, rate limits, standing-instruction refresh, and stash setup.
+- `turnOutputPipeline`: once after successful dispatch. Use for memory extraction, analytics, webhooks, and success-only cleanup.
+- `dispatchInputPipeline`: before every executor call. Use for iteration caps, loop detection, and corrective intervention.
+- `dispatchOutputPipeline`: after every executor call. Use for per-iteration logging and inspection.
+
+Middleware must call `next()` to continue. Not calling `next()` short-circuits intentionally.
+
+Hard rules:
+
+- No primary reasoning models in pipelines.
+- Put secondary preprocessing model calls in pipelines only as an explicit cost/security exception.
+- Use `ctx.stash.get()` and `ctx.stash.set()` for cross-middleware data.
+- Do not put critical failure cleanup in `turnOutputPipeline`; it does not run after input or dispatch failures.
+
+## Iteration Guards
+
+Core ADK does not impose iteration limits. Add a dispatch input guard for runaway loops:
+
+```ts
+const iterationCap = async (ctx, next) => {
+  if (ctx.iteration >= 10) {
+    ctx.nack(new Error('Max iterations exceeded'))
+    return
+  }
+  await next()
+}
+```
+
+For repeated tool calls, use the same checksum convention stored on the tool call and inspect `ctx.toolCallCount(checksum)`.
+
+## Events
+
+`runner.run()` returns no assistant data. Output and telemetry leave through two buses.
+
+Functional bus:
+
+- API: `runner.on`, `runner.off`, `runner.once`.
+- Events: `message`, `thought`, `toolCall`.
+- Use for product output: terminal streaming, SSE, WebSocket messages, tool progress UI.
+
+Observability bus:
+
+- API: `runner.observe`, `runner.unobserve`, `runner.observeOnce`.
+- Events include `turnStart`, `turnEnd`, `dispatchStart`, `dispatchEnd`, `iterationStart`, `iterationEnd`, `toolExecutionStart`, `toolExecutionEnd`, `log`, and `error`.
+- Use for tracing, metrics, structured logs, and error reporting only.
+
+Register listeners before `runner.run()`. If removing a listener changes product behavior, it belongs on the functional bus; if removing it only changes telemetry, it belongs on the observability bus.

package/skills/adk-assembly/references/first-integration.md

@@ -0,0 +1,93 @@
+# First Integration Workflow
+
+Use this reference when the user asks to add ADK to an existing project, create a first agent, scaffold a runnable example, or get from zero to one working turn.
+
+## Choose the Integration Path
+
+Ask only when the answer is not inferable from the project:
+
+1. Runtime: Node, browser, worker, CLI, server, or test harness.
+2. Package manager: npm, pnpm, yarn, or bun.
+3. Executor mode:
+   - Mock executor: no key, no network, best first smoke test.
+   - OpenAI battery: Node/server real-model path.
+   - WebLLM battery: browser-local model path.
+   - BYO executor: custom provider, custom prompt rendering, custom retry/tool loop.
+4. Storage mode:
+   - No-op callbacks for first scaffold/tests.
+   - Real callbacks for production conversation continuity.
+
+Default to the mock executor when the user wants a safe local scaffold and has not provided provider credentials.
+
+## Scaffold Shape
+
+For a first integration, create the smallest explicit assembly rather than hiding ADK behind an abstraction:
+
+```text
+src/
+  noop-storage.ts
+  hydrate-messages.ts
+  agent.ts
+```
+
+If the project already has a convention such as `app/`, `lib/`, `server/`, or `packages/*/src`, adapt the directory names but keep the same separation:
+
+- `noop-storage.ts`: all 25 callbacks with correct arity.
+- `hydrate-messages.ts`: `turnInputPipeline` middleware that calls `ctx.fetchMessages()` and adds results to `ctx.turnMessages`.
+- `agent.ts`: `Message`, `TurnRunner`, executor or battery, event listeners, and `runner.run(rawCtx)`.
+
+Do not invent a `noopStorageAdapter` import from `@nhtio/adk`; it is a local snippet copied into the user's project.
+
+## Dependency Step
+
+Add `@nhtio/adk` only if the target project does not already depend on it. For TypeScript examples that run directly from source, add `tsx`, `typescript`, and `@types/node` as dev dependencies when absent.
+
+Use the detected package manager. For pnpm projects:
+
+```sh
+pnpm add @nhtio/adk
+pnpm add -D tsx typescript @types/node
+```
+
+## Mock Executor First
+
+Prefer the Quickstart mock executor for a first smoke test. It should:
+
+1. Create an assistant `Message`.
+2. Stream text with `helpers.reportMessage(id, reply, { isComplete: true })`.
+3. Persist the message with `ctx.storeMessage(...)`.
+4. Call `ctx.ack()` exactly once.
+
+This proves the runner, storage callbacks, hydration middleware, event listener, and raw turn context are wired before introducing provider credentials.
+
+## Real Model Upgrade
+
+When the user asks for a real model and the runtime supports it, replace only the executor slot:
+
+- Use `OpenAIChatCompletionsAdapter` from `@nhtio/adk/batteries/llm` for OpenAI-compatible Chat Completions.
+- Set `autoAck: true` for simple tool-call-free first turns.
+- Require `OPENAI_API_KEY` or the user's configured provider secret at runtime; never hard-code credentials.
+- Keep `noop-storage.ts` and `hydrate-messages.ts` unchanged from the mock scaffold unless the user is also adding persistence.
+
+## Smoke Test Expectations
+
+A minimal smoke run is successful when:
+
+- `runner.on('message', ...)` is registered before `runner.run(...)`.
+- The process prints at least one assistant message chunk.
+- An observability listener sees `turnEnd`.
+- `runner.run(...)` is awaited but not used as the source of assistant text.
+
+If the user has tests, add the narrowest test that observes the `message` event and asserts the expected text. If no test harness exists, provide a runnable script command such as `pnpm exec tsx src/agent.ts`.
+
+## Upgrade Sequence
+
+After the first turn works, add production capabilities one at a time:
+
+1. Replace no-op message and tool-call callbacks with real persistence.
+2. Add tools and ensure tool calls are reported and persisted.
+3. Add retrieval and memory hydration in `turnInputPipeline`.
+4. Add iteration guards in `dispatchInputPipeline`.
+5. Add telemetry through `runner.observe`, not business behavior.
+
+Do not introduce retrieval, memory, tools, and production persistence in the same first scaffold unless the user explicitly asks for a full integration.

package/skills/adk-assembly/references/storage-and-context.md

@@ -0,0 +1,102 @@
+# Storage and Context
+
+ADK does not persist or hydrate state by default. A complete `TurnRunner` assembly provides 25 callbacks, and the application decides when to call fetch callbacks and where to place returned primitives.
+
+## The 25 Required Callbacks
+
+Retrieval callbacks require exactly one declared parameter, usually `ctx`:
+
+- `fetchMemoriesCallback`
+- `fetchMessagesCallback`
+- `fetchThoughtsCallback`
+- `fetchToolCallsCallback`
+- `fetchToolsCallback`
+- `fetchRetrievablesCallback`
+- `refreshStandingInstructionsCallback`
+
+Persistence callbacks require exactly two declared parameters, usually `ctx` and the value or id:
+
+- Store: `storeMemoryCallback`, `storeMessageCallback`, `storeThoughtCallback`, `storeToolCallCallback`, `storeRetrievableCallback`, `storeStandingInstructionCallback`
+- Mutate: `mutateMemoryCallback`, `mutateMessageCallback`, `mutateThoughtCallback`, `mutateToolCallCallback`, `mutateRetrievableCallback`, `mutateStandingInstructionCallback`
+- Delete: `deleteMemoryCallback`, `deleteMessageCallback`, `deleteThoughtCallback`, `deleteToolCallCallback`, `deleteRetrievableCallback`, `deleteStandingInstructionCallback`
+
+No-ops are valid, but omissions and wrong arity are invalid:
+
+```ts
+fetchMessagesCallback: async (_ctx) => []
+deleteMemoryCallback: async (_ctx, _id) => {}
+```
+
+Do not write arity-zero callbacks such as `async () => []` for fetch callbacks or `async () => {}` for write callbacks.
+
+## Persistence Priorities
+
+- `Message` persistence is required for real conversation continuity.
+- `ToolCall` persistence is required for tool-using agents and multi-iteration loops.
+- `Memory`, `Thought`, `Retrievable`, and standing-instruction callbacks can be no-op for early prototypes if the product does not use those features.
+- Storage batteries do not implement these callbacks; they only store spooled artifact bytes.
+
+## Context Hydration Pattern
+
+New turn-scoped sets start empty. ADK exposes fetch methods, but it does not call them automatically.
+
+Hydrate in `turnInputPipeline`:
+
+```ts
+const hydrateMessages = async (ctx, next) => {
+  const messages = await ctx.fetchMessages()
+  for (const message of messages) {
+    ctx.turnMessages.add(message)
+  }
+  await next()
+}
+```
+
+Use the same pattern for memories, thoughts, tool calls, retrievables, tools, and refreshed standing instructions. Put prerequisite hydration first in `turnInputPipeline` so later middleware and the executor see populated context.
+
+## Messages
+
+Messages represent conversation history. To seed the first user message, return a real `Message` instance from `fetchMessagesCallback` and hydrate it into `ctx.turnMessages`. `RawTurnContext` does not accept message history.
+
+## Tools as Context
+
+`fetchToolsCallback` is required but not automatic. Baseline tools can be supplied in `TurnRunnerConfig.tools`. Dynamic tools must be fetched manually and registered:
+
+```ts
+const dynamicToolsMiddleware = async (ctx, next) => {
+  const tools = await ctx.fetchTools()
+  for (const tool of tools) {
+    ctx.tools.register(tool)
+  }
+  await next()
+}
+```
+
+## Retrieval
+
+Use `Retrievable` for external documents and RAG chunks. Inject standard RAG results in `turnInputPipeline`, not in the executor, unless the task genuinely requires mid-loop search.
+
+Trust tiers are security controls:
+
+- `first-party`: controlled internal content.
+- `third-party-public`: public web/API content.
+- `third-party-private`: user uploads, private integrations, untrusted private content.
+
+Never label user-supplied or public content as `first-party`. Rank, limit, and truncate retrieval results to fit the context budget.
+
+## Memory
+
+Memory is curated durable fact state, not conversation history and not RAG context.
+
+Memory lifecycle:
+
+1. Load ranked memories by explicitly calling `ctx.fetchMemories()` in `turnInputPipeline`.
+2. Add returned `Memory` instances to `ctx.turnMemories`.
+3. Write new memories in one audited path: executor, output middleware, or an external background process.
+4. Persist lifecycle policy through `storeMemoryCallback`, `mutateMemoryCallback`, and `deleteMemoryCallback`.
+
+Avoid storing raw user text as trusted memory. Store source/trust metadata in the application database because the ADK `Memory` primitive contains content, confidence, importance, and timestamps, not a trust tier.
+
+## Standing Instructions
+
+Standing instructions are `string | Tokenizable`, not instances of a `StandingInstruction` class. Refresh them explicitly with `ctx.refreshStandingInstructions()` when the assembly needs current operator or tenant instructions.