@agent-native/core 0.86.1 → 0.87.0

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 */\nimport { AsyncLocalStorage } from \"node:async_hooks\";\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]?: AsyncLocalStorage<RequestContext>;\n  [OBSERVERS_KEY]?: RequestContextObserver[];\n};\nconst globalRef = globalThis as GlobalWithRequestContext;\nif (!globalRef[GLOBAL_KEY]) {\n  globalRef[GLOBAL_KEY] = new AsyncLocalStorage<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 process.env.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 process.env.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 process.env.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 process.env.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}\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/server/transcribe-voice.d.ts

@@ -20,7 +20,7 @@ export declare function createTranscribeVoiceHandler(): import("h3").EventHandle
     error: string;
     text?: undefined;
 } | {
-    error?: undefined;
     text: string;
+    error?: undefined;
 }>>;
 //# sourceMappingURL=transcribe-voice.d.ts.map

package/dist/shared/agent-access.d.ts

@@ -0,0 +1,29 @@
+export declare const AGENT_ACCESS_PARAM = "agent_access";
+export declare const DEFAULT_AGENT_ACCESS_TTL_SECONDS: number;
+export interface AgentAccessResourceScope {
+    resourceKind: string;
+    resourceId: string;
+}
+export interface AgentAccessUrlOptions {
+    origin?: string;
+    basePath?: string;
+    tokenParam?: string;
+}
+export interface AgentAccessApiUrlOptions extends AgentAccessUrlOptions {
+    endpoint: string;
+    resourceId: string;
+    idParam?: string;
+    token?: string | null;
+    extraParams?: Array<[string, string | number | boolean | null | undefined]>;
+}
+export declare function scopedAgentAccessResourceId(resourceKind: string, resourceId: string): string;
+export declare function normalizeAgentAccessBasePath(basePath?: string): string;
+export declare function normalizeAgentAccessOrigin(origin?: string): string;
+export declare function toAgentAccessUrl(pathOrUrl: string, options?: Pick<AgentAccessUrlOptions, "origin" | "basePath">): string;
+export declare function appendAgentAccessParam(urlOrPath: string, token: string, param?: string): string;
+export declare function buildAgentAccessUrl({ path, token, origin, basePath, tokenParam, }: AgentAccessUrlOptions & {
+    path: string;
+    token: string;
+}): string;
+export declare function buildAgentAccessApiUrl({ endpoint, resourceId, idParam, token, tokenParam, extraParams, origin, basePath, }: AgentAccessApiUrlOptions): string;
+//# sourceMappingURL=agent-access.d.ts.map

package/dist/shared/agent-access.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent-access.d.ts","sourceRoot":"","sources":["../../src/shared/agent-access.ts"],"names":[],"mappings":"AAAA,eAAO,MAAM,kBAAkB,iBAAiB,CAAC;AACjD,eAAO,MAAM,gCAAgC,QAAc,CAAC;AAE5D,MAAM,WAAW,wBAAwB;IACvC,YAAY,EAAE,MAAM,CAAC;IACrB,UAAU,EAAE,MAAM,CAAC;CACpB;AAED,MAAM,WAAW,qBAAqB;IACpC,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED,MAAM,WAAW,wBAAyB,SAAQ,qBAAqB;IACrE,QAAQ,EAAE,MAAM,CAAC;IACjB,UAAU,EAAE,MAAM,CAAC;IACnB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,KAAK,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACtB,WAAW,CAAC,EAAE,KAAK,CAAC,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,GAAG,OAAO,GAAG,IAAI,GAAG,SAAS,CAAC,CAAC,CAAC;CAC7E;AAQD,wBAAgB,2BAA2B,CACzC,YAAY,EAAE,MAAM,EACpB,UAAU,EAAE,MAAM,GACjB,MAAM,CAER;AAMD,wBAAgB,4BAA4B,CAAC,QAAQ,CAAC,EAAE,MAAM,GAAG,MAAM,CAGtE;AAED,wBAAgB,0BAA0B,CAAC,MAAM,CAAC,EAAE,MAAM,GAAG,MAAM,CAGlE;AAMD,wBAAgB,gBAAgB,CAC9B,SAAS,EAAE,MAAM,EACjB,OAAO,GAAE,IAAI,CAAC,qBAAqB,EAAE,QAAQ,GAAG,UAAU,CAAM,GAC/D,MAAM,CAIR;AAED,wBAAgB,sBAAsB,CACpC,SAAS,EAAE,MAAM,EACjB,KAAK,EAAE,MAAM,EACb,KAAK,SAAqB,GACzB,MAAM,CAMR;AAED,wBAAgB,mBAAmB,CAAC,EAClC,IAAI,EACJ,KAAK,EACL,MAAM,EACN,QAAQ,EACR,UAA+B,GAChC,EAAE,qBAAqB,GAAG;IACzB,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,MAAM,CAAC;CACf,GAAG,MAAM,CAMT;AAED,wBAAgB,sBAAsB,CAAC,EACrC,QAAQ,EACR,UAAU,EACV,OAAc,EACd,KAAK,EACL,UAA+B,EAC/B,WAAW,EACX,MAAM,EACN,QAAQ,GACT,EAAE,wBAAwB,GAAG,MAAM,CAWnC"}

package/dist/shared/agent-access.js

@@ -0,0 +1,57 @@
+export const AGENT_ACCESS_PARAM = "agent_access";
+export const DEFAULT_AGENT_ACCESS_TTL_SECONDS = 2 * 60 * 60;
+function normalizeResourcePart(value, label) {
+    const trimmed = value.trim();
+    if (!trimmed)
+        throw new Error(`${label} is required`);
+    return trimmed;
+}
+export function scopedAgentAccessResourceId(resourceKind, resourceId) {
+    return `${normalizeResourcePart(resourceKind, "resourceKind")}:${normalizeResourcePart(resourceId, "resourceId")}`;
+}
+function trimSlashes(value) {
+    return value.replace(/^\/+|\/+$/g, "");
+}
+export function normalizeAgentAccessBasePath(basePath) {
+    const trimmed = trimSlashes(basePath ?? "");
+    return trimmed ? `/${trimmed}` : "";
+}
+export function normalizeAgentAccessOrigin(origin) {
+    if (!origin)
+        return "";
+    return origin.replace(/\/+$/g, "");
+}
+function isAbsoluteUrl(value) {
+    return /^[a-z][a-z0-9+.-]*:\/\//i.test(value);
+}
+export function toAgentAccessUrl(pathOrUrl, options = {}) {
+    if (isAbsoluteUrl(pathOrUrl))
+        return pathOrUrl;
+    const path = pathOrUrl.startsWith("/") ? pathOrUrl : `/${pathOrUrl}`;
+    return `${normalizeAgentAccessOrigin(options.origin)}${normalizeAgentAccessBasePath(options.basePath)}${path}`;
+}
+export function appendAgentAccessParam(urlOrPath, token, param = AGENT_ACCESS_PARAM) {
+    const hashIndex = urlOrPath.indexOf("#");
+    const base = hashIndex >= 0 ? urlOrPath.slice(0, hashIndex) : urlOrPath;
+    const hash = hashIndex >= 0 ? urlOrPath.slice(hashIndex) : "";
+    const sep = base.includes("?") ? "&" : "?";
+    return `${base}${sep}${encodeURIComponent(param)}=${encodeURIComponent(token)}${hash}`;
+}
+export function buildAgentAccessUrl({ path, token, origin, basePath, tokenParam = AGENT_ACCESS_PARAM, }) {
+    return appendAgentAccessParam(toAgentAccessUrl(path, { origin, basePath }), token, tokenParam);
+}
+export function buildAgentAccessApiUrl({ endpoint, resourceId, idParam = "id", token, tokenParam = AGENT_ACCESS_PARAM, extraParams, origin, basePath, }) {
+    const params = new URLSearchParams({ [idParam]: resourceId });
+    if (token)
+        params.set(tokenParam, token);
+    for (const [key, value] of extraParams ?? []) {
+        if (value === undefined || value === null || value === "")
+            continue;
+        params.set(key, String(value));
+    }
+    return toAgentAccessUrl(`${endpoint}?${params.toString()}`, {
+        origin,
+        basePath,
+    });
+}
+//# sourceMappingURL=agent-access.js.map

