@agent-native/core 0.96.0 → 0.98.0

package/corpus/core/src/package-lifecycle/manifest.ts

@@ -0,0 +1,120 @@
+export const AGENT_NATIVE_PACKAGE_MANIFEST_VERSION = 1 as const;
+
+export interface AgentNativePackageManifest {
+  manifestVersion: typeof AGENT_NATIVE_PACKAGE_MANIFEST_VERSION;
+  name: string;
+  actions: string[];
+  schemaEntryPoint: string;
+  docs: {
+    llms: string;
+    llmsFull: string;
+    skills: string[];
+  };
+  requiredSecrets: { key: string; label: string; optional?: boolean }[];
+  peerProviders: string[];
+  eject?: {
+    sourceRoot: string;
+    targetDirectory: string;
+  };
+}
+
+export function assertAgentNativePackageManifest(
+  value: unknown,
+): asserts value is AgentNativePackageManifest {
+  const manifest = value as Partial<AgentNativePackageManifest> | null;
+  if (!manifest || typeof manifest !== "object") {
+    throw new Error("Package manifest must be an object");
+  }
+  if (manifest.manifestVersion !== AGENT_NATIVE_PACKAGE_MANIFEST_VERSION) {
+    throw new Error(
+      `Unsupported package manifest version ${String(manifest.manifestVersion)}`,
+    );
+  }
+  if (!manifest.name || !manifest.schemaEntryPoint) {
+    throw new Error("Package manifest is missing name or schemaEntryPoint");
+  }
+  if (!/^(@[a-z0-9._-]+\/)?[a-z0-9._-]+$/.test(manifest.name)) {
+    throw new Error(`Invalid package manifest name: ${manifest.name}`);
+  }
+  if (
+    !manifest.schemaEntryPoint.startsWith(`${manifest.name}/`) ||
+    !isSafeSpecifier(manifest.schemaEntryPoint)
+  ) {
+    throw new Error("Package manifest schemaEntryPoint is unsafe");
+  }
+  if (
+    !Array.isArray(manifest.actions) ||
+    !manifest.docs ||
+    !Array.isArray(manifest.docs.skills) ||
+    !Array.isArray(manifest.requiredSecrets) ||
+    !Array.isArray(manifest.peerProviders)
+  ) {
+    throw new Error("Package manifest contribution lists are invalid");
+  }
+  for (const action of manifest.actions) {
+    if (!/^[a-z0-9][a-z0-9-]*$/.test(action)) {
+      throw new Error(`Invalid package action name: ${action}`);
+    }
+  }
+  for (const skill of manifest.docs.skills) {
+    if (!/^[a-z0-9][a-z0-9-]*$/.test(skill)) {
+      throw new Error(`Invalid package skill name: ${skill}`);
+    }
+  }
+  for (const docPath of [manifest.docs.llms, manifest.docs.llmsFull]) {
+    if (!isSafeRelativePath(docPath)) {
+      throw new Error(`Unsafe package documentation path: ${docPath}`);
+    }
+  }
+  for (const secret of manifest.requiredSecrets) {
+    if (
+      !secret ||
+      !/^[A-Z][A-Z0-9_]*$/.test(secret.key) ||
+      typeof secret.label !== "string" ||
+      secret.label.length === 0 ||
+      secret.label.length > 120 ||
+      (secret.optional !== undefined && typeof secret.optional !== "boolean")
+    ) {
+      throw new Error("Invalid package requiredSecrets entry");
+    }
+  }
+  for (const provider of manifest.peerProviders) {
+    if (
+      typeof provider !== "string" ||
+      !/^[a-z0-9][a-z0-9-]*$/.test(provider)
+    ) {
+      throw new Error(`Invalid package peer provider: ${String(provider)}`);
+    }
+  }
+  if (
+    manifest.eject &&
+    (!isSafeRelativePath(manifest.eject.sourceRoot) ||
+      !isSafeRelativePath(manifest.eject.targetDirectory))
+  ) {
+    throw new Error("Package eject paths must be safe relative paths");
+  }
+}
+
+function isSafeRelativePath(value: unknown): value is string {
+  if (typeof value !== "string" || value.length === 0 || value.includes("\\")) {
+    return false;
+  }
+  if (
+    value.includes("\0") ||
+    value.startsWith("/") ||
+    pathSegments(value).includes("..")
+  ) {
+    return false;
+  }
+  return !value.split("/").includes("");
+}
+
+function isSafeSpecifier(value: string): boolean {
+  return (
+    /^[A-Za-z0-9@._/-]+$/.test(value) && !pathSegments(value).includes("..")
+  );
+}
+
+function pathSegments(value: string): string[] {
+  return value.split("/");
+}

