@agent-native/core 0.100.2 → 0.101.3

package/corpus/core/docs/content/pr-visual-recap.mdx

@@ -102,13 +102,13 @@ explicitly at any time:
 npx @agent-native/core@latest skills add visual-plan --with-github-action
 ```
 
-This installs the `visual-plan` skill (which includes the `visual-recap` skill the action runs) and writes `.github/workflows/pr-visual-recap.yml` into your repo. The workflow calls **published CLI subcommands** through `npx @agent-native/core@latest recap <subcommand>` — including `gate`, `collect-diff`, `block-reference`, `scan`, `build-prompt`, `publish`, `shot`, `comment`, `check`, and `usage` — so nothing is copied into your repo as helper scripts. `setup` and `doctor` are the interactive helpers you run locally; `gate` is the security-gate step the workflow runs before every recap.
+This installs the `visual-plan` skill (which includes the `visual-recap` skill the action runs) and writes `.github/workflows/pr-visual-recap.yml` into your repo. The workflow calls **published CLI subcommands** through `npx @agent-native/recap-cli@latest recap <subcommand>` — including `gate`, `collect-diff`, `block-reference`, `scan`, `build-prompt`, `publish`, `shot`, `comment`, `check`, and `usage` — so nothing is copied into your repo as helper scripts. `setup` and `doctor` are the interactive helpers you run locally; `gate` is the security-gate step the workflow runs before every recap.
 
 Then run the guided setup helper:
 
 ```bash
-npx @agent-native/core@latest recap setup
-npx @agent-native/core@latest recap doctor
+npx @agent-native/recap-cli@latest recap setup
+npx @agent-native/recap-cli@latest recap doctor
 ```
 
 `recap setup` refreshes the workflow, uses `gh` to set GitHub Actions
@@ -118,7 +118,7 @@ set. Secret values are sent to `gh` through stdin, not command arguments. Commit
 the generated workflow file and open a PR to see it run.
 
 By default, the workflow builds its agent prompt from the latest bundled
-`visual-recap` guidance in `@agent-native/core@latest`, including any sibling
+`visual-recap` guidance in `@agent-native/recap-cli@latest`, including any sibling
 reference files the skill ships with. If your repo intentionally customizes and
 pins its committed `visual-recap` folder, set the repository variable
 `VISUAL_RECAP_SKILL_SOURCE=repo`.
@@ -140,8 +140,8 @@ To configure it during guided setup, pass the same JSON value to `--runs-on`,
 then validate the workflow and runner availability with `doctor`:
 
 ```bash
-npx @agent-native/core@latest recap setup --runs-on '["self-hosted","linux","x64","visual-recap"]'
-npx @agent-native/core@latest recap doctor
+npx @agent-native/recap-cli@latest recap setup --runs-on '["self-hosted","linux","x64","visual-recap"]'
+npx @agent-native/recap-cli@latest recap doctor
 ```
 
 The lightweight security gate defaults separately to GitHub-hosted
@@ -186,7 +186,7 @@ If the variable is unset, the action uses `claude`.
 
 Beyond the backend, these repository variables tune how the agent runs:
 
-- **`VISUAL_RECAP_MODEL`** pins the model passed to the CLI (`--model`) — for example `gpt-5.6-sol` for Codex, a Claude model id, or `deepseek-chat` for DeepSeek. It is required for `openai-compatible`; Claude and Codex may leave it unset to use their CLI default.
+- **`VISUAL_RECAP_MODEL`** pins the model passed to the CLI (`--model`) — for example `gpt-5.6-luna` for Codex, a Claude model id, or `deepseek-chat` for DeepSeek. It is required for `openai-compatible`. For the **Claude** backend, leaving it unset now defaults to `claude-sonnet-5`; set the variable explicitly to use a different Claude model, such as the cheaper `claude-haiku-4-5`. For the **Codex** backend, leaving it unset uses the Codex CLI's own default model.
 - **`VISUAL_RECAP_REASONING`** sets the reasoning depth: `none`, `minimal`, `low`, `medium`, `high`, or `xhigh`. It applies to the Codex backend; Claude's reasoning is model-driven, so this variable is ignored there.
 - **`VISUAL_RECAP_BASE_URL`** selects the HTTP(S) base URL for the `openai-compatible` backend. Use the provider's OpenAI-compatible endpoint, such as DeepSeek or Kimi, without embedding credentials in the URL.
 - **`VISUAL_RECAP_SKILL_SOURCE`** controls prompt freshness: `auto`/unset uses the latest bundled skill guidance, while `repo` pins to the committed repo-local `visual-recap` skill folder.
@@ -195,6 +195,24 @@ For example, to run the recap on Codex with GPT-5.6 Sol at high reasoning, set t
 
 For DeepSeek, set `VISUAL_RECAP_AGENT=openai-compatible`, `VISUAL_RECAP_BASE_URL=https://api.deepseek.com/v1`, `VISUAL_RECAP_MODEL=deepseek-chat`, and the `VISUAL_RECAP_API_KEY` secret. Kimi works the same way with its OpenAI-compatible base URL and model id. Other OpenAI-compatible providers use the same three settings.
 