package/dist/shared/agent-access.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent-access.js","sourceRoot":"","sources":["../../src/shared/agent-access.ts"],"names":[],"mappings":"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","sourcesContent":["export const AGENT_ACCESS_PARAM = \"agent_access\";\nexport const DEFAULT_AGENT_ACCESS_TTL_SECONDS = 2 * 60 * 60;\n\nexport interface AgentAccessResourceScope {\n  resourceKind: string;\n  resourceId: string;\n}\n\nexport interface AgentAccessUrlOptions {\n  origin?: string;\n  basePath?: string;\n  tokenParam?: string;\n}\n\nexport interface AgentAccessApiUrlOptions extends AgentAccessUrlOptions {\n  endpoint: string;\n  resourceId: string;\n  idParam?: string;\n  token?: string | null;\n  extraParams?: Array<[string, string | number | boolean | null | undefined]>;\n}\n\nfunction normalizeResourcePart(value: string, label: string): string {\n  const trimmed = value.trim();\n  if (!trimmed) throw new Error(`${label} is required`);\n  return trimmed;\n}\n\nexport function scopedAgentAccessResourceId(\n  resourceKind: string,\n  resourceId: string,\n): string {\n  return `${normalizeResourcePart(resourceKind, \"resourceKind\")}:${normalizeResourcePart(resourceId, \"resourceId\")}`;\n}\n\nfunction trimSlashes(value: string): string {\n  return value.replace(/^\\/+|\\/+$/g, \"\");\n}\n\nexport function normalizeAgentAccessBasePath(basePath?: string): string {\n  const trimmed = trimSlashes(basePath ?? \"\");\n  return trimmed ? `/${trimmed}` : \"\";\n}\n\nexport function normalizeAgentAccessOrigin(origin?: string): string {\n  if (!origin) return \"\";\n  return origin.replace(/\\/+$/g, \"\");\n}\n\nfunction isAbsoluteUrl(value: string): boolean {\n  return /^[a-z][a-z0-9+.-]*:\\/\\//i.test(value);\n}\n\nexport function toAgentAccessUrl(\n  pathOrUrl: string,\n  options: Pick<AgentAccessUrlOptions, \"origin\" | \"basePath\"> = {},\n): string {\n  if (isAbsoluteUrl(pathOrUrl)) return pathOrUrl;\n  const path = pathOrUrl.startsWith(\"/\") ? pathOrUrl : `/${pathOrUrl}`;\n  return `${normalizeAgentAccessOrigin(options.origin)}${normalizeAgentAccessBasePath(options.basePath)}${path}`;\n}\n\nexport function appendAgentAccessParam(\n  urlOrPath: string,\n  token: string,\n  param = AGENT_ACCESS_PARAM,\n): string {\n  const hashIndex = urlOrPath.indexOf(\"#\");\n  const base = hashIndex >= 0 ? urlOrPath.slice(0, hashIndex) : urlOrPath;\n  const hash = hashIndex >= 0 ? urlOrPath.slice(hashIndex) : \"\";\n  const sep = base.includes(\"?\") ? \"&\" : \"?\";\n  return `${base}${sep}${encodeURIComponent(param)}=${encodeURIComponent(token)}${hash}`;\n}\n\nexport function buildAgentAccessUrl({\n  path,\n  token,\n  origin,\n  basePath,\n  tokenParam = AGENT_ACCESS_PARAM,\n}: AgentAccessUrlOptions & {\n  path: string;\n  token: string;\n}): string {\n  return appendAgentAccessParam(\n    toAgentAccessUrl(path, { origin, basePath }),\n    token,\n    tokenParam,\n  );\n}\n\nexport function buildAgentAccessApiUrl({\n  endpoint,\n  resourceId,\n  idParam = \"id\",\n  token,\n  tokenParam = AGENT_ACCESS_PARAM,\n  extraParams,\n  origin,\n  basePath,\n}: AgentAccessApiUrlOptions): string {\n  const params = new URLSearchParams({ [idParam]: resourceId });\n  if (token) params.set(tokenParam, token);\n  for (const [key, value] of extraParams ?? []) {\n    if (value === undefined || value === null || value === \"\") continue;\n    params.set(key, String(value));\n  }\n  return toAgentAccessUrl(`${endpoint}?${params.toString()}`, {\n    origin,\n    basePath,\n  });\n}\n"]}

package/dist/shared/index.d.ts