package/corpus/core/src/provider-api/custom-registry.ts

@@ -64,6 +64,12 @@ export interface UpsertCustomProviderArgs {
   allowedHostSuffixes?: string[];
   defaultHeaders?: Record<string, string>;
   notes?: string;
+  /**
+   * Caller's org role in the target org (`scopeId` when `scope === "org"`),
+   * resolved by the caller (e.g. `provider-api-register.ts`) before invoking
+   * this function. Required — see `assertCanMutateCustomProviderScope`.
+   */
+  orgRole: string | null;
 }
 
 // ---------------------------------------------------------------------------
@@ -258,6 +264,53 @@ export function validateAllowedHostSuffixes(suffixes: string[]): string[] {
   return normalized;
 }
 
+// ---------------------------------------------------------------------------
+// Authorization
+// ---------------------------------------------------------------------------
+
+/**
+ * Thrown by `assertCanMutateCustomProviderScope` when the caller is not
+ * authorized to mutate a scoped custom provider row.
+ */
+export class CustomProviderAuthError extends Error {
+  constructor(
+    readonly statusCode: number,
+    message: string,
+  ) {
+    super(message);
+    this.name = "CustomProviderAuthError";
+  }
+}
+
+/**
+ * Defense-in-depth authorization guard for custom-provider mutations. Mirrors
+ * `assertCanMutateScope` in `server/scoped-key-storage.ts`: user-scoped writes
+ * need no role check (each user only ever mutates their own row), but
+ * org-scoped writes require the caller to be an owner or admin of the target
+ * org (`scopeId`) — otherwise a plain member could repoint an org-wide
+ * provider's base URL or attach a different credential key name that other
+ * members' agents then trust. `scopeId` is accepted (unused today) for
+ * signature parity with `assertCanMutateScope` in case a future scope value
+ * needs it (e.g. a solo-workspace carve-out).
+ *
+ * The only caller today is `provider-api-register.ts`, which resolves
+ * `orgRole` itself and enforces this same check before calling in; this
+ * function is the second, harder-to-bypass layer so a future caller can't
+ * reintroduce the gap by forgetting to check.
+ */
+export function assertCanMutateCustomProviderScope(
+  scope: CustomProviderScope,
+  _scopeId: string,
+  orgRole: string | null,
+): void {
+  if (scope === "user") return;
+  if (orgRole === "owner" || orgRole === "admin") return;
+  throw new CustomProviderAuthError(
+    403,
+    "Only organization owners and admins can register or modify org-scoped custom providers.",
+  );
+}
+
 // ---------------------------------------------------------------------------
 // CRUD
 // ---------------------------------------------------------------------------
