@ekanos/sdk 0.1.1 → 0.1.3

package/dist/mcp/ownership.d.ts

@@ -1,74 +0,0 @@
-/**
- * Ownership guards for member-facing MCP tools.
- *
- * The LLM controls tool arguments. Any member-facing tool that accepts an
- * external per-user identifier (a Wild Apricot contactId, a Discourse
- * username, a LearnWorlds learner id, etc.) is a cross-member data-exposure
- * risk: the caller can pass *someone else's* id and read or act on their
- * data. The org-membership gate (`ensureAccountMembership`) does not catch
- * this — it answers "is this person in the org?", never "is this person's
- * own data?".
- *
- * These helpers make the safe path the default. A tool author reaches for
- * `resolveSelfOnly` instead of writing a bespoke "default to me" resolver,
- * and gets ownership enforcement for free.
- *
- * Resolving "who am I" is integration-specific (each integration maps the
- * Supabase user to its own id space), so the caller supplies `resolveSelf`.
- */
-/**
- * Thrown when a tool caller attempts to access or act on another user's
- * data. Tool `run` bodies should let this propagate (or convert it to a
- * `{ error }` result) — the assistant surfaces a "not permitted" message
- * rather than the forbidden data.
- */
-export declare class ToolOwnershipError extends Error {
-    readonly code = "FORBIDDEN_OWNERSHIP";
-    constructor(resourceLabel?: string);
-}
-/**
- * Self-only identity resolution for member-facing tools.
- *
- *   - caller supplied no id        → returns the caller's own id
- *   - caller supplied their own id → returns it
- *   - caller supplied a different id → throws ToolOwnershipError
- *
- * @example
- *   // In a Wild Apricot read tool:
- *   const contactId = await resolveSelfOnly({
- *     requestedId: args.contactId,
- *     resolveSelf: () => resolveWaContactId(accountId),
- *     resourceLabel: 'member data',
- *   });
- */
-export declare function resolveSelfOnly<TId extends string | number>(params: {
-    /** The identifier the LLM supplied as a tool argument, if any. */
-    requestedId?: TId | null;
-    /** Integration-specific resolver for the calling user's own id. */
-    resolveSelf: () => Promise<TId>;
-    /** Human-readable noun for the error message, e.g. 'member profile'. */
-    resourceLabel?: string;
-}): Promise<TId>;
-/**
- * Ownership verification for tools that act on an opaque resource id (an
- * event registration, a saved document, an invoice) where ownership cannot
- * be inferred from the id itself. Resolves the resource's owner and the
- * caller's own id and throws if they differ (or if the resource has no
- * resolvable owner — fail closed).
- *
- * @example
- *   // In a Wild Apricot cancel tool:
- *   await assertResourceOwnership({
- *     resolveSelf: () => resolveWaContactId(accountId),
- *     resolveOwner: async () => {
- *       const regs = await getContactRegistrations(accountId, await resolveWaContactId(accountId));
- *       return regs.find((r) => r.Id === registrationId)?.Contact.Id;
- *     },
- *     resourceLabel: 'event registration',
- *   });
- */
-export declare function assertResourceOwnership<TId extends string | number>(params: {
-    resolveSelf: () => Promise<TId>;
-    resolveOwner: () => Promise<TId | null | undefined>;
-    resourceLabel?: string;
-}): Promise<void>;

package/dist/mcp/ownership.js

