@agent-native/core 0.91.2 → 0.92.0

package/dist/server/agent-engine-api-key-route.d.ts

@@ -27,11 +27,11 @@ export declare function resolveAgentEngineApiKeyWriteTarget(event: H3Event, scop
 export declare function createAgentEngineApiKeyHandler(): import("h3").EventHandlerWithFetch<import("h3").EventHandlerRequest, Promise<{
     error: any;
 } | {
+    error?: undefined;
     ok: boolean;
     key: string;
     baseUrlKey?: string;
     scope: AgentEngineApiKeyScope;
-    error?: undefined;
 }>>;
 export {};
 //# sourceMappingURL=agent-engine-api-key-route.d.ts.map

package/dist/server/request-context.d.ts

@@ -68,6 +68,13 @@ export interface RequestRunContext {
         content: string;
         isError: boolean;
     }>;
+    /** Per-run fingerprints for large extension bodies already sent to the LLM. */
+    extensionContentReads?: Record<string, string>;
+    /** Per-run fingerprints for repeated tool-search calls already sent to the LLM. */
+    toolSearchReads?: Record<string, {
+        totalTools: number;
+        resultNames: string[];
+    }>;
 }
 export interface RequestContext {
     userEmail?: string;

package/dist/server/request-context.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"request-context.d.ts","sourceRoot":"","sources":["../../src/server/request-context.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"request-context.d.ts","sourceRoot":"","sources":["../../src/server/request-context.ts"],"names":[],"mappings":"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"}

package/dist/server/request-context.js.map

@@ -1 +1 @@
-{"version":3,"file":"request-context.js","sourceRoot":"","sources":["../../src/server/request-context.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Per-request context using AsyncLocalStorage.\n *\n * Replaces the unsafe pattern of mutating `process.env.AGENT_USER_EMAIL` /\n * `process.env.AGENT_ORG_ID` on every request. On Node.js (Netlify, self-hosted)\n * concurrent requests would overwrite each other's env vars. AsyncLocalStorage\n * gives each async call-chain its own isolated context.\n *\n * Supported on all deployment targets:\n * - Node.js (native)\n * - Cloudflare Workers (via nodejs_compat flag)\n * - Deno Deploy (via node:async_hooks compat)\n *\n * For CLI scripts that run outside a request context, the getters fall back to\n * process.env so existing `AGENT_USER_EMAIL=x pnpm action foo` invocations\n * continue to work.\n */\n\ntype AsyncLocalStorageLike<T> = {\n  getStore(): T | undefined;\n  run<R>(store: T, callback: () => R): R;\n};\n\ntype AsyncLocalStorageCtor = new <T>() => AsyncLocalStorageLike<T>;\n\nclass StackAsyncLocalStorage<T> implements AsyncLocalStorageLike<T> {\n  private readonly stack: T[] = [];\n\n  getStore(): T | undefined {\n    return this.stack.at(-1);\n  }\n\n  run<R>(store: T, callback: () => R): R {\n    this.stack.push(store);\n    try {\n      const result = callback();\n      const maybePromise = result as unknown as\n        | { finally?: (callback: () => void) => unknown }\n        | undefined;\n      if (maybePromise && typeof maybePromise.finally === \"function\") {\n        return maybePromise.finally(() => {\n          this.stack.pop();\n        }) as R;\n      }\n      this.stack.pop();\n      return result;\n    } catch (error) {\n      this.stack.pop();\n      throw error;\n    }\n  }\n}\n\nfunction getAsyncLocalStorageCtor(): AsyncLocalStorageCtor | undefined {\n  if (\n    typeof window !== \"undefined\" ||\n    typeof process === \"undefined\" ||\n    !process.versions?.node ||\n    typeof process.getBuiltinModule !== \"function\"\n  ) {\n    return undefined;\n  }\n  return process.getBuiltinModule(\"node:async_hooks\")?.AsyncLocalStorage as\n    | AsyncLocalStorageCtor\n    | undefined;\n}\n\nconst AsyncLocalStorageCtor = getAsyncLocalStorageCtor();\n\nfunction processEnv(name: string): string | undefined {\n  if (typeof process === \"undefined\") return undefined;\n  return process.env?.[name];\n}\n\n/**\n * Per-request agent-run state. Lives on `RequestContext.run` so the\n * agent-chat plugin can populate fields as the run progresses (owner,\n * resolved API key, system prompt, engine, model, threadId) without\n * mutating module-scope `let` bindings — those leak across concurrent\n * requests on a single Node.js process.\n *\n * Mutated in-place by `prepareRun`, `onEngineResolved`, `onRunStart` so\n * tool factory closures (automation, fetch, team, builder-browser) read\n * the live per-request value via `getRequestRunContext()`.\n */\nexport interface RequestRunContext {\n  /** Origin of the current request (used by the builder-browser tool). */\n  requestOrigin?: string;\n  /** Stable browser tab id for tab-scoped app-state reads/writes. */\n  browserTabId?: string;\n  /** Resource scope for the current chat thread, e.g. the active deck. */\n  chatScope?: {\n    type: string;\n    id: string;\n    label?: string;\n  } | null;\n  /** Resolved owner email (set by prepareRun). */\n  owner?: string;\n  /** Owner's active Anthropic API key (set by prepareRun). */\n  userApiKey?: string;\n  /** Thread ID for the current run (set by onRunStart). */\n  threadId?: string;\n  /** System prompt actually sent to the model for this run. */\n  systemPrompt?: string;\n  /** Engine instance for this run (set by onEngineResolved). */\n  engine?: import(\"../agent/engine/types.js\").AgentEngine;\n  /** Model name for this run (set by onEngineResolved). */\n  model?: string;\n  /**\n   * True when this run is executing inside the durable background-function\n   * worker (the `_process-run` self-dispatch), not the synchronous foreground\n   * request. Template `extraContext` / system-prompt builders can read this to\n   * skip heavy, hang-prone enrichment (large data-dictionary DB reads, etc.)\n   * in the worker so it reliably claims its run within the setup budget.\n   */\n  isBackgroundWorker?: boolean;\n  /** Tool calls made so far in the current agent loop. */\n  toolCalls?: Array<{ name: string; input: unknown }>;\n  /** Tool results returned so far in the current agent loop. */\n  toolResults?: Array<{ name: string; content: string; isError: boolean }>;\n}\n\nexport interface RequestContext {\n  userEmail?: string;\n  userName?: string;\n  orgId?: string;\n  timezone?: string;\n  /**\n   * Set when code reads authenticated request context. Public SSR shell/data\n   * should not depend on this value; user/org-specific reads belong behind\n   * client-side actions/API after hydration.\n   */\n  authContextAccessed?: boolean;\n  /**\n   * Origin of the inbound request (e.g. `http://127.0.0.1:8100`). Set by the\n   * MCP mount from the request headers so actions that build externally\n   * fetchable URLs (e.g. design `export-coding-handoff`'s signed raw-code URL)\n   * resolve the real local-workspace origin instead of a prod/localhost\n   * fallback. Optional — absent on paths that don't populate it.\n   */\n  requestOrigin?: string;\n  /**\n   * True when this request is being processed by an integration-platform\n   * webhook (Slack, Telegram, etc.) where the function timeout is the\n   * binding constraint. Code that calls slow remote APIs can use this to apply\n   * tighter budgets on this path while leaving normal agent-chat callers\n   * (5+ min budget) unaffected.\n   */\n  isIntegrationCaller?: boolean;\n  /**\n   * Metadata for the currently-processing integration task. This lets tools\n   * that start long-running remote work persist a continuation that can update\n   * the originating platform thread after the current function budget ends.\n   */\n  integration?: {\n    taskId: string;\n    attempts?: number;\n    incoming: import(\"../integrations/types.js\").IncomingMessage;\n    placeholderRef?: string;\n  };\n  /**\n   * Mutable per-request agent-run state. Populated by the agent-chat plugin\n   * during a run; tool closures dereference it on each invocation.\n   */\n  run?: RequestRunContext;\n}\n\nconst GLOBAL_KEY = \"__agentNativeRequestContextAls\" as const;\nconst OBSERVERS_KEY = \"__agentNativeRequestContextObservers\" as const;\ntype RequestContextObserver = (ctx: RequestContext) => void;\ntype GlobalWithRequestContext = typeof globalThis & {\n  [GLOBAL_KEY]?: AsyncLocalStorageLike<RequestContext>;\n  [OBSERVERS_KEY]?: RequestContextObserver[];\n};\nconst globalRef = globalThis as GlobalWithRequestContext;\nif (!globalRef[GLOBAL_KEY]) {\n  globalRef[GLOBAL_KEY] = AsyncLocalStorageCtor\n    ? new AsyncLocalStorageCtor<RequestContext>()\n    : new StackAsyncLocalStorage<RequestContext>();\n}\nif (!globalRef[OBSERVERS_KEY]) {\n  globalRef[OBSERVERS_KEY] = [];\n}\nconst als = globalRef[GLOBAL_KEY]!;\nconst observers = globalRef[OBSERVERS_KEY]!;\n\n/**\n * Register a callback fired every time `runWithRequestContext` enters a new\n * scope. The hook runs INSIDE the AsyncLocalStorage scope, so observability\n * helpers that read the current isolation scope (e.g. Sentry) attach to the\n * right per-request context.\n *\n * Returned function unregisters the observer. Observers must never throw —\n * any error is swallowed so a misbehaving observer can't break the request\n * path.\n */\nexport function addRequestContextObserver(\n  observer: RequestContextObserver,\n): () => void {\n  observers.push(observer);\n  return () => {\n    const i = observers.indexOf(observer);\n    if (i !== -1) observers.splice(i, 1);\n  };\n}\n\n/**\n * Run a callback within a per-request context. The context is available to all\n * async operations spawned from `fn` via `getRequestUserEmail()` / `getRequestOrgId()`.\n *\n * Any registered `addRequestContextObserver` callbacks fire inside the new\n * scope before `fn` runs, so observability code can pin user/org info onto\n * isolation-scoped backends (Sentry, OpenTelemetry, etc.).\n */\nexport function runWithRequestContext<T>(\n  ctx: RequestContext,\n  fn: () => T | Promise<T>,\n): T | Promise<T> {\n  return als.run(ctx, () => {\n    if (observers.length > 0) {\n      for (const obs of observers) {\n        try {\n          obs(ctx);\n        } catch {\n          // Observers must never break the request path.\n        }\n      }\n    }\n    return fn();\n  });\n}\n\n/**\n * Return the active request context, if this call chain is running under one.\n *\n * This is intentionally distinct from `getRequestUserEmail()`: callers that\n * have an active context with no authenticated user must not fall through to\n * process-wide CLI fallbacks such as `AGENT_USER_EMAIL` or \"latest session\".\n */\nexport function getRequestContext(): RequestContext | undefined {\n  const store = als.getStore();\n  markAuthContextAccess(store);\n  return store;\n}\n\n/**\n * True when AsyncLocalStorage has an active context for this call chain.\n * Useful for helpers that support both HTTP requests and standalone CLI runs.\n */\nexport function hasRequestContext(): boolean {\n  return als.getStore() !== undefined;\n}\n\n/**\n * Get the current request's user email.\n *\n * - If a request context exists (HTTP/A2A path), returns its `userEmail` —\n *   even when that value is `undefined`. The env fallback MUST NOT fire here:\n *   a stale process-wide `AGENT_USER_EMAIL` from a CLI run or previous bug\n *   would leak into an unauthenticated A2A/API call (e.g. unsigned or API-key\n *   modes where `runWithRequestContext({ userEmail: undefined })` is used).\n * - Only when there is NO request context (CLI scripts) do we fall back to\n *   `process.env.AGENT_USER_EMAIL`.\n */\nexport function getRequestUserEmail(): string | undefined {\n  const store = als.getStore();\n  if (store !== undefined) {\n    if (store.userEmail) markAuthContextAccess(store);\n    return store.userEmail;\n  }\n  return processEnv(\"AGENT_USER_EMAIL\");\n}\n\n/**\n * Get the current request's display name, when the auth provider supplied one.\n *\n * The same request-context fallback rules as `getRequestUserEmail()` apply:\n * HTTP/A2A calls only read AsyncLocalStorage, while CLI scripts may opt in via\n * `AGENT_USER_NAME`.\n */\nexport function getRequestUserName(): string | undefined {\n  const store = als.getStore();\n  if (store !== undefined) {\n    if (store.userName) markAuthContextAccess(store);\n    return store.userName;\n  }\n  return processEnv(\"AGENT_USER_NAME\");\n}\n\n/**\n * Get the current request's org ID.\n *\n * Same store-aware semantics as `getRequestUserEmail()` — env fallback is\n * CLI-only, so a request that explicitly has no org doesn't inherit a stale\n * `process.env.AGENT_ORG_ID` from a prior request on the same Lambda instance.\n */\nexport function getRequestOrgId(): string | undefined {\n  const store = als.getStore();\n  if (store !== undefined) {\n    if (store.orgId) markAuthContextAccess(store);\n    return store.orgId;\n  }\n  return processEnv(\"AGENT_ORG_ID\");\n}\n\nfunction markAuthContextAccess(ctx: RequestContext | undefined) {\n  if (!ctx) return;\n  if (ctx.userEmail || ctx.userName || ctx.orgId) {\n    ctx.authContextAccessed = true;\n  }\n}\n\nexport function hasAuthContextAccess(ctx: RequestContext | undefined): boolean {\n  return Boolean(ctx?.authContextAccessed);\n}\n\n/**\n * Get the current request's IANA timezone (e.g. \"America/Los_Angeles\").\n * The UI sends this via the `x-user-timezone` header on every action call, and\n * the agent chat plugin propagates it into the request context so that\n * agent-initiated tool calls also see the user's timezone. Falls back to\n * `process.env.AGENT_USER_TIMEZONE` only for CLI scripts (no request context).\n */\nexport function getRequestTimezone(): string | undefined {\n  const store = als.getStore();\n  if (store !== undefined) return store.timezone;\n  return processEnv(\"AGENT_USER_TIMEZONE\");\n}\n\n/**\n * Returns true when this request is on an integration-platform path (Slack,\n * Telegram, etc.) — i.e. we're inside the integration plugin's processor\n * function and the platform's deliver-by deadline plus the host's function\n * timeout are the binding budget. Non-integration callers (CLI, normal\n * agent chat) should treat this as `false`.\n */\nexport function isIntegrationCallerRequest(): boolean {\n  return als.getStore()?.isIntegrationCaller === true;\n}\n\nexport function getIntegrationRequestContext():\n  | NonNullable<RequestContext[\"integration\"]>\n  | undefined {\n  return als.getStore()?.integration;\n}\n\n/**\n * Convenience: returns `{ userEmail, orgId }` from the active request context,\n * suitable for passing to `resolveCredential(key, ctx)`. Returns `null` when\n * no user is associated with the call (e.g. an unauthenticated public route).\n *\n * For framework actions auto-mounted at `/_agent-native/actions/...` this is\n * always populated because action-routes wraps every invocation in\n * `runWithRequestContext`. For hand-written `/api/*` routes the calling code\n * is responsible for setting up the context (see `runWithRequestContext`).\n */\nexport function getCredentialContext(): {\n  userEmail: string;\n  orgId: string | null;\n} | null {\n  const userEmail = getRequestUserEmail();\n  if (!userEmail) return null;\n  return { userEmail, orgId: getRequestOrgId() ?? null };\n}\n\n/**\n * Get the active request's mutable agent-run state. Returns `undefined` when\n * called outside an agent run (e.g. before `prepareRun` or in a non-agent\n * code path). Callers must tolerate the field absence; use the helper\n * `requireRequestRunContext()` if missing context is a programming error.\n */\nexport function getRequestRunContext(): RequestRunContext | undefined {\n  const store = als.getStore();\n  if (!store) return undefined;\n  return store.run;\n}\n\n/**\n * Ensure a `RequestRunContext` exists on the active request store and\n * return it. Used by the agent-chat handler to attach run state once it\n * starts processing a chat request. Returns `undefined` if there is no\n * active request store (caller should not be invoking this outside ALS).\n */\nexport function ensureRequestRunContext(): RequestRunContext | undefined {\n  const store = als.getStore();\n  if (!store) return undefined;\n  if (!store.run) store.run = {};\n  return store.run;\n}\n"]}
+{"version":3,"file":"request-context.js","sourceRoot":"","sources":["../../src/server/request-context.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Per-request context using AsyncLocalStorage.\n *\n * Replaces the unsafe pattern of mutating `process.env.AGENT_USER_EMAIL` /\n * `process.env.AGENT_ORG_ID` on every request. On Node.js (Netlify, self-hosted)\n * concurrent requests would overwrite each other's env vars. AsyncLocalStorage\n * gives each async call-chain its own isolated context.\n *\n * Supported on all deployment targets:\n * - Node.js (native)\n * - Cloudflare Workers (via nodejs_compat flag)\n * - Deno Deploy (via node:async_hooks compat)\n *\n * For CLI scripts that run outside a request context, the getters fall back to\n * process.env so existing `AGENT_USER_EMAIL=x pnpm action foo` invocations\n * continue to work.\n */\n\ntype AsyncLocalStorageLike<T> = {\n  getStore(): T | undefined;\n  run<R>(store: T, callback: () => R): R;\n};\n\ntype AsyncLocalStorageCtor = new <T>() => AsyncLocalStorageLike<T>;\n\nclass StackAsyncLocalStorage<T> implements AsyncLocalStorageLike<T> {\n  private readonly stack: T[] = [];\n\n  getStore(): T | undefined {\n    return this.stack.at(-1);\n  }\n\n  run<R>(store: T, callback: () => R): R {\n    this.stack.push(store);\n    try {\n      const result = callback();\n      const maybePromise = result as unknown as\n        | { finally?: (callback: () => void) => unknown }\n        | undefined;\n      if (maybePromise && typeof maybePromise.finally === \"function\") {\n        return maybePromise.finally(() => {\n          this.stack.pop();\n        }) as R;\n      }\n      this.stack.pop();\n      return result;\n    } catch (error) {\n      this.stack.pop();\n      throw error;\n    }\n  }\n}\n\nfunction getAsyncLocalStorageCtor(): AsyncLocalStorageCtor | undefined {\n  if (\n    typeof window !== \"undefined\" ||\n    typeof process === \"undefined\" ||\n    !process.versions?.node ||\n    typeof process.getBuiltinModule !== \"function\"\n  ) {\n    return undefined;\n  }\n  return process.getBuiltinModule(\"node:async_hooks\")?.AsyncLocalStorage as\n    | AsyncLocalStorageCtor\n    | undefined;\n}\n\nconst AsyncLocalStorageCtor = getAsyncLocalStorageCtor();\n\nfunction processEnv(name: string): string | undefined {\n  if (typeof process === \"undefined\") return undefined;\n  return process.env?.[name];\n}\n\n/**\n * Per-request agent-run state. Lives on `RequestContext.run` so the\n * agent-chat plugin can populate fields as the run progresses (owner,\n * resolved API key, system prompt, engine, model, threadId) without\n * mutating module-scope `let` bindings — those leak across concurrent\n * requests on a single Node.js process.\n *\n * Mutated in-place by `prepareRun`, `onEngineResolved`, `onRunStart` so\n * tool factory closures (automation, fetch, team, builder-browser) read\n * the live per-request value via `getRequestRunContext()`.\n */\nexport interface RequestRunContext {\n  /** Origin of the current request (used by the builder-browser tool). */\n  requestOrigin?: string;\n  /** Stable browser tab id for tab-scoped app-state reads/writes. */\n  browserTabId?: string;\n  /** Resource scope for the current chat thread, e.g. the active deck. */\n  chatScope?: {\n    type: string;\n    id: string;\n    label?: string;\n  } | null;\n  /** Resolved owner email (set by prepareRun). */\n  owner?: string;\n  /** Owner's active Anthropic API key (set by prepareRun). */\n  userApiKey?: string;\n  /** Thread ID for the current run (set by onRunStart). */\n  threadId?: string;\n  /** System prompt actually sent to the model for this run. */\n  systemPrompt?: string;\n  /** Engine instance for this run (set by onEngineResolved). */\n  engine?: import(\"../agent/engine/types.js\").AgentEngine;\n  /** Model name for this run (set by onEngineResolved). */\n  model?: string;\n  /**\n   * True when this run is executing inside the durable background-function\n   * worker (the `_process-run` self-dispatch), not the synchronous foreground\n   * request. Template `extraContext` / system-prompt builders can read this to\n   * skip heavy, hang-prone enrichment (large data-dictionary DB reads, etc.)\n   * in the worker so it reliably claims its run within the setup budget.\n   */\n  isBackgroundWorker?: boolean;\n  /** Tool calls made so far in the current agent loop. */\n  toolCalls?: Array<{ name: string; input: unknown }>;\n  /** Tool results returned so far in the current agent loop. */\n  toolResults?: Array<{ name: string; content: string; isError: boolean }>;\n  /** Per-run fingerprints for large extension bodies already sent to the LLM. */\n  extensionContentReads?: Record<string, string>;\n  /** Per-run fingerprints for repeated tool-search calls already sent to the LLM. */\n  toolSearchReads?: Record<\n    string,\n    { totalTools: number; resultNames: string[] }\n  >;\n}\n\nexport interface RequestContext {\n  userEmail?: string;\n  userName?: string;\n  orgId?: string;\n  timezone?: string;\n  /**\n   * Set when code reads authenticated request context. Public SSR shell/data\n   * should not depend on this value; user/org-specific reads belong behind\n   * client-side actions/API after hydration.\n   */\n  authContextAccessed?: boolean;\n  /**\n   * Origin of the inbound request (e.g. `http://127.0.0.1:8100`). Set by the\n   * MCP mount from the request headers so actions that build externally\n   * fetchable URLs (e.g. design `export-coding-handoff`'s signed raw-code URL)\n   * resolve the real local-workspace origin instead of a prod/localhost\n   * fallback. Optional — absent on paths that don't populate it.\n   */\n  requestOrigin?: string;\n  /**\n   * True when this request is being processed by an integration-platform\n   * webhook (Slack, Telegram, etc.) where the function timeout is the\n   * binding constraint. Code that calls slow remote APIs can use this to apply\n   * tighter budgets on this path while leaving normal agent-chat callers\n   * (5+ min budget) unaffected.\n   */\n  isIntegrationCaller?: boolean;\n  /**\n   * Metadata for the currently-processing integration task. This lets tools\n   * that start long-running remote work persist a continuation that can update\n   * the originating platform thread after the current function budget ends.\n   */\n  integration?: {\n    taskId: string;\n    attempts?: number;\n    incoming: import(\"../integrations/types.js\").IncomingMessage;\n    placeholderRef?: string;\n  };\n  /**\n   * Mutable per-request agent-run state. Populated by the agent-chat plugin\n   * during a run; tool closures dereference it on each invocation.\n   */\n  run?: RequestRunContext;\n}\n\nconst GLOBAL_KEY = \"__agentNativeRequestContextAls\" as const;\nconst OBSERVERS_KEY = \"__agentNativeRequestContextObservers\" as const;\ntype RequestContextObserver = (ctx: RequestContext) => void;\ntype GlobalWithRequestContext = typeof globalThis & {\n  [GLOBAL_KEY]?: AsyncLocalStorageLike<RequestContext>;\n  [OBSERVERS_KEY]?: RequestContextObserver[];\n};\nconst globalRef = globalThis as GlobalWithRequestContext;\nif (!globalRef[GLOBAL_KEY]) {\n  globalRef[GLOBAL_KEY] = AsyncLocalStorageCtor\n    ? new AsyncLocalStorageCtor<RequestContext>()\n    : new StackAsyncLocalStorage<RequestContext>();\n}\nif (!globalRef[OBSERVERS_KEY]) {\n  globalRef[OBSERVERS_KEY] = [];\n}\nconst als = globalRef[GLOBAL_KEY]!;\nconst observers = globalRef[OBSERVERS_KEY]!;\n\n/**\n * Register a callback fired every time `runWithRequestContext` enters a new\n * scope. The hook runs INSIDE the AsyncLocalStorage scope, so observability\n * helpers that read the current isolation scope (e.g. Sentry) attach to the\n * right per-request context.\n *\n * Returned function unregisters the observer. Observers must never throw —\n * any error is swallowed so a misbehaving observer can't break the request\n * path.\n */\nexport function addRequestContextObserver(\n  observer: RequestContextObserver,\n): () => void {\n  observers.push(observer);\n  return () => {\n    const i = observers.indexOf(observer);\n    if (i !== -1) observers.splice(i, 1);\n  };\n}\n\n/**\n * Run a callback within a per-request context. The context is available to all\n * async operations spawned from `fn` via `getRequestUserEmail()` / `getRequestOrgId()`.\n *\n * Any registered `addRequestContextObserver` callbacks fire inside the new\n * scope before `fn` runs, so observability code can pin user/org info onto\n * isolation-scoped backends (Sentry, OpenTelemetry, etc.).\n */\nexport function runWithRequestContext<T>(\n  ctx: RequestContext,\n  fn: () => T | Promise<T>,\n): T | Promise<T> {\n  return als.run(ctx, () => {\n    if (observers.length > 0) {\n      for (const obs of observers) {\n        try {\n          obs(ctx);\n        } catch {\n          // Observers must never break the request path.\n        }\n      }\n    }\n    return fn();\n  });\n}\n\n/**\n * Return the active request context, if this call chain is running under one.\n *\n * This is intentionally distinct from `getRequestUserEmail()`: callers that\n * have an active context with no authenticated user must not fall through to\n * process-wide CLI fallbacks such as `AGENT_USER_EMAIL` or \"latest session\".\n */\nexport function getRequestContext(): RequestContext | undefined {\n  const store = als.getStore();\n  markAuthContextAccess(store);\n  return store;\n}\n\n/**\n * True when AsyncLocalStorage has an active context for this call chain.\n * Useful for helpers that support both HTTP requests and standalone CLI runs.\n */\nexport function hasRequestContext(): boolean {\n  return als.getStore() !== undefined;\n}\n\n/**\n * Get the current request's user email.\n *\n * - If a request context exists (HTTP/A2A path), returns its `userEmail` —\n *   even when that value is `undefined`. The env fallback MUST NOT fire here:\n *   a stale process-wide `AGENT_USER_EMAIL` from a CLI run or previous bug\n *   would leak into an unauthenticated A2A/API call (e.g. unsigned or API-key\n *   modes where `runWithRequestContext({ userEmail: undefined })` is used).\n * - Only when there is NO request context (CLI scripts) do we fall back to\n *   `process.env.AGENT_USER_EMAIL`.\n */\nexport function getRequestUserEmail(): string | undefined {\n  const store = als.getStore();\n  if (store !== undefined) {\n    if (store.userEmail) markAuthContextAccess(store);\n    return store.userEmail;\n  }\n  return processEnv(\"AGENT_USER_EMAIL\");\n}\n\n/**\n * Get the current request's display name, when the auth provider supplied one.\n *\n * The same request-context fallback rules as `getRequestUserEmail()` apply:\n * HTTP/A2A calls only read AsyncLocalStorage, while CLI scripts may opt in via\n * `AGENT_USER_NAME`.\n */\nexport function getRequestUserName(): string | undefined {\n  const store = als.getStore();\n  if (store !== undefined) {\n    if (store.userName) markAuthContextAccess(store);\n    return store.userName;\n  }\n  return processEnv(\"AGENT_USER_NAME\");\n}\n\n/**\n * Get the current request's org ID.\n *\n * Same store-aware semantics as `getRequestUserEmail()` — env fallback is\n * CLI-only, so a request that explicitly has no org doesn't inherit a stale\n * `process.env.AGENT_ORG_ID` from a prior request on the same Lambda instance.\n */\nexport function getRequestOrgId(): string | undefined {\n  const store = als.getStore();\n  if (store !== undefined) {\n    if (store.orgId) markAuthContextAccess(store);\n    return store.orgId;\n  }\n  return processEnv(\"AGENT_ORG_ID\");\n}\n\nfunction markAuthContextAccess(ctx: RequestContext | undefined) {\n  if (!ctx) return;\n  if (ctx.userEmail || ctx.userName || ctx.orgId) {\n    ctx.authContextAccessed = true;\n  }\n}\n\nexport function hasAuthContextAccess(ctx: RequestContext | undefined): boolean {\n  return Boolean(ctx?.authContextAccessed);\n}\n\n/**\n * Get the current request's IANA timezone (e.g. \"America/Los_Angeles\").\n * The UI sends this via the `x-user-timezone` header on every action call, and\n * the agent chat plugin propagates it into the request context so that\n * agent-initiated tool calls also see the user's timezone. Falls back to\n * `process.env.AGENT_USER_TIMEZONE` only for CLI scripts (no request context).\n */\nexport function getRequestTimezone(): string | undefined {\n  const store = als.getStore();\n  if (store !== undefined) return store.timezone;\n  return processEnv(\"AGENT_USER_TIMEZONE\");\n}\n\n/**\n * Returns true when this request is on an integration-platform path (Slack,\n * Telegram, etc.) — i.e. we're inside the integration plugin's processor\n * function and the platform's deliver-by deadline plus the host's function\n * timeout are the binding budget. Non-integration callers (CLI, normal\n * agent chat) should treat this as `false`.\n */\nexport function isIntegrationCallerRequest(): boolean {\n  return als.getStore()?.isIntegrationCaller === true;\n}\n\nexport function getIntegrationRequestContext():\n  | NonNullable<RequestContext[\"integration\"]>\n  | undefined {\n  return als.getStore()?.integration;\n}\n\n/**\n * Convenience: returns `{ userEmail, orgId }` from the active request context,\n * suitable for passing to `resolveCredential(key, ctx)`. Returns `null` when\n * no user is associated with the call (e.g. an unauthenticated public route).\n *\n * For framework actions auto-mounted at `/_agent-native/actions/...` this is\n * always populated because action-routes wraps every invocation in\n * `runWithRequestContext`. For hand-written `/api/*` routes the calling code\n * is responsible for setting up the context (see `runWithRequestContext`).\n */\nexport function getCredentialContext(): {\n  userEmail: string;\n  orgId: string | null;\n} | null {\n  const userEmail = getRequestUserEmail();\n  if (!userEmail) return null;\n  return { userEmail, orgId: getRequestOrgId() ?? null };\n}\n\n/**\n * Get the active request's mutable agent-run state. Returns `undefined` when\n * called outside an agent run (e.g. before `prepareRun` or in a non-agent\n * code path). Callers must tolerate the field absence; use the helper\n * `requireRequestRunContext()` if missing context is a programming error.\n */\nexport function getRequestRunContext(): RequestRunContext | undefined {\n  const store = als.getStore();\n  if (!store) return undefined;\n  return store.run;\n}\n\n/**\n * Ensure a `RequestRunContext` exists on the active request store and\n * return it. Used by the agent-chat handler to attach run state once it\n * starts processing a chat request. Returns `undefined` if there is no\n * active request store (caller should not be invoking this outside ALS).\n */\nexport function ensureRequestRunContext(): RequestRunContext | undefined {\n  const store = als.getStore();\n  if (!store) return undefined;\n  if (!store.run) store.run = {};\n  return store.run;\n}\n"]}

package/dist/styles/agent-conversation.css

@@ -684,7 +684,7 @@
   }
 }
 