@@ -8,4 +8,5 @@ export { DEFAULT_WORKSPACE_APP_AUDIENCE, WORKSPACE_APP_AUDIENCES, normalizeWorks
 export { AGENT_NATIVE_OPEN_PATH, AGENT_SIDEBAR_QUERY_PARAM, AGENT_SIDEBAR_QUERY_VALUE_CLOSED, isAgentNativeOpenDeepLink, withCollapsedAgentSidebarParam, } from "./agent-sidebar-url.js";
 export { AGENT_NATIVE_DEFAULT_SOCIAL_IMAGE, AGENT_NATIVE_SOCIAL_IMAGE_CACHE_BUSTER, AGENT_NATIVE_SOCIAL_IMAGE_ALT, AGENT_NATIVE_SOCIAL_IMAGE_HEIGHT, AGENT_NATIVE_SOCIAL_IMAGE_PATH, AGENT_NATIVE_SOCIAL_IMAGE_TYPE, AGENT_NATIVE_SOCIAL_IMAGE_WIDTH, defaultSocialImageMeta, withAgentNativeSocialImageCacheBuster, withDefaultSocialImage, type SocialMetaDescriptor, } from "./social-meta.js";
 export { EMBED_MODE_QUERY_PARAM, EMBED_SESSION_COOKIE, EMBED_START_PATH, EMBED_TOKEN_QUERY_PARAM, } from "./embed-auth.js";
+export { AGENT_ACCESS_PARAM, DEFAULT_AGENT_ACCESS_TTL_SECONDS, appendAgentAccessParam, buildAgentAccessApiUrl, buildAgentAccessUrl, normalizeAgentAccessBasePath, normalizeAgentAccessOrigin, scopedAgentAccessResourceId, toAgentAccessUrl, type AgentAccessApiUrlOptions, type AgentAccessResourceScope, type AgentAccessUrlOptions, } from "./agent-access.js";
 //# sourceMappingURL=index.d.ts.map

package/dist/shared/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/shared/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,SAAS,EACT,KAAK,gBAAgB,EACrB,KAAK,oBAAoB,EACzB,KAAK,iBAAiB,GACvB,MAAM,iBAAiB,CAAC;AACzB,OAAO,EAAE,QAAQ,EAAE,KAAK,MAAM,EAAE,MAAM,gBAAgB,CAAC;AACvD,OAAO,EAAE,sBAAsB,EAAE,MAAM,kBAAkB,CAAC;AAC1D,OAAO,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAC;AACzC,OAAO,EACL,+BAA+B,EAC/B,sBAAsB,EACtB,KAAK,mBAAmB,GACzB,MAAM,qBAAqB,CAAC;AAC7B,OAAO,EACL,iCAAiC,EACjC,0BAA0B,EAC1B,yBAAyB,EACzB,gCAAgC,EAChC,2BAA2B,GAC5B,MAAM,uBAAuB,CAAC;AAC/B,OAAO,EACL,8BAA8B,EAC9B,uBAAuB,EACvB,6BAA6B,EAC7B,6BAA6B,EAC7B,2BAA2B,EAC3B,mCAAmC,EACnC,8BAA8B,EAC9B,sCAAsC,EACtC,KAAK,uBAAuB,EAC5B,KAAK,iCAAiC,EACtC,KAAK,oBAAoB,GAC1B,MAAM,6BAA6B,CAAC;AACrC,OAAO,EACL,sBAAsB,EACtB,yBAAyB,EACzB,gCAAgC,EAChC,yBAAyB,EACzB,8BAA8B,GAC/B,MAAM,wBAAwB,CAAC;AAChC,OAAO,EACL,iCAAiC,EACjC,sCAAsC,EACtC,6BAA6B,EAC7B,gCAAgC,EAChC,8BAA8B,EAC9B,8BAA8B,EAC9B,+BAA+B,EAC/B,sBAAsB,EACtB,qCAAqC,EACrC,sBAAsB,EACtB,KAAK,oBAAoB,GAC1B,MAAM,kBAAkB,CAAC;AAC1B,OAAO,EACL,sBAAsB,EACtB,oBAAoB,EACpB,gBAAgB,EAChB,uBAAuB,GACxB,MAAM,iBAAiB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/shared/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,SAAS,EACT,KAAK,gBAAgB,EACrB,KAAK,oBAAoB,EACzB,KAAK,iBAAiB,GACvB,MAAM,iBAAiB,CAAC;AACzB,OAAO,EAAE,QAAQ,EAAE,KAAK,MAAM,EAAE,MAAM,gBAAgB,CAAC;AACvD,OAAO,EAAE,sBAAsB,EAAE,MAAM,kBAAkB,CAAC;AAC1D,OAAO,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAC;AACzC,OAAO,EACL,+BAA+B,EAC/B,sBAAsB,EACtB,KAAK,mBAAmB,GACzB,MAAM,qBAAqB,CAAC;AAC7B,OAAO,EACL,iCAAiC,EACjC,0BAA0B,EAC1B,yBAAyB,EACzB,gCAAgC,EAChC,2BAA2B,GAC5B,MAAM,uBAAuB,CAAC;AAC/B,OAAO,EACL,8BAA8B,EAC9B,uBAAuB,EACvB,6BAA6B,EAC7B,6BAA6B,EAC7B,2BAA2B,EAC3B,mCAAmC,EACnC,8BAA8B,EAC9B,sCAAsC,EACtC,KAAK,uBAAuB,EAC5B,KAAK,iCAAiC,EACtC,KAAK,oBAAoB,GAC1B,MAAM,6BAA6B,CAAC;AACrC,OAAO,EACL,sBAAsB,EACtB,yBAAyB,EACzB,gCAAgC,EAChC,yBAAyB,EACzB,8BAA8B,GAC/B,MAAM,wBAAwB,CAAC;AAChC,OAAO,EACL,iCAAiC,EACjC,sCAAsC,EACtC,6BAA6B,EAC7B,gCAAgC,EAChC,8BAA8B,EAC9B,8BAA8B,EAC9B,+BAA+B,EAC/B,sBAAsB,EACtB,qCAAqC,EACrC,sBAAsB,EACtB,KAAK,oBAAoB,GAC1B,MAAM,kBAAkB,CAAC;AAC1B,OAAO,EACL,sBAAsB,EACtB,oBAAoB,EACpB,gBAAgB,EAChB,uBAAuB,GACxB,MAAM,iBAAiB,CAAC;AACzB,OAAO,EACL,kBAAkB,EAClB,gCAAgC,EAChC,sBAAsB,EACtB,sBAAsB,EACtB,mBAAmB,EACnB,4BAA4B,EAC5B,0BAA0B,EAC1B,2BAA2B,EAC3B,gBAAgB,EAChB,KAAK,wBAAwB,EAC7B,KAAK,wBAAwB,EAC7B,KAAK,qBAAqB,GAC3B,MAAM,mBAAmB,CAAC"}

package/dist/shared/index.js

@@ -8,4 +8,5 @@ export { DEFAULT_WORKSPACE_APP_AUDIENCE, WORKSPACE_APP_AUDIENCES, normalizeWorks
 export { AGENT_NATIVE_OPEN_PATH, AGENT_SIDEBAR_QUERY_PARAM, AGENT_SIDEBAR_QUERY_VALUE_CLOSED, isAgentNativeOpenDeepLink, withCollapsedAgentSidebarParam, } from "./agent-sidebar-url.js";
 export { AGENT_NATIVE_DEFAULT_SOCIAL_IMAGE, AGENT_NATIVE_SOCIAL_IMAGE_CACHE_BUSTER, AGENT_NATIVE_SOCIAL_IMAGE_ALT, AGENT_NATIVE_SOCIAL_IMAGE_HEIGHT, AGENT_NATIVE_SOCIAL_IMAGE_PATH, AGENT_NATIVE_SOCIAL_IMAGE_TYPE, AGENT_NATIVE_SOCIAL_IMAGE_WIDTH, defaultSocialImageMeta, withAgentNativeSocialImageCacheBuster, withDefaultSocialImage, } from "./social-meta.js";
 export { EMBED_MODE_QUERY_PARAM, EMBED_SESSION_COOKIE, EMBED_START_PATH, EMBED_TOKEN_QUERY_PARAM, } from "./embed-auth.js";
+export { AGENT_ACCESS_PARAM, DEFAULT_AGENT_ACCESS_TTL_SECONDS, appendAgentAccessParam, buildAgentAccessApiUrl, buildAgentAccessUrl, normalizeAgentAccessBasePath, normalizeAgentAccessOrigin, scopedAgentAccessResourceId, toAgentAccessUrl, } from "./agent-access.js";
 //# sourceMappingURL=index.js.map

package/dist/shared/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/shared/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,SAAS,GAIV,MAAM,iBAAiB,CAAC;AACzB,OAAO,EAAE,QAAQ,EAAe,MAAM,gBAAgB,CAAC;AACvD,OAAO,EAAE,sBAAsB,EAAE,MAAM,kBAAkB,CAAC;AAC1D,OAAO,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAC;AACzC,OAAO,EACL,+BAA+B,EAC/B,sBAAsB,GAEvB,MAAM,qBAAqB,CAAC;AAC7B,OAAO,EACL,iCAAiC,EACjC,0BAA0B,EAC1B,yBAAyB,EACzB,gCAAgC,EAChC,2BAA2B,GAC5B,MAAM,uBAAuB,CAAC;AAC/B,OAAO,EACL,8BAA8B,EAC9B,uBAAuB,EACvB,6BAA6B,EAC7B,6BAA6B,EAC7B,2BAA2B,EAC3B,mCAAmC,EACnC,8BAA8B,EAC9B,sCAAsC,GAIvC,MAAM,6BAA6B,CAAC;AACrC,OAAO,EACL,sBAAsB,EACtB,yBAAyB,EACzB,gCAAgC,EAChC,yBAAyB,EACzB,8BAA8B,GAC/B,MAAM,wBAAwB,CAAC;AAChC,OAAO,EACL,iCAAiC,EACjC,sCAAsC,EACtC,6BAA6B,EAC7B,gCAAgC,EAChC,8BAA8B,EAC9B,8BAA8B,EAC9B,+BAA+B,EAC/B,sBAAsB,EACtB,qCAAqC,EACrC,sBAAsB,GAEvB,MAAM,kBAAkB,CAAC;AAC1B,OAAO,EACL,sBAAsB,EACtB,oBAAoB,EACpB,gBAAgB,EAChB,uBAAuB,GACxB,MAAM,iBAAiB,CAAC","sourcesContent":["export {\n  agentChat,\n  type AgentChatMessage,\n  type AgentChatCallOptions,\n  type AgentChatResponse,\n} from \"./agent-chat.js\";\nexport { agentEnv, type EnvVar } from \"./agent-env.js\";\nexport { extractOAuthStateAppId } from \"./oauth-state.js\";\nexport { truncate } from \"./truncate.js\";\nexport {\n  llmConnectionTrackingProperties,\n  normalizeLlmConnection,\n  type LlmConnectionStatus,\n} from \"./llm-connection.js\";\nexport {\n  DISPATCH_WORKSPACE_ROOT_REDIRECTS,\n  RESERVED_WORKSPACE_APP_IDS,\n  assertValidWorkspaceAppId,\n  getWorkspaceAppIdValidationError,\n  isValidWorkspaceAppIdFormat,\n} from \"./workspace-app-id.js\";\nexport {\n  DEFAULT_WORKSPACE_APP_AUDIENCE,\n  WORKSPACE_APP_AUDIENCES,\n  normalizeWorkspaceAppAudience,\n  normalizeWorkspaceAppPathList,\n  workspaceAppAudienceFromEnv,\n  workspaceAppAudienceFromPackageJson,\n  workspaceAppRouteAccessFromEnv,\n  workspaceAppRouteAccessFromPackageJson,\n  type WorkspaceAppRouteAccess,\n  type WorkspaceAppRouteAccessFromConfig,\n  type WorkspaceAppAudience,\n} from \"./workspace-app-audience.js\";\nexport {\n  AGENT_NATIVE_OPEN_PATH,\n  AGENT_SIDEBAR_QUERY_PARAM,\n  AGENT_SIDEBAR_QUERY_VALUE_CLOSED,\n  isAgentNativeOpenDeepLink,\n  withCollapsedAgentSidebarParam,\n} from \"./agent-sidebar-url.js\";\nexport {\n  AGENT_NATIVE_DEFAULT_SOCIAL_IMAGE,\n  AGENT_NATIVE_SOCIAL_IMAGE_CACHE_BUSTER,\n  AGENT_NATIVE_SOCIAL_IMAGE_ALT,\n  AGENT_NATIVE_SOCIAL_IMAGE_HEIGHT,\n  AGENT_NATIVE_SOCIAL_IMAGE_PATH,\n  AGENT_NATIVE_SOCIAL_IMAGE_TYPE,\n  AGENT_NATIVE_SOCIAL_IMAGE_WIDTH,\n  defaultSocialImageMeta,\n  withAgentNativeSocialImageCacheBuster,\n  withDefaultSocialImage,\n  type SocialMetaDescriptor,\n} from \"./social-meta.js\";\nexport {\n  EMBED_MODE_QUERY_PARAM,\n  EMBED_SESSION_COOKIE,\n  EMBED_START_PATH,\n  EMBED_TOKEN_QUERY_PARAM,\n} from \"./embed-auth.js\";\n"]}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/shared/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,SAAS,GAIV,MAAM,iBAAiB,CAAC;AACzB,OAAO,EAAE,QAAQ,EAAe,MAAM,gBAAgB,CAAC;AACvD,OAAO,EAAE,sBAAsB,EAAE,MAAM,kBAAkB,CAAC;AAC1D,OAAO,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAC;AACzC,OAAO,EACL,+BAA+B,EAC/B,sBAAsB,GAEvB,MAAM,qBAAqB,CAAC;AAC7B,OAAO,EACL,iCAAiC,EACjC,0BAA0B,EAC1B,yBAAyB,EACzB,gCAAgC,EAChC,2BAA2B,GAC5B,MAAM,uBAAuB,CAAC;AAC/B,OAAO,EACL,8BAA8B,EAC9B,uBAAuB,EACvB,6BAA6B,EAC7B,6BAA6B,EAC7B,2BAA2B,EAC3B,mCAAmC,EACnC,8BAA8B,EAC9B,sCAAsC,GAIvC,MAAM,6BAA6B,CAAC;AACrC,OAAO,EACL,sBAAsB,EACtB,yBAAyB,EACzB,gCAAgC,EAChC,yBAAyB,EACzB,8BAA8B,GAC/B,MAAM,wBAAwB,CAAC;AAChC,OAAO,EACL,iCAAiC,EACjC,sCAAsC,EACtC,6BAA6B,EAC7B,gCAAgC,EAChC,8BAA8B,EAC9B,8BAA8B,EAC9B,+BAA+B,EAC/B,sBAAsB,EACtB,qCAAqC,EACrC,sBAAsB,GAEvB,MAAM,kBAAkB,CAAC;AAC1B,OAAO,EACL,sBAAsB,EACtB,oBAAoB,EACpB,gBAAgB,EAChB,uBAAuB,GACxB,MAAM,iBAAiB,CAAC;AACzB,OAAO,EACL,kBAAkB,EAClB,gCAAgC,EAChC,sBAAsB,EACtB,sBAAsB,EACtB,mBAAmB,EACnB,4BAA4B,EAC5B,0BAA0B,EAC1B,2BAA2B,EAC3B,gBAAgB,GAIjB,MAAM,mBAAmB,CAAC","sourcesContent":["export {\n  agentChat,\n  type AgentChatMessage,\n  type AgentChatCallOptions,\n  type AgentChatResponse,\n} from \"./agent-chat.js\";\nexport { agentEnv, type EnvVar } from \"./agent-env.js\";\nexport { extractOAuthStateAppId } from \"./oauth-state.js\";\nexport { truncate } from \"./truncate.js\";\nexport {\n  llmConnectionTrackingProperties,\n  normalizeLlmConnection,\n  type LlmConnectionStatus,\n} from \"./llm-connection.js\";\nexport {\n  DISPATCH_WORKSPACE_ROOT_REDIRECTS,\n  RESERVED_WORKSPACE_APP_IDS,\n  assertValidWorkspaceAppId,\n  getWorkspaceAppIdValidationError,\n  isValidWorkspaceAppIdFormat,\n} from \"./workspace-app-id.js\";\nexport {\n  DEFAULT_WORKSPACE_APP_AUDIENCE,\n  WORKSPACE_APP_AUDIENCES,\n  normalizeWorkspaceAppAudience,\n  normalizeWorkspaceAppPathList,\n  workspaceAppAudienceFromEnv,\n  workspaceAppAudienceFromPackageJson,\n  workspaceAppRouteAccessFromEnv,\n  workspaceAppRouteAccessFromPackageJson,\n  type WorkspaceAppRouteAccess,\n  type WorkspaceAppRouteAccessFromConfig,\n  type WorkspaceAppAudience,\n} from \"./workspace-app-audience.js\";\nexport {\n  AGENT_NATIVE_OPEN_PATH,\n  AGENT_SIDEBAR_QUERY_PARAM,\n  AGENT_SIDEBAR_QUERY_VALUE_CLOSED,\n  isAgentNativeOpenDeepLink,\n  withCollapsedAgentSidebarParam,\n} from \"./agent-sidebar-url.js\";\nexport {\n  AGENT_NATIVE_DEFAULT_SOCIAL_IMAGE,\n  AGENT_NATIVE_SOCIAL_IMAGE_CACHE_BUSTER,\n  AGENT_NATIVE_SOCIAL_IMAGE_ALT,\n  AGENT_NATIVE_SOCIAL_IMAGE_HEIGHT,\n  AGENT_NATIVE_SOCIAL_IMAGE_PATH,\n  AGENT_NATIVE_SOCIAL_IMAGE_TYPE,\n  AGENT_NATIVE_SOCIAL_IMAGE_WIDTH,\n  defaultSocialImageMeta,\n  withAgentNativeSocialImageCacheBuster,\n  withDefaultSocialImage,\n  type SocialMetaDescriptor,\n} from \"./social-meta.js\";\nexport {\n  EMBED_MODE_QUERY_PARAM,\n  EMBED_SESSION_COOKIE,\n  EMBED_START_PATH,\n  EMBED_TOKEN_QUERY_PARAM,\n} from \"./embed-auth.js\";\nexport {\n  AGENT_ACCESS_PARAM,\n  DEFAULT_AGENT_ACCESS_TTL_SECONDS,\n  appendAgentAccessParam,\n  buildAgentAccessApiUrl,\n  buildAgentAccessUrl,\n  normalizeAgentAccessBasePath,\n  normalizeAgentAccessOrigin,\n  scopedAgentAccessResourceId,\n  toAgentAccessUrl,\n  type AgentAccessApiUrlOptions,\n  type AgentAccessResourceScope,\n  type AgentAccessUrlOptions,\n} from \"./agent-access.js\";\n"]}

