@agent-native/core 0.52.0 → 0.53.0

package/docs/content/template-plan.md

@@ -180,22 +180,34 @@ or set the convention for your agent environment:
 export AGENT_NATIVE_PLANS_MODE=local-files
 ```
 
-In this mode the agent writes a local MDX folder under `plans/<slug>/` and must
-not call the hosted Plan MCP tools. The durable files are:
+In this mode the agent writes a local MDX folder and must not call the hosted
+Plan MCP tools. Use a repo folder such as `plans/<slug>/` when you want the plan
+checked in with the code. Use a temp or ignored folder, such as
+`/tmp/agent-native-plans/<slug>/` or `.agent-native/plans/<slug>/`, when the
+plan should stay out of git. The folder contains:
 
 - `plan.mdx`
 - optional `canvas.mdx`
 - optional `prototype.mdx`
 - optional `.plan-state.json`
 
-After writing the folder, the agent validates and previews it locally:
+After writing the folder, the agent starts a tiny localhost bridge and opens the
+hosted Plan UI against that local-only source:
 
 ```bash
-npx @agent-native/core@latest plan local preview --dir plans/<slug> --kind plan --open
+npx @agent-native/core@latest plan local serve --dir plans/<slug> --kind plan --open
 ```
 
-If you run the Plan app locally with the same `PLAN_LOCAL_DIR`, you can open the
-read-only app route:
+The bridge URL looks like
+`https://plan.agent-native.com/local-plans/<slug>?bridge=http://127.0.0.1:...`.
+The page is the normal Plan viewer, but the browser fetches `plan.mdx`,
+`canvas.mdx`, `prototype.mdx`, `.plan-state.json`, and local image assets from
+the localhost bridge. Plan content is not written to the hosted database and is
+not sent through hosted Plan actions. Keep the bridge process running while you
+review; the URL is local to your machine and is not a shareable team link.
+
+If you run the Plan app locally with the same `PLAN_LOCAL_DIR`, you can also
+open the read-only app route:
 
 ```text
 http://localhost:<port>/local-plans/<slug>
@@ -206,8 +218,8 @@ Plan database. It also disables hosted sharing, browser comments, plan history,
 and publish/export receipts until you explicitly opt into publishing. To move a
 local plan into the hosted database, call `publish-visual-plan` with the local
 MDX folder path; this uploads the plan, assigns it a hosted ID, enables sharing
-and commenting, and returns the hosted URL. It does
-not automatically make your coding agent's LLM local; choose a local or approved
+and commenting, and returns the hosted URL. Local-files mode does not
+automatically make your coding agent's LLM local; choose a local or approved
 model if that privacy boundary matters too.
 
 ## Desktop local file sync {#desktop-local-sync}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agent-native/core",
-  "version": "0.52.0",
+  "version": "0.53.0",
   "type": "module",
   "engines": {
     "node": ">=22"
@@ -74,6 +74,7 @@
     "./agent/context-xray/actions/context-evict": "./dist/agent/context-xray/actions/context-evict.js",
     "./agent/context-xray/actions/context-restore": "./dist/agent/context-xray/actions/context-restore.js",
     "./agent/context-xray/actions/context-report": "./dist/agent/context-xray/actions/context-report.js",
+    "./agent/observational-memory": "./dist/agent/observational-memory/index.js",
     "./resources": "./dist/resources/index.js",
     "./resources/store": "./dist/resources/store.js",
     "./resources/metadata": "./dist/resources/metadata.js",
@@ -135,6 +136,7 @@
     "./styles/agent-native.css": "./dist/styles/agent-native.css",
     "./agent/engine": "./dist/agent/engine/index.js",
     "./agent/harness": "./dist/agent/harness/index.js",
+    "./eval": "./dist/eval/index.js",
     "./tsconfig.base.json": "./tsconfig.base.json"
   },
   "sideEffects": [
@@ -142,6 +144,7 @@
   ],
   "files": [
     "bin",
+    "blueprints",
     "dist",
     "docs",
     "tsconfig.base.json",
@@ -264,6 +267,7 @@
     "ws": ">=8"
   },
   "optionalDependencies": {
+    "@opentelemetry/api": "^1.9.1",
     "playwright": "^1.60.0"
   },
   "peerDependenciesMeta": {

package/src/templates/workspace-core/.agents/skills/external-agents/SKILL.md

@@ -416,3 +416,13 @@ before telling the user they are unauthenticated.
 - **a2a-protocol** — the `ask-agent` meta-tool and JSON-RPC peer calls
 - **adding-a-feature** — the four-area checklist (add a `link` builder when a
   feature produces a navigable resource)
+
+## Blueprint installer
+
+To add a whole new integration the agent-native way, `agent-native add <kind>
+<name|url>` prints a curated Markdown blueprint to stdout — pipe it into the
+external coding agent you connected (`agent-native add provider stripe |
+claude`) and it applies the changes against the live repo. A URL emits a
+generic research-and-integrate blueprint instead. Seeded kinds:
+`provider` / `channel` / `sandbox` / `action`. Add your own by dropping a
+`.md` in `packages/core/blueprints/<kind>/`. See the Blueprint Installer doc.

package/src/templates/workspace-core/.agents/skills/harness-agents/SKILL.md

@@ -80,6 +80,26 @@ existing run routes as `goalId=agent-harness`.
   Preserve `defineAction` auth, request context, timeouts, truncation, and
   read-only metadata.
 
+## Code Execution Sandbox
+
+- The `run-code` tool executes through a pluggable `SandboxAdapter`
+  (`packages/core/src/coding-tools/sandbox/`). The default
+  `LocalChildProcessAdapter` spawns a locked-down local Node child process;
+  swap it via `AGENT_NATIVE_SANDBOX` or `registerSandboxAdapter()` for a
+  Docker/remote/durable backend (the lever to exceed the hosted ~40s code-exec
+  ceiling). An adapter only runs the already-prepared, non-secret module source
+  — it never sees app secrets. See the Sandbox Adapters doc; `agent-native add
+  sandbox docker` emits a full Docker-adapter recipe.
+
+## Sub-Agent Delegation Depth
+
+- Sub-agent spawning is capped server-side (default depth `2`) so delegation
+  chains can't fan out indefinitely. Override at deploy time with
+  `AGENT_NATIVE_MAX_SUBAGENT_DEPTH` (`0` disables sub-agents; clamped to `16`).
+  Enforcement is ambient via `evaluateSubagentDepth` in
+  `packages/core/src/server/agent-teams.ts` — independent of any tool-level
+  guard. See the Agent Teams doc for the depth model.
+
 ## Don't
 
 - Don't add Claude Code, Codex, Cursor, Mastra, or Pi as an `AgentEngine`.

package/src/templates/workspace-core/.agents/skills/observability/SKILL.md

@@ -75,6 +75,26 @@ const criteria: EvalCriteria = {
 };
 ```
 