-/* Tool-code viewer that uses shiki inside the ToolDetailViewer. */
+/* Tool-code viewer that uses shiki inside the Codex-style gray box. */
 .agent-tool-code .agent-markdown-shiki {
   margin: 0;
   border-radius: 0;

package/dist/templates/default/.agents/skills/self-modifying-code/SKILL.md

@@ -28,7 +28,19 @@ Not all modifications are equal. Use this to decide what level of care is needed
 | 1: Data       | Files in `data/`      | JSON state, generated content, markdown          | Nothing — these are routine       |
 | 2: Source     | App code              | Components, routes, styles, scripts              | Run `pnpm typecheck && pnpm lint` |
 | 3: Config     | Project config        | `package.json`, `tsconfig.json`, `vite.config.*` | Ask for explicit approval first   |
-| 4: Off limits | Secrets and framework | `.env`, `@agent-native/core` internals           | Never modify these                |
+| 4: Off limits | Secrets and framework | `.env`, `@agent-native/*` packages & overrides   | Never modify these                |
+
+Tier 4 includes **all** of the following — not only editing package source:
+
+- Files under `node_modules/@agent-native/*` (core, dispatch, scheduling, …)
+- `pnpm.overrides`, `overrides`, `resolutions`, or `patchedDependencies` that
+  target any `@agent-native/*` package
+- Local patches, vendored copies, or invented "dispatch/core behavior"
+  shims meant to paper over a version skew or failed upgrade
+
+When an older branch needs current packages, use **`agent-native upgrade`**
+(see the `upgrade-agent-native` skill). If upgrade or typecheck fails, fix
+**app** code or stop and ask — do not patch the framework.
 
 ## Git Checkpoint Pattern
 
@@ -74,13 +86,19 @@ inline strings in components.
 ## Don't
 
 - Don't modify `.env` files or files containing secrets
-- Don't modify `@agent-native/core` package internals
+- Don't modify `@agent-native/core`, `@agent-native/dispatch`, or other
+  `@agent-native/*` package internals (including under `node_modules`)
+- Don't add `pnpm.overrides` / `patchedDependencies` / `resolutions` for
+  `@agent-native/*` to "make the app run" after a version bump
+- Don't invent local dispatch/core behavior overrides when upgrade fails —
+  run `npx @agent-native/core@latest upgrade`, then fix app-level errors only
 - Don't modify `.agents/skills/` or `AGENTS.md` unless explicitly requested
 - Don't skip the typecheck/lint step after editing source code
 - Don't make source changes without a git checkpoint to roll back to
 
 ## Related Skills
 
+- **upgrade-agent-native** — supported path to bring an older app/workspace current
 - **storing-data** — Tier 1 modifications (data files) are the safest and most common
 - **actions** — The agent can create or modify actions to add new capabilities
 - **delegate-to-agent** — Self-modification requests come through the agent chat

package/dist/templates/default/.agents/skills/upgrade-agent-native/SKILL.md

@@ -0,0 +1,87 @@
+---
+name: upgrade-agent-native
+description: >-
+  Bring an older Agent Native app or workspace current. Use when updating
+  @agent-native/core, fixing a broken upgrade, or when tempted to patch or
+  override core/dispatch packages to make an old branch run.
+scope: dev
+metadata:
+  internal: true
+---
+
+# Upgrade Agent Native
+
+## Rule
+
+When an older Agent Native app/branch needs to run on current packages, use
+`agent-native upgrade`. Never "fix" upgrade breakage with
+`pnpm.overrides`, `patchedDependencies`, `resolutions`, local patches, or
+edits under `node_modules/@agent-native/*` — especially not against
+`@agent-native/core` or `@agent-native/dispatch`.
+
+## Why
+
+Agents often respond to a failed core bump by inventing framework patches and
+dispatch behavior overrides. That hides the real app-level break, drifts from
+upstream, and makes the next upgrade worse. The supported path is bump →
+install → refresh scaffold skills → verify, then fix **app** code only.
+
+## How
+
+1. **Doctor first (optional but recommended)**
+
+   ```bash
+   npx @agent-native/core@latest upgrade check
+   ```
+
+   This reports framework overrides/patches and pending `@agent-native/*`
+   bumps. If overrides/patches are present, remove them before continuing.
+
+2. **Run the upgrade**
+
+   ```bash
+   npx @agent-native/core@latest upgrade
+   ```
+
+   Or from an already-installed CLI: `pnpm exec agent-native upgrade` /
+   `agent-native upgrade`.
+
+   What it does:
+
+   - Blocks (unless `--force`) when `@agent-native/*` overrides/patches exist
+   - Rewrites non-local `@agent-native/*` dependency pins to `latest`
+   - Runs the package manager install
+   - Runs `skills update scaffold --project`
+   - Runs `typecheck` when the project has that script
+
+3. **If upgrade or typecheck fails**
+
+   - Read the concrete error
+   - Fix **app** source, actions, config, or env — not framework packages
+   - Re-run `agent-native upgrade` or `pnpm typecheck`
+   - Stop and ask the user if you cannot fix the app-level error
+
+4. **Dry-run / partial runs**
+
+   ```bash
+   agent-native upgrade --dry-run
+   agent-native upgrade --skip-verify
+   agent-native upgrade --skip-install   # package.json bumps only
+   ```
+
+## Don't
+
+- Don't add `pnpm.overrides`, `overrides`, `resolutions`, or
+  `patchedDependencies` for any `@agent-native/*` package
+- Don't edit `node_modules/@agent-native/core` or
+  `node_modules/@agent-native/dispatch`
+- Don't invent local "dispatch behavior" shims to paper over version skew
+- Don't keep iterating with more framework patches after a failed install
+- Don't skip `skills update scaffold --project` after a core bump (the
+  upgrade command does this for you)
+
+## Related Skills
+
+- **self-modifying-code** — Tier 4: framework packages are off limits
+- **agent-native-docs** — version-matched docs after the bump
+- **portability** — keep app code provider-agnostic across upgrades

package/dist/templates/default/AGENTS.md

@@ -38,9 +38,15 @@ Read these local package docs before implementing advanced Agent Native
 features. Prefer this app's own `AGENTS.md` and `.agents/skills/` for
 app-specific rules, then use the corpus for reusable framework/template
 patterns.
-After updating `@agent-native/core`, run `pnpm skills:update` or
-`npx @agent-native/core@latest skills update scaffold --project` from the app
-root to refresh framework-provided `.agents/skills` and repair `CLAUDE.md` /
+To bring an older app current, run `pnpm upgrade:agent-native` or
+`npx @agent-native/core@latest upgrade` from the app root. That bumps
+`@agent-native/*` deps, installs, refreshes scaffold skills, and typechecks.
+Do **not** add `pnpm.overrides` / patches against `@agent-native/*` or edit
+`node_modules/@agent-native/*` when an upgrade fails — fix app code or ask.
+See the `upgrade-agent-native` and `self-modifying-code` skills.
+After a manual core bump only, `pnpm skills:update` (or
+`npx @agent-native/core@latest skills update scaffold --project`) still
+refreshes framework-provided `.agents/skills` and repairs `CLAUDE.md` /
 `.claude/skills` compatibility links.
 
 ### Database Code
@@ -150,6 +156,7 @@ Skills in `.agents/skills/` provide detailed guidance for each architectural rul
 | `delegate-to-agent`    | Before adding LLM calls or AI delegation                                          |
 | `actions`              | Before creating or modifying actions                                              |
 | `self-modifying-code`  | Before editing source, components, or styles                                      |