+## Cost
+
+Each recap run is a full agentic coding-agent session reading a real diff, not a cheap templated summary, so its cost tracks model choice and how often it runs:
+
+- **A full session per PR push.** The default trigger fires on `synchronize`, so a PR that gets pushed to ten times runs the agent ten times.
+- **The whole PR each time**, not just the commits since the last run — cost scales with total PR size, not incremental diff size.
+- **Diff input capped at ~600KB.** This bounds the worst case per run, but large diffs still cost meaningfully more than small ones.
+- **One automatic retry on failure**, which can roughly double the cost of a run that fails transiently.
+
+To reduce cost:
+
+- **Pin a cheaper model.** For Claude, set `VISUAL_RECAP_MODEL=claude-haiku-4-5` for simple or small repos — it's the cheapest Claude tier; `claude-sonnet-5` (the default) is the balanced tier.
+- **Switch to Codex with a cheaper model.** Set `VISUAL_RECAP_AGENT=codex` with `VISUAL_RECAP_MODEL=gpt-5.6-luna` (the cheapest GPT-5.6 tier) or `gpt-5.6-terra` (mid-tier), and set `VISUAL_RECAP_REASONING=low` to cut reasoning-token spend further. Reasoning depth only applies to Codex.
+- **Point at a cheaper OpenAI-compatible provider.** Set `VISUAL_RECAP_AGENT=openai-compatible` with `VISUAL_RECAP_BASE_URL`/`VISUAL_RECAP_MODEL`/`VISUAL_RECAP_API_KEY` targeting DeepSeek, Kimi, or any other OpenAI-compatible endpoint.
+- **Recap less often.** Edit the installed workflow's `on.pull_request.types` from `[opened, synchronize, reopened, ready_for_review, closed]` to `[opened, ready_for_review, closed]` so it recaps only when a PR opens and when it merges, instead of on every push.
+
+Every run records what it actually spent: the workflow's `recap usage` step attaches token and cost usage to the published plan, so you can look at real spend per run instead of guessing.
+
 ## Secrets and variables
 
 Set these in your repository's **Settings → Secrets and variables → Actions**.
@@ -225,11 +243,11 @@ Plans app.
 
 **Solo: a personal token still works.** Mint it with `npx @agent-native/core@latest connect`
 against your Plans app. For the hosted app, this also writes a local
-publish-token file that `npx @agent-native/core@latest recap setup` can read:
+publish-token file that `npx @agent-native/recap-cli@latest recap setup` can read:
 
 ```bash
 npx @agent-native/core@latest connect https://plan.agent-native.com --client codex
-npx @agent-native/core@latest recap setup
+npx @agent-native/recap-cli@latest recap setup
 ```
 
 If you prefer manual setup, paste the token into the GitHub secret. Use a
@@ -238,18 +256,18 @@ real token.
 
 ### Optional (only if you change defaults)
 
-| Secret / variable        | Default                         | When you need it                                                                                                                                |
-| ------------------------ | ------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- |
-| `OPENAI_API_KEY`         | —                               | Secret. Set together with `VISUAL_RECAP_AGENT=codex` to run the recap with Codex instead.                                                       |
-| `VISUAL_RECAP_API_KEY`   | —                               | Secret. Set with `VISUAL_RECAP_AGENT=openai-compatible` for DeepSeek, Kimi, or another OpenAI-compatible provider.                              |
-| `VISUAL_RECAP_AGENT`     | `claude`                        | Variable. Selects the coding-agent backend (`claude`, `codex`, or `openai-compatible`).                                                         |
-| `VISUAL_RECAP_BASE_URL`  | required for compatible backend | Variable. HTTP(S) base URL for the OpenAI-compatible backend; credentials are rejected.                                                         |
-| `VISUAL_RECAP_MODEL`     | required for compatible backend | Variable. Provider model id for OpenAI-compatible backends; optional for Claude/Codex, where unset uses the CLI default.                        |
-| `VISUAL_RECAP_REASONING` | each model's default            | Variable. Reasoning depth: `none`, `minimal`, `low`, `medium`, `high`, or `xhigh`. Applies to the Codex backend.                                |
-| `RECAP_CLI_VERSION`      | `latest`                        | Variable. Pins the `@agent-native/core` CLI version the workflow installs — e.g. `1.5.0`. See [Version pinning](#version-pinning-copy-variant). |
-| `PLAN_RECAP_APP_URL`     | `https://plan.agent-native.com` | Secret. Only when self-hosting the Plans app at a different origin.                                                                             |
+| Secret / variable        | Default                                                       | When you need it                                                                                                                                                                                                                                         |
+| ------------------------ | ------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `OPENAI_API_KEY`         | —                                                             | Secret. Set together with `VISUAL_RECAP_AGENT=codex` to run the recap with Codex instead.                                                                                                                                                                |
+| `VISUAL_RECAP_API_KEY`   | —                                                             | Secret. Set with `VISUAL_RECAP_AGENT=openai-compatible` for DeepSeek, Kimi, or another OpenAI-compatible provider.                                                                                                                                       |
+| `VISUAL_RECAP_AGENT`     | `claude`                                                      | Variable. Selects the coding-agent backend (`claude`, `codex`, or `openai-compatible`).                                                                                                                                                                  |
+| `VISUAL_RECAP_BASE_URL`  | required for compatible backend                               | Variable. HTTP(S) base URL for the OpenAI-compatible backend; credentials are rejected.                                                                                                                                                                  |
+| `VISUAL_RECAP_MODEL`     | `claude-sonnet-5` for Claude; required for compatible backend | Variable. Provider model id for OpenAI-compatible backends (required there). For Claude, unset now defaults to `claude-sonnet-5` — set it to override, e.g. `claude-haiku-4-5` for the cheapest tier. For Codex, unset uses the Codex CLI's own default. |
+| `VISUAL_RECAP_REASONING` | each model's default                                          | Variable. Reasoning depth: `none`, `minimal`, `low`, `medium`, `high`, or `xhigh`. Applies to the Codex backend.                                                                                                                                         |
+| `RECAP_CLI_VERSION`      | `latest`                                                      | Variable. Pins the `@agent-native/recap-cli` version the workflow installs — e.g. `1.5.0`. See [Version pinning](#version-pinning-copy-variant).                                                                                                         |
+| `PLAN_RECAP_APP_URL`     | `https://plan.agent-native.com`                               | Secret. Only when self-hosting the Plans app at a different origin.                                                                                                                                                                                      |
 
-The workflow auto-detects how to invoke its helper CLI (local source inside this monorepo, the published `@agent-native/core` elsewhere), so there is no `RECAP_CLI` variable to set.
+The workflow auto-detects how to invoke its helper CLI (local source inside this monorepo, the published `@agent-native/recap-cli` elsewhere), so there is no `RECAP_CLI` variable to set.
 
 ## Inline screenshot in the comment
 
@@ -390,9 +408,9 @@ recap without sending recap content to the Agent-Native Plan database, run the
 same helper flow locally in local-files mode instead:
 
 ```bash
-npx @agent-native/core@latest recap collect-diff --base main --head HEAD --out recap.diff --stat recap.stat
-npx @agent-native/core@latest recap scan --diff recap.diff
-npx @agent-native/core@latest recap build-prompt --pr 123 --diff recap.diff --stat recap.stat --local-files --local-dir plans/pr-123-visual-recap
+npx @agent-native/recap-cli@latest recap collect-diff --base main --head HEAD --out recap.diff --stat recap.stat
+npx @agent-native/recap-cli@latest recap scan --diff recap.diff
+npx @agent-native/recap-cli@latest recap build-prompt --pr 123 --diff recap.diff --stat recap.stat --local-files --local-dir plans/pr-123-visual-recap
 ```
 
 Give the generated `recap-prompt.md` to your coding agent. In local-files mode
@@ -422,7 +440,7 @@ The recap is a review aid layered on top of the normal PR flow:
 
 ## Version pinning (copy variant) {#version-pinning-copy-variant}
 
-By default the copy-variant workflow installs `@agent-native/core@latest` at run time so every recap run automatically picks up the newest CLI. If your CI needs reproducible tooling, set the **`RECAP_CLI_VERSION`** repository variable to pin the installed version:
+By default the copy-variant workflow installs `@agent-native/recap-cli@latest` at run time so every recap run automatically picks up the newest CLI. If your CI needs reproducible tooling, set the **`RECAP_CLI_VERSION`** repository variable to pin the installed version:
 
 1. Go to your repo's **Settings → Secrets and variables → Actions → Variables**.
 2. Create a variable named `RECAP_CLI_VERSION` with a value like `1.5.0`.
@@ -433,7 +451,7 @@ For the reusable-caller variant, use the `cli-version` input instead (see [Versi
 
 ## Secret-scan allowlist
 
-Before publishing a recap the workflow runs `npx @agent-native/core@latest recap scan` to detect likely secrets in the diff. Any PR whose diff matches a known-secret pattern is blocked with an explanatory comment — the recap is not published, and no diff content is sent to the coding agent.
+Before publishing a recap the workflow runs `npx @agent-native/recap-cli@latest recap scan` to detect likely secrets in the diff. Any PR whose diff matches a known-secret pattern is blocked with an explanatory comment — the recap is not published, and no diff content is sent to the coding agent.
 
 In rare cases a repo has intentional test fixtures or non-secret strings that superficially resemble secret patterns (e.g., a fixture key in a test file). To suppress a false positive, create `.github/recap-scan-allowlist` in the root of your repository.
 
@@ -467,7 +485,7 @@ The allowlist is only consulted by the secret-scan gate. It does not affect what
 
 ### Why use the reusable variant?
 
-The default installer copies the full ~360-line workflow YAML into your repo (the **copy** option). This is the right choice for air-gapped repos or repos that need to audit every line of what runs. The downside is that bug fixes and improvements never reach you — you need to re-run `npx @agent-native/core@latest recap setup` manually after each release.
+The default installer copies the full ~360-line workflow YAML into your repo (the **copy** option). This is the right choice for air-gapped repos or repos that need to audit every line of what runs. The downside is that bug fixes and improvements never reach you — you need to re-run `npx @agent-native/recap-cli@latest recap setup` manually after each release.
 
 The **reusable** option writes a thin ~20-line caller instead. It delegates to `BuilderIO/agent-native/.github/workflows/pr-visual-recap-reusable.yml` via `uses:`. Every caller automatically picks up the latest logic when the workflow runs, with no local update needed.
 
@@ -480,7 +498,7 @@ The **reusable** option writes a thin ~20-line caller instead. It delegates to `
 
 ### Caller snippet
 
-This is what `npx @agent-native/core@latest recap setup --reusable` writes (or you can paste it manually):
+This is what `npx @agent-native/recap-cli@latest recap setup --reusable` writes (or you can paste it manually):
 
 ```yaml
 name: PR Visual Recap
@@ -517,7 +535,7 @@ jobs:
       skill-source: ${{ vars.VISUAL_RECAP_SKILL_SOURCE || 'auto' }}
       runs-on: ${{ vars.VISUAL_RECAP_RUNS_ON || '"ubuntu-latest"' }}
       gate-runs-on: ${{ vars.VISUAL_RECAP_GATE_RUNS_ON || 'ubuntu-latest' }}
-      # cli-version: "latest"  # pin to a specific @agent-native/core version
+      # cli-version: "latest"  # pin to a specific @agent-native/recap-cli version
 ```
 
 The same secrets and variables described in [Secrets and variables](#secrets-and-variables) apply — set them in your repo settings the same way as for the copy variant. The reusable caller forwards `VISUAL_RECAP_RUNS_ON` through its JSON `runs-on` input for the full recap job and `VISUAL_RECAP_GATE_RUNS_ON` through its plain-label `gate-runs-on` input for the metadata-only gate. The latter is used only for trusted same-repository authors; other PRs use GitHub-hosted `ubuntu-latest`. Omitting either input preserves its `ubuntu-latest` default.
@@ -526,15 +544,15 @@ The same secrets and variables described in [Secrets and variables](#secrets-and
 
 ```bash
 # Write the thin caller instead of the full copy:
-npx @agent-native/core@latest recap setup --reusable
+npx @agent-native/recap-cli@latest recap setup --reusable
 
 # Or with a pinned ref for reproducibility:
-npx @agent-native/core@latest recap setup --reusable --ref v1.2.3
+npx @agent-native/recap-cli@latest recap setup --reusable --ref v1.2.3
 ```
 
 Both variants write the workflow to `.github/workflows/pr-visual-recap.yml`. If an existing workflow is already there and differs, the command refuses and tells you to pass `--force` to overwrite.
 
-After writing, run `npx @agent-native/core@latest recap doctor` as usual to confirm secrets are configured.
+After writing, run `npx @agent-native/recap-cli@latest recap doctor` as usual to confirm secrets are configured.
 
 ### Version pinning
 
@@ -544,7 +562,7 @@ By default the caller references `@main`, which always uses the latest published
 uses: BuilderIO/agent-native/.github/workflows/pr-visual-recap-reusable.yml@v1.2.3
 ```
 
-The `cli-version` input controls which `@agent-native/core` CLI version runs inside the workflow — leave it at `"latest"` to track the newest release, or pin it to a version string (e.g. `"1.5.0"`) for full reproducibility.
+The `cli-version` input controls which `@agent-native/recap-cli` version runs inside the workflow — leave it at `"latest"` to track the newest release, or pin it to a version string (e.g. `"1.5.0"`) for full reproducibility.
 
 ### workflow_call event context
 

package/corpus/core/docs/content/template-plan.mdx

@@ -226,6 +226,20 @@ If the first pass still has answerable decisions, the agent can place an
 **Open Questions** form at the bottom of the same plan. Answering it and sending
 it to the agent starts a revision turn against the existing plan.
 
+## Cost and model choice
+
+Generating a plan or recap runs a full agentic session against your coding
+agent's LLM, not a lightweight template fill, so cost scales with the size of
+the diff or plan and the model you choose.
+
+- The app's own default chat model is Sonnet 5; change it any time in
+  **Settings**. Haiku is the cheaper Claude option, and Luna is the cheaper
+  option in the GPT-5.6 family.
+- Automated PR recaps from the GitHub Action run separately from the
+  interactive app and have their own model and cost knobs — see
+  [PR Visual Recap](/docs/pr-visual-recap) for `VISUAL_RECAP_MODEL`,
+  `VISUAL_RECAP_AGENT`, and `VISUAL_RECAP_REASONING`.
+
 ## What you can do with it
 
 - **Review before implementation.** React to diagrams, wireframes, option tabs,

package/corpus/core/docs/content/toolkit-comments-review.mdx

@@ -24,9 +24,9 @@ status such as draft, review, approved, or needs changes.
 | ------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- |
 | `registerReviewableResource()` | Register a resource type and optional access resolver for review actions.                                                                                         |
 | Comment actions                | `list-review-comments`, `create-review-comment`, `reply-review-comment`, `resolve-review-thread`, and `delete-review-comment`.                                    |
-| Feedback actions               | `get-review-feedback` and `consume-review-feedback` for agent-readable review queues.                                                                             |
+| Feedback actions               | `get-review-feedback`, `send-review-thread-to-agent`, and `consume-review-feedback` for root-thread agent queues and human handoffs.                              |
 | Review status action           | `set-review-status` for draft, in review, approved, and changes requested states.                                                                                 |
-| `ReviewThreadPanel`            | Drop-in React panel with comment composer, replies, resolve, and delete controls.                                                                                 |
+| `ReviewThreadPanel`            | Drop-in React panel with capability-gated composer, reply, resolve, delete, and custom thread-action controls.                                                    |
 | `ReviewStatusBadge`            | Controlled status badge for app headers, sidebars, and review panels.                                                                                             |
 | Review hooks                   | `useReviewComments()`, `useCreateReviewComment()`, `useReplyReviewComment()`, `useResolveReviewThread()`, `useDeleteReviewComment()`, and `useSetReviewStatus()`. |
 | Mentions helpers               | `extractReviewMentions()` and `normalizeReviewMentions()` for `@[Label](mailto:email@example.com)` tokens.                                                        |
@@ -42,6 +42,13 @@ specialize anchor shapes, but the common model preserves:
 - `parentCommentId` for replies
 - optional `mentions`
 - optional `anchor` or `resolutionTarget`
+- optional `resolutionNote` on a resolved root thread
+
+`list-review-comments` supports anonymous reads for resources whose access
+resolver grants public viewer access. Public viewer responses redact ownership,
+organization, email, and actor metadata while preserving safe display names and
+the caller-specific `canDelete` capability. Its `summary` reports unpaginated
+open-root and agent-queue counts even when the returned comment page is bounded.
 
 ## Register A Resource {#register-resource}
 
@@ -76,6 +83,9 @@ export function DocumentReview({ documentId }: { documentId: string }) {
       resourceType="document"
       resourceId={documentId}
       targetId="intro-section"
+      canReply
+      canResolve={false}
+      canDeleteComment={(comment) => comment.canDelete === true}
     />
   );
 }
@@ -93,6 +103,10 @@ actions and thread UI.
 - Agents can read open review feedback before changing code or content.
 - `consumedAt` and `resolved` are separate. An agent can consume a piece of
   feedback without closing the reviewer-visible thread.
+- The root comment owns routing. A human-targeted root is absent from the agent
+  queue; sending it back to the agent clears its previous consumption marker.
+- Agents can pass `resolutionNote` to `resolve-review-thread` so verification
+  evidence remains attached to the resolved root.
 
 ## What's next
 

package/corpus/core/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agent-native/core",
-  "version": "0.100.2",
+  "version": "0.101.3",
   "description": "Framework for agent-native application development — where AI agents and UI share SQL state, actions, and context",
   "homepage": "https://github.com/BuilderIO/agent-native#readme",
   "bugs": {
@@ -156,6 +156,7 @@
     "./review/actions/consume-review-feedback": "./dist/review/actions/consume-review-feedback.js",
     "./review/actions/get-review-feedback": "./dist/review/actions/get-review-feedback.js",
     "./review/actions/set-review-status": "./dist/review/actions/set-review-status.js",
+    "./review/actions/send-review-thread-to-agent": "./dist/review/actions/send-review-thread-to-agent.js",
     "./comments-review/actions/list-review-comments": "./dist/review/actions/list-review-comments.js",
     "./comments-review/actions/create-review-comment": "./dist/review/actions/create-review-comment.js",
     "./comments-review/actions/reply-review-comment": "./dist/review/actions/reply-review-comment.js",
@@ -164,6 +165,7 @@
     "./comments-review/actions/consume-review-feedback": "./dist/review/actions/consume-review-feedback.js",
     "./comments-review/actions/get-review-feedback": "./dist/review/actions/get-review-feedback.js",
     "./comments-review/actions/set-review-status": "./dist/review/actions/set-review-status.js",
+    "./comments-review/actions/send-review-thread-to-agent": "./dist/review/actions/send-review-thread-to-agent.js",
     "./sharing": "./dist/sharing/index.js",
     "./sharing/actions/share-resource": "./dist/sharing/actions/share-resource.js",
     "./sharing/actions/unshare-resource": "./dist/sharing/actions/unshare-resource.js",
@@ -251,6 +253,7 @@
     "prepublishOnly": "npm run build"
   },
   "dependencies": {
+    "@agent-native/recap-cli": "workspace:*",
     "@agent-native/toolkit": "workspace:^",
     "@amplitude/analytics-browser": "^2.41.1",
     "@anthropic-ai/sdk": "^0.90.0",

package/corpus/core/src/a2a/index.ts

@@ -1,5 +1,6 @@
 // Server (H3/Nitro)
-export { mountA2A } from "./server.js";
+export { mountA2A, verifyA2AToken } from "./server.js";
+export type { A2ATokenPayload } from "./server.js";
 export { generateAgentCard } from "./agent-card.js";
 
 // Client

package/corpus/core/src/a2a/server.ts

@@ -38,10 +38,11 @@ function warnA2AUnauthOnce(): void {
 }
 
 /**
- * Verify an inbound A2A JWT signed with the shared A2A_SECRET.
- * Returns the caller's email (from `sub` claim) if valid, null otherwise.
+ * Result of verifying an inbound A2A JWT. `email` is the caller identity from
+ * the token's `sub` claim (null when verification fails), `orgDomain` mirrors
+ * the verified `org_domain` claim when present.
  */
-interface A2ATokenPayload {
+export interface A2ATokenPayload {
   email: string | null;
   orgDomain: string | null;
 }
@@ -58,9 +59,11 @@ function addSecretCandidate(
 /**
  * Resolve the audience (`aud`) value to expect in an inbound JWT. We use the
  * receiver's app URL — it's the natural identifier of "who this token was
- * minted for". Falls back to undefined when no app URL is configured, in
- * which case the audience check is skipped (backward-compat with tokens
- * minted before the audience claim shipped).
+ * minted for". Returns undefined when no app URL is configured and no request
+ * host is derivable; `verifyA2AToken` then rejects any token that carries an
+ * `aud` claim (fail closed — a correctly signed token minted for another
+ * service must not verify here). Only tokens without an `aud` claim (minted
+ * before the audience claim shipped) skip the audience check.
  */
 function expectedJwtAudience(event: any | undefined): string | undefined {
   const fromEnv =
@@ -80,9 +83,24 @@ function expectedJwtAudience(event: any | undefined): string | undefined {
   return undefined;
 }
 
-async function verifyA2AToken(
+/**
+ * Verify an inbound A2A bearer token (HS256) exactly as the
+ * `/_agent-native/a2a` endpoint does: it peeks at the unverified `org_domain`
+ * claim to build an ordered candidate-secret set (`process.env.A2A_SECRET`
+ * plus any org-level secret for that domain), then verifies the JWT — checking
+ * `aud`/`iss` when the token carries them and `exp` always. Returns the
+ * caller's email (`sub`) and org domain on success, or `{ email: null,
+ * orgDomain: null }` on any failure (malformed, bad signature, expired, or no
+ * secret configured), never throwing.
+ *
+ * Exported so workspaces can accept A2A callers on the HTTP action route with
+ * the same routine — including org-level fallback secrets — instead of
+ * reimplementing a partial verifier. Pass the H3 `event` to enable org-domain →
+ * org-secret lookup and audience derivation; it is optional.
+ */
+export async function verifyA2AToken(
   token: string,
-  event: any | undefined,
+  event?: any,
 ): Promise<A2ATokenPayload> {
   // Step 1: Peek at JWT claims WITHOUT verification to get org_domain.
   // This is safe because we only use org_domain to look up the secret,
@@ -132,8 +150,15 @@ async function verifyA2AToken(
   try {
     const verifyOptions: jose.JWTVerifyOptions = {};
     if (unverifiedPayload && typeof unverifiedPayload.aud !== "undefined") {
+      // Fail closed: the token was minted for a specific audience, but this
+      // receiver can't derive its own expected audience (no APP_URL/URL and no
+      // usable request host). Accepting here would let a correctly-signed token
+      // whose `aud` targets ANOTHER service verify against a shared secret. A
+      // token that self-declares an audience must be checked against ours, so
+      // when we have nothing to check it against we reject rather than skip.
       const aud = expectedJwtAudience(event);
-      if (aud) verifyOptions.audience = aud;
+      if (!aud) return { email: null, orgDomain: null };
+      verifyOptions.audience = aud;
     }
     if (
       unverifiedPayload &&

package/corpus/core/src/agent/production-agent.ts

@@ -2659,7 +2659,7 @@ function rateLimitRecoveryHint(message: string): string {
 }
 
 const SOURCE_SWEEP_TOOL_NAME =
-  /\b(?:api|calls?|deals?|events?|issues?|messages?|metrics?|provider|query|records?|request|search|tickets?|transcripts?)\b/i;
+  /\b(?:api|calls?|deals?|docs?|events?|issues?|messages?|metrics?|provider|query|records?|request|search|source|tickets?|transcripts?)\b/i;
 
 const SOURCE_SWEEP_PROVIDER_TOKEN =
   /\b(?:amplitude|apollo|bigquery|commonroom|data-source|ga4|github|gong|grafana|hubspot|jira|mixpanel|notion|posthog|postgres|postgresql|pylon|sentry|slack|stripe)\b/i;
@@ -2680,6 +2680,18 @@ const SOURCE_SWEEP_EXCLUDED_TOOLS = new Set([
   "view-screen",
 ]);
 
+// The Docs app intentionally exposes several small read-only lookup actions
+// rather than a bulk reader. Keep the per-tool guard for repeated lookups, but
+// do not combine this family into the cross-tool convergence budget.
+const SOURCE_SWEEP_AGGREGATE_EXCLUDED_TOOLS = new Set([
+  "docs-search",
+  "list-docs",
+  "read-doc",
+  "read-source-file",
+  "search-docs",
+  "search-source",
+]);
+
 function normalizeToolNameForHeuristics(name: string): string {
   return name.replace(/[_-]+/g, " ");
 }
@@ -2698,20 +2710,27 @@ function isLikelySourceSweepTool(
   );
 }
 
+function isLikelyAggregateSourceSweepTool(
+  name: string,
+  entry: ActionEntry | undefined,
+): boolean {
+  return (
+    !SOURCE_SWEEP_AGGREGATE_EXCLUDED_TOOLS.has(name.toLowerCase()) &&
+    isLikelySourceSweepTool(name, entry)
+  );
+}
+
 function hasExhaustedSourceSweepBudget(opts: {
   priorToolCalls: readonly AgentLoopToolCallSummary[];
   actions: Record<string, ActionEntry>;
   threshold?: number;
 }): boolean {
   const threshold = opts.threshold ?? SOURCE_SWEEP_TOOL_CALL_THRESHOLD;
-  const counts = new Map<string, number>();
-  for (const call of opts.priorToolCalls) {
-    if (!isLikelySourceSweepTool(call.name, opts.actions[call.name])) continue;
-    const next = (counts.get(call.name) ?? 0) + 1;
-    if (next >= threshold) return true;
-    counts.set(call.name, next);
-  }
-  return false;
+  return (
+    opts.priorToolCalls.filter((call) =>
+      isLikelyAggregateSourceSweepTool(call.name, opts.actions[call.name]),
+    ).length >= threshold
+  );
 }
 
 function sourceSweepDelegationText(input: unknown): string {
@@ -2784,11 +2803,16 @@ export function repeatedSourceSweepGuardMessage(opts: {
   toolName: string;
   priorCalls: number;
   threshold?: number;
+  scope?: "tool" | "aggregate";
 }): string {
   const threshold = opts.threshold ?? SOURCE_SWEEP_TOOL_CALL_THRESHOLD;
+  const target =
+    opts.scope === "aggregate"
+      ? "read-only source/search tools"
+      : "the same read-only source/search tool";
   return (
     `Skipped ${opts.toolName}: this turn already made ${opts.priorCalls} ` +
-    `call(s) to the same read-only source/search tool, which exceeds the ` +
+    `call(s) to ${target}, which exceeds the ` +
     `${threshold}-call convergence budget. Stop calling ${opts.toolName} ` +
     `one item at a time and change strategy before answering. If a broader ` +
     `read-only bulk/source mechanism is available, use it now: provider API ` +
@@ -2812,6 +2836,7 @@ export function shouldGuardRepeatedSourceSweep(opts: {
   toolName: string;
   entry: ActionEntry | undefined;
   priorToolCalls: readonly AgentLoopToolCallSummary[];
+  actions?: Record<string, ActionEntry>;
   threshold?: number;
 }): { toolName: string; priorCalls: number; message: string } | null {
   if (!isLikelySourceSweepTool(opts.toolName, opts.entry)) return null;
@@ -2819,6 +2844,25 @@ export function shouldGuardRepeatedSourceSweep(opts: {
   const priorCalls = opts.priorToolCalls.filter(
     (call) => call.name === opts.toolName,
   ).length;
+  const priorSourceSweepCalls = opts.priorToolCalls.filter((call) =>
+    isLikelyAggregateSourceSweepTool(
+      call.name,
+      opts.actions?.[call.name] ??
+        (call.name === opts.toolName ? opts.entry : undefined),
+    ),
+  ).length;
+  if (priorSourceSweepCalls >= threshold) {
+    return {
+      toolName: opts.toolName,
+      priorCalls: priorSourceSweepCalls,
+      message: repeatedSourceSweepGuardMessage({
+        toolName: opts.toolName,
+        priorCalls: priorSourceSweepCalls,
+        threshold,
+        scope: "aggregate",
+      }),
+    };
+  }
   if (priorCalls < threshold) return null;
   return {
     toolName: opts.toolName,
@@ -2827,6 +2871,7 @@ export function shouldGuardRepeatedSourceSweep(opts: {
       toolName: opts.toolName,
       priorCalls,
       threshold,
+      scope: "tool",
     }),
   };
 }
@@ -3831,6 +3876,7 @@ export async function runAgentLoop(opts: {
         toolName: toolCall.name,
         entry: actionEntry,
         priorToolCalls: sourceSweepToolCallHistory,
+        actions,
       });
       const sourceSweepDelegationGuard =
         sourceSweepDelegationGuardActive &&

package/corpus/core/src/cli/create.ts

@@ -480,21 +480,7 @@ async function scaffoldWorkspaceRoot(
     }
   }
 
-  const localToolkit = localToolkitOverride();
-  if (localToolkit) {
-    const wsPath = path.join(targetDir, "pnpm-workspace.yaml");
-    const existing = fs.existsSync(wsPath)
-      ? fs.readFileSync(wsPath, "utf-8")
-      : "";
-    const updated = mergeWorkspaceYamlSections(existing, {
-      overrides: {
-        '"@agent-native/toolkit"': JSON.stringify(localToolkit),
-      },
-    });
-    if (updated !== existing) {
-      fs.writeFileSync(wsPath, updated);
-    }
-  }
+  applyLocalWorkspaceOverrides(targetDir);
 
   const corePackageDir = path.join(targetDir, "packages", "shared");
   fs.mkdirSync(path.join(targetDir, "packages"), { recursive: true });
@@ -579,6 +565,8 @@ export async function addAppToWorkspace(
     process.exit(1);
   }
 
+  applyLocalWorkspaceOverrides(workspace.workspaceRoot);
+
   clack.intro("Add an app to your workspace");
 
   const installed = listInstalledApps(workspace.workspaceRoot);
@@ -1101,6 +1089,12 @@ function postProcessStandalone(
       sections.overrides['"@agent-native/toolkit"'] =
         JSON.stringify(localToolkit);
     }
+    const localRecapCli = localRecapCliOverride();
+    if (localRecapCli) {
+      sections.overrides ??= {};
+      sections.overrides['"@agent-native/recap-cli"'] =
+        JSON.stringify(localRecapCli);
+    }
     let updated = mergeWorkspaceYamlSections(existing, sections);
     updated = mergeWorkspaceYamlListItems(
       updated,
@@ -1399,6 +1393,11 @@ async function downloadGitHubSubdir(
 ): Promise<void> {
   validateRepoName(repo);
   const refs = getGitHubTemplateRefCandidates();
+  if (refs.length === 0) {
+    throw new Error(
+      "Cannot download first-party scaffold files without a versioned @agent-native/core package.",
+    );
+  }
   const errors: string[] = [];
   for (const ref of refs) {
     const tarUrl = `https://api.github.com/repos/${repo}/tarball/${encodeURIComponent(ref)}`;
@@ -1660,6 +1659,34 @@ function localToolkitOverride(): string | null {
   return localToolkit ? pathToFileURL(localToolkit).href : null;
 }
 
+function localRecapCliOverride(): string | null {
+  if (process.env.AGENT_NATIVE_CREATE_USE_LOCAL_CORE !== "1") return null;
+  const localRecapCli = findLocalPackage("recap-cli");
+  return localRecapCli ? pathToFileURL(localRecapCli).href : null;
+}
+
+function applyLocalWorkspaceOverrides(targetDir: string): void {
+  const localToolkit = localToolkitOverride();
+  const localRecapCli = localRecapCliOverride();
+  if (!localToolkit && !localRecapCli) return;
+
+  const wsPath = path.join(targetDir, "pnpm-workspace.yaml");
+  const existing = fs.existsSync(wsPath)
+    ? fs.readFileSync(wsPath, "utf-8")
+    : "";
+  const updated = mergeWorkspaceYamlSections(existing, {
+    overrides: {
+      ...(localToolkit
+        ? { '"@agent-native/toolkit"': JSON.stringify(localToolkit) }
+        : {}),
+      ...(localRecapCli
+        ? { '"@agent-native/recap-cli"': JSON.stringify(localRecapCli) }
+        : {}),
+    },
+  });
+  if (updated !== existing) fs.writeFileSync(wsPath, updated);
+}
+
 function getCorePackageVersion(): string | undefined {
   try {
     const packageRoot = path.resolve(__dirname, "../..");
@@ -1680,9 +1707,11 @@ function getCorePackageVersion(): string | undefined {
  *   - ≥ 0.8.0:  changesets per-package tags
  *               `@agent-native/core@<version>` (current).
  *
- * `main` is the final fallback so dev builds and brand-new releases (where
- * the tag has not propagated yet) still work — at the cost of pulling
- * potentially newer template code than the running CLI was built against.
+ * Published CLIs intentionally use only immutable version tags. Falling back
+ * to mutable `main` can copy a template that imports exports not present in
+ * the installed core package, leaving a generated app broken at SSR startup.
+ * Local framework development uses the checkout's templates and packages
+ * before this downloader runs, so it does not need a mutable fallback.
  */
 function getGitHubTemplateRefCandidates(): string[] {
   const version = getCorePackageVersion();
@@ -1691,7 +1720,6 @@ function getGitHubTemplateRefCandidates(): string[] {
     candidates.push(`@agent-native/core@${version}`);
     candidates.push(`v${version}`);
   }
-  candidates.push("main");
   return candidates;
 }