+#### Evals (CI gate)
+
+The three layers above score *real production runs* after the fact. For an active, deterministic gate, use the first-class `*.eval.ts` primitive from `@agent-native/core/eval` (source: `packages/core/src/eval/*`). It runs the actual agent loop against fixed inputs and exits non-zero below threshold, so it gates CI/deploys.
+
+```ts
+// evals/faq.eval.ts
+import { defineEval, contains, llmJudge } from "@agent-native/core/eval";
+
+export default defineEval({
+  name: "answers the FAQ",
+  input: { prompt: "What is your return policy?" },
+  threshold: 0.7,
+  scorers: [contains("30 days"), llmJudge({ criteria: "accuracy" })],
+});
+```
+
+- Built-in scorers: `exactMatch` / `contains` / `usesTool` (pure JS) and `llmJudge` (provider-agnostic judge).
+- Custom scorers: `createScorer` with the 4-step `preprocess → analyze → generateScore → generateReason` pipeline (only `generateScore` is required).
+- Run as a gate: `agent-native eval [pattern] [--json] [--threshold N]` — discovers `**/*.eval.ts` and `evals/*.ts`, runs the agent, and exits non-zero if any eval is below its threshold. An app with no eval files exits `0`. Complements (does not replace) the post-hoc scoring in `evals.ts`. See the Evals doc.
+
 ### 4. Experiments
 
 A/B testing with sticky user-level assignment: