@agent-native/core 0.107.2 → 0.109.0

package/corpus/core/src/feature-flags/store.ts

@@ -0,0 +1,176 @@
+import { getOrgSetting, mutateOrgSetting } from "../settings/org-settings.js";
+import { getSetting, mutateSetting } from "../settings/store.js";
+import {
+  getFeatureFlagDefinition,
+  type FeatureFlagDefinition,
+} from "./registry.js";
+
+export type FeatureFlagMode = "off" | "on" | "rules";
+
+export interface FeatureFlagRules {
+  version: 1;
+  mode: FeatureFlagMode;
+  emails: string[];
+  orgIds: string[];
+  percentage: number;
+  updatedAt: number | null;
+  updatedBy: string | null;
+}
+
+export interface FeatureFlagScope {
+  userEmail?: string;
+  /** Canonical authenticated identity. V1 callers use normalized email. */
+  userKey?: string;
+  orgId?: string | null;
+}
+
+export const FEATURE_FLAG_SETTINGS_PREFIX = "feature-flag:";
+
+function settingKey(key: string): string {
+  return `${FEATURE_FLAG_SETTINGS_PREFIX}${key}`;
+}
+
+export function defaultFeatureFlagRules(): FeatureFlagRules {
+  return {
+    version: 1,
+    mode: "off",
+    emails: [],
+    orgIds: [],
+    percentage: 0,
+    updatedAt: null,
+    updatedBy: null,
+  };
+}
+
+function stringList(value: unknown): string[] {
+  if (!Array.isArray(value)) return [];
+  return [
+    ...new Set(
+      value
+        .filter((item): item is string => typeof item === "string")
+        .map((item) => item.trim())
+        .filter(Boolean),
+    ),
+  ].sort();
+}
+
+export function normalizeFeatureFlagRules(value: unknown): FeatureFlagRules {
+  if (!value || typeof value !== "object") return defaultFeatureFlagRules();
+  const raw = value as Record<string, unknown>;
+  const mode: FeatureFlagMode =
+    raw.mode === "on" || raw.mode === "rules" || raw.mode === "off"
+      ? raw.mode
+      : "off";
+  const percentage =
+    typeof raw.percentage === "number" && Number.isFinite(raw.percentage)
+      ? Math.max(0, Math.min(100, Math.floor(raw.percentage)))
+      : 0;
+  return {
+    version: 1,
+    mode,
+    emails: stringList(raw.emails).map((email) => email.toLowerCase()),
+    orgIds: stringList(raw.orgIds),
+    percentage,
+    updatedAt:
+      typeof raw.updatedAt === "number" && Number.isSafeInteger(raw.updatedAt)
+        ? raw.updatedAt
+        : null,
+    updatedBy:
+      typeof raw.updatedBy === "string" && raw.updatedBy.trim()
+        ? raw.updatedBy.trim().toLowerCase()
+        : null,
+  };
+}
+
+export async function getFeatureFlagRules(
+  key: string,
+  scope: Pick<FeatureFlagScope, "orgId">,
+): Promise<FeatureFlagRules> {
+  if (!getFeatureFlagDefinition(key)) return defaultFeatureFlagRules();
+  // An organization-specific rule overrides the global rule. The fallback is
+  // what makes global exact-org targeting meaningful for callers in an org.
+  const stored = scope.orgId?.trim()
+    ? ((await getOrgSetting(scope.orgId, settingKey(key))) ??
+      (await getSetting(settingKey(key))))
+    : await getSetting(settingKey(key));
+  return normalizeFeatureFlagRules(stored);
+}
+
+/**
+ * Atomically derive one flag's scoped rules. An org's first override starts
+ * from the global fallback, then becomes independently CAS-protected.
+ */
+export async function mutateFeatureFlagRules(
+  key: string,
+  scope: Pick<FeatureFlagScope, "orgId">,
+  updater: (
+    current: FeatureFlagRules,
+  ) => FeatureFlagRules | Promise<FeatureFlagRules>,
+): Promise<FeatureFlagRules> {
+  if (!getFeatureFlagDefinition(key)) {
+    throw new Error(`Unknown feature flag: ${key}`);
+  }
+  const mutate = async (stored: Record<string, unknown> | null) => {
+    const fallback =
+      stored == null && scope.orgId?.trim()
+        ? await getSetting(settingKey(key))
+        : null;
+    return {
+      ...(await updater(normalizeFeatureFlagRules(stored ?? fallback))),
+    };
+  };
+  const persisted = scope.orgId?.trim()
+    ? await mutateOrgSetting(scope.orgId, settingKey(key), mutate)
+    : await mutateSetting(settingKey(key), mutate);
+  return normalizeFeatureFlagRules(persisted);
+}
+
+function rolloutBucket(input: string): number {
+  // FNV-1a is deliberately tiny, deterministic, and independent of runtime.
+  let hash = 0x811c9dc5;
+  for (let index = 0; index < input.length; index += 1) {
+    hash ^= input.charCodeAt(index);
+    hash = Math.imul(hash, 0x01000193);
+  }
+  return (hash >>> 0) % 100;
+}
+
+export function evaluateFeatureFlagRules(
+  key: string,
+  rules: FeatureFlagRules,
+  scope: FeatureFlagScope,
+): boolean {
+  if (rules.mode === "off") return false;
+  if (rules.mode === "on") return true;
+  const email = scope.userEmail?.trim().toLowerCase();
+  if (email && rules.emails.includes(email)) return true;
+  if (scope.orgId && rules.orgIds.includes(scope.orgId)) return true;
+  const userKey = scope.userKey?.trim() || email;
+  if (!userKey || rules.percentage <= 0) return false;
+  return rolloutBucket(`${key}:${userKey}`) < rules.percentage;
+}
+
+export async function evaluateFeatureFlag(
+  key: string,
+  scope: FeatureFlagScope = {},
+): Promise<boolean> {
+  if (!getFeatureFlagDefinition(key)) return false;
+  try {
+    return evaluateFeatureFlagRules(
+      key,
+      await getFeatureFlagRules(key, scope),
+      scope,
+    );
+  } catch {
+    // A feature flag must never become an availability dependency.
+    return false;
+  }
+}
+
+/** Ergonomic app-action guard. Accepts either a registered definition or its key. */
+export async function isFeatureFlagEnabled(
+  flag: string | FeatureFlagDefinition,
+  scope: FeatureFlagScope = {},
+): Promise<boolean> {
+  return evaluateFeatureFlag(typeof flag === "string" ? flag : flag.key, scope);
+}

package/corpus/core/src/index.ts

@@ -142,6 +142,21 @@ export {
   type AutomationWorkflowDefinition,
   type JsonSchema,
 } from "./automation/index.js";
+export {
+  createFeatureFlagsPlugin,
+  defineFeatureFlag,
+  defineFeatureFlags,
+  evaluateFeatureFlag,
+  getFeatureFlagDefinition,
+  getFeatureFlagRules,
+  isFeatureFlagEnabled,
+  listFeatureFlags,
+  registerFeatureFlags,
+  type FeatureFlagDefinition,
+  type FeatureFlagMode,
+  type FeatureFlagRules,
+  type FeatureFlagScope,
+} from "./feature-flags/index.js";
 
 // Server
 export {

package/corpus/core/src/localization/default-messages.ts

@@ -33,6 +33,53 @@ const messages = {
     openResourceSettings: "Open resource settings",
     backHome: "Back to home",
   },
+  featureFlags: {
+    title: "Feature flags",
+    description: "Control staged capabilities without changing a deployment.",
+    enableForMe: "Enable for me",
+    enabledForMe: "Enabled for you",
+    youHaveAccess: "You have access",
+    youDoNotHaveAccess: "You don't have access",
+    currentUserUnknown: "Your access couldn't be evaluated",
+    moreActions: "More actions for {{name}}",
+    disableForEveryone: "Disable for everyone",
+    disableForEveryoneTitle: "Disable {{name}} for everyone?",
+    disableForEveryoneDescription:
+      "This immediately removes access for every targeted person and organization. You can configure a new rollout later.",
+    editTargeting: "Edit targeting",
+    editTargetingFor: "Edit targeting for {{name}}",
+    targetingTitle: "Edit targeting — {{name}}",
+    targetingDescription:
+      "Choose who can use this capability. Changes apply immediately.",
+    noFlags: "No feature flags are registered for this app.",
+    defaultOn: "Code fallback: on",
+    defaultOff: "Code fallback: off",
+    enabledFor: "Enabled for",
+    modeLabel: "Availability",
+    emailsLabel: "People",
+    orgIdsLabel: "Organization IDs",
+    percentageLabel: "Percentage of users",
+    targetingRuleHelp:
+      "A person gets access if they match any email, organization, or percentage rule.",
+    targetingSummary: "Currently enabled for: {{audience}}.",
+    saveRules: "Save changes",
+    cancel: "Cancel",
+    inherited: "No matching targets",
+    off: "Off",
+    targeted: "Targeted",
+    everyone: "Everyone",
+    everyoneAudience: "everyone",
+    emailCount_one: "{{count}} email",
+    emailCount_other: "{{count}} emails",
+    organizationCount_one: "{{count}} organization",
+    organizationCount_other: "{{count}} organizations",
+    percentageRollout: "{{count}}% rollout",
+    lastChanged: "Last changed: {{metadata}}",
+    mutationUnverified:
+      "We couldn't verify the change to {{name}}. Reload flags before trying again.",
+    mutationUnverifiedGeneric:
+      "We couldn't verify this feature flag change. Reload flags before trying again.",
+  },
   dispatch: {
     nav: {
       chat: "Chat",
@@ -82,6 +129,9 @@ const messages = {
         'Apps in the "{{workspace}}" workspace. Each app gets its own route under this workspace and shares its database, auth, and agent chat.',
       appsInWorkspace: "Apps in {{workspace}}",
       workspaceApps: "Workspace apps",
+      otherApps: "Other apps",
+      otherAppsDescription: "Open other apps available to you.",
+      availableCount: "{{count}} available",
       activeCount: "{{count}} active",
       hiddenCount: "{{count}} hidden",
       createApp: "Create app",

package/corpus/core/src/mcp/build-server.ts

@@ -345,7 +345,7 @@ function warnFullCatalogServed(toolCount: number): void {
   );
 }
 
-function isAuthenticatedReadAction(entry: ActionEntry): boolean {
+export function isAuthenticatedReadAction(entry: ActionEntry): boolean {
   return (
     entry.http !== false &&
     entry.http?.method === "GET" &&
@@ -404,7 +404,7 @@ const AUTO_READ_EXCLUDED_ACTION_PATTERNS: RegExp[] = [
   /browser-session/,
 ];
 
-function isAutoReadExcludedActionName(name: string): boolean {
+export function isAutoReadExcludedActionName(name: string): boolean {
   return (
     AUTO_READ_EXCLUDED_ACTION_NAMES.has(name) ||
     AUTO_READ_EXCLUDED_ACTION_PATTERNS.some((pattern) => pattern.test(name))

package/corpus/core/src/progress/actions.ts

@@ -35,6 +35,7 @@ Use for non-trivial work with multiple real steps (not single-action lookups). D
 - Exactly one task in progress at a time; never batch-complete steps after the fact — update as you go.
 - Always transition pending → in_progress before completing a step.
 - If the task pivots (scope change, unexpected blocker), update the current step to reflect it before continuing.
+- Only include fields for the selected action; do not send empty placeholder fields.
 - End every run with "complete" (succeeded / failed / cancelled). Never leave a run open indefinitely.
 
 Actions:
@@ -78,8 +79,9 @@ Actions:
             },
             status: {
               type: "string",
-              enum: ["succeeded", "failed", "cancelled"],
-              description: "[complete] Terminal status for the run.",
+              enum: ["", "succeeded", "failed", "cancelled"],
+              description:
+                '[complete] Terminal status for the run. Omit it for "start" and "update".',
             },
             active: {
               type: "boolean",

package/corpus/core/src/provider-api/index.ts

@@ -1284,6 +1284,35 @@ const PROVIDER_CONFIGS: Record<ProviderApiId, ProviderApiConfig> = {
     defaultHeaders: { "Notion-Version": "2026-03-11" },
     templateUses: ["analytics", "brain", "content", "dispatch"],
     examples: [{ label: "Search", method: "POST", path: "/search", body: {} }],
+    corpusRecipes: [
+      {
+        label: "Search a Notion data source with complete cursor coverage",
+        useWhen:
+          "Use for coverage-sensitive searches across one known Notion data source's page properties. This does not search page block bodies.",
+        workflow: [
+          "Resolve the exact data source id and apply the narrowest provider-side filter and filter_properties projection first.",
+          "Start provider-corpus-job with mode=paginated-search and pass next_cursor back as start_cursor in the POST body.",
+          "Search only the returned properties and report the 10,000-result API ceiling plus any incomplete request_status.",
+          "For page body text, stage page ids and fetch block children through a separate bounded data program; property search is not body search.",
+        ],
+        request: {
+          method: "POST",
+          path: "/data_sources/<data-source-id>/query",
+          body: { page_size: 100 },
+        },
+        pagination: {
+          itemsPath: "results",
+          nextCursorPath: "next_cursor",
+          cursorBodyPath: "start_cursor",
+          maxPages: 100,
+        },
+        search: {
+          textPaths: ["properties"],
+          idPaths: ["id"],
+          metadataPaths: ["id", "url", "created_time", "last_edited_time"],
+        },
+      },
+    ],
   },
   posthog: {
     id: "posthog",
@@ -1306,11 +1335,21 @@ const PROVIDER_CONFIGS: Record<ProviderApiId, ProviderApiConfig> = {
     ],
     examples: [
       {
-        label: "List events",
-        method: "GET",
-        path: "/api/projects/{projectId}/events/",
+        label: "Aggregate events with HogQL",
+        method: "POST",
+        path: "/api/projects/{projectId}/query/",
+        body: {
+          query: {
+            kind: "HogQLQuery",
+            query:
+              "SELECT event, count() AS events FROM events WHERE timestamp >= now() - INTERVAL 7 DAY GROUP BY event ORDER BY events DESC LIMIT 100",
+          },
+        },
       },
     ],
+    notes: [
+      "Prefer the query endpoint with a bounded HogQL projection or server-side aggregation over paging raw events into the agent context.",
+    ],
   },
   prometheus: {
     id: "prometheus",
@@ -1400,6 +1439,39 @@ const PROVIDER_CONFIGS: Record<ProviderApiId, ProviderApiConfig> = {
       { label: "Search messages", method: "GET", path: "/search.messages" },
       { label: "Post message", method: "POST", path: "/chat.postMessage" },
     ],
+    notes: [
+      "Bot-token reads must not call conversations.join implicitly. A bot can read only conversations it is already a member of with the required history scope.",
+      "search.messages requires a compatible user token; do not assume a bot token can use it. Use conversations.history for channel-scoped bot reads.",
+    ],
+    corpusRecipes: [
+      {
+        label: "Search complete Slack channel history",
+        useWhen:
+          "Use for all-message, mention, phrase, or absence-sensitive searches in one known Slack conversation without one agent turn per cursor page.",
+        workflow: [
+          "Resolve the exact channel id without joining or mutating membership.",
+          "Start provider-corpus-job with mode=paginated-search against conversations.history, bounded by oldest/latest when possible.",
+          "Pass response_metadata.next_cursor back as cursor and let quota_wait pause/resume rate-limited installations.",
+          "Report channel id, time bounds, pages, messages searched, matches, and is_limited or access gaps.",
+        ],
+        request: {
+          method: "GET",
+          path: "/conversations.history",
+          query: { channel: "<channel-id>" },
+        },
+        pagination: {
+          itemsPath: "messages",
+          nextCursorPath: "response_metadata.next_cursor",
+          cursorParam: "cursor",
+          maxPages: 500,
+        },
+        search: {
+          textPaths: ["text", "blocks", "attachments"],
+          idPaths: ["ts", "client_msg_id"],
+          metadataPaths: ["ts", "user", "thread_ts", "type", "subtype"],
+        },
+      },
+    ],
   },
   stripe: {
     id: "stripe",
@@ -1690,60 +1762,66 @@ export async function executeProviderApiRequest(
   // --- fetchAllPages mode ---
   if (args.fetchAllPages) {
     const pageCfg = args.fetchAllPages;
-    const { items, pageCount, lastStatus, lastContentType } =
-      await fetchAllPages(pageCfg, async (extra) => {
-        const queryWithCursor = extra?.query
-          ? mergeQueryObjects(
-              substituteUnknown(args.query, placeholders),
-              extra.query,
-            )
-          : substituteUnknown(args.query, placeholders);
-        const pageUrl = buildProviderUrl({
-          config,
-          baseUrl,
-          rawPath: substituteString(args.path, placeholders),
-          query: queryWithCursor,
-        });
-        const bodyWithCursor = extra?.bodyCursor
-          ? setValueAtPath(
-              substituteUnknown(args.body, placeholders),
-              extra.bodyCursor.path,
-              extra.bodyCursor.value,
-            )
-          : substituteUnknown(args.body, placeholders);
-        const pageBody = prepareBody(bodyWithCursor, { ...headers });
-        const requestKey = createProviderRequestDedupeKey({
-          method,
-          url: pageUrl.href,
-          body: pageBody,
-          headers,
-        });
-        const resp = await fetchWithTimeout(pageUrl.href, {
+    const {
+      items,
+      pageCount,
+      lastStatus,
+      lastContentType,
+      truncated,
+      nextCursor,
+    } = await fetchAllPages(pageCfg, async (extra) => {
+      const queryWithCursor = extra?.query
+        ? mergeQueryObjects(
+            substituteUnknown(args.query, placeholders),
+            extra.query,
+          )
+        : substituteUnknown(args.query, placeholders);
+      const pageUrl = buildProviderUrl({
+        config,
+        baseUrl,
+        rawPath: substituteString(args.path, placeholders),
+        query: queryWithCursor,
+      });
+      const bodyWithCursor = extra?.bodyCursor
+        ? setValueAtPath(
+            substituteUnknown(args.body, placeholders),
+            extra.bodyCursor.path,
+            extra.bodyCursor.value,
+          )
+        : substituteUnknown(args.body, placeholders);
+      const pageBody = prepareBody(bodyWithCursor, headers);
+      const requestKey = createProviderRequestDedupeKey({
+        method,
+        url: pageUrl.href,
+        body: pageBody,
+        headers,
+      });
+      const resp = await fetchWithTimeout(pageUrl.href, {
+        method,
+        headers,
+        body: pageBody,
+        maxBytes: effectiveMaxBytes,
+        timeoutMs: clampTimeout(args.timeoutMs),
+        secretValues: auth.secretValues,
+        quota: {
+          identity: quotaIdentity,
           method,
-          headers,
-          body: pageBody,
-          maxBytes: effectiveMaxBytes,
-          timeoutMs: clampTimeout(args.timeoutMs),
-          secretValues: auth.secretValues,
-          quota: {
-            identity: quotaIdentity,
-            method,
-            target: describeProviderRequestTarget(
-              pageUrl.href,
-              auth.secretValues,
-            ),
-            requestKey,
-          },
-        });
-        return {
-          text:
-            resp.text ??
-            (resp.json !== undefined ? JSON.stringify(resp.json) : ""),
-          contentType: resp.contentType,
-          status: resp.status,
-          ok: resp.ok,
-        };
+          target: describeProviderRequestTarget(
+            pageUrl.href,
+            auth.secretValues,
+          ),
+          requestKey,
+        },
       });
+      return {
+        text:
+          resp.text ??
+          (resp.json !== undefined ? JSON.stringify(resp.json) : ""),
+        contentType: resp.contentType,
+        status: resp.status,
+        ok: resp.ok,
+      };
+    });
 
     const allItemsJson = JSON.stringify(items, null, 2);
     const metadata = {
@@ -1751,6 +1829,8 @@ export async function executeProviderApiRequest(
       pagesRead: pageCount,
       totalItems: Array.isArray(items) ? items.length : 0,
       lastStatus,
+      truncated,
+      nextCursor,
     };
 
     if (args.saveToFile) {
@@ -2642,57 +2722,63 @@ async function executeCustomProviderApiRequest(
   // --- fetchAllPages mode (same cursor pagination as built-in providers) ---
   if (args.fetchAllPages) {
     const pageCfg = args.fetchAllPages;
-    const { items, pageCount, lastStatus, lastContentType } =
-      await fetchAllPages(pageCfg, async (extra) => {
-        const queryWithCursor = extra?.query
-          ? mergeQueryObjects(args.query, extra.query)
-          : args.query;
-        const pageUrl = buildProviderUrl({
-          config: syntheticConfig,
-          baseUrl,
-          rawPath: args.path,
-          query: queryWithCursor,
-        });
-        const bodyWithCursor = extra?.bodyCursor
-          ? setValueAtPath(
-              args.body,
-              extra.bodyCursor.path,
-              extra.bodyCursor.value,
-            )
-          : args.body;
-        const pageBody = prepareBody(bodyWithCursor, { ...headers });
-        const requestKey = createProviderRequestDedupeKey({
-          method,
-          url: pageUrl.href,
-          body: pageBody,
-          headers,
-        });
-        const resp = await fetchWithTimeout(pageUrl.href, {
+    const {
+      items,
+      pageCount,
+      lastStatus,
+      lastContentType,
+      truncated,
+      nextCursor,
+    } = await fetchAllPages(pageCfg, async (extra) => {
+      const queryWithCursor = extra?.query
+        ? mergeQueryObjects(args.query, extra.query)
+        : args.query;
+      const pageUrl = buildProviderUrl({
+        config: syntheticConfig,
+        baseUrl,
+        rawPath: args.path,
+        query: queryWithCursor,
+      });
+      const bodyWithCursor = extra?.bodyCursor
+        ? setValueAtPath(
+            args.body,
+            extra.bodyCursor.path,
+            extra.bodyCursor.value,
+          )
+        : args.body;
+      const pageBody = prepareBody(bodyWithCursor, headers);
+      const requestKey = createProviderRequestDedupeKey({
+        method,
+        url: pageUrl.href,
+        body: pageBody,
+        headers,
+      });
+      const resp = await fetchWithTimeout(pageUrl.href, {
+        method,
+        headers,
+        body: pageBody,
+        maxBytes: effectiveMaxBytes,
+        timeoutMs: clampTimeout(args.timeoutMs),
+        secretValues: auth.secretValues,
+        quota: {
+          identity: quotaIdentity,
           method,
-          headers,
-          body: pageBody,
-          maxBytes: effectiveMaxBytes,
-          timeoutMs: clampTimeout(args.timeoutMs),
-          secretValues: auth.secretValues,
-          quota: {
-            identity: quotaIdentity,
-            method,
-            target: describeProviderRequestTarget(
-              pageUrl.href,
-              auth.secretValues,
-            ),
-            requestKey,
-          },
-        });
-        return {
-          text:
-            resp.text ??
-            (resp.json !== undefined ? JSON.stringify(resp.json) : ""),
-          contentType: resp.contentType,
-          status: resp.status,
-          ok: resp.ok,
-        };
+          target: describeProviderRequestTarget(
+            pageUrl.href,
+            auth.secretValues,
+          ),
+          requestKey,
+        },
       });
+      return {
+        text:
+          resp.text ??
+          (resp.json !== undefined ? JSON.stringify(resp.json) : ""),
+        contentType: resp.contentType,
+        status: resp.status,
+        ok: resp.ok,
+      };
+    });
 
     const allItemsJson = JSON.stringify(items, null, 2);
     const metadata = {
@@ -2704,6 +2790,8 @@ async function executeCustomProviderApiRequest(
       pagesRead: pageCount,
       totalItems: Array.isArray(items) ? items.length : 0,
       lastStatus,
+      truncated,
+      nextCursor,
     };
 
     if (args.saveToFile) {
@@ -5146,6 +5234,8 @@ async function fetchAllPages(
   pageCount: number;
   lastStatus: number;
   lastContentType: string | null;
+  truncated: boolean;
+  nextCursor: string | null;
 }> {
   const maxPages = Math.min(
     Number.isFinite(config.maxPages) && config.maxPages! > 0
@@ -5159,6 +5249,7 @@ async function fetchAllPages(
   let pageCount = 0;
   let lastStatus = 0;
   let lastContentType: string | null = null;
+  let truncated = false;
 
   if (!config.cursorParam && !config.cursorBodyPath) {
     throw new Error(
@@ -5224,12 +5315,21 @@ async function fetchAllPages(
       nextCursor === null ||
       nextCursor === cursor
     ) {
+      truncated = false;
       break;
     }
     cursor = String(nextCursor);
+    truncated = pageCount >= maxPages;
   }
 
-  return { items, pageCount, lastStatus, lastContentType };
+  return {
+    items,
+    pageCount,
+    lastStatus,
+    lastContentType,
+    truncated,
+    nextCursor: truncated ? (cursor ?? null) : null,
+  };
 }
 
 function fingerprint(value: string): string {