@agent-native/core 0.52.0 → 0.54.0

package/docs/content/observational-memory.md

@@ -0,0 +1,63 @@
+---
+title: "Observational Memory"
+description: "Background three-tier compaction (recent raw → observations → reflections) that keeps long agent threads cheap and prompt-cache-stable without touching short conversations."
+---
+
+# Observational Memory
+
+A long-running agent thread accumulates a huge transcript: every message, every tool call, every result. Replaying that whole history into the model on each turn is expensive and eventually blows the context window. **Observational Memory (OM)** compacts the older part of a long thread into a dated, layered summary so the model still knows what happened — just at a fraction of the token cost — while the most recent turns stay verbatim.
+
+OM is entirely automatic and owner-scoped. **Short threads are unaffected**: until a thread crosses the first compaction threshold, OM is a no-op and the context is byte-for-byte what it would be without it.
+
+## The three tiers {#tiers}
+
+OM represents a long thread as three layers, from most-distilled to most-recent:
+
+| Tier                    | What it is                                                                                        |
+| ----------------------- | ------------------------------------------------------------------------------------------------- |
+| **Reflections**         | Highest-level, condensed from the observation log once it grows large. The long-arc summary.      |
+| **Observations**        | Dense, dated entries that fold a stretch of raw messages into a compact record of what happened.  |
+| **Recent raw messages** | The last N turns, kept **verbatim** — never folded — so the agent always sees the latest context. |
+
+On each turn, the read side assembles these into a single self-labeled `[Observational Memory]` block that replaces the raw older prefix, keeps the recent-raw window intact, and tells the model to treat the compacted record as authoritative (don't redo completed work, trust the recorded decisions, names, dates, and status).
+
+## How compaction runs {#compaction}
+
+Two passes run as a **fire-and-forget, best-effort** step _after_ a clean turn, so they never add latency to the user-visible response and any failure is swallowed:
+
+1. **Observer** — once a thread's _unobserved_ messages exceed the observation token threshold, folds them into a single dense observation entry.
+2. **Reflector** — once the persisted observation log itself exceeds the reflection token threshold, condenses the observations into a higher-level reflection.
+
+Both passes no-op below their thresholds, so calling the compactor after every turn is cheap. Because OM replaces the volatile raw prefix with stable compacted text, it also keeps the prompt **cache-stable** across turns of a long thread.
+
+OM data lives in the app's own SQL database, scoped to the owner (and org when present) — the same scoping model as the rest of the framework. It is never shared across users.
+
+## Configuration {#config}
+
+Defaults are conservative. An operator can dial compaction at deploy time with `AGENT_NATIVE_OM_*` environment variables (no redeploy of the app code needed); an invalid or missing value always falls back to the named default.
+
+| Env var                                       | Default | What it controls                                                                       |
+| --------------------------------------------- | ------- | -------------------------------------------------------------------------------------- |
+| `AGENT_NATIVE_OM_OBSERVATION_TOKEN_THRESHOLD` | `30000` | Unobserved-message tokens that trigger the Observer to fold them into one observation. |
+| `AGENT_NATIVE_OM_REFLECTION_TOKEN_THRESHOLD`  | `40000` | Observation-log tokens that trigger the Reflector to condense into a reflection.       |
+| `AGENT_NATIVE_OM_RECENT_RAW_MESSAGE_COUNT`    | `12`    | How many of the most-recent messages stay verbatim (never folded into an observation). |
+
+The Observer and Reflector output caps (4000 / 2000 tokens) keep a single compaction pass from itself blowing the budget; they are tunable in code via `resolveObservationalMemoryConfig({ ... })` but not env-exposed.
+
+> [!TIP]
+> Lower the thresholds to compact sooner (cheaper long threads, slightly more summarization); raise them to keep more raw history in context before compacting. Set `AGENT_NATIVE_OM_RECENT_RAW_MESSAGE_COUNT` higher if your workflows need a longer verbatim tail.
+
+## When it kicks in {#when}
+
+OM only changes behavior for threads long enough to have produced at least one observation or reflection. Concretely:
+
+- A brand-new or short thread: no OM entries yet → the context is the plain transcript, unchanged.
+- A long thread that has crossed the observation threshold: the older prefix is replaced by the compacted `[Observational Memory]` block, the recent-raw tail stays verbatim, and token usage drops substantially.
+
+The injection is best-effort and boundary-safe — if a safe trim point can't be found (e.g. a pending tool-use/result pair sits at the window edge), OM injects the memory block _additively_ without trimming rather than risk dropping a pending tool result.
+
+## Related
+
+- [**Context X-Ray**](/docs/using-your-agent) — inspect what's actually in the live context window.
+- [**Observability**](/docs/observability) — token and cost metrics per run, where OM's savings show up.
+- [**Custom Agents & Teams**](/docs/agent-teams) — long sub-agent runs benefit from the same compaction.

package/docs/content/plan-plugin.md

@@ -40,6 +40,11 @@ the Plan MCP connector. They write `plans/<slug>/plan.mdx` plus optional
 npx @agent-native/core@latest plan local preview --dir plans/<slug> --kind plan --open
 ```
 
+For folders in the current repo, the direct local route includes `?path=...` so
+the local Plan app can keep browser edits saving to the repo folder. The Plan
+app uses `apps.plan.roots[0].path` in `agent-native.json` as the default place
+to save promoted local plans, falling back to `plans/`.
+
 This keeps plan content out of the Agent-Native Plan database. Hosted sharing,
 comments, screenshots, and plan history are unavailable until you explicitly
 publish later.

package/docs/content/pr-visual-recap.md

@@ -216,13 +216,17 @@ the prompt instructs the agent to write `plans/pr-123-visual-recap/plan.mdx`
 plus optional visual files and then run:
 
 ```bash
-npx @agent-native/core@latest plan local preview --dir plans/pr-123-visual-recap --kind recap --open
+npx @agent-native/core@latest plan local serve --dir plans/pr-123-visual-recap --kind recap --open
 ```
 
-The returned `file://` preview, or `/local-plans/pr-123-visual-recap` in a local
-Plan app using the same `PLAN_LOCAL_DIR`, is the review link. This mode disables
-the hosted sticky PR comment, inline screenshot upload, usage attachment, and
-browser comments until you explicitly publish.
+The returned URL opens the hosted Plan UI while the browser reads the recap MDX
+from a localhost bridge. Recap content is not written to the hosted Plan
+database, and the URL only works on the machine running the bridge. If you run
+the Plan app locally with the same `PLAN_LOCAL_DIR`, the
+`/local-plans/pr-123-visual-recap` route is also valid. Repo-backed folders can
+open as `/local-plans/pr-123-visual-recap?path=plans%2Fpr-123-visual-recap`.
+This mode disables the hosted sticky PR comment, inline screenshot upload,
+usage attachment, and browser comments until you explicitly publish.
 
 ## It's informational, not a gate
 

package/docs/content/processors.md

@@ -0,0 +1,99 @@
+---
+title: "In-Loop Processors"
+description: "Loop-internal observer/guardrail hooks that watch the model's streamed output and tool calls mid-run and can abort it — the seam for real-time guardrails and proof-of-done gates."
+---
+
+# In-Loop Processors
+
+A `Processor` is a loop-internal **observer/guardrail** for the agent run. It watches the model's streamed output and the tool calls it requests _as the run progresses_, keeps its own scratch state, and can **abort** the run before a "done" is claimed. This is the structural prerequisite for real-time guardrails (block disallowed output mid-stream) and a proof-of-done / coverage gate (inspect what the model is about to do and halt it).
+
+> [!WARNING]
+> A processor is **configuration**, not a tool, not an action, and not an authoring DSL. Processors only observe, mutate their own stream-scoped state, and `abort()`. They never define app behavior, replace actions, or appear to the model. App operations belong in [actions](/docs/actions).
+
+## The hooks {#hooks}
+
+A processor implements any subset of three optional lifecycle hooks (the shape is borrowed from Mastra's output processors):
+
+| Hook                  | Fires…                                                                | Use it to…                                                  |
+| --------------------- | --------------------------------------------------------------------- | ----------------------------------------------------------- |
+| `processOutputStream` | per streamed chunk (text / thinking deltas) while the model generates | react to output before the full turn lands                  |
+| `processOutputStep`   | once per model response, around tool execution                        | inspect the tool calls the model is about to run; gate them |
+| `processOutputResult` | once at run end, with the final assistant text                        | record a verdict / proof-of-done over the completed answer  |
+
+Each processor gets its own mutable, run-scoped `state` object that persists across every one of its hook invocations within a single run and is **isolated** from other processors' state.
+
+```ts
+import type { Processor } from "@agent-native/core";
+
+const noSecretsInOutput: Processor = {
+  name: "no-secrets",
+  processOutputStream({ part, abort }) {
+    if (part.type === "text" && /sk-live_/.test(part.text)) {
+      abort("Model attempted to emit a live secret token.", {
+        kind: "secret-leak",
+      });
+    }
+  },
+};
+
+const coverageGate: Processor = {
+  name: "proof-of-done",
+  processOutputStep({ toolCalls, state }) {
+    // Track what the model has actually done this run...
+    for (const call of toolCalls) {
+      (state.ran ??= new Set<string>()).add(call.name);
+    }
+  },
+  processOutputResult({ text, state }) {
+    // ...and record a verdict over the final answer.
+    const ran = state.ran as Set<string> | undefined;
+    state.verdict = ran?.has("run-tests") ? "verified" : "unverified";
+  },
+};
+```
+
+## Aborting with `TripWire` {#tripwire}
+
+A hook halts the run by calling `abort(reason, meta?)`, which throws a **`TripWire`**. The loop catches it, emits a single **`tripwire` event**, stops cleanly, and surfaces the reason as the final assistant message.
+
+```ts
+import { TripWire } from "@agent-native/core";
+```
+
+The `tripwire` event carries:
+
+| Field       | Type     | Notes                                                          |
+| ----------- | -------- | -------------------------------------------------------------- |
+| `reason`    | `string` | The human-readable reason passed to `abort`.                   |
+| `processor` | `string` | Name of the processor that aborted, when it declared a `name`. |
+
+`TripWire` also carries optional structured `meta` and the originating `processor` name for programmatic consumers that `instanceof`-check it. Because a halt is graceful, `processOutputResult` still fires on the (halted) final text so a proof-of-done processor can record its verdict even when the run was aborted.
+
+## Wiring processors {#wiring}
+
+Processors are configured in code via the `processors` array on `runAgentLoop`:
+
+```ts
+await runAgentLoop({
+  engine,
+  model,
+  systemPrompt,
+  tools,
+  messages,
+  actions,
+  send,
+  signal,
+  processors: [noSecretsInOutput, coverageGate],
+});
+```
+
+**Zero-overhead when unused.** The loop builds the processor chain only when at least one processor is supplied; when `processors` is omitted or empty, none of the seam code runs and the loop is byte-for-byte unchanged. Hooks run in registration order and may be sync or async.
+
+> [!NOTE]
+> The loop-level seam is the deliverable today and is callable directly by sub-agents, A2A, MCP, and tests. Threading `processors` through the HTTP chat handler (so a per-request resolver can configure them without calling `runAgentLoop` directly) is convenience plumbing that is not yet wired — configure processors at the `runAgentLoop` call site for now.
+
+## Related
+
+- [**Durable Resume**](/docs/durable-resume) — how the loop survives interruptions without re-running completed side effects.
+- [**Custom Agents & Teams**](/docs/agent-teams) — sub-agents run the same loop and can carry their own processors.
+- [**Observability**](/docs/observability) — record processor verdicts alongside run traces.

package/docs/content/sandbox-adapters.md

@@ -0,0 +1,134 @@
+---
+title: "Sandbox Adapters"
+description: "Swap the backend that runs the agent's run-code tool — local child process by default, a remote/durable runner when you need to exceed the hosted code-exec ceiling."
+---
+
+# Sandbox Adapters
+
+The `run-code` tool runs agent-supplied JavaScript in an isolated environment. **Sandbox adapters** factor the _execution_ concern out of that tool so the backend can be swapped — a local child process by default, or a Docker / remote / durable runner — without touching the agent loop, `run-code.ts`, the localhost bridge, the env scrub, or the output formatting.
+
+## Why a seam {#why}
+
+The default backend spawns a locked-down local Node child process. That's bounded by the hosting process: on the hosted platform it shares the agent loop's soft execution ceiling (~40s before timeout/continuation thrash). A remote or durable adapter is the lever to exceed that ceiling — it runs large data jobs to completion independently of the request lifecycle.
+
+Keeping the contract narrow means a remote adapter inherits the same security posture. The parent process keeps ownership of everything secret-bearing: it builds the sandbox module, runs the localhost bridge (which holds the request context and applies host allowlists + SSRF guards), scrubs the env, and formats output. An adapter only receives an already-prepared, **non-secret** module source plus resource limits — it is responsible solely for _running_ it and capturing stdout/stderr/exit status.
+
+## The interface {#interface}
+
+The seam lives in core at `packages/core/src/coding-tools/sandbox/` — `adapter.ts` (the contract), `index.ts` (selection: `getSandboxAdapter()` / `registerSandboxAdapter()`), and `local-child-process-adapter.ts` (the default). It is wired in-package by `run-code.ts`; a host plugs in a different backend through the `index.ts` registration helper (or, for a Docker backend, via the [blueprint](/docs/blueprint-installer) that edits these files directly).
+
+Every backend implements `SandboxAdapter`:
+
+```ts
+interface SandboxAdapter {
+  /** Stable id, surfaced for diagnostics and adapter selection. */
+  readonly id: string;
+  /** Execute one prepared sandbox module and capture its output. */
+  run(request: SandboxRunRequest): Promise<SandboxRunResult>;
+}
+```
+
+The request and result are intentionally small and opaque:
+
+```ts
+interface SandboxRunRequest {
+  /**
+   * The complete ESM module source to execute. Already wraps the user's code
+   * and embeds the loopback bridge URL/token; the adapter does NOT parse or
+   * rewrite it.
+   */
+  moduleSource: string;
+  /**
+   * Scrubbed environment — only safe POSIX vars (PATH/HOME/TMPDIR/…), never app
+   * secrets. Adapters must not augment this with the parent's own environment.
+   */
+  env: Record<string, string>;
+  /** Hard wall-clock timeout in milliseconds. The adapter must enforce it. */
+  timeoutMs: number;
+  /**
+   * Loopback port of the parent's bridge server (reachable over 127.0.0.1). A
+   * remote adapter that can't reach the parent's loopback must tunnel or proxy
+   * this to support bridge-backed globals (`appAction`, `providerFetch`, …).
+   */
+  bridgePort: number;
+}
+
+interface SandboxRunResult {
+  stdout: string;
+  stderr: string;
+  /** `0` on clean exit, non-zero on failure, `null` when killed by a signal. */
+  exitCode: number | null;
+  /** True when the run was killed for exceeding `timeoutMs`. */
+  timedOut: boolean;
+}
+```
+
+## The default: `LocalChildProcessAdapter` {#default}
+
+Out of the box, `getSandboxAdapter()` returns `LocalChildProcessAdapter` (`id: "local-child-process"`). It preserves the historical `run-code` behavior byte-for-byte:
+
+- The prepared module source is written to a fresh temp dir.
+- The child runs with the scrubbed env (no secrets), with `TMPDIR`/`TEMP`/`TMP` pointed inside the sandbox dir.
+- When the Node permission model is available (`--permission`, or `--experimental-permission` on Node 20), the child is denied filesystem access outside its temp dir, plus child processes, workers, and native addons. Outbound network is _not_ blocked by the permission model — but the env scrub means such requests carry no credentials, and all authenticated calls go through the parent's loopback bridge.
+- A timeout sends `SIGTERM`, then `SIGKILL` after a 2s grace period.
+- Temp files are cleaned up best-effort after the run.
+
+> [!WARNING]
+> The default adapter uses `node:child_process`, which does not exist on edge/worker runtimes (Cloudflare Workers, Netlify Edge Functions). Run `run-code` in a standard Node.js environment, or register a remote adapter.
+
+## Selecting an adapter {#selection}
+
+Resolution order — an explicitly registered adapter wins; otherwise the env var selects a built-in; otherwise the local default is used:
+
+```txt
+registerSandboxAdapter(adapter)  →  AGENT_NATIVE_SANDBOX  →  local default
+```
+
+### `AGENT_NATIVE_SANDBOX` env var {#env}
+
+Selects a built-in adapter by id. Currently only `local` (the default) is wired; unknown values fall back to local rather than failing the run.
+
+```bash
+AGENT_NATIVE_SANDBOX=local   # the default — explicit
+```
+
+### `registerSandboxAdapter()` {#register}
+
+A host process overrides the backend for all subsequent `run-code` invocations through the seam's `index.ts` — for example, to run every call in a remote container:
+
+```ts
+import {
+  registerSandboxAdapter,
+  type SandboxAdapter,
+} from "./coding-tools/sandbox/index.js";
+
+class RemoteSandboxAdapter implements SandboxAdapter {
+  readonly id = "remote";
+  async run(request) {
+    // Ship request.moduleSource to the durable runner, enforce request.timeoutMs,
+    // proxy bridge calls back to request.bridgePort, and return stdout/stderr/exitCode.
+  }
+}
+
+registerSandboxAdapter(new RemoteSandboxAdapter());
+// Pass `null` to clear the override and fall back to env-var / default resolution.
+```
+
+## The seam for a durable runner {#durable}
+
+This interface is deliberately the seam for a future remote/durable sandbox. A remote or durable adapter (Docker, a Vercel-Sandbox-style runner, or a queued background worker) would:
+
+1. Implement `SandboxAdapter.run` against an out-of-process runtime.
+2. Tunnel the loopback bridge (or proxy bridge calls back to the parent).
+3. Let large data jobs run to completion independently of the request lifecycle — exceeding the hosted ~40s code-exec ceiling that bounds the local child-process adapter.
+
+Register it under a new `AGENT_NATIVE_SANDBOX` value (e.g. `remote`) and/or via `registerSandboxAdapter()`. The agent loop and `run-code.ts` never change.
+
+> [!TIP]
+> The `agent-native add sandbox docker` blueprint emits a full, self-contained recipe for implementing a Docker adapter against this seam. See [Blueprint Installer](/docs/blueprint-installer).
+
+## What's next
+
+- [**Blueprint Installer**](/docs/blueprint-installer) — `agent-native add sandbox docker` prints a Docker-adapter recipe
+- [**Agent Teams**](/docs/agent-teams) — delegating heavy work to sub-agents
+- [**Security**](/docs/security) — the env scrub and bridge allowlist posture

package/docs/content/template-plan.md

@@ -97,6 +97,22 @@ connector, so use the Agent-Native CLI path when you want the one-command setup.
 > Plan skills _and_ the connector in one install and auto-updates as the skills
 > improve — see [Plan plugin & marketplace](/docs/plan-plugin).
 
+### Open Plans inside VS Code {#vscode-extension}
+
+If you live in VS Code, the Agent Native VS Code extension can open the same
+Plan review surface in a side panel instead of sending you to a separate browser
+tab. Plans tools still return the normal web link, and the MCP metadata also
+includes a VS Code handoff URL:
+
+```text
+vscode://builderio.agent-native/open?url=<encoded-plan-url>
+```
+
+The extension handles that URI, opens the decoded Plan URL in a VS Code webview,
+and includes a command to run the existing Agent Native MCP connect flow for VS
+Code / GitHub Copilot. This is especially useful from Claude Code or another
+coding-agent workflow where the plan should stay next to the files being edited.
+
 ## Use it from your coding agent
 
 After installation, ask your agent for the command that fits the work:
@@ -110,9 +126,9 @@ After installation, ask your agent for the command that fits the work:
   before/after blocks instead of a wall of raw diff.
 
 The agent should inspect the codebase first, then create the visual plan when a
-wrong direction would be costly. The returned Plans link opens the review UI so
-you can annotate, correct, choose options, and ask for updates before code
-changes begin.
+wrong direction would be costly. The returned Plans link opens the review UI in
+the browser or VS Code, so you can annotate, correct, choose options, and ask for
+updates before code changes begin.
 
 When a Codex, Claude Code, Markdown, or pasted plan already exists, use
 `/visual-plan`; the agent preserves that source plan and builds the richer review
@@ -180,34 +196,72 @@ 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 editable app route:
 
 ```text
 http://localhost:<port>/local-plans/<slug>
 ```
 
+For repo-backed folders, the direct local route can carry the repo-relative
+folder path so browser edits keep writing to that folder:
+
+```text
+http://localhost:<port>/local-plans/<slug>?path=plans%2F<slug>
+```
+
+The Plan app uses `apps.plan.roots[0].path` in `agent-native.json` as the
+default repo location for promoted local plans, falling back to `plans/`:
+
+```json
+{
+  "version": 1,
+  "apps": {
+    "plan": {
+      "mode": "local-files",
+      "roots": [{ "name": "Plans", "path": "plans", "kind": "plans" }]
+    }
+  }
+}
+```
+
+Direct local Plan routes include a menu action to save a temporary local folder
+into that repo location. After promotion, the page reopens with `?path=...` and
+continues autosaving MDX edits to the repo folder.
+
 Local-files mode prevents plan or recap content from going to the Agent-Native
 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}
@@ -232,6 +286,27 @@ This path does not require cloning the Plan app or running a CLI. It is for
 file-first review/editing around a hosted plan, not for keeping plan content out
 of the hosted database.
 
+## Deleting hosted plan data {#delete-data}
+
+Signed-in owners can delete their hosted plans and recaps from the Plans list or
+the plan action menu.
+
+- **Soft delete** moves the plan to the **Deleted** tab, makes normal plan
+  views/direct links stop working, and removes public access by making the row
+  private. The SQL rows are retained so the owner can restore the plan later.
+- **Restore** is available from the **Deleted** tab for soft-deleted plans.
+- **Permanent delete** removes the hosted plan row and plan-scoped comments,
+  sections, activity events, version snapshots, share grants, abuse reports, and
+  SQL asset records. The UI requires typing `DELETE <plan-id>` before the final
+  button enables.
+
+Permanent delete removes the Plan app's database records and SQL-backed asset
+bytes/references. If a deployment uses an external upload provider, provider
+object retention follows that provider's lifecycle because the shared upload
+abstraction does not currently expose object deletion. Local-files privacy mode
+keeps the source in your local MDX folder instead; deleting hosted data does not
+touch local files.
+
 ## Useful prompts
 
 - "Use `/visual-plan` before changing the auth flow."
@@ -275,16 +350,16 @@ The local template is useful when you are developing Plans itself, testing local
 
 Schema lives in `templates/plan/server/db/schema.ts`. Core tables:
 
-| Table              | What it holds                                                                                                                                                |
-| ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------ |
-| `plans`            | Each plan or recap — `title`, `brief`, `kind` (plan/recap), `status`, `source`, `html`/`markdown`/`content`, `hosted_plan_id/url`, usage stats, `source_url` |
-| `plan_sections`    | Ordered sections within a plan — `type`, `title`, `body`, `html`, `sort_order`, `created_by`                                                                 |
-| `plan_comments`    | Threaded comments — `kind`, `status`, `anchor`, `message`, `resolution_target`, `mentions_json`, `resolved_by`                                               |
-| `plan_events`      | Audit log of agent/human events on a plan                                                                                                                    |
-| `plan_versions`    | Point-in-time snapshots for version history                                                                                                                  |
-| `plan_shares`      | Per-principal share grants (viewer / editor / admin)                                                                                                         |
-| `plan_guest_mints` | Rate-limit records for guest session issuance                                                                                                                |
-| `plan_assets`      | Inline image assets stored as base64 (fallback when no upload provider)                                                                                      |
+| Table              | What it holds                                                                                                                                                                           |
+| ------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `plans`            | Each plan or recap — `title`, `brief`, `kind` (plan/recap), `status`, `source`, `html`/`markdown`/`content`, `hosted_plan_id/url`, usage stats, `source_url`, `deleted_at`/`deleted_by` |
+| `plan_sections`    | Ordered sections within a plan — `type`, `title`, `body`, `html`, `sort_order`, `created_by`                                                                                            |
+| `plan_comments`    | Threaded comments — `kind`, `status`, `anchor`, `message`, `resolution_target`, `mentions_json`, `resolved_by`                                                                          |
+| `plan_events`      | Audit log of agent/human events on a plan                                                                                                                                               |
+| `plan_versions`    | Point-in-time snapshots for version history                                                                                                                                             |
+| `plan_shares`      | Per-principal share grants (viewer / editor / admin)                                                                                                                                    |
+| `plan_guest_mints` | Rate-limit records for guest session issuance                                                                                                                                           |
+| `plan_assets`      | Inline image assets stored as base64 (fallback when no upload provider)                                                                                                                 |
 
 ### Key actions
 
@@ -292,6 +367,7 @@ Actions in `templates/plan/actions/`:
 
 - **Creation** — `create-visual-plan`, `create-visual-recap`, `create-ui-plan`, `create-prototype-plan`, `create-plan-design`, `create-visual-questions`
 - **Reading & editing** — `get-visual-plan`, `update-visual-plan`, `list-visual-plans`, `import-visual-plan-source`, `patch-visual-plan-source`, `read-visual-plan-source`, `export-visual-plan`
+- **Lifecycle** — `delete-visual-plan` for owner-only soft delete, restore, and typed-confirmation permanent delete
 - **Publishing & sharing** — `publish-visual-plan`
 - **Versions** — `list-plan-versions`, `get-plan-version`, `restore-plan-version`
 - **Comments & feedback** — `get-plan-feedback`, `reply-to-plan-comment`, `resolve-plan-comment`, `consume-plan-feedback`, `delete-plan-comment`

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agent-native/core",
-  "version": "0.52.0",
+  "version": "0.54.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",
@@ -162,6 +165,7 @@
     "@libsql/client": "^0.15.0",
     "@modelcontextprotocol/ext-apps": "1.7.2",
     "@modelcontextprotocol/sdk": "^1.29.0",
+    "@mozilla/readability": "0.6.0",
     "@neondatabase/serverless": "^1.1.0",
     "@radix-ui/react-dialog": "1.1.15",
     "@radix-ui/react-dropdown-menu": "^2.1.16",
@@ -209,6 +213,7 @@
     "jiti": "^2.6.1",
     "jose": "^6.2.2",
     "kiwi-schema": "^0.5.0",
+    "linkedom": "0.18.12",
     "lowlight": "^3.3.0",
     "minimatch": "^10.0.0",
     "nanoid": "^5.1.9",
@@ -221,10 +226,12 @@
     "recharts": "^3.8.1",
     "remark-gfm": "^4.0.1",
     "roughjs": "4.6.6",
+    "safe-regex2": "5.1.1",
     "shiki": "^4.0.2",
     "sonner": "^2.0.7",
     "tailwind-merge": "^3.5.0",
     "tiptap-markdown": "^0.9.0",
+    "turndown": "7.2.4",
     "tw-animate-css": "1.4.0",
     "y-protocols": "^1.0.7",
     "yjs": "^13.6.31",
@@ -264,6 +271,7 @@
     "ws": ">=8"
   },
   "optionalDependencies": {
+    "@opentelemetry/api": "^1.9.1",
     "playwright": "^1.60.0"
   },
   "peerDependenciesMeta": {
@@ -376,6 +384,7 @@
     "@types/pako": "^2.0.4",
     "@types/react": "^19.2.14",
     "@types/react-dom": "^19.2.3",
+    "@types/turndown": "5.0.6",
     "@types/ws": "^8.18.1",
     "@vitejs/plugin-react-swc": "^4.0.0",
     "@vitest/coverage-v8": "4.1.5",