@@ -1,83 +0,0 @@
-/**
- * Ownership guards for member-facing MCP tools.
- *
- * The LLM controls tool arguments. Any member-facing tool that accepts an
- * external per-user identifier (a Wild Apricot contactId, a Discourse
- * username, a LearnWorlds learner id, etc.) is a cross-member data-exposure
- * risk: the caller can pass *someone else's* id and read or act on their
- * data. The org-membership gate (`ensureAccountMembership`) does not catch
- * this — it answers "is this person in the org?", never "is this person's
- * own data?".
- *
- * These helpers make the safe path the default. A tool author reaches for
- * `resolveSelfOnly` instead of writing a bespoke "default to me" resolver,
- * and gets ownership enforcement for free.
- *
- * Resolving "who am I" is integration-specific (each integration maps the
- * Supabase user to its own id space), so the caller supplies `resolveSelf`.
- */
-/**
- * Thrown when a tool caller attempts to access or act on another user's
- * data. Tool `run` bodies should let this propagate (or convert it to a
- * `{ error }` result) — the assistant surfaces a "not permitted" message
- * rather than the forbidden data.
- */
-export class ToolOwnershipError extends Error {
-    constructor(resourceLabel = 'data') {
-        super(`Forbidden: you can only access your own ${resourceLabel}.`);
-        this.code = 'FORBIDDEN_OWNERSHIP';
-        this.name = 'ToolOwnershipError';
-    }
-}
-/**
- * Self-only identity resolution for member-facing tools.
- *
- *   - caller supplied no id        → returns the caller's own id
- *   - caller supplied their own id → returns it
- *   - caller supplied a different id → throws ToolOwnershipError
- *
- * @example
- *   // In a Wild Apricot read tool:
- *   const contactId = await resolveSelfOnly({
- *     requestedId: args.contactId,
- *     resolveSelf: () => resolveWaContactId(accountId),
- *     resourceLabel: 'member data',
- *   });
- */
-export async function resolveSelfOnly(params) {
-    const selfId = await params.resolveSelf();
-    if (params.requestedId !== undefined &&
-        params.requestedId !== null &&
-        params.requestedId !== selfId) {
-        throw new ToolOwnershipError(params.resourceLabel);
-    }
-    return selfId;
-}
-/**
- * Ownership verification for tools that act on an opaque resource id (an
- * event registration, a saved document, an invoice) where ownership cannot
- * be inferred from the id itself. Resolves the resource's owner and the
- * caller's own id and throws if they differ (or if the resource has no
- * resolvable owner — fail closed).
- *
- * @example
- *   // In a Wild Apricot cancel tool:
- *   await assertResourceOwnership({
- *     resolveSelf: () => resolveWaContactId(accountId),
- *     resolveOwner: async () => {
- *       const regs = await getContactRegistrations(accountId, await resolveWaContactId(accountId));
- *       return regs.find((r) => r.Id === registrationId)?.Contact.Id;
- *     },
- *     resourceLabel: 'event registration',
- *   });
- */
-export async function assertResourceOwnership(params) {
-    const [selfId, ownerId] = await Promise.all([
-        params.resolveSelf(),
-        params.resolveOwner(),
-    ]);
-    if (ownerId === null || ownerId === undefined || ownerId !== selfId) {
-        throw new ToolOwnershipError(params.resourceLabel);
-    }
-}
-//# sourceMappingURL=ownership.js.map

package/dist/mcp/ownership.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"ownership.js","sourceRoot":"","sources":["../../src/mcp/ownership.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAEH;;;;;GAKG;AACH,MAAM,OAAO,kBAAmB,SAAQ,KAAK;IAG3C,YAAY,aAAa,GAAG,MAAM;QAChC,KAAK,CAAC,2CAA2C,aAAa,GAAG,CAAC,CAAC;QAH5D,SAAI,GAAG,qBAAqB,CAAC;QAIpC,IAAI,CAAC,IAAI,GAAG,oBAAoB,CAAC;IACnC,CAAC;CACF;AAED;;;;;;;;;;;;;;GAcG;AACH,MAAM,CAAC,KAAK,UAAU,eAAe,CAA8B,MAOlE;IACC,MAAM,MAAM,GAAG,MAAM,MAAM,CAAC,WAAW,EAAE,CAAC;IAE1C,IACE,MAAM,CAAC,WAAW,KAAK,SAAS;QAChC,MAAM,CAAC,WAAW,KAAK,IAAI;QAC3B,MAAM,CAAC,WAAW,KAAK,MAAM,EAC7B,CAAC;QACD,MAAM,IAAI,kBAAkB,CAAC,MAAM,CAAC,aAAa,CAAC,CAAC;IACrD,CAAC;IAED,OAAO,MAAM,CAAC;AAChB,CAAC;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAM,CAAC,KAAK,UAAU,uBAAuB,CAE3C,MAID;IACC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,MAAM,OAAO,CAAC,GAAG,CAAC;QAC1C,MAAM,CAAC,WAAW,EAAE;QACpB,MAAM,CAAC,YAAY,EAAE;KACtB,CAAC,CAAC;IAEH,IAAI,OAAO,KAAK,IAAI,IAAI,OAAO,KAAK,SAAS,IAAI,OAAO,KAAK,MAAM,EAAE,CAAC;QACpE,MAAM,IAAI,kBAAkB,CAAC,MAAM,CAAC,aAAa,CAAC,CAAC;IACrD,CAAC;AACH,CAAC","sourcesContent":["/**\n * Ownership guards for member-facing MCP tools.\n *\n * The LLM controls tool arguments. Any member-facing tool that accepts an\n * external per-user identifier (a Wild Apricot contactId, a Discourse\n * username, a LearnWorlds learner id, etc.) is a cross-member data-exposure\n * risk: the caller can pass *someone else's* id and read or act on their\n * data. The org-membership gate (`ensureAccountMembership`) does not catch\n * this — it answers \"is this person in the org?\", never \"is this person's\n * own data?\".\n *\n * These helpers make the safe path the default. A tool author reaches for\n * `resolveSelfOnly` instead of writing a bespoke \"default to me\" resolver,\n * and gets ownership enforcement for free.\n *\n * Resolving \"who am I\" is integration-specific (each integration maps the\n * Supabase user to its own id space), so the caller supplies `resolveSelf`.\n */\n\n/**\n * Thrown when a tool caller attempts to access or act on another user's\n * data. Tool `run` bodies should let this propagate (or convert it to a\n * `{ error }` result) — the assistant surfaces a \"not permitted\" message\n * rather than the forbidden data.\n */\nexport class ToolOwnershipError extends Error {\n  readonly code = 'FORBIDDEN_OWNERSHIP';\n\n  constructor(resourceLabel = 'data') {\n    super(`Forbidden: you can only access your own ${resourceLabel}.`);\n    this.name = 'ToolOwnershipError';\n  }\n}\n\n/**\n * Self-only identity resolution for member-facing tools.\n *\n *   - caller supplied no id        → returns the caller's own id\n *   - caller supplied their own id → returns it\n *   - caller supplied a different id → throws ToolOwnershipError\n *\n * @example\n *   // In a Wild Apricot read tool:\n *   const contactId = await resolveSelfOnly({\n *     requestedId: args.contactId,\n *     resolveSelf: () => resolveWaContactId(accountId),\n *     resourceLabel: 'member data',\n *   });\n */\nexport async function resolveSelfOnly<TId extends string | number>(params: {\n  /** The identifier the LLM supplied as a tool argument, if any. */\n  requestedId?: TId | null;\n  /** Integration-specific resolver for the calling user's own id. */\n  resolveSelf: () => Promise<TId>;\n  /** Human-readable noun for the error message, e.g. 'member profile'. */\n  resourceLabel?: string;\n}): Promise<TId> {\n  const selfId = await params.resolveSelf();\n\n  if (\n    params.requestedId !== undefined &&\n    params.requestedId !== null &&\n    params.requestedId !== selfId\n  ) {\n    throw new ToolOwnershipError(params.resourceLabel);\n  }\n\n  return selfId;\n}\n\n/**\n * Ownership verification for tools that act on an opaque resource id (an\n * event registration, a saved document, an invoice) where ownership cannot\n * be inferred from the id itself. Resolves the resource's owner and the\n * caller's own id and throws if they differ (or if the resource has no\n * resolvable owner — fail closed).\n *\n * @example\n *   // In a Wild Apricot cancel tool:\n *   await assertResourceOwnership({\n *     resolveSelf: () => resolveWaContactId(accountId),\n *     resolveOwner: async () => {\n *       const regs = await getContactRegistrations(accountId, await resolveWaContactId(accountId));\n *       return regs.find((r) => r.Id === registrationId)?.Contact.Id;\n *     },\n *     resourceLabel: 'event registration',\n *   });\n */\nexport async function assertResourceOwnership<\n  TId extends string | number,\n>(params: {\n  resolveSelf: () => Promise<TId>;\n  resolveOwner: () => Promise<TId | null | undefined>;\n  resourceLabel?: string;\n}): Promise<void> {\n  const [selfId, ownerId] = await Promise.all([\n    params.resolveSelf(),\n    params.resolveOwner(),\n  ]);\n\n  if (ownerId === null || ownerId === undefined || ownerId !== selfId) {\n    throw new ToolOwnershipError(params.resourceLabel);\n  }\n}\n"]}