+| `upgrade-agent-native` | Before updating an older app/branch or when tempted to patch `@agent-native/*`    |
 | `capture-learnings`    | Before recording user preferences or corrections                                  |
 | `frontend-design`      | Before building or restyling any UI component, page, or layout                    |
 | `shadcn-ui`            | Before adding, updating, or debugging shadcn/ui components                        |

package/dist/templates/default/package.json

@@ -9,7 +9,8 @@
     "typecheck": "agent-native typecheck",
     "action": "agent-native action",
     "script": "agent-native script",
-    "skills:update": "agent-native skills update scaffold --project"
+    "skills:update": "agent-native skills update scaffold --project",
+    "upgrade:agent-native": "agent-native upgrade"
   },
   "dependencies": {
     "@agent-native/core": "latest",

package/dist/templates/headless/.agents/skills/upgrade-agent-native/SKILL.md

@@ -0,0 +1,87 @@
+---
+name: upgrade-agent-native
+description: >-
+  Bring an older Agent Native app or workspace current. Use when updating
+  @agent-native/core, fixing a broken upgrade, or when tempted to patch or
+  override core/dispatch packages to make an old branch run.
+scope: dev
+metadata:
+  internal: true
+---
+
+# Upgrade Agent Native
+
+## Rule
+
+When an older Agent Native app/branch needs to run on current packages, use
+`agent-native upgrade`. Never "fix" upgrade breakage with
+`pnpm.overrides`, `patchedDependencies`, `resolutions`, local patches, or
+edits under `node_modules/@agent-native/*` — especially not against
+`@agent-native/core` or `@agent-native/dispatch`.
+
+## Why
+
+Agents often respond to a failed core bump by inventing framework patches and
+dispatch behavior overrides. That hides the real app-level break, drifts from
+upstream, and makes the next upgrade worse. The supported path is bump →
+install → refresh scaffold skills → verify, then fix **app** code only.
+
+## How
+
+1. **Doctor first (optional but recommended)**
+
+   ```bash
+   npx @agent-native/core@latest upgrade check
+   ```
+
+   This reports framework overrides/patches and pending `@agent-native/*`
+   bumps. If overrides/patches are present, remove them before continuing.
+
+2. **Run the upgrade**
+
+   ```bash
+   npx @agent-native/core@latest upgrade
+   ```
+
+   Or from an already-installed CLI: `pnpm exec agent-native upgrade` /
+   `agent-native upgrade`.
+
+   What it does:
+
+   - Blocks (unless `--force`) when `@agent-native/*` overrides/patches exist
+   - Rewrites non-local `@agent-native/*` dependency pins to `latest`
+   - Runs the package manager install
+   - Runs `skills update scaffold --project`
+   - Runs `typecheck` when the project has that script
+
+3. **If upgrade or typecheck fails**
+
+   - Read the concrete error
+   - Fix **app** source, actions, config, or env — not framework packages
+   - Re-run `agent-native upgrade` or `pnpm typecheck`
+   - Stop and ask the user if you cannot fix the app-level error
+
+4. **Dry-run / partial runs**
+
+   ```bash
+   agent-native upgrade --dry-run
+   agent-native upgrade --skip-verify
+   agent-native upgrade --skip-install   # package.json bumps only
+   ```
+
+## Don't
+
+- Don't add `pnpm.overrides`, `overrides`, `resolutions`, or
+  `patchedDependencies` for any `@agent-native/*` package
+- Don't edit `node_modules/@agent-native/core` or
+  `node_modules/@agent-native/dispatch`
+- Don't invent local "dispatch behavior" shims to paper over version skew
+- Don't keep iterating with more framework patches after a failed install
+- Don't skip `skills update scaffold --project` after a core bump (the
+  upgrade command does this for you)
+
+## Related Skills
+
+- **self-modifying-code** — Tier 4: framework packages are off limits
+- **agent-native-docs** — version-matched docs after the bump
+- **portability** — keep app code provider-agnostic across upgrades

