@agent-native/core 0.113.0 → 0.114.0

package/src/server/request-context.ts

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

package/src/server/request-origin.ts

@@ -0,0 +1,67 @@
+import { getRequestHeader, type H3Event } from "h3";
+
+function isLoopbackHost(host: string): boolean {
+  return host.startsWith("localhost:") || host.startsWith("127.0.0.1:");
+}
+
+/**
+ * Reject cross-site POSTs. Cookies are `SameSite=None; Secure` over HTTPS so
+ * the browser would otherwise attach the session to a forged form submission
+ * from evil.com, causing us to spend provider credits on the user's behalf.
+ * Same-origin browsers always send `Origin` on POST; if it's missing we fall
+ * back to `Sec-Fetch-Site` so Safari's fetch-spec behavior still works.
+ */
+export function isSameOriginRequest(event: H3Event): boolean {
+  // Fetch metadata is browser-controlled and describes the relationship
+  // before a reverse proxy rewrites Host (dev-lazy maps :8080 to :8088).
+  // Reject an explicit cross-site signal before consulting forgeable headers.
+  const fetchSite = getRequestHeader(event, "sec-fetch-site");
+  if (fetchSite) return fetchSite === "same-origin" || fetchSite === "none";
+
+  const host = getRequestHeader(event, "host");
+  const origin = getRequestHeader(event, "origin");
+  if (origin && host) {
+    try {
+      const parsed = new URL(origin);
+      const forwardedProto = getRequestHeader(event, "x-forwarded-proto");
+      const forwardedProtocol =
+        forwardedProto === "https" || forwardedProto === "http"
+          ? `${forwardedProto}:`
+          : null;
+      const matchesScheme = forwardedProtocol
+        ? parsed.protocol === forwardedProtocol
+        : parsed.protocol === "https:" ||
+          (parsed.protocol === "http:" && isLoopbackHost(host));
+      if (parsed.host === host && matchesScheme) return true;
+      // Tauri desktop dev serves the tray WebView from localhost:1420 while
+      // the app server lives on the template dev port. Production Tauri
+      // WebViews can also send a tauri://localhost origin. Trust that custom
+      // scheme, while limiting the web-scheme desktop origins below to a
+      // loopback app server so arbitrary websites still fail the CSRF check.
+      if (parsed.protocol === "tauri:" && parsed.hostname === "localhost") {
+        return true;
+      }
+      if (
+        (parsed.protocol === "http:" || parsed.protocol === "https:") &&
+        parsed.hostname === "tauri.localhost" &&
+        isLoopbackHost(host)
+      ) {
+        return true;
+      }
+      if (
+        parsed.protocol === "http:" &&
+        (parsed.hostname === "localhost" || parsed.hostname === "127.0.0.1") &&
+        parsed.port === "1420" &&
+        isLoopbackHost(host)
+      ) {
+        return true;
+      }
+      return false;
+    } catch {
+      return false;
+    }
+  }
+  // No Origin and no Sec-Fetch-Site: likely a non-browser client (curl,
+  // server-side) — safe to allow, CSRF requires a browser with ambient cookies.
+  return true;
+}

package/src/server/resources-plugin.ts

@@ -0,0 +1,119 @@
+import { defineEventHandler, setResponseStatus, getMethod } from "h3";
+
+import {
+  handleListResources,
+  handleGetResourceTree,
+  handleGetEffectiveResourceContext,
+  handleGetResource,
+  handleCreateResource,
+  handleUpdateResource,
+  handleDeleteResource,
+  handleUploadResource,
+} from "../resources/handlers.js";
+import {
+  getH3App,
+  markDefaultPluginProvided,
+} from "./framework-request-handler.js";
+
+type NitroPluginDef = (nitroApp: any) => void | Promise<void>;
+
+/**
+ * Creates a Nitro plugin that mounts all resource CRUD routes.
+ *
+ * Routes:
+ *   GET    /_agent-native/resources          — list resources
+ *   POST   /_agent-native/resources          — create resource
+ *   GET    /_agent-native/resources/tree     — get resource tree
+ *   POST   /_agent-native/resources/upload   — upload file
+ *   GET    /_agent-native/resources/:id      — get resource by ID
+ *   PUT    /_agent-native/resources/:id      — update resource
+ *   DELETE /_agent-native/resources/:id      — delete resource
+ */
+export function createResourcesPlugin(): NitroPluginDef {
+  return async (nitroApp: any) => {
+    markDefaultPluginProvided(nitroApp, "resources");
+    // Mount specific sub-routes BEFORE the catch-all
+
+    getH3App(nitroApp).use(
+      "/_agent-native/resources/effective",
+      defineEventHandler(async (event) => {
+        if (getMethod(event) !== "GET") {
+          setResponseStatus(event, 405);
+          return { error: "Method not allowed" };
+        }
+        return handleGetEffectiveResourceContext(event);
+      }),
+    );
+
+    getH3App(nitroApp).use(
+      "/_agent-native/resources/tree",
+      defineEventHandler(async (event) => {
+        if (getMethod(event) !== "GET") {
+          setResponseStatus(event, 405);
+          return { error: "Method not allowed" };
+        }
+        return handleGetResourceTree(event);
+      }),
+    );
+
+    getH3App(nitroApp).use(
+      "/_agent-native/resources/upload",
+      defineEventHandler(async (event) => {
+        if (getMethod(event) !== "POST") {
+          setResponseStatus(event, 405);
+          return { error: "Method not allowed" };
+        }
+        return handleUploadResource(event);
+      }),
+    );
+
+    // Catch-all for /_agent-native/resources and /_agent-native/resources/:id
+    getH3App(nitroApp).use(
+      "/_agent-native/resources",
+      defineEventHandler(async (event) => {
+        const method = getMethod(event);
+        // h3 strips the mount prefix, so event.path is "/" or "/:id"
+        const raw = (event.path || "/").split("?")[0];
+        const subPath = raw.replace(/^\//, "");
+
+        // No sub-path: /_agent-native/resources — list or create
+        if (!subPath || subPath === "") {
+          if (method === "GET") return handleListResources(event);
+          if (method === "POST") return handleCreateResource(event);
+          setResponseStatus(event, 405);
+          return { error: "Method not allowed" };
+        }
+
+        // Already handled by dedicated routes above
+        if (
+          subPath === "effective" ||
+          subPath === "tree" ||
+          subPath === "upload"
+        )
+          return;
+
+        // /_agent-native/resources/:id — get, update, delete
+        event.context.params = { ...event.context.params, id: subPath };
+
+        if (method === "GET") return handleGetResource(event);
+        if (method === "PUT") return handleUpdateResource(event);
+        if (method === "DELETE") return handleDeleteResource(event);
+
+        setResponseStatus(event, 405);
+        return { error: "Method not allowed" };
+      }),
+    );
+  };
+}
+
+/**
+ * Default resources plugin — mount with no configuration needed.
+ *
+ * Usage in templates:
+ * ```ts
+ * // server/plugins/resources.ts
+ * import { defaultResourcesPlugin } from "@agent-native/core/server";
+ * export default defaultResourcesPlugin;
+ * ```
+ */
+export const defaultResourcesPlugin: NitroPluginDef = createResourcesPlugin();