@@ -269,6 +322,7 @@ export function validateAllowedHostSuffixes(suffixes: string[]): string[] {
 export async function upsertCustomProvider(
   args: UpsertCustomProviderArgs,
 ): Promise<string> {
+  assertCanMutateCustomProviderScope(args.scope, args.scopeId, args.orgRole);
   await ensureTable();
   validateProviderId(args.id);
   validateAuth(args.auth);
@@ -333,7 +387,9 @@ export async function deleteCustomProvider(
   scope: CustomProviderScope,
   scopeId: string,
   id: string,
+  orgRole: string | null,
 ): Promise<boolean> {
+  assertCanMutateCustomProviderScope(scope, scopeId, orgRole);
   await ensureTable();
   const client = getDbExec();
   const { rowsAffected } = await client.execute({

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

@@ -47,6 +47,8 @@ export {
   listCustomProviders,
   getCustomProvider,
   validateCustomBaseUrl,
+  assertCanMutateCustomProviderScope,
+  CustomProviderAuthError,
 } from "./custom-registry.js";
 
 export const PROVIDER_API_IDS = [

package/corpus/core/src/secrets/storage.ts

@@ -142,37 +142,57 @@ export async function writeAppSecret(args: WriteSecretArgs): Promise<string> {
   const client = getDbExec();
   const now = Date.now();
   const encrypted = encryptValue(value);
+  const id = randomUUID();
 
-  // Upsert by (scope, scope_id, key). Keep the existing row's id on update so
-  // references stay stable.
-  const { rows } = await client.execute({
-    sql: `SELECT id FROM app_secrets WHERE scope = ? AND scope_id = ? AND key = ?`,
-    args: [scope, scopeId, key],
-  });
-  if (rows.length > 0) {
-    const id = rows[0].id as string;
-    await client.execute({
-      sql: `UPDATE app_secrets SET encrypted_value = ?, description = ?, url_allowlist = ?, updated_at = ? WHERE id = ?`,
-      args: [encrypted, description ?? null, urlAllowlist ?? null, now, id],
+  // Atomic upsert by (scope, scope_id, key). Previously this was a
+  // SELECT-then-branch (UPDATE if found, else INSERT): under concurrent
+  // writers for the same key both could see "no row" and both attempt
+  // INSERT, and the loser threw a raw UNIQUE(scope, scope_id, key)
+  // constraint violation (a user-facing 500) instead of updating. A single
+  // `INSERT ... ON CONFLICT DO UPDATE` closes that window — it's one
+  // statement, so there's no gap between "check" and "act". `id` is
+  // deliberately left out of the `DO UPDATE SET` list so an existing row
+  // keeps its original id (any stored references stay stable); only a
+  // genuinely new row gets the freshly generated `id`. This syntax is
+  // portable across SQLite (UPSERT since 3.24) and Postgres.
+  const upsertSql = `INSERT INTO app_secrets (id, scope, scope_id, key, encrypted_value, description, url_allowlist, created_at, updated_at)
+    VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)
+    ON CONFLICT (scope, scope_id, key) DO UPDATE SET
+      encrypted_value = excluded.encrypted_value,
+      description = excluded.description,
+      url_allowlist = excluded.url_allowlist,
+      updated_at = excluded.updated_at`;
+  const upsertArgs = [
+    id,
+    scope,
+    scopeId,
+    key,
+    encrypted,
+    description ?? null,
+    urlAllowlist ?? null,
+    now,
+    now,
+  ];
+
+  if (isPostgres()) {
+    const { rows } = await client.execute({
+      sql: `${upsertSql} RETURNING id`,
+      args: upsertArgs,
     });
-    return id;
+    return String(rows[0]?.id ?? id);
   }
-  const id = randomUUID();
-  await client.execute({
-    sql: `INSERT INTO app_secrets (id, scope, scope_id, key, encrypted_value, description, url_allowlist, created_at, updated_at) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)`,
-    args: [
-      id,
-      scope,
-      scopeId,
-      key,
-      encrypted,
-      description ?? null,
-      urlAllowlist ?? null,
-      now,
-      now,
-    ],
+
+  // SQLite: RETURNING support varies across better-sqlite3/libsql builds, so
+  // (matching the convention elsewhere in this codebase, e.g.
+  // integrations/pending-tasks-store.ts) re-read the id afterward instead of
+  // relying on it. The row is guaranteed to exist at this point, so this is
+  // a plain lookup rather than a TOCTOU-prone gate on the write itself.
+  await client.execute({ sql: upsertSql, args: upsertArgs });
+  const { rows } = await client.execute({
+    sql: `SELECT id FROM app_secrets WHERE scope = ? AND scope_id = ? AND key = ? LIMIT 1`,
+    args: [scope, scopeId, key],
   });
-  return id;
+  return String(rows[0]?.id ?? id);
 }
 
 export interface ReadSecretResult {
@@ -181,6 +201,40 @@ export interface ReadSecretResult {
   updatedAt: number;
 }
 
+type AppSecretsReadQuery = { sql: string; args: unknown[] };
+
+/**
+ * True only when the database says the app_secrets table itself is missing.
+ * Other query failures must propagate unchanged: attempting schema bootstrap
+ * for connectivity, permission, or syntax errors both hides the real failure
+ * and can introduce DDL onto a latency-sensitive read path.
+ */
+function isMissingAppSecretsTableError(error: unknown): boolean {
+  if (!(error instanceof Error)) return false;
+  const code = String((error as Error & { code?: unknown }).code ?? "");
+  const message = error.message.toLowerCase();
+  const namesAppSecrets = /(?:app_secrets|"app_secrets")/.test(message);
+
+  if (code === "42P01") return namesAppSecrets;
+  return (
+    namesAppSecrets &&
+    (message.includes("no such table") ||
+      (message.includes("relation") && message.includes("does not exist")))
+  );
+}
+
+/** Execute a read without schema probes on the normal path. */
+async function executeAppSecretsRead(query: AppSecretsReadQuery) {
+  const client = getDbExec();
+  try {
+    return await client.execute(query);
+  } catch (error) {
+    if (!isMissingAppSecretsTableError(error)) throw error;
+    await ensureTable();
+    return client.execute(query);
+  }
+}
+
 /**
  * Read a secret's plaintext value. Returns null when not found. The caller
  * is responsible for never logging the returned value.
@@ -188,10 +242,8 @@ export interface ReadSecretResult {
 export async function readAppSecret(
   ref: SecretRef,
 ): Promise<ReadSecretResult | null> {
-  await ensureTable();
   const { key, scope, scopeId } = ref;
-  const client = getDbExec();
-  const { rows } = await client.execute({
+  const { rows } = await executeAppSecretsRead({
     sql: `SELECT encrypted_value, updated_at FROM app_secrets WHERE scope = ? AND scope_id = ? AND key = ? LIMIT 1`,
     args: [scope, scopeId, key],
   });
@@ -210,6 +262,38 @@ export async function readAppSecret(
   }
 }
 
+/** Read several keys from one scope in a single database round trip. */
+export async function readAppSecrets(args: {
+  keys: readonly string[];
+  scope: SecretScope;
+  scopeId: string;
+}): Promise<Map<string, ReadSecretResult>> {
+  const keys = [...new Set(args.keys.filter(Boolean))];
+  if (keys.length === 0) return new Map();
+
+  const placeholders = keys.map(() => "?").join(", ");
+  const { rows } = await executeAppSecretsRead({
+    sql: `SELECT key, encrypted_value, updated_at FROM app_secrets WHERE scope = ? AND scope_id = ? AND key IN (${placeholders})`,
+    args: [args.scope, args.scopeId, ...keys],
+  });
+  const results = new Map<string, ReadSecretResult>();
+  for (const row of rows) {
+    const key = String(row.key ?? "");
+    if (!key) continue;
+    try {
+      const value = decryptValue(row.encrypted_value as string);
+      results.set(key, {
+        value,
+        last4: last4(value),
+        updatedAt: Number(row.updated_at ?? 0),
+      });
+    } catch {
+      // Match readAppSecret: corrupted or stale ciphertext behaves as missing.
+    }
+  }
+  return results;
+}
+
 /**
  * Return just the metadata for a secret (no value). Used by the list route so
  * the UI can show the "Set" pill and last-4 without the decrypted value going

package/corpus/core/src/server/action-discovery.ts

@@ -606,6 +606,10 @@ export async function mergeCoreSharingActions(
       () => import("../audit/actions/list-audit-events.js"),
     ],
     ["get-audit-event", () => import("../audit/actions/get-audit-event.js")],
+    [
+      "export-audit-events",
+      () => import("../audit/actions/export-audit-events.js"),
+    ],
     // History kit — reusable version snapshots and restore surface.
     [
       "create-resource-version",

package/corpus/core/src/server/agent-chat/action-filters-a2a.ts

@@ -0,0 +1,199 @@
+import { getHeader } from "h3";
+
+import {
+  appendA2AArtifactLinks,
+  type A2AArtifactResponseOptions,
+  type A2AToolResultSummary,
+} from "../../a2a/artifact-response.js";
+import { collectFinalResponseTextFromAgentEvents } from "../../a2a/response-text.js";
+import type { EngineTool } from "../../agent/engine/types.js";
+import {
+  filterInitialEngineTools,
+  type ActionEntry,
+} from "../../agent/production-agent.js";
+import { runAgentLoopDirectWithSoftTimeout } from "../../agent/run-loop-with-resume.js";
+import type { AgentChatEvent } from "../../agent/types.js";
+import { withConfiguredAppBasePath } from "../app-base-path.js";
+import type { AgentChatPluginOptions } from "./plugin-options.js";
+
+// ---------------------------------------------------------------------------
+// Action-visibility filters (read-only / agent-exposed / public-agent-safe)
+// and the A2A (agent-to-agent) final-response assembly + delegated-run
+// helpers that share those filters.
+// ---------------------------------------------------------------------------
+
+export function filterReadOnlyActions(
+  actions: Record<string, ActionEntry>,
+): Record<string, ActionEntry> {
+  return Object.fromEntries(
+    Object.entries(actions).filter(([, entry]) => entry.readOnly === true),
+  );
+}
+
+/** Drop actions that opted out of agent exposure via `agentTool: false`. They
+ *  remain callable from the frontend / HTTP (mounted separately from this
+ *  agent tool surface — see `httpActions`) but never appear in any agent tool
+ *  list (in-app assistant, MCP, A2A, job/trigger runners) or actions prompt.
+ *  Default-allow: only an explicit `false` is excluded. */
+export function filterAgentTools(
+  actions: Record<string, ActionEntry>,
+): Record<string, ActionEntry> {
+  return Object.fromEntries(
+    Object.entries(actions).filter(([, entry]) => entry.agentTool !== false),
+  );
+}
+
+export function filterPublicAgentActions(
+  actions: Record<string, ActionEntry>,
+): Record<string, ActionEntry> {
+  return Object.fromEntries(
+    Object.entries(actions).filter(([, entry]) => {
+      const config = entry.publicAgent;
+      return (
+        config?.expose === true &&
+        config.readOnly === true &&
+        config.requiresAuth !== true &&
+        config.isConsequential !== true
+      );
+    }),
+  );
+}
+
+export function buildPublicAgentA2ASkills(
+  actions: Record<string, ActionEntry>,
+): Array<{
+  id: string;
+  name: string;
+  description: string;
+  publicAgent: ActionEntry["publicAgent"];
+}> {
+  return Object.entries(filterPublicAgentActions(actions)).map(
+    ([name, entry]) => ({
+      id: name,
+      name,
+      description: entry.tool.description,
+      publicAgent: entry.publicAgent,
+    }),
+  );
+}
+
+export function resolveArtifactBaseUrl(
+  event: any | undefined,
+): string | undefined {
+  const fromEnv =
+    process.env.APP_URL ||
+    process.env.URL ||
+    process.env.DEPLOY_URL ||
+    process.env.BETTER_AUTH_URL;
+  if (fromEnv) return withConfiguredAppBasePath(String(fromEnv));
+
+  try {
+    const proto = getHeader(event, "x-forwarded-proto") || "https";
+    const host = getHeader(event, "host");
+    if (host) return withConfiguredAppBasePath(`${proto}://${host}`);
+  } catch {}
+
+  return undefined;
+}
+
+export function assembleA2AFinalResponse(
+  events: readonly AgentChatEvent[],
+  toolResults: readonly A2AToolResultSummary[],
+  options: A2AArtifactResponseOptions & { event?: any } = {},
+): { responseText: string; finalText: string } {
+  const terminalError = getA2ATerminalErrorEvent(events);
+  const responseText = collectFinalResponseTextFromAgentEvents(events, {
+    fallbackToPreToolText: !terminalError,
+  });
+  const finalText = appendA2AArtifactLinks(responseText, [...toolResults], {
+    baseUrl: options.baseUrl ?? resolveArtifactBaseUrl(options.event),
+    includeReferencedArtifacts: true,
+  });
+  if (terminalError && !finalText.trim()) {
+    throw new Error(formatA2ATerminalError(terminalError));
+  }
+  return { responseText, finalText };
+}
+
+function getA2ATerminalErrorEvent(
+  events: readonly AgentChatEvent[],
+): Extract<AgentChatEvent, { type: "error" }> | null {
+  for (let i = events.length - 1; i >= 0; i--) {
+    const event = events[i];
+    if (event.type === "clear") continue;
+    if (event.type === "done") return null;
+    if (event.type === "error") return event;
+    if (event.type === "auto_continue") {
+      return {
+        type: "error",
+        error: `Agent stopped before finishing (${event.reason}).`,
+        errorCode: event.reason,
+        recoverable: true,
+      };
+    }
+  }
+  return null;
+}
+
+function formatA2ATerminalError(
+  event: Extract<AgentChatEvent, { type: "error" }>,
+): string {
+  const parts = [
+    event.error || "Agent failed before producing a final response.",
+    event.errorCode ? `code: ${event.errorCode}` : "",
+    event.details ? `details: ${event.details}` : "",
+  ].filter(Boolean);
+  return parts.join("\n");
+}
+
+type A2AAgentLoopRunner = typeof runAgentLoopDirectWithSoftTimeout;
+
+/**
+ * Run an A2A-delegated agent turn with the same final-response guard used by
+ * the app's interactive chat surface.
+ *
+ * Keeping this in one helper prevents delegated calls from silently bypassing
+ * template guarantees such as Analytics' requirement to query real data
+ * before presenting metrics or exhaustive provider conclusions.
+ */
+export function runA2AAgentLoop(
+  runOptions: Parameters<A2AAgentLoopRunner>[0],
+  pluginOptions: Pick<
+    AgentChatPluginOptions,
+    "finalResponseGuard" | "runSoftTimeoutMs"
+  >,
+  timeoutOptions: Parameters<A2AAgentLoopRunner>[2],
+  runner: A2AAgentLoopRunner = runAgentLoopDirectWithSoftTimeout,
+) {
+  return runner(
+    {
+      ...runOptions,
+      finalResponseGuard: pluginOptions.finalResponseGuard,
+    },
+    pluginOptions.runSoftTimeoutMs,
+    timeoutOptions,
+  );
+}
+
+/**
+ * Keep delegated A2A turns on the same compact initial tool surface as
+ * interactive chat. `tool-search` remains in the initial set, while the
+ * complete registry is supplied separately so the run loop can load a matched
+ * schema after a tool-search result.
+ */
+export function createA2AEngineToolSurface(
+  availableTools: EngineTool[],
+  initialToolNames?: string[],
+): { tools: EngineTool[]; availableTools: EngineTool[] } {
+  return {
+    tools: filterInitialEngineTools(availableTools, initialToolNames),
+    availableTools,
+  };
+}
+
+export function resolveInitialToolNames(
+  templateActions: Record<string, ActionEntry>,
+  configured?: string[],
+): string[] {
+  return configured ?? Object.keys(templateActions);
+}