package/dist/templates/headless/AGENTS.md

@@ -38,9 +38,15 @@ first-party template patterns ships in `node_modules/@agent-native/core/corpus`.
 Read these local package docs before implementing advanced Agent Native
 features. Prefer this app's own `AGENTS.md` for app-specific rules, then use
 the corpus for reusable framework/template patterns.
-After updating `@agent-native/core`, run `pnpm skills:update` or
-`npx @agent-native/core@latest skills update scaffold --project` from the app
-root to refresh framework-provided `.agents/skills` and repair `CLAUDE.md` /
+To bring an older app current, run `pnpm upgrade:agent-native` or
+`npx @agent-native/core@latest upgrade` from the app root. That bumps
+`@agent-native/*` deps, installs, refreshes scaffold skills, and typechecks.
+Do **not** add `pnpm.overrides` / patches against `@agent-native/*` or edit
+`node_modules/@agent-native/*` when an upgrade fails — fix app code or ask.
+See the `upgrade-agent-native` and `self-modifying-code` skills.
+After a manual core bump only, `pnpm skills:update` (or
+`npx @agent-native/core@latest skills update scaffold --project`) still
+refreshes framework-provided `.agents/skills` and repairs `CLAUDE.md` /
 `.claude/skills` compatibility links.
 
 ## Actions