package/dist/mcp/types.d.ts

@@ -1,145 +0,0 @@
-import type { SupabaseClient } from '@supabase/supabase-js';
-import type { IntegrationContext } from '@ekanos/integration-schema';
-export type ToolParamsSchema = {
-    type: 'object';
-    properties?: Record<string, unknown>;
-    required?: string[];
-    additionalProperties?: boolean;
-};
-export type ToolContext = {
-    req: Request;
-    /**
-     * Admin Supabase client for in-process MCP execution.
-     * This bypasses RLS; tools must perform their own authorization checks before
-     * reading or mutating protected data.
-     */
-    supabase: SupabaseClient;
-    user: {
-        id: string;
-    } & Record<string, unknown>;
-    /** The resolved account slug from the workspace context (injected by MCP route) */
-    accountSlug?: string;
-    /** The resolved account ID (UUID) from the workspace context (injected by MCP route) */
-    accountId?: string;
-    /** The resolved source ID (UUID) for the current tenant/workspace */
-    sourceId?: string | null;
-    /** The user's resolved IANA timezone (e.g. 'America/New_York') */
-    timezone?: string;
-    /** Whether the authenticated user is a platform super-admin */
-    isSuperAdmin?: boolean;
-    /**
-     * Who is executing this tool call.
-     *
-     * Undefined (the default for every user-facing MCP path) is treated as
-     * `'user'` — the historical behavior. `'machine'` marks a non-interactive
-     * caller (the Workflow Gateway) whose identity IS the account-bound gateway
-     * token, not a signed-in session. See machineGrant below and the
-     * "Machine-principal design" section of context/N8N_INTEGRATION_PLAN.md.
-     */
-    principal?: 'user' | 'machine';
-    /**
-     * Present only when `principal === 'machine'`. Carries the account the
-     * gateway token is bound to (the sole source of account identity for a
-     * machine call), the token row id, and the token creator for audit
-     * attribution. `getAccountId` / `ensureAccountMembership` read this instead
-     * of doing a DB membership lookup — the token itself is the authorization.
-     */
-    machineGrant?: {
-        accountId: string;
-        tokenId: string;
-        createdBy: string | null;
-    };
-    /**
-     * The host-built capability context
-     * (docs/devex/capability-context-proposal.md), attached ADDITIVELY by the
-     * MCP route after authorization. This is the CANONICAL `IntegrationContext`
-     * from `@ekanos/integration-schema` — the same declaration `@ekanos/sdk`
-     * re-exports, so there is no structural twin to drift and no core→SDK
-     * package cycle. Migrated tools may still narrow it with
-     * `requireContext(ctx)` from `@ekanos/sdk/context`; existing tools that
-     * never touch this field are unaffected.
-     */
-    integrationContext?: IntegrationContext;
-};
-export type ToolRunResult = unknown;
-/**
- * The partner execution channel — the ONLY way partner-authored tool code
- * runs (capability-context proposal §3 + sdk-export-map.md adversarial
- * review outcomes 1–2).
- *
- * The first argument is the host-built capability context — the canonical
- * `IntegrationContext` from `@ekanos/integration-schema`, the one declaration
- * both `@ekanos/sdk` (authoring) and this package (host) import. The
- * client-bearing `ToolContext` (req, admin supabase, identity fields) is
- * structurally absent from this signature — a partner tool cannot reach it.
- */
-export type PartnerToolRun = (integrationContext: IntegrationContext, args: Record<string, unknown>) => Promise<ToolRunResult>;
-export type ToolModule = {
-    name: string;
-    description?: string;
-    parameters?: ToolParamsSchema;
-    run: (ctx: ToolContext, args: Record<string, unknown>) => Promise<ToolRunResult>;
-    /**
-     * Partner EXECUTION function. Set by host adapter code
-     * (`registerPartnerIntegration`'s tool adapter) alongside the host BRAND
-     * (`brandPartnerTool`, mcp/helpers.ts) — never by first-party tool modules.
-     *
-     * IMPORTANT: this property is NOT the partner classification authority
-     * (that is the module-private WeakSet brand — a property can be forged,
-     * stripped, or varied between reads). For a host-branded tool the executor:
-     * - invokes `partnerRun(integrationContext, args)` with the host-built
-     *   capability context and NOTHING else (no ToolContext, no prepareArgs,
-     *   no toUi);
-     * - FAILS CLOSED if the capability context or this function is missing —
-     *   there is no legacy-context fallback for a branded tool.
-     *
-     * An UNBRANDED object carrying this property is treated as first-party and
-     * can never reach the partner path — so a partner cannot escape into, and a
-     * spoofed property cannot fake, the capability-only channel.
-     */
-    partnerRun?: PartnerToolRun;
-    prepareArgs?: (ctx: ToolContext, rawArgs: unknown) => Promise<Record<string, unknown>>;
-    ui?: UiComponentMeta | UiComponentMeta[];
-    toUi?: (ctx: ToolContext, result: unknown) => Promise<null | RenderInstruction | RenderInstruction[]>;
-    /**
-     * Side-effect classification — used by the SOC 2 audit log to decide
-     * whether the call is recorded. When omitted, the audit layer derives
-     * it from the tool name (read-verb prefixes → 'read', otherwise 'write').
-     * Tool authors should set this explicitly when the heuristic would be
-     * wrong (e.g. a `generate_*` tool that materially mutates server state).
-     * See packages/agents/src/security/tool-effect.ts.
-     */
-    effect?: 'read' | 'write';
-    /**
-     * Data classification of what this tool exposes. Mirror of
-     * `Sensitivity` in packages/agents/src/security/redact.ts — kept inline
-     * here to avoid a backwards dependency from integrations-core onto agents.
-     * Reads that expose 'pii' or 'financial' data are recorded in the audit
-     * log even though they are not writes. Defaults to undefined (treated
-     * as 'internal' by the audit filter, 'pii' by the redaction layer).
-     */
-    sensitivity?: 'public' | 'internal' | 'pii' | 'financial';
-    /**
-     * A REPRESENTATIVE example of this tool's SUCCESS return value (top-level
-     * shape, minimal realistic values, arrays trimmed to one element). Consumed
-     * by the workflow authoring layer two ways:
-     *   1. Codegen grounding — the example is embedded in the workflow-generation
-     *      prompt so the model wires `{{stepId.field}}` refs against the tool's
-     *      REAL output keys instead of guessing (`deals` vs `contacts`,
-     *      `contact_id` vs `contactId` — observed failure class).
-     *   2. Ref linting — a workflow ref into this tool's output whose first path
-     *      segment is not a key of this example is rejected at authoring time.
-     * Keep it SMALL (it ships in prompts), faithful to the actual run() return,
-     * and free of real customer data. Omitting it just skips both uses.
-     */
-    outputExample?: Record<string, unknown>;
-};
-export type UiComponentMeta = {
-    component: string;
-    propsSchema: ToolParamsSchema;
-    doc?: string;
-};
-export type RenderInstruction = {
-    component: string;
-    props: unknown;
-};