package/docs/content/components.mdx

@@ -25,6 +25,19 @@ Avoid importing UI components from the bare `@agent-native/core` package. Use
 `@agent-native/core/client` or a focused `@agent-native/core/client/*` subpath
 so bundlers choose the browser-safe entry.
 
+Use `@agent-native/toolkit` for reusable app-building pieces that are not part
+of the foundational runtime contract: shadcn-style UI primitives, shared hooks,
+simple app shell helpers, and other template composition modules. Core keeps
+compatibility re-exports for migrated internals during the transition, but new
+template and app code should import toolkit modules directly:
+
+```tsx
+import { Button } from "@agent-native/toolkit/ui/button";
+import { Toaster } from "@agent-native/toolkit/ui/sonner";
+import { useToast } from "@agent-native/toolkit/hooks/use-toast";
+import { useSetHeaderActions } from "@agent-native/toolkit/app-shell";
+```
+
 <Diagram id="doc-block-u3yfqy" title="Drop down a layer, not out of the framework" summary={"Each layer keeps the same runtime — actions, thread state, and SQL-backed sync — while giving you more control over the chrome."}>
 
 ```html

package/docs/content/creating-templates.mdx

@@ -7,6 +7,13 @@ description: "How to create and publish your own agent-native app templates."
 
 Templates are complete, forkable agent-native apps that solve a real workflow. The first-party templates are built with the same framework surface you use: React routes for the UI, Drizzle SQL for data, actions for operations, workspace resources for agent behavior, and polling sync so the agent and UI stay aligned.
 
+Use `@agent-native/core` for the runtime contract: actions, server plugins,
+database helpers, app state, routing helpers, and agent chat. Use
+`@agent-native/toolkit` for reusable app-building UI and helpers such as shared
+shadcn-style primitives, toast/mobile hooks, date pickers, and simple app shell
+slots. Keep template-specific variants local when they encode product behavior
+or visual identity.
+
 A good template:
 
 - Solves one workflow end-to-end, with useful seed data or an empty-state flow.

package/docs/content/locales/ar-SA/components.mdx

@@ -25,6 +25,15 @@ import { ResourcesPanel } from "@agent-native/core/client/resources";
 `@agent-native/core/client` أو مسار فرعي `@agent-native/core/client/*` مركّز
 لذلك يختار القائمون على التجميع الإدخال الآمن للمتصفح.
 
+استخدم `@agent-native/toolkit` للقطع القابلة لإعادة الاستخدام في بناء التطبيقات التي ليست جزءا من عقد وقت التشغيل الأساسي: عناصر UI بأسلوب shadcn، hooks المشتركة، مساعدات هيكل التطبيق البسيطة، ووحدات تركيب القوالب. يحتفظ Core بإعادة تصدير توافقية أثناء الانتقال، لكن يجب أن تستورد القوالب والتطبيقات الجديدة وحدات toolkit مباشرة:
+
+```tsx
+import { Button } from "@agent-native/toolkit/ui/button";
+import { Toaster } from "@agent-native/toolkit/ui/sonner";
+import { useToast } from "@agent-native/toolkit/hooks/use-toast";
+import { useSetHeaderActions } from "@agent-native/toolkit/app-shell";
+```
+
 <Diagram id="doc-block-1vw6fvr" title={"المنسدلة طبقة، وليس خارج الإطار"} summary={"تحتفظ كل طبقة بنفس وقت التشغيل — الإجراءات، وحالة مؤشر الترابط، ومزامنة SQL-backed — بينما تمنحك مزيدًا من التحكم في Chrome."}>
 
 ```html

package/docs/content/locales/ar-SA/creating-templates.mdx

@@ -7,6 +7,8 @@ description: "كيفية إنشاء ونشر قوالب تطبيقات الوك
 
 النماذج عبارة عن تطبيقات متكاملة ومتشعبة للوكلاء الأصليين تعمل على حل سير العمل الحقيقي. تم إنشاء قوالب الطرف الأول بنفس سطح إطار العمل الذي تستخدمه: مسارات React لـ UI، وDrizzle SQL للبيانات، وactions للعمليات، وموارد مساحة العمل لسلوك الوكيل، ومزامنة الاستقصاء بحيث يظل الوكيل وUI متوازيين.
 
+استخدم `@agent-native/core` لعقد وقت التشغيل: actions، مكونات server الإضافية، مساعدات قاعدة البيانات، حالة التطبيق، مساعدات التوجيه، ودردشة الوكيل. استخدم `@agent-native/toolkit` لعناصر UI ومساعدات بناء التطبيقات القابلة لإعادة الاستخدام مثل primitives المشتركة، hooks للتنبيه والجوال، منتقيات التاريخ، وفتحات هيكل التطبيق البسيطة. أبق المتغيرات الخاصة بالقالب محلية عندما تعبّر عن سلوك المنتج أو هويته البصرية.
+
 نموذج جيد:
 
 - يعمل على حل سير عمل واحد من البداية إلى النهاية، باستخدام بيانات أولية مفيدة أو تدفق في حالة فارغة.

package/docs/content/locales/ar-SA/template-analytics.mdx

@@ -149,6 +149,12 @@ pnpm dev
 
 **Session replay agent handoff.** Session recordings stay private, but the session detail page can mint a temporary **Copy for agent** link. The two-hour `agent_access` URL lets an external agent read replay summaries, timelines, and bounded event details without exposing blob/provider URLs or making the recording public.
 
+Implementation note: use the shared core agent-access helpers
+(`createScopedAgentAccessGrant`, `verifyScopedAgentAccessToken`,
+`buildAgentAccessUrl`, and `buildAgentAccessApiUrl`) for the SSR/bot-visible
+URL contract. Keep replay chunk authorization, diagnostics payloads, and the
+session detail UI local to Analytics.
+
 ### العمل مع الوكيل
 
 يعرف الوكيل دائمًا ما تنظر إليه. يتم إدخال حالة الشاشة الحالية في كل رسالة ككتلة `<current-screen>` - فهي تحتوي على العرض النشط، ولوحة المعلومات المفتوحة أو التحليل، وأي عوامل تصفية محددة.

package/docs/content/locales/ar-SA/template-clips.mdx

@@ -133,6 +133,13 @@ API، لذا فإن النماذج التي تقبل النص أو الصور ا
 
 Temporary private agent links are also supported: the Share dialog can mint a two-hour `agent_access` URL for any recording the viewer can access. Agents use that token with the share page and JSON APIs, and the clip does not become public.
 
+Implementation note: use the shared core agent-access helpers
+(`createScopedAgentAccessGrant`, `verifyScopedAgentAccessToken`,
+`buildAgentAccessUrl`, and `buildAgentAccessApiUrl`) for the SSR/bot-visible
+URL contract. Keep Clips-specific visibility checks, transcript/frame payloads,
+and player UI local. New links use `agent_access`; routes should continue
+accepting the legacy `t` query where existing agent API URLs may already use it.
+
 تتبع نقاط النهاية نفس القواعد العامة/كلمة المرور/انتهاء الصلاحية مثل صفحة المشاركة.
 تتطلب المقاطع المحمية بكلمة مرور كلمة المرور مرة واحدة؛ تعود الاستجابات الناجحة
 روابط رمزية قصيرة العمر بحيث لا يحتاج وكلاء المراحل النهائية إلى النص العادي

package/docs/content/locales/ar-SA/tracking.mdx

@@ -241,6 +241,12 @@ VITE_AGENT_NATIVE_SESSION_REPLAY_SAMPLE_RATE=0.1
 
 عندما تحتاج إلى تسليم تسجيل خاص إلى وكيل خارجي، استخدم عنصر التحكم **نسخ للوكيل** في صفحة تفاصيل الجلسة. فهو يُنشئ رابط `agent_access` محدد النطاق بالتسجيل ومدته ساعتان، ويقوم بعرض SSR لحمولة اكتشاف صغيرة على `/sessions/:recordingId`، ولا يكشف إلا عن واجهات برمجة تطبيقات JSON الخاصة بسياق/أحداث الوكيل. لا تتغير رؤية التسجيل.
 
+Implementation note: the reusable layer is the core agent-access URL contract,
+not a replay-specific UI abstraction. Use `createScopedAgentAccessGrant`,
+`verifyScopedAgentAccessToken`, `buildAgentAccessUrl`, and
+`buildAgentAccessApiUrl` for scoped SSR and JSON API links; keep replay storage,
+diagnostics shaping, and access policy inside the Analytics template.
+
 للتطوير المحلي فقط، يمكن لـ Analytics الرجوع إلى أجزاء SQL مضمّنة محدودة السعة عندما يكون تخزين blob الخاص غير متاح. يجب أن تُهيّئ عمليات النشر في الإنتاج تخزين blob خاصًا أو مشفّرًا بدلاً من الاعتماد على Postgres لحمولات إعادة التشغيل.
 
 ## متقدم: الموفرون المخصصون والداخليون {#advanced}

package/docs/content/locales/de-DE/components.mdx

@@ -25,6 +25,15 @@ Vermeiden Sie den Import von UI-Komponenten aus dem bloßen `@agent-native/core`
 `@agent-native/core/client` oder ein fokussierter `@agent-native/core/client/*`-Unterpfad
 daher wählen Bundler den browsersicheren Eintrag.
 
+Verwenden Sie `@agent-native/toolkit` für wiederverwendbare App-Bausteine, die nicht Teil des grundlegenden Laufzeitvertrags sind: shadcn-artige UI-Primitives, gemeinsame Hooks, einfache App-Shell-Helfer und weitere Template-Kompositionsmodule. Core behält während der Umstellung Kompatibilitäts-Reexports, aber neuer Template- und App-Code sollte Toolkit-Module direkt importieren:
+
+```tsx
+import { Button } from "@agent-native/toolkit/ui/button";
+import { Toaster } from "@agent-native/toolkit/ui/sonner";
+import { useToast } from "@agent-native/toolkit/hooks/use-toast";
+import { useSetHeaderActions } from "@agent-native/toolkit/app-shell";
+```
+
 <Diagram id="doc-block-6bst90" title="Lassen Sie eine Ebene nach unten fallen, nicht aus dem Framework heraus" summary={"Jede Ebene behält die gleiche Laufzeit bei – Aktionen, Thread-Status und SQL-backed-Synchronisierung – und gibt Ihnen gleichzeitig mehr Kontrolle über Chrome."}>
 
 ```html

package/docs/content/locales/de-DE/creating-templates.mdx

@@ -7,6 +7,8 @@ description: "So erstellen und veröffentlichen Sie Ihre eigenen agentennativen
 
 Vorlagen sind vollständige, forkbare agentennative Apps, die einen echten Arbeitsablauf lösen. Die Erstanbieter-Vorlagen werden mit derselben Framework-Oberfläche erstellt, die Sie verwenden: React-Routen für UI, Drizzle SQL für Daten, actions für Vorgänge, Arbeitsbereichsressourcen für Agentenverhalten und Abfragesynchronisierung, damit der Agent und UI aufeinander abgestimmt bleiben.
 
+Verwenden Sie `@agent-native/core` für den Laufzeitvertrag: Actions, Server-Plugins, Datenbank-Helfer, App-State, Routing-Helfer und Agent-Chat. Verwenden Sie `@agent-native/toolkit` für wiederverwendbare App-Building-UI und Helfer wie gemeinsame Primitives, Toast- und Mobile-Hooks, Date-Picker und einfache App-Shell-Slots. Halten Sie template-spezifische Varianten lokal, wenn sie Produktverhalten oder visuelle Identität kodieren.
+
 Eine gute Vorlage:
 
 - Löst einen Workflow durchgängig, mit nützlichen Seed-Daten oder einem Leerzustandsfluss.

package/docs/content/locales/de-DE/template-analytics.mdx

@@ -149,6 +149,12 @@ CLI gibt den lokalen Entwickler URL aus. Melden Sie sich bei Google an und öffn
 
 **Session replay agent handoff.** Session recordings stay private, but the session detail page can mint a temporary **Copy for agent** link. The two-hour `agent_access` URL lets an external agent read replay summaries, timelines, and bounded event details without exposing blob/provider URLs or making the recording public.
 
+Implementation note: use the shared core agent-access helpers
+(`createScopedAgentAccessGrant`, `verifyScopedAgentAccessToken`,
+`buildAgentAccessUrl`, and `buildAgentAccessApiUrl`) for the SSR/bot-visible
+URL contract. Keep replay chunk authorization, diagnostics payloads, and the
+session detail UI local to Analytics.
+
 ### Zusammenarbeit mit dem Agenten
 
 Der Agent weiß immer, was Sie sehen. Der aktuelle Bildschirmstatus wird als `<current-screen>`-Block in jede Nachricht eingefügt – er enthält die aktive Ansicht, das geöffnete Dashboard oder die geöffnete Analyse und alle ausgewählten Filter.

package/docs/content/locales/de-DE/template-clips.mdx

@@ -133,6 +133,13 @@ Agent.
 
 Temporary private agent links are also supported: the Share dialog can mint a two-hour `agent_access` URL for any recording the viewer can access. Agents use that token with the share page and JSON APIs, and the clip does not become public.
 
+Implementation note: use the shared core agent-access helpers
+(`createScopedAgentAccessGrant`, `verifyScopedAgentAccessToken`,
+`buildAgentAccessUrl`, and `buildAgentAccessApiUrl`) for the SSR/bot-visible
+URL contract. Keep Clips-specific visibility checks, transcript/frame payloads,
+and player UI local. New links use `agent_access`; routes should continue
+accepting the legacy `t` query where existing agent API URLs may already use it.
+
 Die Endpunkte folgen denselben öffentlichen/Passwort-/Ablaufregeln wie die Freigabeseite.
 Passwortgeschützte Clips erfordern das einmalige Passwort; Erfolgreiche Antworten werden zurückgegeben
 kurzlebige tokenisierte Links, sodass nachgeschaltete Agenten den Klartext nicht benötigen

package/docs/content/locales/de-DE/tracking.mdx

@@ -241,6 +241,12 @@ Das Analytics-Template speichert Replay-Metadaten in SQL (`session_recordings`)
 
 Wenn Sie eine private Aufzeichnung an einen externen Agenten übergeben müssen, verwenden Sie auf der Sitzungsdetailseite die Funktion **Copy for agent**. Sie erzeugt einen zwei Stunden gültigen, aufzeichnungsgebundenen `agent_access`-Link, rendert eine kleine Discovery-Payload per SSR unter `/sessions/:recordingId` und stellt ausschließlich die JSON-APIs für Agent-Kontext/-Ereignisse bereit. Die Sichtbarkeit der Aufzeichnung ändert sich dadurch nicht.
 
+Implementation note: the reusable layer is the core agent-access URL contract,
+not a replay-specific UI abstraction. Use `createScopedAgentAccessGrant`,
+`verifyScopedAgentAccessToken`, `buildAgentAccessUrl`, and
+`buildAgentAccessApiUrl` for scoped SSR and JSON API links; keep replay storage,
+diagnostics shaping, and access policy inside the Analytics template.
+
 Nur für die lokale Entwicklung kann Analytics auf begrenzte SQL-Inline-Chunks zurückgreifen, wenn kein privater Blob-Speicher verfügbar ist. Produktions-Deployments sollten privaten oder verschlüsselten Blob-Speicher konfigurieren, anstatt sich für Replay-Payloads auf Postgres zu verlassen.
 
 ## Erweitert: benutzerdefinierte Anbieter und Interna {#advanced}

package/docs/content/locales/es-ES/components.mdx

@@ -25,6 +25,15 @@ Evite importar componentes UI desde el paquete básico `@agent-native/core`. Usa
 `@agent-native/core/client` o una subruta `@agent-native/core/client/*` enfocada
 para que los paquetes elijan la entrada segura para el navegador.
 
+Use `@agent-native/toolkit` para piezas reutilizables de construcción de aplicaciones que no forman parte del contrato fundacional del runtime: primitivas UI estilo shadcn, hooks compartidos, ayudantes simples de shell de aplicación y otros módulos para componer plantillas. Core conserva reexports de compatibilidad durante la transición, pero el código nuevo de plantillas y aplicaciones debe importar módulos de toolkit directamente:
+
+```tsx
+import { Button } from "@agent-native/toolkit/ui/button";
+import { Toaster } from "@agent-native/toolkit/ui/sonner";
+import { useToast } from "@agent-native/toolkit/hooks/use-toast";
+import { useSetHeaderActions } from "@agent-native/toolkit/app-shell";
+```
+
 <Diagram id="doc-block-1v79shu" title="Bajar una capa, no fuera del marco." summary={"Cada capa mantiene el mismo tiempo de ejecución (acciones, estado del subproceso y sincronización SQL-backed) al tiempo que le brinda más control sobre Chrome."}>
 
 ```html

package/docs/content/locales/es-ES/creating-templates.mdx

@@ -7,6 +7,8 @@ description: "Cómo crear y publicar sus propias plantillas de aplicaciones nati
 
 Las plantillas son aplicaciones nativas del agente completas y bifurcables que resuelven un flujo de trabajo real. Las plantillas propias se crean con la misma superficie de marco que usted utiliza: rutas React para UI, Drizzle SQL para datos, actions para operaciones, recursos del espacio de trabajo para el comportamiento del agente y sincronización de sondeos para que el agente y UI permanezcan alineados.
 
+Use `@agent-native/core` para el contrato de runtime: actions, plugins de servidor, helpers de base de datos, estado de aplicación, helpers de rutas y chat del agente. Use `@agent-native/toolkit` para UI reutilizable y helpers de construcción de apps, como primitivas compartidas, hooks de toast/móvil, selectores de fecha y slots simples de shell de aplicación. Mantenga locales las variantes específicas de una plantilla cuando codifiquen comportamiento de producto o identidad visual.
+
 Una buena plantilla:
 
 - Resuelve un flujo de trabajo de principio a fin, con datos iniciales útiles o un flujo de estado vacío.

package/docs/content/locales/es-ES/template-analytics.mdx

@@ -149,6 +149,12 @@ El CLI imprime el desarrollador local URL. Inicia sesión con Google y luego abr
 
 **Session replay agent handoff.** Session recordings stay private, but the session detail page can mint a temporary **Copy for agent** link. The two-hour `agent_access` URL lets an external agent read replay summaries, timelines, and bounded event details without exposing blob/provider URLs or making the recording public.
 
+Implementation note: use the shared core agent-access helpers
+(`createScopedAgentAccessGrant`, `verifyScopedAgentAccessToken`,
+`buildAgentAccessUrl`, and `buildAgentAccessApiUrl`) for the SSR/bot-visible
+URL contract. Keep replay chunk authorization, diagnostics payloads, and the
+session detail UI local to Analytics.
+
 ### Trabajar con el agente
 
 El agente siempre sabe lo que estás mirando. El estado actual de la pantalla se inyecta en cada mensaje como un bloque `<current-screen>`: contiene la vista activa, el panel o análisis abierto y los filtros seleccionados.

package/docs/content/locales/es-ES/template-clips.mdx

@@ -133,6 +133,13 @@ agente.
 
 Temporary private agent links are also supported: the Share dialog can mint a two-hour `agent_access` URL for any recording the viewer can access. Agents use that token with the share page and JSON APIs, and the clip does not become public.
 
+Implementation note: use the shared core agent-access helpers
+(`createScopedAgentAccessGrant`, `verifyScopedAgentAccessToken`,
+`buildAgentAccessUrl`, and `buildAgentAccessApiUrl`) for the SSR/bot-visible
+URL contract. Keep Clips-specific visibility checks, transcript/frame payloads,
+and player UI local. New links use `agent_access`; routes should continue
+accepting the legacy `t` query where existing agent API URLs may already use it.
+
 Los puntos finales siguen las mismas reglas de público/contraseña/caducidad que la página para compartir.
 Los clips protegidos con contraseña requieren la contraseña una vez; regresan respuestas exitosas
 Enlaces tokenizados de corta duración para que los agentes posteriores no necesiten el texto sin formato

package/docs/content/locales/es-ES/tracking.mdx

@@ -241,6 +241,12 @@ La plantilla de Analytics almacena los metadatos de repetición en SQL (`session
 
 Cuando necesite entregar una grabación privada a un agente externo, use el control **Copiar para el agente** de la página de detalle de la sesión. Este genera un enlace `agent_access` de dos horas con alcance limitado a la grabación, renderiza en el servidor (SSR) una pequeña carga útil de descubrimiento en `/sessions/:recordingId`, y expone únicamente las API JSON de contexto/eventos del agente. La visibilidad de la grabación no cambia.
 
+Implementation note: the reusable layer is the core agent-access URL contract,
+not a replay-specific UI abstraction. Use `createScopedAgentAccessGrant`,
+`verifyScopedAgentAccessToken`, `buildAgentAccessUrl`, and
+`buildAgentAccessApiUrl` for scoped SSR and JSON API links; keep replay storage,
+diagnostics shaping, and access policy inside the Analytics template.
+
 Solo para desarrollo local, Analytics puede recurrir a fragmentos en línea de SQL limitados cuando el almacenamiento de blob privado no está disponible. Las implementaciones de producción deberían configurar almacenamiento de blob privado o cifrado en lugar de depender de Postgres para las cargas útiles de repetición.
 
 ## Avanzado: proveedores personalizados e internos {#advanced}

package/docs/content/locales/fr-FR/components.mdx

@@ -25,6 +25,15 @@ import { ResourcesPanel } from "@agent-native/core/client/resources";
 `@agent-native/core/client` ou un sous-chemin `@agent-native/core/client/*` ciblé
 les bundlers choisissent donc l'entrée sécurisée pour le navigateur.
 
+Utilisez `@agent-native/toolkit` pour les éléments réutilisables de construction d'applications qui ne font pas partie du contrat fondamental du runtime : primitives UI de style shadcn, hooks partagés, aides simples de shell d'application et autres modules de composition de modèles. Core conserve des réexportations de compatibilité pendant la transition, mais le nouveau code de modèle et d'application doit importer directement les modules toolkit :
+
+```tsx
+import { Button } from "@agent-native/toolkit/ui/button";
+import { Toaster } from "@agent-native/toolkit/ui/sonner";
+import { useToast } from "@agent-native/toolkit/hooks/use-toast";
+import { useSetHeaderActions } from "@agent-native/toolkit/app-shell";
+```
+
 <Diagram id="doc-block-n2zqzy" title={"Déposez un calque, pas hors du cadre"} summary={"Chaque couche conserve le même temps d'exécution (actions, état du thread et synchronisation SQL-backed) tout en vous donnant plus de contrôle sur le chrome."}>
 
 ```html

package/docs/content/locales/fr-FR/creating-templates.mdx

@@ -7,6 +7,8 @@ description: "Comment créer et publier vos propres modèles d'applications nati
 
 Les modèles sont des applications natives d'agent complètes et exploitables qui résolvent un véritable flux de travail. Les modèles propriétaires sont créés avec la même surface de structure que vous utilisez : routes React pour le UI, Drizzle SQL pour les données, actions pour les opérations, ressources d'espace de travail pour le comportement de l'agent et synchronisation des interrogations afin que l'agent et le UI restent alignés.
 
+Utilisez `@agent-native/core` pour le contrat de runtime : actions, plugins serveur, aides de base de données, état de l'application, aides de routage et chat de l'agent. Utilisez `@agent-native/toolkit` pour l'UI réutilisable de construction d'applications et les aides comme les primitives partagées, les hooks toast/mobile, les sélecteurs de date et les slots simples de shell d'application. Gardez les variantes propres au modèle locales lorsqu'elles encodent un comportement produit ou une identité visuelle.
+
 Un bon modèle :
 
 - Résout un flux de travail de bout en bout, avec des données de départ utiles ou un flux à état vide.

package/docs/content/locales/fr-FR/template-analytics.mdx

@@ -149,6 +149,12 @@ Le CLI imprime le développement local URL. Connectez-vous avec Google, puis ouv
 
 **Session replay agent handoff.** Session recordings stay private, but the session detail page can mint a temporary **Copy for agent** link. The two-hour `agent_access` URL lets an external agent read replay summaries, timelines, and bounded event details without exposing blob/provider URLs or making the recording public.
 
+Implementation note: use the shared core agent-access helpers
+(`createScopedAgentAccessGrant`, `verifyScopedAgentAccessToken`,
+`buildAgentAccessUrl`, and `buildAgentAccessApiUrl`) for the SSR/bot-visible
+URL contract. Keep replay chunk authorization, diagnostics payloads, and the
+session detail UI local to Analytics.
+
 ### Travailler avec l'agent
 
 L'agent sait toujours ce que vous regardez. L'état actuel de l'écran est injecté dans chaque message sous forme de bloc `<current-screen>` : il contient la vue active, le tableau de bord ou l'analyse ouvert et tous les filtres sélectionnés.

package/docs/content/locales/fr-FR/template-clips.mdx

@@ -133,6 +133,13 @@ agent.
 
 Temporary private agent links are also supported: the Share dialog can mint a two-hour `agent_access` URL for any recording the viewer can access. Agents use that token with the share page and JSON APIs, and the clip does not become public.
 
+Implementation note: use the shared core agent-access helpers
+(`createScopedAgentAccessGrant`, `verifyScopedAgentAccessToken`,
+`buildAgentAccessUrl`, and `buildAgentAccessApiUrl`) for the SSR/bot-visible
+URL contract. Keep Clips-specific visibility checks, transcript/frame payloads,
+and player UI local. New links use `agent_access`; routes should continue
+accepting the legacy `t` query where existing agent API URLs may already use it.
+
 Les points de terminaison suivent les mêmes règles de public/mot de passe/expiration que la page de partage.
 Les clips protégés par mot de passe nécessitent le mot de passe une seule fois ; les réponses positives reviennent
 Liens tokenisés de courte durée afin que les agents en aval n'aient pas besoin du texte brut

package/docs/content/locales/fr-FR/tracking.mdx

@@ -241,6 +241,12 @@ Le modèle Analytics stocke les métadonnées de relecture en SQL (`session_reco
 
 Lorsque vous devez transmettre un enregistrement privé à un agent externe, utilisez le contrôle **Copy for agent** de la page de détail de session. Il génère un lien `agent_access` limité à l'enregistrement, valide deux heures, effectue le rendu SSR d'une petite charge utile de découverte sur `/sessions/:recordingId`, et n'expose que les API JSON de contexte/événements de l'agent. La visibilité de l'enregistrement ne change pas.
 
+Implementation note: the reusable layer is the core agent-access URL contract,
+not a replay-specific UI abstraction. Use `createScopedAgentAccessGrant`,
+`verifyScopedAgentAccessToken`, `buildAgentAccessUrl`, and
+`buildAgentAccessApiUrl` for scoped SSR and JSON API links; keep replay storage,
+diagnostics shaping, and access policy inside the Analytics template.
+
 Pour le développement local uniquement, Analytics peut se replier sur des blocs SQL en ligne plafonnés lorsque le stockage blob privé n'est pas disponible. Les déploiements en production doivent configurer un stockage blob privé ou chiffré plutôt que de s'appuyer sur Postgres pour les charges utiles de relecture.
 
 ## Avancé : fournisseurs personnalisés et éléments internes {#advanced}

package/docs/content/locales/hi-IN/components.mdx

@@ -25,6 +25,15 @@ import { ResourcesPanel } from "@agent-native/core/client/resources";
 `@agent-native/core/client` या एक केंद्रित `@agent-native/core/client/*` उपपथ
 इसलिए बंडलर ब्राउज़र-सुरक्षित प्रविष्टि चुनते हैं।
 
+`@agent-native/toolkit` का उपयोग उन पुन: उपयोग योग्य ऐप-बिल्डिंग हिस्सों के लिए करें जो मूल रनटाइम अनुबंध का भाग नहीं हैं: shadcn-शैली UI primitives, साझा hooks, सरल ऐप shell helpers, और अन्य template composition modules. संक्रमण के दौरान Core compatibility re-exports रखता है, लेकिन नए template और app code को toolkit modules सीधे import करने चाहिए:
+
+```tsx
+import { Button } from "@agent-native/toolkit/ui/button";
+import { Toaster } from "@agent-native/toolkit/ui/sonner";
+import { useToast } from "@agent-native/toolkit/hooks/use-toast";
+import { useSetHeaderActions } from "@agent-native/toolkit/app-shell";
+```
+
 <Diagram id="doc-block-109zkj3" title={"एक परत नीचे गिराएं, ढांचे से बाहर नहीं"} summary={"प्रत्येक परत आपको क्रोम पर अधिक नियंत्रण प्रदान करते हुए समान रनटाइम - क्रियाएं, थ्रेड स्थिति और SQL-backed सिंक रखती है।"}>
 
 ```html