The examples index is the first page most visitors open after the root
README, but it never said the scripts import the framework source and
need a repository checkout, which examples run without an API key, or
that four integrations existed at all.
- Add a "Run an example" block (clone, install, key, npx tsx) and note
the two exceptions: observability-v2 needs a build, apps have their
own start scripts. Explain how to port a script into a real project.
- Add a "No API key needed" table for the seven offline examples.
- Let the basics scripts switch provider through OMA_PROVIDER and
OMA_MODEL instead of hard-coding Claude, following the convention the
cookbook already uses.
- List external-agent-acp, external-agent-process, with-engram, and
with-tencentdb-memory, and fail test:example-catalog when a catalog
entry has no link in the index so it cannot drift again.
- Reorder sections so the 20-row providers table no longer sits between
basics and the patterns and cookbook tables; mark production/ as empty.
- Align integrations/README.md with the apps grouping and define the
mcp-<server>.ts versus with-<product>/ naming by example shape.
The example catalog's controlled vocabulary had no term for runtime plan repair, so the only example that runs recovery in repairable mode was filed under generic run-tasks and structured-output capabilities and could not be reached by a capability filter. Adds adaptive-recovery to the runtime validator and the public catalog schema, and tags commission-reconciliation-recovery with it.
Adds a no-key cookbook that walks the full repairable-recovery lifecycle on a synthetic commission reconciliation: three source-scoped investigations produce a typed temporal-evidence gap, a named Replanner appends targeted agreement and policy history lookups plus replacement reconciliation and output tasks, and the run either completes with a RECONCILED result or stops at the configured revision limit and fails closed to MANUAL_REVIEW_REQUIRED outside the task graph. Documents the recipe in docs/adaptive-recovery.md and registers it in the example catalog.
Every observability example used an in-process exporter, which proves the
adapter's semantics but never serializes a span or opens a socket. Nothing in
the repository showed the path an OpenTelemetry user actually takes, so the
exporter choice, Resource, auth headers, and shutdown order were left for each
reader to reconstruct.
`otlp-backend.ts` runs OTel SDK to OTLP/HTTP exporter to HTTP to a backend, and
prints what crossed the wire. The backend is a loopback listener the example
starts itself, so it still needs no API key, no external collector, and no
internet access; `OTLP_URL` and `OTLP_HEADERS` redirect the same payload to a
hosted vendor.
It also demonstrates two things that are easy to get wrong. `service.name`
belongs to the provider's Resource, and a provider built without one files
every span under `unknown_service:node`. Tool input and output require both
halves of the capture opt-in, so the example sets the core policy and the
adapter mode together and states what the run exports without them.
`runToolDemo` joins the shared demo runtime so the example can show a real
`execute_tool` span; the existing `runDemo` export is unchanged. The example is
registered in the catalog and in the smoke script, which now runs eight
examples.
- separate application-owned data from model-visible text, image, and file content
- map rich results across built-in adapters and preserve them through recovery
- retain backward compatibility for string tools and text-only errors
Closes#466
The eval CLI tests and the two example smoke scripts located tsx with a
fixed number of `..` segments, assuming a hoisted install directly above
the workspace. A git worktree has no local node_modules and resolves
upwards to the main checkout, and a non-hoisted install keeps
node_modules inside the workspace, so the path pointed at nothing:
spawnSync failed to launch and 12 tests reported `status: null` instead
of a CLI exit code.
Resolve `tsx/cli` through Node's own module resolution behind a shared
tests/helpers/tsx-cli.ts, and spawn it with process.execPath rather than
executing the node_modules/.bin shim, which is a .cmd wrapper on Windows
that spawnSync cannot launch without a shell. `.bin/tsx` already links
to the same dist/cli.mjs, so the spawned command is unchanged.
Contributors can now run the full core suite directly from a worktree
without hand-linking tsx.
* docs: align Chinese README with English version, optimize translations
- Restructure Chinese README to match English section order
- Add demo image, CI badge, Core Concepts section, AgentPool.runParallel
- Optimize 20+ translations for natural Chinese tech writing
- Tone adjustment: reduce colloquial language, unify terminology
- Remove feature-dump tagline and Grok/Groq disclaimer from both versions
- Clean up English README: fix awkward phrasing, missing article, extra blank line
- Add docs/observability.md and docs/providers.md
* Update README hero animation
* docs: use package-safe README hero URL
Jack Chen