@ekanos/sdk 0.1.2 → 0.1.4

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"]}