package/dist/templates/headless/package.json

@@ -7,6 +7,7 @@
     "agent": "agent-native agent",
     "script": "agent-native script",
     "skills:update": "agent-native skills update scaffold --project",
+    "upgrade:agent-native": "agent-native upgrade",
     "typecheck": "tsc --noEmit"
   },
   "dependencies": {

package/dist/templates/workspace-core/.agents/skills/self-modifying-code/SKILL.md

@@ -28,7 +28,19 @@ Not all modifications are equal. Use this to decide what level of care is needed
 | 1: Data       | Files in `data/`      | JSON state, generated content, markdown          | Nothing — these are routine       |
 | 2: Source     | App code              | Components, routes, styles, scripts              | Run `pnpm typecheck && pnpm lint` |
 | 3: Config     | Project config        | `package.json`, `tsconfig.json`, `vite.config.*` | Ask for explicit approval first   |
-| 4: Off limits | Secrets and framework | `.env`, `@agent-native/core` internals           | Never modify these                |
+| 4: Off limits | Secrets and framework | `.env`, `@agent-native/*` packages & overrides   | Never modify these                |
+
+Tier 4 includes **all** of the following — not only editing package source:
+
+- Files under `node_modules/@agent-native/*` (core, dispatch, scheduling, …)
+- `pnpm.overrides`, `overrides`, `resolutions`, or `patchedDependencies` that
+  target any `@agent-native/*` package
+- Local patches, vendored copies, or invented "dispatch/core behavior"
+  shims meant to paper over a version skew or failed upgrade
+
+When an older branch needs current packages, use **`agent-native upgrade`**
+(see the `upgrade-agent-native` skill). If upgrade or typecheck fails, fix
+**app** code or stop and ask — do not patch the framework.
 
 ## Git Checkpoint Pattern
 
@@ -74,13 +86,19 @@ inline strings in components.
 ## Don't
 
 - Don't modify `.env` files or files containing secrets
-- Don't modify `@agent-native/core` package internals
+- Don't modify `@agent-native/core`, `@agent-native/dispatch`, or other
+  `@agent-native/*` package internals (including under `node_modules`)
+- Don't add `pnpm.overrides` / `patchedDependencies` / `resolutions` for
+  `@agent-native/*` to "make the app run" after a version bump
+- Don't invent local dispatch/core behavior overrides when upgrade fails —
+  run `npx @agent-native/core@latest upgrade`, then fix app-level errors only
 - Don't modify `.agents/skills/` or `AGENTS.md` unless explicitly requested
 - Don't skip the typecheck/lint step after editing source code
 - Don't make source changes without a git checkpoint to roll back to
 
 ## Related Skills
 
+- **upgrade-agent-native** — supported path to bring an older app/workspace current
 - **storing-data** — Tier 1 modifications (data files) are the safest and most common
 - **actions** — The agent can create or modify actions to add new capabilities
 - **delegate-to-agent** — Self-modification requests come through the agent chat

package/dist/templates/workspace-core/.agents/skills/upgrade-agent-native/SKILL.md

@@ -0,0 +1,87 @@
+---
+name: upgrade-agent-native
+description: >-
+  Bring an older Agent Native app or workspace current. Use when updating
+  @agent-native/core, fixing a broken upgrade, or when tempted to patch or
+  override core/dispatch packages to make an old branch run.
+scope: dev
+metadata:
+  internal: true
+---
+
+# Upgrade Agent Native
+
+## Rule
+
+When an older Agent Native app/branch needs to run on current packages, use
+`agent-native upgrade`. Never "fix" upgrade breakage with
+`pnpm.overrides`, `patchedDependencies`, `resolutions`, local patches, or
+edits under `node_modules/@agent-native/*` — especially not against
+`@agent-native/core` or `@agent-native/dispatch`.
+
+## Why
+
+Agents often respond to a failed core bump by inventing framework patches and
+dispatch behavior overrides. That hides the real app-level break, drifts from
+upstream, and makes the next upgrade worse. The supported path is bump →
+install → refresh scaffold skills → verify, then fix **app** code only.
+
+## How
+
+1. **Doctor first (optional but recommended)**
+
+   ```bash
+   npx @agent-native/core@latest upgrade check
+   ```
+
+   This reports framework overrides/patches and pending `@agent-native/*`
+   bumps. If overrides/patches are present, remove them before continuing.
+
+2. **Run the upgrade**
+
+   ```bash
+   npx @agent-native/core@latest upgrade
+   ```
+
+   Or from an already-installed CLI: `pnpm exec agent-native upgrade` /
+   `agent-native upgrade`.
+
+   What it does:
+
+   - Blocks (unless `--force`) when `@agent-native/*` overrides/patches exist
+   - Rewrites non-local `@agent-native/*` dependency pins to `latest`
+   - Runs the package manager install
+   - Runs `skills update scaffold --project`
+   - Runs `typecheck` when the project has that script
+
+3. **If upgrade or typecheck fails**
+
+   - Read the concrete error
+   - Fix **app** source, actions, config, or env — not framework packages
+   - Re-run `agent-native upgrade` or `pnpm typecheck`
+   - Stop and ask the user if you cannot fix the app-level error
+
+4. **Dry-run / partial runs**
+
+   ```bash
+   agent-native upgrade --dry-run
+   agent-native upgrade --skip-verify
+   agent-native upgrade --skip-install   # package.json bumps only
+   ```
+
+## Don't
+
+- Don't add `pnpm.overrides`, `overrides`, `resolutions`, or
+  `patchedDependencies` for any `@agent-native/*` package
+- Don't edit `node_modules/@agent-native/core` or
+  `node_modules/@agent-native/dispatch`
+- Don't invent local "dispatch behavior" shims to paper over version skew
+- Don't keep iterating with more framework patches after a failed install
+- Don't skip `skills update scaffold --project` after a core bump (the
+  upgrade command does this for you)
+
+## Related Skills
+
+- **self-modifying-code** — Tier 4: framework packages are off limits
+- **agent-native-docs** — version-matched docs after the bump
+- **portability** — keep app code provider-agnostic across upgrades

