@agent-native/core 0.87.0 → 0.90.1

package/corpus/core/src/templates/workspace-core/.agents/skills/data-programs/SKILL.md

@@ -0,0 +1,128 @@
+---
+name: data-programs
+description: >-
+  Save a run-code fetch/join/aggregate script as a stored, refreshable data
+  source any app's own charts/tables can render, instead of a hardcoded
+  provider action or a per-view re-fetch. Use when an ad-hoc run-code or
+  provider-api-request analysis should become a live, cached data source other
+  users or panels can reuse.
+---
+
+# Data Programs
+
+A **data program** is a named, stored, agent-authored JS script that fetches,
+joins, filters, or aggregates data — provider APIs via `providerFetch` /
+`providerFetchAll` / `providerSearchAll`, app data via `appAction`, or
+Resources-backed workspace files — and emits a small `{ rows, schema }`
+result that gets cached in SQL. Any app can render that result through its
+own table/chart components; nothing about the primitive is analytics-specific.
+
+This ships automatically wherever `run-code` is available — there is nothing
+to mount, wire, or configure per app. If your app already has run-code
+enabled, `save-data-program` / `preview-data-program` / `run-data-program` /
+`list-data-programs` / `get-data-program` / `delete-data-program` are already
+registered actions.
+
+## Why this exists
+
+Without it, "build a live view of X" tends to end in one of two bad places:
+a hardcoded action per vendor/query shape (brittle, doesn't scale to every
+customer's custom fields), or re-running the same fetch/join logic from
+scratch on every page view (slow, and it re-spends the same provider quota
+every time someone looks at a chart). A data program is the middle ground:
+write the fetch/join/aggregate logic once as ordinary `run-code`, save it, and
+let the cache + refresh policy handle "how often does this actually need to
+re-run."
+
+## Authoring workflow
+
+1. Prototype the fetch/join/aggregate logic as a normal `run-code` script and
+   confirm it returns the rows you expect.
+2. Change it to call `emit(rows, schema?)` exactly once at the end instead of
+   returning or printing the result.
+3. Save it with `save-data-program({ name, title, description, code,
+   defaultParams?, refreshMode?, refreshTtlMs?, background? })`. This
+   **dry-runs the code with `defaultParams` before persisting** and rejects
+   the save with a structured error if it fails, so a broken program is never
+   stored. On success it returns `{ programId, rowCount, columns,
+   sampleRows }` — use that as proof the program produces the rows you
+   expect.
+4. Bind whatever UI needs the result. Your app's own read path calls
+   `run-data-program({ programId, params?, forceRefresh?, includeRows? })`
+   and gets back rows/schema/cache metadata to hand to your own table/chart
+   components — there is no dashboard-specific plumbing baked into the
+   primitive itself. (The analytics template's `"program"` dashboard panel
+   source is one such adoption, not a required pattern — see its
+   `data-programs` skill if you want a concrete UI wiring reference.)
+5. Iterate without persisting via `preview-data-program({ code, params? })` —
+   same dry-run path, no stored row.
+
+## The sandbox surface
+
+Exactly the `run-code` globals (`providerFetch`, `providerFetchAll`,
+`providerSearchAll`, `appAction`, `webFetch`, `workspace*` Resources helpers),
+plus:
+
+- `params` — a **frozen** global object holding the params for this run.
+  Read-only; mutating it throws.
+- `emit(rows, schema?)` — call exactly once, at the end. `rows` must be an
+  array of plain objects. `schema`, when provided, is
+  `{ name: string, type: string }[]`; when omitted it's inferred from the
+  first 50 rows (a column is `"json"` if rows disagree on primitive type,
+  otherwise `"number"` / `"string"` / `"boolean"`). `console.log` remains free
+  for debugging and never interferes with parsing the emitted result.
+
+Caps enforced on every run:
+
+| Limit | Value |
+| --- | --- |
+| Max emitted rows | 10,000 (excess dropped, `truncated: true`) |
+| Max emitted result size | 4 MiB (rows dropped from the end to fit; a single oversized row is a hard failure) |
+| Max active programs per app | 200 |
+| Minimum refresh TTL | 60,000 ms |
+| Run rows kept per (program, params) | 5 most recent |
+
+Truncation is always explicit (`truncated: true`) — never a silent drop.
+
+## Caching and refresh model
+
+Every `(programId, paramsHash)` pair has its own run history:
+
+| Situation | Behavior |
+| --- | --- |
+| Fresh cache (younger than `refreshTtlMs`, or `refreshMode: "manual"` with a prior success) | Returns cached rows instantly, `cacheHit: true` |
+| Stale cache | Re-executes synchronously (25s budget for view-triggered reads, 120s for agent/manual calls), replacing the cache on success |
+| `refreshMode: "manual"` | Only refreshes on explicit `forceRefresh: true` |
+| No cache yet | Executes synchronously like a normal first fetch |
+| `background: true` program with no fresh cache | Serves the last good run with `stale: true` and enqueues a durable background execution; a later call finalizes it once complete |
+| Background program still running, no prior success | `background_pending` failure — surface an explicit "still computing" state, never a blank result |
+| Execution fails | Structured `{ code, message }` failure; a previous success is attached as `lastGoodRun` for stale-serve |
+| Program archived (soft-deleted) | Explicit `archived` failure |
+
+Use `background: true` only for scripts that routinely exceed the foreground
+timeout (large multi-provider joins, deep pagination). Everything else should
+stay foreground.
+
+## Security notes
+
+- **Credentials are always the calling viewer's, never the program author's.**
+  `providerFetch` inside a program resolves auth using the caller's own
+  request context. A viewer without a configured provider key sees that
+  provider's normal auth error on that program's result — never another
+  user's data.
+- **Programs are shareable org-internal only — never public.** Sharing a
+  program means teammates can view its cached result; because execution uses
+  the *viewer's* credentials, only bind to or view a program you trust.
+- Raw provider tokens never reach the model or the browser. Only the
+  `{ rows, schema }` an `emit()` call produces ever leaves the sandbox.
+- The mutating/executing actions (`save-data-program`, `preview-data-program`,
+  `run-data-program`, `delete-data-program`) are not callable from a
+  sandboxed extension/iframe bridge — only from the agent or a server-side
+  read path.
+
+## Related skills
+
+- `actions` for `run-code` conventions and the sandbox globals this primitive
+  is built on.
+- `sharing` for the org-internal, never-public sharing model programs use.
+- `security` for credential-handling and access-scoping invariants.

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

@@ -132,10 +132,16 @@ const custom = resolveAgentHarness("acp", {
   (`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.
+  Docker/remote backend. 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.
+- Long compute exceeds the hosted ~40s run ceiling via the built-in durable
+  background backend: per-call `background: true` on `run-code` (or
+  `AGENT_NATIVE_SANDBOX=background` to queue every call) enqueues to the
+  `sandbox_executions` table and executes out-of-band — self-dispatched to
+  `/_agent-native/sandbox/_process-execution` on serverless, in-process on
+  long-lived Node — with lease-based claiming, retries, and owner-scoped
+  polling via `run-code {executionId}` / `get-code-execution`.
 
 ## Sub-Agent Delegation Depth
 

package/corpus/core/src/vite/agents-bundle-plugin.ts

@@ -30,6 +30,18 @@ const TEMPLATE_SKILLS_DIRS = [
   path.join(".agent", "skills"),
 ] as const;
 
+/**
+ * Coalesce window for the dev-server full-reload sent after AGENTS.md /
+ * SKILL.md changes. Agents (and Fusion editing sessions) frequently write
+ * several skill files back-to-back, and editor atomic saves surface as
+ * unlink+add pairs — without coalescing, every one of those watcher events
+ * triggered its own full page reload, which reads as the app "constantly
+ * refreshing" while an agent works. Module invalidation still happens per
+ * event (it's cheap and keeps the next request fresh); only the browser
+ * reload is batched.
+ */
+const FULL_RELOAD_COALESCE_MS = 500;
+
 async function emitBundleModule(projectRoot: string): Promise<string> {
   // If the project is inside an enterprise monorepo with a workspace core,
   // merge in its AGENTS.md + skills. Template skills override workspace
@@ -126,12 +138,25 @@ export function agentsBundlePlugin(): Plugin {
         return false;
       };
 
+      let reloadTimer: ReturnType<typeof setTimeout> | null = null;
+      const scheduleFullReload = () => {
+        if (reloadTimer) clearTimeout(reloadTimer);
+        reloadTimer = setTimeout(() => {
+          reloadTimer = null;
+          server.ws.send({ type: "full-reload" });
+        }, FULL_RELOAD_COALESCE_MS);
+      };
+      server.httpServer?.once("close", () => {
+        if (reloadTimer) clearTimeout(reloadTimer);
+        reloadTimer = null;
+      });
+
       const invalidate = (file: string) => {
         if (!shouldInvalidate(file)) return;
         const mod = server.moduleGraph.getModuleById(RESOLVED_ID);
         if (mod) {
           server.moduleGraph.invalidateModule(mod);
-          server.ws.send({ type: "full-reload" });
+          scheduleFullReload();
         }
       };
 

package/corpus/core/src/vite/client.ts

@@ -579,6 +579,7 @@ const CORE_CLIENT_SUBPATHS = [
   "@agent-native/core/client/composer",
   "@agent-native/core/client/conversation",
   "@agent-native/core/client/editor",
+  "@agent-native/core/client/i18n",
   "@agent-native/core/client/resources",
   // Dedicated subpath that exports ONLY appBasePath/agentNativePath/appPath.
   // entry.client.tsx imports from here so it never pulls the full client barrel
@@ -599,6 +600,8 @@ const CORE_CLIENT_SUBPATHS = [
   "@agent-native/core/voice",
 ];
 
+const NODE_SSR_NATIVE_EXTERNALS = ["better-sqlite3", "bindings"];
+
 function getDefaultOptimizeDeps(cwd: string): string[] {
   const inMonorepo = findCoreSrcDir(cwd) !== null;
   const entries: Array<{ specifier: string; packageName?: string }> = [
@@ -633,6 +636,10 @@ function getDefaultOptimizeDeps(cwd: string): string[] {
             specifier: "@agent-native/core/client/editor",
             packageName: "@agent-native/core",
           },
+          {
+            specifier: "@agent-native/core/client/i18n",
+            packageName: "@agent-native/core",
+          },
           {
             specifier: "@agent-native/core/client/resources",
             packageName: "@agent-native/core",
@@ -853,6 +860,7 @@ function getCoreSourceAliases(
       coreSrc,
       "client/editor/index.ts",
     ),
+    "@agent-native/core/client/i18n": path.join(coreSrc, "client/i18n.tsx"),
     "@agent-native/core/client/resources": path.join(
       coreSrc,
       "client/resources/index.ts",
@@ -1739,6 +1747,7 @@ function ssrStubPlugin(packages: string[]): Plugin | null {
     "captureException",
     "common",
     "createLowlight",
+    "createNodeFromContent",
     "defaultUrlTransform",
     "extensions",
     "findTable",
@@ -2303,6 +2312,10 @@ function createAgentNativeConfig(
       ? {
           ...(userConfig.ssr ?? {}),
           noExternal: /^(?!node:)/,
+          external: [
+            ...NODE_SSR_NATIVE_EXTERNALS,
+            ...arrayFrom((userConfig.ssr as { external?: any })?.external),
+          ],
           // Pick the workspace-core's compiled `dist/` exports in prod —
           // Node-style `default` condition matches what edge runtimes (CF
           // Workers, Deno) can actually load. Without this, Vite's prod

package/corpus/templates/analytics/.agents/skills/actions/SKILL.md

@@ -161,6 +161,18 @@ to find likely URLs, `web-request` or `provider-api-docs` with clean
 `webFetch()` when you need to grep, aggregate, or compare many pages before
 returning a small result.
 
+For LONG compute, `run-code` supports durable background executions: pass
+`background: true` and the code is enqueued to a `sandbox_executions` row and
+executed out-of-band with a generous budget (default 10 min), surviving the
+hosted agent run's ~40s soft timeout. The call returns
+`{ executionId, status: "queued" }` immediately with polling guidance; check
+progress with `run-code` `{ executionId }` (or the `get-code-execution` tool
+where registered) — results persist after completion. Use background for big
+cross-source joins, multi-page provider sweeps, and heavy analysis scripts;
+keep quick scripts in the default foreground mode. Agents should continue
+other work between polls, and on `failed`/`timed_out` split the computation or
+persist intermediate progress with `workspaceWrite` and re-run.
+
 ### The `http` Option
 
 Controls how the action is exposed as an HTTP endpoint:
@@ -205,6 +217,49 @@ run: async (args) => {
 }
 ```
 
+### Returning Images the Agent Can See (`_agentImages`)
+
+An action's return object may include the well-known optional field
+`_agentImages` to attach vision images (screenshots, chart previews, rendered
+designs) to the tool result. The agent literally sees them — enabling visual
+self-review loops — while the field itself is stripped from the JSON text the
+model reads.
+
+```ts
+run: async ({ dashboardId }) => {
+  const shot = await renderDashboardPng(dashboardId); // Buffer
+  return {
+    dashboardId,
+    panelCount: 6,
+    _agentImages: [
+      // Either a public https URL (preferred — the provider fetches it)…
+      { url: "https://cdn.example.com/previews/dash-1.png", label: "overview" },
+      // …or base64 without a data: prefix (mediaType required; a full
+      // data:image/png;base64,… URL in `data` is also accepted and parsed).
+      { data: shot.toString("base64"), mediaType: "image/png" },
+    ],
+  };
+},
+```
+
+Rules and limits:
+
+- Shape: `Array<{ url?: string; data?: string; mediaType?: string; label?: string }>`.
+  Each entry needs `url` (https only) **or** `data`. Supported media types:
+  `image/jpeg`, `image/png`, `image/gif`, `image/webp`.
+- Caps: max **4 images** per result; max **~2MB of base64** per image.
+  Over-cap or invalid entries never fail the call — they become text notes in
+  the result telling the model what was dropped and why.
+- Persistence: the run ledger stores only the string result plus compact
+  `[image: …]` notes (URLs verbatim; base64 as a byte-count placeholder) —
+  never the payload. Images are re-attached only for the live turn; replayed
+  history is text-only, so prefer stable `url` images the model can re-request.
+- Engine support: native Anthropic and vision-capable AI-SDK providers
+  (anthropic, openai, google, openrouter) receive real image blocks; other
+  paths (Builder gateway, non-vision providers) degrade to the text notes.
+- External MCP tools need no changes — standard MCP `image` content parts are
+  converted automatically under the same caps.
+
 ### Validating Return Values (`outputSchema`)
 
 `schema` validates inputs; `outputSchema` validates what the action **returns**. Pass any Standard Schema-compatible schema (Zod, Valibot, ArkType) and the framework validates the result _after_ `run()` resolves — input validated before `run`, output after.

package/corpus/templates/analytics/.agents/skills/analysis-workspace/SKILL.md

@@ -39,6 +39,14 @@ window, then read them back selectively for synthesis.
   durable files outside `scratch/` only when the user wants to keep them.
 - **run-code aggregation**: call `workspaceRead` / `workspaceWrite` inside a
   `run-code` block to load and process data that's too large to print as output.
+- **Long compute**: for aggregation scripts that could exceed ~30 s (big
+  cross-source joins, multi-page provider sweeps), run `run-code` with
+  `background: true`. It returns `{ executionId, status: "queued" }`
+  immediately and executes durably out-of-band (default 10 min budget),
+  surviving the hosted run timeout. Continue other work, then poll with
+  `run-code` `{ executionId }` for the persisted result. On `failed`/
+  `timed_out`, chunk the work or persist intermediate progress with
+  `workspaceWrite` and re-run.
 
 ## Workspace File Helpers