@agent-native/core 0.79.26 → 0.80.0

package/corpus/core/docs/content/workspace.mdx

@@ -11,13 +11,68 @@ Every agent-native app ships with a **workspace**: the customization layer that
 
 The twist: **it's SQL rows, not filesystem files.** Each user gets their own workspace stored in the database. There's no dev-box to spin up, no container per user, no files to mount. A multi-tenant SaaS can give every user a fully-customizable agent for essentially free, because all of it is rows — personal memory, personal MCP servers, personal skills, personal sub-agents — and the shared codebase hosts all of them at once.
 
-```an-diagram title="A Claude-Code workspace, but stored in SQL" summary="The same customization layer — instructions, skills, memory, agents, jobs, MCP — except every file is a row in a shared multi-tenant database."
-{
-  "html": "<div class=\"ws-map\"><div class=\"diagram-card cc\"><span class=\"diagram-pill warn\">Claude Code / Codex</span><small class=\"diagram-muted\">~/.claude/ on a local disk</small><div class=\"ws-files\"><span class=\"diagram-box\">CLAUDE.md</span><span class=\"diagram-box\">skills/</span><span class=\"diagram-box\">memory</span><span class=\"diagram-box\">mcp.json</span></div><small class=\"diagram-muted\">one codebase per developer</small></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-card an\"><span class=\"diagram-pill accent\">Agent-native workspace</span><small class=\"diagram-muted\">rows in one SQL database</small><div class=\"ws-rows\"><span class=\"diagram-pill\">AGENTS.md</span><span class=\"diagram-pill\">skills/&hellip;</span><span class=\"diagram-pill\">memory/&hellip;</span><span class=\"diagram-pill\">mcp-servers/&hellip;</span></div><small class=\"diagram-muted\">one codebase, many users, scoped <code>u:&lt;email&gt;:&hellip;</code></small></div></div>",
-  "css": ".ws-map{display:flex;align-items:center;gap:16px;flex-wrap:wrap}.ws-map .diagram-card{display:flex;flex-direction:column;gap:8px;padding:16px 18px;flex:1;min-width:220px}.ws-map .ws-files,.ws-map .ws-rows{display:flex;flex-wrap:wrap;gap:6px;margin:4px 0}.ws-map .diagram-arrow{font-size:24px}"
+<Diagram id="doc-block-13zbuxe" title="A Claude-Code workspace, but stored in SQL" summary={"The same customization layer — instructions, skills, memory, agents, jobs, MCP — except every file is a row in a shared multi-tenant database."}>
+
+```html
+<div class="ws-map">
+  <div class="diagram-card cc">
+    <span class="diagram-pill warn">Claude Code / Codex</span
+    ><small class="diagram-muted">~/.claude/ on a local disk</small>
+    <div class="ws-files">
+      <span class="diagram-box">CLAUDE.md</span
+      ><span class="diagram-box">skills/</span
+      ><span class="diagram-box">memory</span
+      ><span class="diagram-box">mcp.json</span>
+    </div>
+    <small class="diagram-muted">one codebase per developer</small>
+  </div>
+  <div class="diagram-arrow diagram-muted" aria-hidden="true">&rarr;</div>
+  <div class="diagram-card an">
+    <span class="diagram-pill accent">Agent-native workspace</span
+    ><small class="diagram-muted">rows in one SQL database</small>
+    <div class="ws-rows">
+      <span class="diagram-pill">AGENTS.md</span
+      ><span class="diagram-pill">skills/&hellip;</span
+      ><span class="diagram-pill">memory/&hellip;</span
+      ><span class="diagram-pill">mcp-servers/&hellip;</span>
+    </div>
+    <small class="diagram-muted"
+      >one codebase, many users, scoped
+      <code>u:&lt;email&gt;:&hellip;</code></small
+    >
+  </div>
+</div>
+```
+
+```css
+.ws-map {
+  display: flex;
+  align-items: center;
+  gap: 16px;
+  flex-wrap: wrap;
+}
+.ws-map .diagram-card {
+  display: flex;
+  flex-direction: column;
+  gap: 8px;
+  padding: 16px 18px;
+  flex: 1;
+  min-width: 220px;
+}
+.ws-map .ws-files,
+.ws-map .ws-rows {
+  display: flex;
+  flex-wrap: wrap;
+  gap: 6px;
+  margin: 4px 0;
+}
+.ws-map .diagram-arrow {
+  font-size: 24px;
 }
 ```
 
+</Diagram>
+
 | Claude Code / Codex              | Agent-native workspace                             |
 | -------------------------------- | -------------------------------------------------- |
 | Files on your local disk         | Rows in a shared SQL database                      |
@@ -51,13 +106,61 @@ The canonical paths that control how the agent uses each resource:
 
 These paths apply across all three scopes — workspace, organization/app, and personal. The later scope wins when the same path exists at multiple levels.
 
-```an-diagram title="Three scopes, one effective file" summary="The runtime resolves the same path across workspace, app, and personal scopes on read — the most specific scope wins."
-{
-  "html": "<div class=\"ws-stack\"><div class=\"diagram-card\"><span class=\"diagram-pill\">Workspace</span><small class=\"diagram-muted\">company-wide defaults from Dispatch</small><code>context/brand.md</code></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&darr;</div><div class=\"diagram-card\"><span class=\"diagram-pill\">Organization / app</span><small class=\"diagram-muted\">team override for one app</small><code>context/brand.md</code></div><div class=\"diagram-arrow diagram-muted\" aria-hidden=\"true\">&darr;</div><div class=\"diagram-card\"><span class=\"diagram-pill accent\">Personal</span><small class=\"diagram-muted\">per-user override &mdash; wins</small><code>context/brand.md</code></div><div class=\"diagram-arrow diagram-accent\" aria-hidden=\"true\">&rarr;</div><div class=\"diagram-box ok\">Effective <code>context/brand.md</code></div></div>",
-  "css": ".ws-stack{display:flex;flex-direction:column;align-items:flex-start;gap:8px}.ws-stack .diagram-card{display:flex;flex-direction:column;gap:4px;padding:12px 16px;min-width:280px}.ws-stack .diagram-arrow{font-size:20px;align-self:center}.ws-stack code{font-size:.85em}.ws-stack .diagram-box{align-self:center;margin-top:4px}"
+<Diagram id="doc-block-i69rby" title="Three scopes, one effective file" summary={"The runtime resolves the same path across workspace, app, and personal scopes on read — the most specific scope wins."}>
+
+```html
+<div class="ws-stack">
+  <div class="diagram-card">
+    <span class="diagram-pill">Workspace</span
+    ><small class="diagram-muted">company-wide defaults from Dispatch</small
+    ><code>context/brand.md</code>
+  </div>
+  <div class="diagram-arrow diagram-muted" aria-hidden="true">&darr;</div>
+  <div class="diagram-card">
+    <span class="diagram-pill">Organization / app</span
+    ><small class="diagram-muted">team override for one app</small
+    ><code>context/brand.md</code>
+  </div>
+  <div class="diagram-arrow diagram-muted" aria-hidden="true">&darr;</div>
+  <div class="diagram-card">
+    <span class="diagram-pill accent">Personal</span
+    ><small class="diagram-muted">per-user override &mdash; wins</small
+    ><code>context/brand.md</code>
+  </div>
+  <div class="diagram-arrow diagram-accent" aria-hidden="true">&rarr;</div>
+  <div class="diagram-box ok">Effective <code>context/brand.md</code></div>
+</div>
+```
+
+```css
+.ws-stack {
+  display: flex;
+  flex-direction: column;
+  align-items: flex-start;
+  gap: 8px;
+}
+.ws-stack .diagram-card {
+  display: flex;
+  flex-direction: column;
+  gap: 4px;
+  padding: 12px 16px;
+  min-width: 280px;
+}
+.ws-stack .diagram-arrow {
+  font-size: 20px;
+  align-self: center;
+}
+.ws-stack code {
+  font-size: 0.85em;
+}
+.ws-stack .diagram-box {
+  align-self: center;
+  margin-top: 4px;
 }
 ```
 
+</Diagram>
+
 ## Getting Started: a 1-minute walkthrough {#getting-started}
 
 Change how the agent behaves, in 60 seconds.

package/corpus/core/docs/content/writing-agent-instructions.mdx

@@ -7,13 +7,54 @@ description: "How to write great agent instructions for an agent-native app or t
 
 The agent's behavior in an agent-native app is only as good as the instructions you give it. Three surfaces carry that guidance: `AGENTS.md` (the map), skills (the deep dives), and action/tool descriptions (how the agent picks the right tool). Write each one for fast retrieval, not for prose.
 
-```an-diagram title="Three authored surfaces + one runtime surface" summary="AGENTS.md and tool descriptions load every turn; skills load on demand; application_state is written live by your UI."
-{
-  "html": "<div class=\"diagram-surfaces\"><div class=\"diagram-card always\" data-rough><span class=\"diagram-pill accent\">Every turn</span><strong>AGENTS.md</strong><small class=\"diagram-muted\">the map: purpose, core rules, state keys, action + skills index</small></div><div class=\"diagram-card always\" data-rough><span class=\"diagram-pill accent\">Every turn</span><strong>Tool descriptions</strong><small class=\"diagram-muted\">drive tool selection — one precise sentence each</small></div><div class=\"diagram-card ondemand\" data-rough><span class=\"diagram-pill\">On demand</span><strong>Skills</strong><small class=\"diagram-muted\">deep how-to, loaded when the description fires</small></div><div class=\"diagram-card runtime\" data-rough><span class=\"diagram-pill ok\">Live</span><strong>application_state</strong><small class=\"diagram-muted\">written by your UI: navigation, selection, focus</small></div></div>",
-  "css": ".diagram-surfaces{display:grid;grid-template-columns:repeat(2,minmax(0,1fr));gap:12px}.diagram-surfaces .diagram-card{display:flex;flex-direction:column;gap:6px;padding:14px 16px}"
+<Diagram id="doc-block-hwfuxq" title="Three authored surfaces + one runtime surface" summary={"AGENTS.md and tool descriptions load every turn; skills load on demand; application_state is written live by your UI."}>
+
+```html
+<div class="diagram-surfaces">
+  <div class="diagram-card always" data-rough>
+    <span class="diagram-pill accent">Every turn</span><strong>AGENTS.md</strong
+    ><small class="diagram-muted"
+      >the map: purpose, core rules, state keys, action + skills index</small
+    >
+  </div>
+  <div class="diagram-card always" data-rough>
+    <span class="diagram-pill accent">Every turn</span
+    ><strong>Tool descriptions</strong
+    ><small class="diagram-muted"
+      >drive tool selection — one precise sentence each</small
+    >
+  </div>
+  <div class="diagram-card ondemand" data-rough>
+    <span class="diagram-pill">On demand</span><strong>Skills</strong
+    ><small class="diagram-muted"
+      >deep how-to, loaded when the description fires</small
+    >
+  </div>
+  <div class="diagram-card runtime" data-rough>
+    <span class="diagram-pill ok">Live</span><strong>application_state</strong
+    ><small class="diagram-muted"
+      >written by your UI: navigation, selection, focus</small
+    >
+  </div>
+</div>
+```
+
+```css
+.diagram-surfaces {
+  display: grid;
+  grid-template-columns: repeat(2, minmax(0, 1fr));
+  gap: 12px;
+}
+.diagram-surfaces .diagram-card {
+  display: flex;
+  flex-direction: column;
+  gap: 6px;
+  padding: 14px 16px;
 }
 ```
 
+</Diagram>
+
 ## Keep AGENTS.md small and skimmable {#small-agents-md}
 
 `AGENTS.md` is loaded as orientation. It should be the smallest thing that lets the agent act correctly, with everything deep pushed into skills. Aim for these sections and little else:

package/corpus/core/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agent-native/core",
-  "version": "0.79.26",
+  "version": "0.80.0",
   "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": {
@@ -89,6 +89,7 @@
     "./embedding/react": "./dist/embedding/react.js",
     "./onboarding": "./dist/onboarding/index.js",
     "./shared": "./dist/shared/index.js",
+    "./voice": "./dist/voice/index.js",
     "./scripts": "./dist/scripts/index.js",
     "./application-state": "./dist/application-state/index.js",
     "./settings": "./dist/settings/index.js",

package/corpus/core/src/agent/engine/index.ts

@@ -30,6 +30,7 @@ export {
   isAgentEnginePackageInstalled,
   isStoredEngineUsable,
   isStoredEngineUsableForRequest,
+  isResolvedEngineUsableForRequest,
   type AgentEngineEntry,
   type ResolveEngineConfig,
 } from "./registry.js";

package/corpus/core/src/agent/engine/registry.ts

@@ -412,6 +412,46 @@ export async function isStoredEngineUsableForRequest(
   return true;
 }
 
+/**
+ * Request-aware credential preflight for an already-resolved engine instance.
+ * `resolveEngine()` may still return a default or explicitly requested engine
+ * object before credentials are actually usable; call this before starting a
+ * user-visible run so missing providers fail immediately.
+ */
+export async function isResolvedEngineUsableForRequest(
+  engine: AgentEngine,
+  options: { apiKey?: string } = {},
+): Promise<boolean> {
+  const entry = _registry.get(engine.name);
+  // Custom engines may have their own credential contract outside the core
+  // registry metadata, so do not block them speculatively.
+  if (!entry) return true;
+  if (!isAgentEnginePackageInstalled(entry)) return false;
+  if (entry.requiredEnvVars.length === 0) return true;
+
+  if (entry.name === "builder") {
+    const creds = await resolveBuilderCredentials();
+    return Boolean(creds.privateKey && creds.publicKey);
+  }
+
+  if (options.apiKey?.trim()) return true;
+
+  for (const key of entry.requiredEnvVars) {
+    try {
+      if (await resolveSecret(key)) continue;
+    } catch {
+      // Fall through to deployment-level fallback when allowed.
+    }
+    if (
+      !canUseDeployCredentialFallbackForRequest() ||
+      !readDeployCredentialEnv(key)
+    ) {
+      return false;
+    }
+  }
+  return true;
+}
+
 export interface ResolveEngineConfig {
   /** Explicit engine name or instance from createAgentChatPlugin options */
   engineOption?:

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

@@ -67,6 +67,7 @@ import {
   registerBuiltinEngines,
   getStoredModelForEngine,
   normalizeModelForEngine,
+  isResolvedEngineUsableForRequest,
 } from "./engine/index.js";
 import { resolveMaxOutputTokensForEngine } from "./engine/output-tokens.js";
 import { PROVIDER_TO_ENV } from "./engine/provider-env-vars.js";
@@ -4206,8 +4207,11 @@ export function createProductionAgentHandler(
       `[agent-chat] resolved engine=${engine.name} model=${model} requestEngine=${requestEngine ?? "(none)"}`,
     );
 
-    // Check for API key before starting a run (only for anthropic engine)
-    if (engine.name === "anthropic" && !effectiveApiKey) {
+    if (
+      !(await isResolvedEngineUsableForRequest(engine, {
+        apiKey: effectiveApiKey,
+      }))
+    ) {
       setResponseHeader(event, "Content-Type", "text/event-stream");
       setResponseHeader(event, "Cache-Control", "no-cache");
       setResponseHeader(event, "Connection", "keep-alive");

package/corpus/core/src/application-state/store.ts

@@ -12,11 +12,11 @@ import { emitAppStateChange, emitAppStateDelete } from "./emitter.js";
 let _initPromise: Promise<void> | undefined;
 
 // Escapes LIKE wildcards (`%`, `_`) and the escape char itself so a caller's
-// literal prefix is matched verbatim. Used with `ESCAPE '\'` in prefix queries
+// literal prefix is matched verbatim. Used with `ESCAPE '!'` in prefix queries
 // below; without this, a prefix such as `user_settings` would treat `_` as a
 // single-char wildcard and over-match (e.g. delete `userXsettings`).
 function escapeLike(s: string): string {
-  return s.replace(/([\\%_])/g, "\\$1");
+  return s.replace(/[!%_]/g, (match) => `!${match}`);
 }
 
 async function ensureTable(): Promise<void> {
@@ -155,7 +155,7 @@ export async function appStateList(
   await ensureTable();
   const client = getDbExec();
   const { rows } = await client.execute({
-    sql: `SELECT key, value FROM application_state WHERE session_id = ? AND key LIKE ? ESCAPE '\\'`,
+    sql: `SELECT key, value FROM application_state WHERE session_id = ? AND key LIKE ? ESCAPE '!'`,
     args: [sessionId, escapeLike(keyPrefix) + "%"],
   });
   return rows.map((row) => ({
@@ -174,14 +174,14 @@ export async function appStateDeleteByPrefix(
 
   // Get keys first so we can emit events
   const { rows } = await client.execute({
-    sql: `SELECT key FROM application_state WHERE session_id = ? AND key LIKE ? ESCAPE '\\'`,
+    sql: `SELECT key FROM application_state WHERE session_id = ? AND key LIKE ? ESCAPE '!'`,
     args: [sessionId, escapeLike(keyPrefix) + "%"],
   });
 
   if (rows.length === 0) return 0;
 
   const result = await client.execute({
-    sql: `DELETE FROM application_state WHERE session_id = ? AND key LIKE ? ESCAPE '\\'`,
+    sql: `DELETE FROM application_state WHERE session_id = ? AND key LIKE ? ESCAPE '!'`,
     args: [sessionId, escapeLike(keyPrefix) + "%"],
   });
 

package/corpus/core/src/chat-threads/store.ts

@@ -571,7 +571,7 @@ export async function listThreads(
 }
 
 function escapeLike(s: string): string {
-  return s.replace(/([\\%_])/g, "\\$1");
+  return s.replace(/[!%_]/g, (match) => `!${match}`);
 }
 
 export async function searchThreads(
@@ -589,7 +589,7 @@ export async function searchThreads(
   const filters: string[] = [
     `owner_email = ?`,
     `message_count > 0`,
-    `(title LIKE ? ESCAPE '\\' OR preview LIKE ? ESCAPE '\\' OR thread_data LIKE ? ESCAPE '\\')`,
+    `(title LIKE ? ESCAPE '!' OR preview LIKE ? ESCAPE '!' OR thread_data LIKE ? ESCAPE '!')`,
   ];
   const args: (string | number)[] = [ownerEmail, pattern, pattern, pattern];
   if (options.scope) {