package/dist/templates/workspace-root/AGENTS.md

@@ -27,10 +27,16 @@ first-party template patterns ships in `node_modules/@agent-native/core/corpus`.
 Use package docs for framework APIs, the package corpus for reusable
 framework/template patterns, and `packages/shared/AGENTS.md` plus
 `packages/shared/.agents/skills/` for workspace-specific conventions.
-After updating `@agent-native/core`, run `pnpm skills:update` or
-`npx @agent-native/core@latest skills update scaffold --project` from the
-workspace root to refresh framework-provided shared skills and repair
-`CLAUDE.md` / `.claude/skills` compatibility links.
+To bring an older workspace current, run `pnpm upgrade:agent-native` or
+`npx @agent-native/core@latest upgrade` from the workspace root. That bumps
+`@agent-native/*` deps, installs, refreshes scaffold skills, and typechecks.
+Do **not** add `pnpm.overrides` / patches against `@agent-native/*` or edit
+`node_modules/@agent-native/*` when an upgrade fails — fix app code or ask.
+See the `upgrade-agent-native` and `self-modifying-code` skills.
+After a manual core bump only, `pnpm skills:update` (or
+`npx @agent-native/core@latest skills update scaffold --project`) still
+refreshes framework-provided shared skills and repairs `CLAUDE.md` /
+`.claude/skills` compatibility links.
 
 ## Core Agent Rule
 