package/dist/mcp/types.js

@@ -1,2 +0,0 @@
-export {};
-//# sourceMappingURL=types.js.map

package/dist/mcp/types.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/mcp/types.ts"],"names":[],"mappings":"","sourcesContent":["import type { SupabaseClient } from '@supabase/supabase-js';\n\nimport type { IntegrationContext } from '@ekanos/integration-schema';\n\nexport type ToolParamsSchema = {\n  type: 'object';\n  properties?: Record<string, unknown>;\n  required?: string[];\n  additionalProperties?: boolean;\n};\n\nexport type ToolContext = {\n  req: Request;\n  /**\n   * Admin Supabase client for in-process MCP execution.\n   * This bypasses RLS; tools must perform their own authorization checks before\n   * reading or mutating protected data.\n   */\n  supabase: SupabaseClient;\n  user: { id: string } & Record<string, unknown>;\n  /** The resolved account slug from the workspace context (injected by MCP route) */\n  accountSlug?: string;\n  /** The resolved account ID (UUID) from the workspace context (injected by MCP route) */\n  accountId?: string;\n  /** The resolved source ID (UUID) for the current tenant/workspace */\n  sourceId?: string | null;\n  /** The user's resolved IANA timezone (e.g. 'America/New_York') */\n  timezone?: string;\n  /** Whether the authenticated user is a platform super-admin */\n  isSuperAdmin?: boolean;\n  /**\n   * Who is executing this tool call.\n   *\n   * Undefined (the default for every user-facing MCP path) is treated as\n   * `'user'` — the historical behavior. `'machine'` marks a non-interactive\n   * caller (the Workflow Gateway) whose identity IS the account-bound gateway\n   * token, not a signed-in session. See machineGrant below and the\n   * \"Machine-principal design\" section of context/N8N_INTEGRATION_PLAN.md.\n   */\n  principal?: 'user' | 'machine';\n  /**\n   * Present only when `principal === 'machine'`. Carries the account the\n   * gateway token is bound to (the sole source of account identity for a\n   * machine call), the token row id, and the token creator for audit\n   * attribution. `getAccountId` / `ensureAccountMembership` read this instead\n   * of doing a DB membership lookup — the token itself is the authorization.\n   */\n  machineGrant?: {\n    accountId: string;\n    tokenId: string;\n    createdBy: string | null;\n  };\n  /**\n   * The host-built capability context\n   * (docs/devex/capability-context-proposal.md), attached ADDITIVELY by the\n   * MCP route after authorization. This is the CANONICAL `IntegrationContext`\n   * from `@ekanos/integration-schema` — the same declaration `@ekanos/sdk`\n   * re-exports, so there is no structural twin to drift and no core→SDK\n   * package cycle. Migrated tools may still narrow it with\n   * `requireContext(ctx)` from `@ekanos/sdk/context`; existing tools that\n   * never touch this field are unaffected.\n   */\n  integrationContext?: IntegrationContext;\n};\n\nexport type ToolRunResult = unknown;\n\n/**\n * The partner execution channel — the ONLY way partner-authored tool code\n * runs (capability-context proposal §3 + sdk-export-map.md adversarial\n * review outcomes 1–2).\n *\n * The first argument is the host-built capability context — the canonical\n * `IntegrationContext` from `@ekanos/integration-schema`, the one declaration\n * both `@ekanos/sdk` (authoring) and this package (host) import. The\n * client-bearing `ToolContext` (req, admin supabase, identity fields) is\n * structurally absent from this signature — a partner tool cannot reach it.\n */\nexport type PartnerToolRun = (\n  integrationContext: IntegrationContext,\n  args: Record<string, unknown>,\n) => Promise<ToolRunResult>;\n\nexport type ToolModule = {\n  name: string;\n  description?: string;\n  parameters?: ToolParamsSchema;\n  run: (\n    ctx: ToolContext,\n    args: Record<string, unknown>,\n  ) => Promise<ToolRunResult>;\n\n  /**\n   * Partner EXECUTION function. Set by host adapter code\n   * (`registerPartnerIntegration`'s tool adapter) alongside the host BRAND\n   * (`brandPartnerTool`, mcp/helpers.ts) — never by first-party tool modules.\n   *\n   * IMPORTANT: this property is NOT the partner classification authority\n   * (that is the module-private WeakSet brand — a property can be forged,\n   * stripped, or varied between reads). For a host-branded tool the executor:\n   * - invokes `partnerRun(integrationContext, args)` with the host-built\n   *   capability context and NOTHING else (no ToolContext, no prepareArgs,\n   *   no toUi);\n   * - FAILS CLOSED if the capability context or this function is missing —\n   *   there is no legacy-context fallback for a branded tool.\n   *\n   * An UNBRANDED object carrying this property is treated as first-party and\n   * can never reach the partner path — so a partner cannot escape into, and a\n   * spoofed property cannot fake, the capability-only channel.\n   */\n  partnerRun?: PartnerToolRun;\n\n  // Optional advanced features\n  // Compute/override arguments from context so the model doesn't need to supply them\n  prepareArgs?: (\n    ctx: ToolContext,\n    rawArgs: unknown,\n  ) => Promise<Record<string, unknown>>;\n\n  // UI rendering support: declare components and map results to render instructions\n  ui?: UiComponentMeta | UiComponentMeta[];\n  toUi?: (\n    ctx: ToolContext,\n    result: unknown,\n  ) => Promise<null | RenderInstruction | RenderInstruction[]>;\n\n  /**\n   * Side-effect classification — used by the SOC 2 audit log to decide\n   * whether the call is recorded. When omitted, the audit layer derives\n   * it from the tool name (read-verb prefixes → 'read', otherwise 'write').\n   * Tool authors should set this explicitly when the heuristic would be\n   * wrong (e.g. a `generate_*` tool that materially mutates server state).\n   * See packages/agents/src/security/tool-effect.ts.\n   */\n  effect?: 'read' | 'write';\n\n  /**\n   * Data classification of what this tool exposes. Mirror of\n   * `Sensitivity` in packages/agents/src/security/redact.ts — kept inline\n   * here to avoid a backwards dependency from integrations-core onto agents.\n   * Reads that expose 'pii' or 'financial' data are recorded in the audit\n   * log even though they are not writes. Defaults to undefined (treated\n   * as 'internal' by the audit filter, 'pii' by the redaction layer).\n   */\n  sensitivity?: 'public' | 'internal' | 'pii' | 'financial';\n\n  /**\n   * A REPRESENTATIVE example of this tool's SUCCESS return value (top-level\n   * shape, minimal realistic values, arrays trimmed to one element). Consumed\n   * by the workflow authoring layer two ways:\n   *   1. Codegen grounding — the example is embedded in the workflow-generation\n   *      prompt so the model wires `{{stepId.field}}` refs against the tool's\n   *      REAL output keys instead of guessing (`deals` vs `contacts`,\n   *      `contact_id` vs `contactId` — observed failure class).\n   *   2. Ref linting — a workflow ref into this tool's output whose first path\n   *      segment is not a key of this example is rejected at authoring time.\n   * Keep it SMALL (it ships in prompts), faithful to the actual run() return,\n   * and free of real customer data. Omitting it just skips both uses.\n   */\n  outputExample?: Record<string, unknown>;\n};\n\nexport type UiComponentMeta = {\n  component: string;\n  propsSchema: ToolParamsSchema;\n  doc?: string;\n};\n\nexport type RenderInstruction = {\n  component: string;\n  props: unknown;\n};\n"]}