package/dist/templates/workspace-root/package.json

@@ -8,6 +8,7 @@
     "typecheck": "pnpm -r typecheck",
     "repair:workspace-org": "tsx scripts/repair-workspace-org.ts",
     "skills:update": "agent-native skills update scaffold --project",
+    "upgrade:agent-native": "agent-native upgrade",
     "fmt:check": "oxfmt --check .",
     "lint": "pnpm fmt:check"
   },

package/docs/content/faq.mdx

@@ -227,6 +227,23 @@ SSE gives same-process writes an immediate path to the browser, and a lightweigh
 
 AI is non-deterministic, so you need conversation flow to give feedback and iterate — not one-shot buttons — and the agent already has your codebase, instructions, skills, and history that an inline call lacks. Routing everything through the agent is also what lets the app be driven from Slack, Telegram, or another agent. See [Key Concepts — Agent chat bridge](/docs/key-concepts#agent-chat-bridge).
 
+### How do I upgrade an older Agent Native app? {#upgrade-older-app}
+
+Run the supported upgrade path from the app or workspace root:
+
+```bash
+npx @agent-native/core@latest upgrade
+```
+
+That bumps `@agent-native/*` dependencies to `latest`, installs, refreshes
+scaffold skills (`skills update scaffold --project`), and runs typecheck when
+available. Use `upgrade check` first if you want a doctor-only report of
+framework overrides/patches and pending bumps.
+
+Do **not** fix a broken upgrade with `pnpm.overrides`, `patchedDependencies`,
+or edits under `node_modules/@agent-native/*` (especially core/dispatch). If
+upgrade or typecheck fails, fix app-level code or ask — then re-run upgrade.
+
 ### Why is this a framework and not a library? {#why-framework-not-library}
 
 The shared database, live sync, actions system, and application state only work because they're wired together from the ground up — the UI reacts to agent changes instantly, agents communicate, and the agent understands what the user is looking at. A library gives you pieces; this is an architecture. See [Key Concepts](/docs/key-concepts).