@illuma-ai/agents 1.4.0-alpha.3 → 1.4.0-alpha.4

package/dist/cjs/providers/tools-server/ToolsServerCapabilityProvider.cjs

@@ -113,6 +113,10 @@ function normalizeEntry(entry) {
             icon: entry.icon,
             category: entry.category,
             tags: entry.tags,
+            // Governance — hosts use these to gate UI/role/environment.
+            hidden: entry.hidden,
+            admin: entry.admin,
+            env: entry.env,
         },
     };
 }

package/dist/cjs/providers/tools-server/ToolsServerCapabilityProvider.cjs.map

@@ -1 +1 @@
-{"version":3,"file":"ToolsServerCapabilityProvider.cjs","sources":["../../../../src/providers/tools-server/ToolsServerCapabilityProvider.ts"],"sourcesContent":["/**\n * ToolsServerCapabilityProvider — capabilities sourced from a tools-server\n * HTTP endpoint.\n *\n * Fetches the manifest via GET /manifest, builds proxy StructuredTools via\n * POST /execute/:tool. Manifest is cached (TTL-configurable) so repeated\n * init cycles don't refetch.\n *\n * See docs/architecture-capability-layer.md for the design rationale.\n */\n\nimport type { AxiosInstance } from 'axios';\nimport type { StructuredToolInterface } from '@langchain/core/tools';\nimport {\n  CapabilityKind,\n  type Capability,\n  type CapabilityFilter,\n  type CapabilityProvider,\n  type CredentialMap,\n} from '@/providers/types';\nimport {\n  createHttpClient,\n  type HttpClientConfig,\n  assertOk,\n} from '@/utils/httpClient';\nimport {\n  ManifestCache,\n  filterToCacheKey,\n  applyFilter,\n} from '@/utils/toolManifest';\nimport { buildProxyTool } from '@/tools/proxyTool';\n\n/** Configuration for ToolsServerCapabilityProvider. */\nexport interface ToolsServerConfig {\n  /** Tools-server base URL (e.g., https://tools.illuma.ai or http://localhost:3500). */\n  baseUrl: string;\n  /** API key sent as x-api-key header on all requests. Required. */\n  apiKey: string;\n  /** Optional override for manifest path. Defaults to `/manifest`. */\n  manifestPath?: string;\n  /** Optional override for execute path template. Defaults to `/execute/:name`. */\n  executePath?: string;\n  /** Request timeout in ms. Defaults to 30_000. */\n  timeoutMs?: number;\n  /** Manifest cache TTL in ms. 0 disables. Defaults to 60_000 (1 min). */\n  manifestTtlMs?: number;\n  /** Optional pre-built axios instance (for testing). */\n  client?: AxiosInstance;\n  /** Optional proxy override (defaults to process.env.PROXY). */\n  proxy?: string | null;\n}\n\n/**\n * Shape of a single entry from tools-server's /manifest response.\n *\n * Matches the tools-server ManifestToolEntry type. We define our own here\n * to avoid cross-package coupling — the shape is a stable HTTP contract.\n */\ninterface ToolsServerManifestEntry {\n  pluginKey: string;\n  name: string;\n  description: string;\n  icon?: string;\n  authConfig?: Array<{\n    authField: string;\n    label?: string;\n    description?: string;\n    source?: string;\n    required?: boolean;\n    prod?: boolean;\n    admin?: boolean;\n    hide?: boolean;\n  }>;\n  /** Input schema as JSON Schema (tools-server emits `schema`). */\n  schema?: unknown;\n  /** Legacy alias accepted for backwards compatibility. */\n  jsonSchema?: unknown;\n  category?: string;\n  tags?: string[];\n  toolkit?: string;\n  endpoint?: string;\n}\n\nexport class ToolsServerCapabilityProvider implements CapabilityProvider {\n  readonly providerId: string;\n  private readonly client: AxiosInstance;\n  private readonly manifestPath: string;\n  private readonly executePath: string;\n  private readonly cache: ManifestCache;\n\n  constructor(private readonly config: ToolsServerConfig) {\n    const {\n      baseUrl,\n      apiKey,\n      manifestPath = '/manifest',\n      executePath = '/execute/:name',\n      timeoutMs = 30_000,\n      manifestTtlMs = 60_000,\n      client,\n      proxy,\n    } = config;\n\n    if (!baseUrl) {\n      throw new Error('ToolsServerCapabilityProvider: baseUrl is required');\n    }\n    if (!apiKey) {\n      throw new Error('ToolsServerCapabilityProvider: apiKey is required');\n    }\n\n    this.providerId = `tools-server:${baseUrl}`;\n    this.manifestPath = manifestPath;\n    this.executePath = executePath;\n    this.cache = new ManifestCache({ ttlMs: manifestTtlMs });\n\n    if (client) {\n      this.client = client;\n    } else {\n      const httpConfig: HttpClientConfig = {\n        baseURL: baseUrl,\n        apiKey,\n        timeoutMs,\n        proxy,\n      };\n      this.client = createHttpClient(httpConfig);\n    }\n  }\n\n  async fetchManifest(filter?: CapabilityFilter): Promise<Capability[]> {\n    const cacheKey = filterToCacheKey(filter);\n    const cached = this.cache.get(cacheKey);\n    if (cached) {\n      // DEBUG: cache hit (remove after stabilization)\n      // eslint-disable-next-line no-console\n      console.debug(\n        `[${this.providerId}] manifest cache hit — ${cached.length} caps`\n      );\n      return cached;\n    }\n\n    // DEBUG\n    // eslint-disable-next-line no-console\n    console.debug(\n      `[${this.providerId}] fetching manifest from ${this.manifestPath}`\n    );\n\n    const res = await this.client.get<ToolsServerManifestEntry[]>(\n      this.manifestPath\n    );\n    assertOk(res.status, this.manifestPath, res.data);\n\n    const entries = Array.isArray(res.data) ? res.data : [];\n    const capabilities: Capability[] = entries.map((entry) =>\n      normalizeEntry(entry)\n    );\n\n    // Apply filter before caching the full list separately so unfiltered\n    // refetches don't re-hit the network.\n    const fullCacheKey = filterToCacheKey();\n    this.cache.set(fullCacheKey, capabilities);\n\n    const filtered = applyFilter(capabilities, filter);\n    if (cacheKey !== fullCacheKey) {\n      this.cache.set(cacheKey, filtered);\n    }\n\n    // DEBUG\n    // eslint-disable-next-line no-console\n    console.debug(\n      `[${this.providerId}] manifest loaded — ${capabilities.length} caps, ${filtered.length} after filter`\n    );\n\n    return filtered;\n  }\n\n  async createRunnables(\n    capabilities: Capability[],\n    credentials: CredentialMap\n  ): Promise<StructuredToolInterface[]> {\n    return capabilities.map((cap) =>\n      buildProxyTool(cap, credentials, {\n        client: this.client,\n        executePath: this.executePath,\n      })\n    );\n  }\n\n  /** Force a manifest refresh on next fetchManifest call. */\n  invalidateCache(): void {\n    this.cache.clear();\n  }\n}\n\n/**\n * Translate a raw tools-server manifest entry into a typed Capability.\n * Defensive — tools-server may add fields; we pull only what we need.\n */\nfunction normalizeEntry(entry: ToolsServerManifestEntry): Capability {\n  return {\n    kind: CapabilityKind.TOOL,\n    name: entry.pluginKey,\n    description: entry.description ?? '',\n    schema: entry.schema ?? entry.jsonSchema,\n    authConfig: (entry.authConfig ?? []).map((ac) => ({\n      authField: ac.authField,\n      label: ac.label,\n      description: ac.description,\n      required: ac.required,\n      prod: ac.prod,\n      admin: ac.admin,\n      hide: ac.hide,\n      // Source is a string in wire format; downstream consumers coerce to AuthSource.\n      source: ac.source as Capability['authConfig'][number]['source'],\n    })),\n    metadata: {\n      icon: entry.icon,\n      category: entry.category,\n      tags: entry.tags,\n    },\n  };\n}\n"],"names":["ManifestCache","createHttpClient","filterToCacheKey","assertOk","applyFilter","buildProxyTool","CapabilityKind"],"mappings":";;;;;;;AAAA;;;;;;;;;AASG;MA0EU,6BAA6B,CAAA;AAOX,IAAA,MAAA;AANpB,IAAA,UAAU;AACF,IAAA,MAAM;AACN,IAAA,YAAY;AACZ,IAAA,WAAW;AACX,IAAA,KAAK;AAEtB,IAAA,WAAA,CAA6B,MAAyB,EAAA;QAAzB,IAAA,CAAA,MAAM,GAAN,MAAM;QACjC,MAAM,EACJ,OAAO,EACP,MAAM,EACN,YAAY,GAAG,WAAW,EAC1B,WAAW,GAAG,gBAAgB,EAC9B,SAAS,GAAG,MAAM,EAClB,aAAa,GAAG,MAAM,EACtB,MAAM,EACN,KAAK,GACN,GAAG,MAAM;QAEV,IAAI,CAAC,OAAO,EAAE;AACZ,YAAA,MAAM,IAAI,KAAK,CAAC,oDAAoD,CAAC;QACvE;QACA,IAAI,CAAC,MAAM,EAAE;AACX,YAAA,MAAM,IAAI,KAAK,CAAC,mDAAmD,CAAC;QACtE;AAEA,QAAA,IAAI,CAAC,UAAU,GAAG,CAAA,aAAA,EAAgB,OAAO,EAAE;AAC3C,QAAA,IAAI,CAAC,YAAY,GAAG,YAAY;AAChC,QAAA,IAAI,CAAC,WAAW,GAAG,WAAW;AAC9B,QAAA,IAAI,CAAC,KAAK,GAAG,IAAIA,0BAAa,CAAC,EAAE,KAAK,EAAE,aAAa,EAAE,CAAC;QAExD,IAAI,MAAM,EAAE;AACV,YAAA,IAAI,CAAC,MAAM,GAAG,MAAM;QACtB;aAAO;AACL,YAAA,MAAM,UAAU,GAAqB;AACnC,gBAAA,OAAO,EAAE,OAAO;gBAChB,MAAM;gBACN,SAAS;gBACT,KAAK;aACN;AACD,YAAA,IAAI,CAAC,MAAM,GAAGC,2BAAgB,CAAC,UAAU,CAAC;QAC5C;IACF;IAEA,MAAM,aAAa,CAAC,MAAyB,EAAA;AAC3C,QAAA,MAAM,QAAQ,GAAGC,6BAAgB,CAAC,MAAM,CAAC;QACzC,MAAM,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,QAAQ,CAAC;QACvC,IAAI,MAAM,EAAE;;;AAGV,YAAA,OAAO,CAAC,KAAK,CACX,CAAA,CAAA,EAAI,IAAI,CAAC,UAAU,CAAA,uBAAA,EAA0B,MAAM,CAAC,MAAM,CAAA,KAAA,CAAO,CAClE;AACD,YAAA,OAAO,MAAM;QACf;;;AAIA,QAAA,OAAO,CAAC,KAAK,CACX,CAAA,CAAA,EAAI,IAAI,CAAC,UAAU,CAAA,yBAAA,EAA4B,IAAI,CAAC,YAAY,CAAA,CAAE,CACnE;AAED,QAAA,MAAM,GAAG,GAAG,MAAM,IAAI,CAAC,MAAM,CAAC,GAAG,CAC/B,IAAI,CAAC,YAAY,CAClB;AACD,QAAAC,mBAAQ,CAAC,GAAG,CAAC,MAAM,EAAE,IAAI,CAAC,YAAY,EAAE,GAAG,CAAC,IAAI,CAAC;QAEjD,MAAM,OAAO,GAAG,KAAK,CAAC,OAAO,CAAC,GAAG,CAAC,IAAI,CAAC,GAAG,GAAG,CAAC,IAAI,GAAG,EAAE;AACvD,QAAA,MAAM,YAAY,GAAiB,OAAO,CAAC,GAAG,CAAC,CAAC,KAAK,KACnD,cAAc,CAAC,KAAK,CAAC,CACtB;;;AAID,QAAA,MAAM,YAAY,GAAGD,6BAAgB,EAAE;QACvC,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,YAAY,EAAE,YAAY,CAAC;QAE1C,MAAM,QAAQ,GAAGE,wBAAW,CAAC,YAAY,EAAE,MAAM,CAAC;AAClD,QAAA,IAAI,QAAQ,KAAK,YAAY,EAAE;YAC7B,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,QAAQ,EAAE,QAAQ,CAAC;QACpC;;;AAIA,QAAA,OAAO,CAAC,KAAK,CACX,CAAA,CAAA,EAAI,IAAI,CAAC,UAAU,CAAA,oBAAA,EAAuB,YAAY,CAAC,MAAM,CAAA,OAAA,EAAU,QAAQ,CAAC,MAAM,CAAA,aAAA,CAAe,CACtG;AAED,QAAA,OAAO,QAAQ;IACjB;AAEA,IAAA,MAAM,eAAe,CACnB,YAA0B,EAC1B,WAA0B,EAAA;AAE1B,QAAA,OAAO,YAAY,CAAC,GAAG,CAAC,CAAC,GAAG,KAC1BC,wBAAc,CAAC,GAAG,EAAE,WAAW,EAAE;YAC/B,MAAM,EAAE,IAAI,CAAC,MAAM;YACnB,WAAW,EAAE,IAAI,CAAC,WAAW;AAC9B,SAAA,CAAC,CACH;IACH;;IAGA,eAAe,GAAA;AACb,QAAA,IAAI,CAAC,KAAK,CAAC,KAAK,EAAE;IACpB;AACD;AAED;;;AAGG;AACH,SAAS,cAAc,CAAC,KAA+B,EAAA;IACrD,OAAO;QACL,IAAI,EAAEC,oBAAc,CAAC,IAAI;QACzB,IAAI,EAAE,KAAK,CAAC,SAAS;AACrB,QAAA,WAAW,EAAE,KAAK,CAAC,WAAW,IAAI,EAAE;AACpC,QAAA,MAAM,EAAE,KAAK,CAAC,MAAM,IAAI,KAAK,CAAC,UAAU;AACxC,QAAA,UAAU,EAAE,CAAC,KAAK,CAAC,UAAU,IAAI,EAAE,EAAE,GAAG,CAAC,CAAC,EAAE,MAAM;YAChD,SAAS,EAAE,EAAE,CAAC,SAAS;YACvB,KAAK,EAAE,EAAE,CAAC,KAAK;YACf,WAAW,EAAE,EAAE,CAAC,WAAW;YAC3B,QAAQ,EAAE,EAAE,CAAC,QAAQ;YACrB,IAAI,EAAE,EAAE,CAAC,IAAI;YACb,KAAK,EAAE,EAAE,CAAC,KAAK;YACf,IAAI,EAAE,EAAE,CAAC,IAAI;;YAEb,MAAM,EAAE,EAAE,CAAC,MAAoD;AAChE,SAAA,CAAC,CAAC;AACH,QAAA,QAAQ,EAAE;YACR,IAAI,EAAE,KAAK,CAAC,IAAI;YAChB,QAAQ,EAAE,KAAK,CAAC,QAAQ;YACxB,IAAI,EAAE,KAAK,CAAC,IAAI;AACjB,SAAA;KACF;AACH;;;;"}
+{"version":3,"file":"ToolsServerCapabilityProvider.cjs","sources":["../../../../src/providers/tools-server/ToolsServerCapabilityProvider.ts"],"sourcesContent":["/**\n * ToolsServerCapabilityProvider — capabilities sourced from a tools-server\n * HTTP endpoint.\n *\n * Fetches the manifest via GET /manifest, builds proxy StructuredTools via\n * POST /execute/:tool. Manifest is cached (TTL-configurable) so repeated\n * init cycles don't refetch.\n *\n * See docs/architecture-capability-layer.md for the design rationale.\n */\n\nimport type { AxiosInstance } from 'axios';\nimport type { StructuredToolInterface } from '@langchain/core/tools';\nimport {\n  CapabilityKind,\n  type Capability,\n  type CapabilityFilter,\n  type CapabilityProvider,\n  type CredentialMap,\n} from '@/providers/types';\nimport {\n  createHttpClient,\n  type HttpClientConfig,\n  assertOk,\n} from '@/utils/httpClient';\nimport {\n  ManifestCache,\n  filterToCacheKey,\n  applyFilter,\n} from '@/utils/toolManifest';\nimport { buildProxyTool } from '@/tools/proxyTool';\n\n/** Configuration for ToolsServerCapabilityProvider. */\nexport interface ToolsServerConfig {\n  /** Tools-server base URL (e.g., https://tools.illuma.ai or http://localhost:3500). */\n  baseUrl: string;\n  /** API key sent as x-api-key header on all requests. Required. */\n  apiKey: string;\n  /** Optional override for manifest path. Defaults to `/manifest`. */\n  manifestPath?: string;\n  /** Optional override for execute path template. Defaults to `/execute/:name`. */\n  executePath?: string;\n  /** Request timeout in ms. Defaults to 30_000. */\n  timeoutMs?: number;\n  /** Manifest cache TTL in ms. 0 disables. Defaults to 60_000 (1 min). */\n  manifestTtlMs?: number;\n  /** Optional pre-built axios instance (for testing). */\n  client?: AxiosInstance;\n  /** Optional proxy override (defaults to process.env.PROXY). */\n  proxy?: string | null;\n}\n\n/**\n * Shape of a single entry from tools-server's /manifest response.\n *\n * Matches the tools-server ManifestToolEntry type. We define our own here\n * to avoid cross-package coupling — the shape is a stable HTTP contract.\n */\ninterface ToolsServerManifestEntry {\n  pluginKey: string;\n  name: string;\n  description: string;\n  icon?: string;\n  authConfig?: Array<{\n    authField: string;\n    label?: string;\n    description?: string;\n    source?: string;\n    required?: boolean;\n    prod?: boolean;\n    admin?: boolean;\n    hide?: boolean;\n  }>;\n  /** Input schema as JSON Schema (tools-server emits `schema`). */\n  schema?: unknown;\n  /** Legacy alias accepted for backwards compatibility. */\n  jsonSchema?: unknown;\n  category?: string;\n  tags?: string[];\n  toolkit?: string;\n  endpoint?: string;\n  /** Governance flags forwarded by tools-server getManifest(). */\n  hidden?: boolean;\n  admin?: boolean;\n  env?: Array<'development' | 'production' | 'test' | 'staging'>;\n}\n\nexport class ToolsServerCapabilityProvider implements CapabilityProvider {\n  readonly providerId: string;\n  private readonly client: AxiosInstance;\n  private readonly manifestPath: string;\n  private readonly executePath: string;\n  private readonly cache: ManifestCache;\n\n  constructor(private readonly config: ToolsServerConfig) {\n    const {\n      baseUrl,\n      apiKey,\n      manifestPath = '/manifest',\n      executePath = '/execute/:name',\n      timeoutMs = 30_000,\n      manifestTtlMs = 60_000,\n      client,\n      proxy,\n    } = config;\n\n    if (!baseUrl) {\n      throw new Error('ToolsServerCapabilityProvider: baseUrl is required');\n    }\n    if (!apiKey) {\n      throw new Error('ToolsServerCapabilityProvider: apiKey is required');\n    }\n\n    this.providerId = `tools-server:${baseUrl}`;\n    this.manifestPath = manifestPath;\n    this.executePath = executePath;\n    this.cache = new ManifestCache({ ttlMs: manifestTtlMs });\n\n    if (client) {\n      this.client = client;\n    } else {\n      const httpConfig: HttpClientConfig = {\n        baseURL: baseUrl,\n        apiKey,\n        timeoutMs,\n        proxy,\n      };\n      this.client = createHttpClient(httpConfig);\n    }\n  }\n\n  async fetchManifest(filter?: CapabilityFilter): Promise<Capability[]> {\n    const cacheKey = filterToCacheKey(filter);\n    const cached = this.cache.get(cacheKey);\n    if (cached) {\n      // DEBUG: cache hit (remove after stabilization)\n      // eslint-disable-next-line no-console\n      console.debug(\n        `[${this.providerId}] manifest cache hit — ${cached.length} caps`\n      );\n      return cached;\n    }\n\n    // DEBUG\n    // eslint-disable-next-line no-console\n    console.debug(\n      `[${this.providerId}] fetching manifest from ${this.manifestPath}`\n    );\n\n    const res = await this.client.get<ToolsServerManifestEntry[]>(\n      this.manifestPath\n    );\n    assertOk(res.status, this.manifestPath, res.data);\n\n    const entries = Array.isArray(res.data) ? res.data : [];\n    const capabilities: Capability[] = entries.map((entry) =>\n      normalizeEntry(entry)\n    );\n\n    // Apply filter before caching the full list separately so unfiltered\n    // refetches don't re-hit the network.\n    const fullCacheKey = filterToCacheKey();\n    this.cache.set(fullCacheKey, capabilities);\n\n    const filtered = applyFilter(capabilities, filter);\n    if (cacheKey !== fullCacheKey) {\n      this.cache.set(cacheKey, filtered);\n    }\n\n    // DEBUG\n    // eslint-disable-next-line no-console\n    console.debug(\n      `[${this.providerId}] manifest loaded — ${capabilities.length} caps, ${filtered.length} after filter`\n    );\n\n    return filtered;\n  }\n\n  async createRunnables(\n    capabilities: Capability[],\n    credentials: CredentialMap\n  ): Promise<StructuredToolInterface[]> {\n    return capabilities.map((cap) =>\n      buildProxyTool(cap, credentials, {\n        client: this.client,\n        executePath: this.executePath,\n      })\n    );\n  }\n\n  /** Force a manifest refresh on next fetchManifest call. */\n  invalidateCache(): void {\n    this.cache.clear();\n  }\n}\n\n/**\n * Translate a raw tools-server manifest entry into a typed Capability.\n * Defensive — tools-server may add fields; we pull only what we need.\n */\nfunction normalizeEntry(entry: ToolsServerManifestEntry): Capability {\n  return {\n    kind: CapabilityKind.TOOL,\n    name: entry.pluginKey,\n    description: entry.description ?? '',\n    schema: entry.schema ?? entry.jsonSchema,\n    authConfig: (entry.authConfig ?? []).map((ac) => ({\n      authField: ac.authField,\n      label: ac.label,\n      description: ac.description,\n      required: ac.required,\n      prod: ac.prod,\n      admin: ac.admin,\n      hide: ac.hide,\n      // Source is a string in wire format; downstream consumers coerce to AuthSource.\n      source: ac.source as Capability['authConfig'][number]['source'],\n    })),\n    metadata: {\n      icon: entry.icon,\n      category: entry.category,\n      tags: entry.tags,\n      // Governance — hosts use these to gate UI/role/environment.\n      hidden: entry.hidden,\n      admin: entry.admin,\n      env: entry.env,\n    },\n  };\n}\n"],"names":["ManifestCache","createHttpClient","filterToCacheKey","assertOk","applyFilter","buildProxyTool","CapabilityKind"],"mappings":"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"}

package/dist/cjs/providers/types.cjs.map

@@ -1 +1 @@
-{"version":3,"file":"types.cjs","sources":["../../../src/providers/types.ts"],"sourcesContent":["/**\n * CapabilityProvider types — the abstraction that lets agents consume tools,\n * skills, and MCP-backed capabilities through a single interface regardless\n * of where they come from.\n *\n * Design principles:\n *   1. Source-agnostic — providers are distinguished by WHERE they come from\n *      (tools-server, skill store, MCP server), not by the backend service\n *      any individual tool calls.\n *   2. Credential-agnostic — providers receive a flat credentialMap from the\n *      host; they don't know about user settings, databases, OAuth flows.\n *   3. Extension-ready — the shape reserves slots for upcoming patterns\n *      (skills injectedMessages, ToolCall.auth/expires_at, skill sessions)\n *      so when those land we don't refactor the core.\n */\n\nimport type { StructuredToolInterface } from '@langchain/core/tools';\n\n/**\n * Kind of capability. Today only TOOL is implemented; SKILL and MCP are\n * reserved — SkillCapabilityProvider + MCPCapabilityProvider will populate\n * them in later phases. Keeping the enum from day one prevents a breaking\n * change when those ship.\n */\nexport enum CapabilityKind {\n  TOOL = 'tool',\n  SKILL = 'skill',\n  MCP = 'mcp',\n  /**\n   * Remote agent reachable over the A2A (Agent-to-Agent) protocol.\n   * The library's `A2ACapabilityProvider` is a client for this kind —\n   * invoking an A2A capability sends a JSON-RPC `tasks/send` to the\n   * remote agent's endpoint.\n   */\n  A2A = 'a2a',\n}\n\n/**\n * Where an auth credential comes from. Used by hosts to decide whether to\n * forward the credential per-request or let the capability provider resolve\n * it from its own environment.\n */\nexport enum AuthSource {\n  /** Resolved by the capability provider itself from its environment. Host never sends. */\n  SERVER = 'server',\n  /** User-configured value stored in the host's credential store. Host forwards per-request. */\n  USER = 'user',\n  /** Active OAuth/session token. Host forwards per-request from active session. */\n  FORWARDED = 'forwarded',\n}\n\n/**\n * One entry in a capability's auth config. Describes a single credential\n * the capability needs. The `source` field tells the host how to resolve\n * the value; the `prod`/`admin`/`hide` flags control UI visibility.\n */\nexport interface AuthConfigEntry {\n  /** Environment-variable-style name (e.g., \"OPENAI_API_KEY\"). Stable identifier. */\n  authField: string;\n  /** Human-readable label for UI. */\n  label?: string;\n  /** Optional description of how to obtain the credential. */\n  description?: string;\n  /** Where the value comes from. Defaults to USER if unspecified. */\n  source?: AuthSource;\n  /** True if the credential is required for the capability to function. */\n  required?: boolean;\n  /** Platform-managed in production — never prompt user. */\n  prod?: boolean;\n  /** Only admins can configure. */\n  admin?: boolean;\n  /** Never show in any UI (used when source === SERVER). */\n  hide?: boolean;\n}\n\n/**\n * Arbitrary metadata attached to a capability. Extension point.\n *\n * Fields prefixed with \"Reserved for\" are not populated today but exist in\n * the type so upstream patterns (skills, auth expiration, sessions) can\n * drop in without a schema migration.\n */\nexport interface CapabilityMetadata {\n  /** Icon URL or path relative to the provider's static asset root. */\n  icon?: string;\n  /** Category for UI grouping (e.g., \"search\", \"image\", \"finance\"). */\n  category?: string;\n  /** Free-form tags for filtering / search. */\n  tags?: string[];\n\n  // --- Reserved for upstream patterns (not populated today) ---\n\n  /** Reserved for upstream `fix/auth-events` — auth mode declared by tool. */\n  auth?: string;\n  /** Reserved for upstream `fix/auth-events` — Unix timestamp for token expiration. */\n  expires_at?: number;\n  /** Reserved for upstream skills — capability returns injected messages on execute. */\n  injectedMessages?: boolean;\n  /** Reserved for upstream skills — capability consumes ToolSessionMap state. */\n  sessionAware?: boolean;\n}\n\n/**\n * A single capability — a tool, skill, or MCP-backed operation that an agent\n * can invoke. The shape mirrors common plugin-manifest conventions so the\n * same entry can round-trip between an upstream catalog and a host registry.\n */\nexport interface Capability {\n  /** What kind of capability this is. Controls how it's invoked downstream. */\n  kind: CapabilityKind;\n  /**\n   * Stable unique identifier. For tools this is the pluginKey\n   * (e.g., \"dalle\", \"wikipedia\"). For skills this is the skill's `name`.\n   * Used everywhere the capability is referenced.\n   */\n  name: string;\n  /** Human-readable description for the LLM and UI. */\n  description: string;\n  /**\n   * Input schema as JSON Schema. For tools this comes from the Zod schema\n   * passed through `zodToJsonSchema`. Optional for capabilities with no\n   * input (e.g., parameter-less skills).\n   */\n  schema?: unknown;\n  /** Credential requirements. */\n  authConfig: AuthConfigEntry[];\n  /** Extension metadata. See CapabilityMetadata. */\n  metadata: CapabilityMetadata;\n}\n\n/** Filter for fetchManifest. All fields optional; missing = no filter. */\nexport interface CapabilityFilter {\n  kind?: CapabilityKind;\n  tags?: string[];\n  /** Restrict to capabilities whose `name` is in this list. */\n  names?: string[];\n}\n\n/**\n * A flat credential map: authField → value.\n *\n * The host is responsible for resolving values (from env vars, user\n * settings, OAuth sessions, etc.) before passing to the provider. The\n * provider does not inspect the origin — it just forwards to the tool.\n */\nexport type CredentialMap = Record<string, string>;\n\n/**\n * The core interface. All concrete providers implement this.\n *\n * Providers are identified by `providerId` for logging/debug. They fetch\n * their own manifest and build LangChain-compatible runnables from it.\n *\n * Lifetime: a provider may be instantiated once at startup (e.g., tools-\n * server pointing at a stable URL) or per-user (e.g., MCP with per-user\n * OAuth). The interface is agnostic.\n */\nexport interface CapabilityProvider {\n  /** Stable identifier for this provider instance (e.g., \"tools-server:https://...\"). */\n  readonly providerId: string;\n\n  /**\n   * Return the list of capabilities this provider exposes.\n   *\n   * Implementations may cache the manifest — the contract is that the\n   * returned list reflects the provider's current view of available\n   * capabilities.\n   *\n   * @param filter optional filter to scope the result\n   */\n  fetchManifest(filter?: CapabilityFilter): Promise<Capability[]>;\n\n  /**\n   * Build LangChain StructuredTools from a set of capabilities using the\n   * caller-supplied credentials.\n   *\n   * Called at agent init. The returned tools are bound to the LLM and\n   * invoked during the graph's tool-calling loop.\n   *\n   * @param capabilities the subset of capabilities the agent wants to use\n   * @param credentials credential values keyed by authField\n   */\n  createRunnables(\n    capabilities: Capability[],\n    credentials: CredentialMap\n  ): Promise<StructuredToolInterface[]>;\n}\n"],"names":["CapabilityKind","AuthSource"],"mappings":";;AAAA;;;;;;;;;;;;;;AAcG;AAIH;;;;;AAKG;AACSA;AAAZ,CAAA,UAAY,cAAc,EAAA;AACxB,IAAA,cAAA,CAAA,MAAA,CAAA,GAAA,MAAa;AACb,IAAA,cAAA,CAAA,OAAA,CAAA,GAAA,OAAe;AACf,IAAA,cAAA,CAAA,KAAA,CAAA,GAAA,KAAW;AACX;;;;;AAKG;AACH,IAAA,cAAA,CAAA,KAAA,CAAA,GAAA,KAAW;AACb,CAAC,EAXWA,sBAAc,KAAdA,sBAAc,GAAA,EAAA,CAAA,CAAA;AAa1B;;;;AAIG;AACSC;AAAZ,CAAA,UAAY,UAAU,EAAA;;AAEpB,IAAA,UAAA,CAAA,QAAA,CAAA,GAAA,QAAiB;;AAEjB,IAAA,UAAA,CAAA,MAAA,CAAA,GAAA,MAAa;;AAEb,IAAA,UAAA,CAAA,WAAA,CAAA,GAAA,WAAuB;AACzB,CAAC,EAPWA,kBAAU,KAAVA,kBAAU,GAAA,EAAA,CAAA,CAAA;;"}
+{"version":3,"file":"types.cjs","sources":["../../../src/providers/types.ts"],"sourcesContent":["/**\n * CapabilityProvider types — the abstraction that lets agents consume tools,\n * skills, and MCP-backed capabilities through a single interface regardless\n * of where they come from.\n *\n * Design principles:\n *   1. Source-agnostic — providers are distinguished by WHERE they come from\n *      (tools-server, skill store, MCP server), not by the backend service\n *      any individual tool calls.\n *   2. Credential-agnostic — providers receive a flat credentialMap from the\n *      host; they don't know about user settings, databases, OAuth flows.\n *   3. Extension-ready — the shape reserves slots for upcoming patterns\n *      (skills injectedMessages, ToolCall.auth/expires_at, skill sessions)\n *      so when those land we don't refactor the core.\n */\n\nimport type { StructuredToolInterface } from '@langchain/core/tools';\n\n/**\n * Kind of capability. Today only TOOL is implemented; SKILL and MCP are\n * reserved — SkillCapabilityProvider + MCPCapabilityProvider will populate\n * them in later phases. Keeping the enum from day one prevents a breaking\n * change when those ship.\n */\nexport enum CapabilityKind {\n  TOOL = 'tool',\n  SKILL = 'skill',\n  MCP = 'mcp',\n  /**\n   * Remote agent reachable over the A2A (Agent-to-Agent) protocol.\n   * The library's `A2ACapabilityProvider` is a client for this kind —\n   * invoking an A2A capability sends a JSON-RPC `tasks/send` to the\n   * remote agent's endpoint.\n   */\n  A2A = 'a2a',\n}\n\n/**\n * Where an auth credential comes from. Used by hosts to decide whether to\n * forward the credential per-request or let the capability provider resolve\n * it from its own environment.\n */\nexport enum AuthSource {\n  /** Resolved by the capability provider itself from its environment. Host never sends. */\n  SERVER = 'server',\n  /** User-configured value stored in the host's credential store. Host forwards per-request. */\n  USER = 'user',\n  /** Active OAuth/session token. Host forwards per-request from active session. */\n  FORWARDED = 'forwarded',\n}\n\n/**\n * One entry in a capability's auth config. Describes a single credential\n * the capability needs. The `source` field tells the host how to resolve\n * the value; the `prod`/`admin`/`hide` flags control UI visibility.\n */\nexport interface AuthConfigEntry {\n  /** Environment-variable-style name (e.g., \"OPENAI_API_KEY\"). Stable identifier. */\n  authField: string;\n  /** Human-readable label for UI. */\n  label?: string;\n  /** Optional description of how to obtain the credential. */\n  description?: string;\n  /** Where the value comes from. Defaults to USER if unspecified. */\n  source?: AuthSource;\n  /** True if the credential is required for the capability to function. */\n  required?: boolean;\n  /** Platform-managed in production — never prompt user. */\n  prod?: boolean;\n  /** Only admins can configure. */\n  admin?: boolean;\n  /** Never show in any UI (used when source === SERVER). */\n  hide?: boolean;\n}\n\n/**\n * Arbitrary metadata attached to a capability. Extension point.\n *\n * Fields prefixed with \"Reserved for\" are not populated today but exist in\n * the type so upstream patterns (skills, auth expiration, sessions) can\n * drop in without a schema migration.\n */\nexport interface CapabilityMetadata {\n  /** Icon URL or path relative to the provider's static asset root. */\n  icon?: string;\n  /** Category for UI grouping (e.g., \"search\", \"image\", \"finance\"). */\n  category?: string;\n  /** Free-form tags for filtering / search. */\n  tags?: string[];\n\n  // --- Governance flags ------------------------------------------------\n\n  /**\n   * When true, hosts omit this capability from user-facing pickers\n   * (Agent Builder, tool dropdown). Still invokable when a saved agent\n   * references it by name.\n   */\n  hidden?: boolean;\n  /** When true, only admin-role users can enable or invoke this capability. */\n  admin?: boolean;\n  /**\n   * Deployment-stage restriction. When set, hosts whose deployment stage\n   * isn't in the array should hide the capability (e.g., a prod host\n   * shouldn't surface a tool with `env: ['development']`).\n   */\n  env?: Array<'development' | 'production' | 'test' | 'staging'>;\n\n  // --- Reserved for upstream patterns (not populated today) ---\n\n  /** Reserved for upstream `fix/auth-events` — auth mode declared by tool. */\n  auth?: string;\n  /** Reserved for upstream `fix/auth-events` — Unix timestamp for token expiration. */\n  expires_at?: number;\n  /** Reserved for upstream skills — capability returns injected messages on execute. */\n  injectedMessages?: boolean;\n  /** Reserved for upstream skills — capability consumes ToolSessionMap state. */\n  sessionAware?: boolean;\n}\n\n/**\n * A single capability — a tool, skill, or MCP-backed operation that an agent\n * can invoke. The shape mirrors common plugin-manifest conventions so the\n * same entry can round-trip between an upstream catalog and a host registry.\n */\nexport interface Capability {\n  /** What kind of capability this is. Controls how it's invoked downstream. */\n  kind: CapabilityKind;\n  /**\n   * Stable unique identifier. For tools this is the pluginKey\n   * (e.g., \"dalle\", \"wikipedia\"). For skills this is the skill's `name`.\n   * Used everywhere the capability is referenced.\n   */\n  name: string;\n  /** Human-readable description for the LLM and UI. */\n  description: string;\n  /**\n   * Input schema as JSON Schema. For tools this comes from the Zod schema\n   * passed through `zodToJsonSchema`. Optional for capabilities with no\n   * input (e.g., parameter-less skills).\n   */\n  schema?: unknown;\n  /** Credential requirements. */\n  authConfig: AuthConfigEntry[];\n  /** Extension metadata. See CapabilityMetadata. */\n  metadata: CapabilityMetadata;\n}\n\n/** Filter for fetchManifest. All fields optional; missing = no filter. */\nexport interface CapabilityFilter {\n  kind?: CapabilityKind;\n  tags?: string[];\n  /** Restrict to capabilities whose `name` is in this list. */\n  names?: string[];\n}\n\n/**\n * A flat credential map: authField → value.\n *\n * The host is responsible for resolving values (from env vars, user\n * settings, OAuth sessions, etc.) before passing to the provider. The\n * provider does not inspect the origin — it just forwards to the tool.\n */\nexport type CredentialMap = Record<string, string>;\n\n/**\n * The core interface. All concrete providers implement this.\n *\n * Providers are identified by `providerId` for logging/debug. They fetch\n * their own manifest and build LangChain-compatible runnables from it.\n *\n * Lifetime: a provider may be instantiated once at startup (e.g., tools-\n * server pointing at a stable URL) or per-user (e.g., MCP with per-user\n * OAuth). The interface is agnostic.\n */\nexport interface CapabilityProvider {\n  /** Stable identifier for this provider instance (e.g., \"tools-server:https://...\"). */\n  readonly providerId: string;\n\n  /**\n   * Return the list of capabilities this provider exposes.\n   *\n   * Implementations may cache the manifest — the contract is that the\n   * returned list reflects the provider's current view of available\n   * capabilities.\n   *\n   * @param filter optional filter to scope the result\n   */\n  fetchManifest(filter?: CapabilityFilter): Promise<Capability[]>;\n\n  /**\n   * Build LangChain StructuredTools from a set of capabilities using the\n   * caller-supplied credentials.\n   *\n   * Called at agent init. The returned tools are bound to the LLM and\n   * invoked during the graph's tool-calling loop.\n   *\n   * @param capabilities the subset of capabilities the agent wants to use\n   * @param credentials credential values keyed by authField\n   */\n  createRunnables(\n    capabilities: Capability[],\n    credentials: CredentialMap\n  ): Promise<StructuredToolInterface[]>;\n}\n"],"names":["CapabilityKind","AuthSource"],"mappings":";;AAAA;;;;;;;;;;;;;;AAcG;AAIH;;;;;AAKG;AACSA;AAAZ,CAAA,UAAY,cAAc,EAAA;AACxB,IAAA,cAAA,CAAA,MAAA,CAAA,GAAA,MAAa;AACb,IAAA,cAAA,CAAA,OAAA,CAAA,GAAA,OAAe;AACf,IAAA,cAAA,CAAA,KAAA,CAAA,GAAA,KAAW;AACX;;;;;AAKG;AACH,IAAA,cAAA,CAAA,KAAA,CAAA,GAAA,KAAW;AACb,CAAC,EAXWA,sBAAc,KAAdA,sBAAc,GAAA,EAAA,CAAA,CAAA;AAa1B;;;;AAIG;AACSC;AAAZ,CAAA,UAAY,UAAU,EAAA;;AAEpB,IAAA,UAAA,CAAA,QAAA,CAAA,GAAA,QAAiB;;AAEjB,IAAA,UAAA,CAAA,MAAA,CAAA,GAAA,MAAa;;AAEb,IAAA,UAAA,CAAA,WAAA,CAAA,GAAA,WAAuB;AACzB,CAAC,EAPWA,kBAAU,KAAVA,kBAAU,GAAA,EAAA,CAAA,CAAA;;"}

package/dist/cjs/tools/artifacts/schema.cjs

@@ -2,7 +2,12 @@
 
 var zod = require('zod');
 
-const ARTIFACT_WRITE_ACTIONS = ['write', 'edit', 'verify', 'delete'];
+const ARTIFACT_WRITE_ACTIONS = [
+    'write',
+    'edit',
+    'verify',
+    'delete',
+];
 const CONTENT_READ_ACTIONS = ['read', 'search', 'list', 'info'];
 const artifactToolSchema = zod.z.object({
     action: zod.z
@@ -26,7 +31,10 @@ const artifactToolSchema = zod.z.object({
         .string()
         .optional()
         .describe('Exact string to find and replace (required for edit).'),
-    new_str: zod.z.string().optional().describe('Replacement string (required for edit).'),
+    new_str: zod.z
+        .string()
+        .optional()
+        .describe('Replacement string (required for edit).'),
     replace_all: zod.z
         .boolean()
         .optional()
@@ -44,12 +52,27 @@ const contentReaderSchema = zod.z.object({
     start_line: zod.z.number().optional().describe('1-based start line for reading.'),
     end_line: zod.z.number().optional().describe('1-based end line (inclusive).'),
     // search
-    pattern: zod.z.string().optional().describe('Regex pattern (required for search).'),
-    flags: zod.z.string().optional().describe('Regex flags (e.g., "i" for case-insensitive).'),
-    context: zod.z.number().optional().describe('Lines of context around each match.'),
+    pattern: zod.z
+        .string()
+        .optional()
+        .describe('Regex pattern (required for search).'),
+    flags: zod.z
+        .string()
+        .optional()
+        .describe('Regex flags (e.g., "i" for case-insensitive).'),
+    context: zod.z
+        .number()
+        .optional()
+        .describe('Lines of context around each match.'),
     // shared pagination
-    offset: zod.z.number().optional().describe('Offset for read or search pagination.'),
-    limit: zod.z.number().optional().describe('Max lines (read) or matches (search).'),
+    offset: zod.z
+        .number()
+        .optional()
+        .describe('Offset for read or search pagination.'),
+    limit: zod.z
+        .number()
+        .optional()
+        .describe('Max lines (read) or matches (search).'),
 });
 const ARTIFACT_TOOL_NAME = 'artifact_tool';
 const CONTENT_READER_NAME = 'content_reader';

package/dist/cjs/tools/artifacts/schema.cjs.map

@@ -1 +1 @@
-{"version":3,"file":"schema.cjs","sources":["../../../../src/tools/artifacts/schema.ts"],"sourcesContent":["import { z } from 'zod';\n\nexport const ARTIFACT_WRITE_ACTIONS = ['write', 'edit', 'verify', 'delete'] as const;\nexport const CONTENT_READ_ACTIONS = ['read', 'search', 'list', 'info'] as const;\n\nexport const artifactToolSchema = z.object({\n  action: z\n    .enum(ARTIFACT_WRITE_ACTIONS)\n    .describe(\n      'Authoring action: write (create/overwrite), edit (str_replace), verify (syntax check), delete (remove).',\n    ),\n  content_id: z\n    .string()\n    .optional()\n    .describe(\n      'ID of the artifact entry. Required for edit/verify/delete; optional for write (supply to overwrite an existing entry).',\n    ),\n\n  // write\n  content: z\n    .string()\n    .optional()\n    .describe('Full file content (required for write action).'),\n  name: z\n    .string()\n    .optional()\n    .describe(\n      'Filename for the new entry (required when creating). MUST include the correct file extension — the extension drives the preview template.',\n    ),\n\n  // edit (str_replace)\n  old_str: z\n    .string()\n    .optional()\n    .describe('Exact string to find and replace (required for edit).'),\n  new_str: z.string().optional().describe('Replacement string (required for edit).'),\n  replace_all: z\n    .boolean()\n    .optional()\n    .describe(\n      'edit: when true, replaces every occurrence of old_str. When false (default) and old_str matches more than one location, the edit is refused.',\n    ),\n});\n\nexport const contentReaderSchema = z.object({\n  action: z\n    .enum(CONTENT_READ_ACTIONS)\n    .describe(\n      'Read-only action: read (lines), search (regex), list (all entries), info (metadata).',\n    ),\n  content_id: z\n    .string()\n    .optional()\n    .describe(\n      'ID of the content entry. Required for read/search/info. Omit for list.',\n    ),\n\n  // read pagination\n  start_line: z.number().optional().describe('1-based start line for reading.'),\n  end_line: z.number().optional().describe('1-based end line (inclusive).'),\n\n  // search\n  pattern: z.string().optional().describe('Regex pattern (required for search).'),\n  flags: z.string().optional().describe('Regex flags (e.g., \"i\" for case-insensitive).'),\n  context: z.number().optional().describe('Lines of context around each match.'),\n\n  // shared pagination\n  offset: z.number().optional().describe('Offset for read or search pagination.'),\n  limit: z.number().optional().describe('Max lines (read) or matches (search).'),\n});\n\nexport const ARTIFACT_TOOL_NAME = 'artifact_tool';\nexport const CONTENT_READER_NAME = 'content_reader';\n\nexport type ArtifactToolInput = z.infer<typeof artifactToolSchema>;\nexport type ContentReaderInput = z.infer<typeof contentReaderSchema>;\n"],"names":["z"],"mappings":";;;;AAEO,MAAM,sBAAsB,GAAG,CAAC,OAAO,EAAE,MAAM,EAAE,QAAQ,EAAE,QAAQ;AACnE,MAAM,oBAAoB,GAAG,CAAC,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,MAAM;AAE9D,MAAM,kBAAkB,GAAGA,KAAC,CAAC,MAAM,CAAC;AACzC,IAAA,MAAM,EAAEA;SACL,IAAI,CAAC,sBAAsB;SAC3B,QAAQ,CACP,yGAAyG,CAC1G;AACH,IAAA,UAAU,EAAEA;AACT,SAAA,MAAM;AACN,SAAA,QAAQ;SACR,QAAQ,CACP,wHAAwH,CACzH;;AAGH,IAAA,OAAO,EAAEA;AACN,SAAA,MAAM;AACN,SAAA,QAAQ;SACR,QAAQ,CAAC,gDAAgD,CAAC;AAC7D,IAAA,IAAI,EAAEA;AACH,SAAA,MAAM;AACN,SAAA,QAAQ;SACR,QAAQ,CACP,2IAA2I,CAC5I;;AAGH,IAAA,OAAO,EAAEA;AACN,SAAA,MAAM;AACN,SAAA,QAAQ;SACR,QAAQ,CAAC,uDAAuD,CAAC;AACpE,IAAA,OAAO,EAAEA,KAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE,CAAC,QAAQ,CAAC,yCAAyC,CAAC;AAClF,IAAA,WAAW,EAAEA;AACV,SAAA,OAAO;AACP,SAAA,QAAQ;SACR,QAAQ,CACP,8IAA8I,CAC/I;AACJ,CAAA;AAEM,MAAM,mBAAmB,GAAGA,KAAC,CAAC,MAAM,CAAC;AAC1C,IAAA,MAAM,EAAEA;SACL,IAAI,CAAC,oBAAoB;SACzB,QAAQ,CACP,sFAAsF,CACvF;AACH,IAAA,UAAU,EAAEA;AACT,SAAA,MAAM;AACN,SAAA,QAAQ;SACR,QAAQ,CACP,wEAAwE,CACzE;;AAGH,IAAA,UAAU,EAAEA,KAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE,CAAC,QAAQ,CAAC,iCAAiC,CAAC;AAC7E,IAAA,QAAQ,EAAEA,KAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE,CAAC,QAAQ,CAAC,+BAA+B,CAAC;;AAGzE,IAAA,OAAO,EAAEA,KAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE,CAAC,QAAQ,CAAC,sCAAsC,CAAC;AAC/E,IAAA,KAAK,EAAEA,KAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE,CAAC,QAAQ,CAAC,+CAA+C,CAAC;AACtF,IAAA,OAAO,EAAEA,KAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE,CAAC,QAAQ,CAAC,qCAAqC,CAAC;;AAG9E,IAAA,MAAM,EAAEA,KAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE,CAAC,QAAQ,CAAC,uCAAuC,CAAC;AAC/E,IAAA,KAAK,EAAEA,KAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE,CAAC,QAAQ,CAAC,uCAAuC,CAAC;AAC/E,CAAA;AAEM,MAAM,kBAAkB,GAAG;AAC3B,MAAM,mBAAmB,GAAG;;;;;;;;;"}
+{"version":3,"file":"schema.cjs","sources":["../../../../src/tools/artifacts/schema.ts"],"sourcesContent":["import { z } from 'zod';\n\nexport const ARTIFACT_WRITE_ACTIONS = [\n  'write',\n  'edit',\n  'verify',\n  'delete',\n] as const;\nexport const CONTENT_READ_ACTIONS = ['read', 'search', 'list', 'info'] as const;\n\nexport const artifactToolSchema = z.object({\n  action: z\n    .enum(ARTIFACT_WRITE_ACTIONS)\n    .describe(\n      'Authoring action: write (create/overwrite), edit (str_replace), verify (syntax check), delete (remove).'\n    ),\n  content_id: z\n    .string()\n    .optional()\n    .describe(\n      'ID of the artifact entry. Required for edit/verify/delete; optional for write (supply to overwrite an existing entry).'\n    ),\n\n  // write\n  content: z\n    .string()\n    .optional()\n    .describe('Full file content (required for write action).'),\n  name: z\n    .string()\n    .optional()\n    .describe(\n      'Filename for the new entry (required when creating). MUST include the correct file extension — the extension drives the preview template.'\n    ),\n\n  // edit (str_replace)\n  old_str: z\n    .string()\n    .optional()\n    .describe('Exact string to find and replace (required for edit).'),\n  new_str: z\n    .string()\n    .optional()\n    .describe('Replacement string (required for edit).'),\n  replace_all: z\n    .boolean()\n    .optional()\n    .describe(\n      'edit: when true, replaces every occurrence of old_str. When false (default) and old_str matches more than one location, the edit is refused.'\n    ),\n});\n\nexport const contentReaderSchema = z.object({\n  action: z\n    .enum(CONTENT_READ_ACTIONS)\n    .describe(\n      'Read-only action: read (lines), search (regex), list (all entries), info (metadata).'\n    ),\n  content_id: z\n    .string()\n    .optional()\n    .describe(\n      'ID of the content entry. Required for read/search/info. Omit for list.'\n    ),\n\n  // read pagination\n  start_line: z.number().optional().describe('1-based start line for reading.'),\n  end_line: z.number().optional().describe('1-based end line (inclusive).'),\n\n  // search\n  pattern: z\n    .string()\n    .optional()\n    .describe('Regex pattern (required for search).'),\n  flags: z\n    .string()\n    .optional()\n    .describe('Regex flags (e.g., \"i\" for case-insensitive).'),\n  context: z\n    .number()\n    .optional()\n    .describe('Lines of context around each match.'),\n\n  // shared pagination\n  offset: z\n    .number()\n    .optional()\n    .describe('Offset for read or search pagination.'),\n  limit: z\n    .number()\n    .optional()\n    .describe('Max lines (read) or matches (search).'),\n});\n\nexport const ARTIFACT_TOOL_NAME = 'artifact_tool';\nexport const CONTENT_READER_NAME = 'content_reader';\n\nexport type ArtifactToolInput = z.infer<typeof artifactToolSchema>;\nexport type ContentReaderInput = z.infer<typeof contentReaderSchema>;\n"],"names":["z"],"mappings":";;;;AAEO,MAAM,sBAAsB,GAAG;IACpC,OAAO;IACP,MAAM;IACN,QAAQ;IACR,QAAQ;;AAEH,MAAM,oBAAoB,GAAG,CAAC,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,MAAM;AAE9D,MAAM,kBAAkB,GAAGA,KAAC,CAAC,MAAM,CAAC;AACzC,IAAA,MAAM,EAAEA;SACL,IAAI,CAAC,sBAAsB;SAC3B,QAAQ,CACP,yGAAyG,CAC1G;AACH,IAAA,UAAU,EAAEA;AACT,SAAA,MAAM;AACN,SAAA,QAAQ;SACR,QAAQ,CACP,wHAAwH,CACzH;;AAGH,IAAA,OAAO,EAAEA;AACN,SAAA,MAAM;AACN,SAAA,QAAQ;SACR,QAAQ,CAAC,gDAAgD,CAAC;AAC7D,IAAA,IAAI,EAAEA;AACH,SAAA,MAAM;AACN,SAAA,QAAQ;SACR,QAAQ,CACP,2IAA2I,CAC5I;;AAGH,IAAA,OAAO,EAAEA;AACN,SAAA,MAAM;AACN,SAAA,QAAQ;SACR,QAAQ,CAAC,uDAAuD,CAAC;AACpE,IAAA,OAAO,EAAEA;AACN,SAAA,MAAM;AACN,SAAA,QAAQ;SACR,QAAQ,CAAC,yCAAyC,CAAC;AACtD,IAAA,WAAW,EAAEA;AACV,SAAA,OAAO;AACP,SAAA,QAAQ;SACR,QAAQ,CACP,8IAA8I,CAC/I;AACJ,CAAA;AAEM,MAAM,mBAAmB,GAAGA,KAAC,CAAC,MAAM,CAAC;AAC1C,IAAA,MAAM,EAAEA;SACL,IAAI,CAAC,oBAAoB;SACzB,QAAQ,CACP,sFAAsF,CACvF;AACH,IAAA,UAAU,EAAEA;AACT,SAAA,MAAM;AACN,SAAA,QAAQ;SACR,QAAQ,CACP,wEAAwE,CACzE;;AAGH,IAAA,UAAU,EAAEA,KAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE,CAAC,QAAQ,CAAC,iCAAiC,CAAC;AAC7E,IAAA,QAAQ,EAAEA,KAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE,CAAC,QAAQ,CAAC,+BAA+B,CAAC;;AAGzE,IAAA,OAAO,EAAEA;AACN,SAAA,MAAM;AACN,SAAA,QAAQ;SACR,QAAQ,CAAC,sCAAsC,CAAC;AACnD,IAAA,KAAK,EAAEA;AACJ,SAAA,MAAM;AACN,SAAA,QAAQ;SACR,QAAQ,CAAC,+CAA+C,CAAC;AAC5D,IAAA,OAAO,EAAEA;AACN,SAAA,MAAM;AACN,SAAA,QAAQ;SACR,QAAQ,CAAC,qCAAqC,CAAC;;AAGlD,IAAA,MAAM,EAAEA;AACL,SAAA,MAAM;AACN,SAAA,QAAQ;SACR,QAAQ,CAAC,uCAAuC,CAAC;AACpD,IAAA,KAAK,EAAEA;AACJ,SAAA,MAAM;AACN,SAAA,QAAQ;SACR,QAAQ,CAAC,uCAAuC,CAAC;AACrD,CAAA;AAEM,MAAM,kBAAkB,GAAG;AAC3B,MAAM,mBAAmB,GAAG;;;;;;;;;"}

package/dist/cjs/tools/artifacts/tool.cjs

@@ -106,7 +106,10 @@ function createArtifactTool(config) {
                     return await handlers.delete(args, scope);
                 }
                 default:
-                    return [`Unknown action: ${input.action}`, {}];
+                    return [
+                        `Unknown action: ${input.action}`,
+                        {},
+                    ];
             }
         }
         catch (err) {
@@ -183,7 +186,10 @@ function createContentReaderTool(config) {
                     return await handlers.info(args, scope);
                 }
                 default:
-                    return [`Unknown action: ${input.action}`, {}];
+                    return [
+                        `Unknown action: ${input.action}`,
+                        {},
+                    ];
             }
         }
         catch (err) {

package/dist/cjs/tools/artifacts/tool.cjs.map

@@ -1 +1 @@
-{"version":3,"file":"tool.cjs","sources":["../../../../src/tools/artifacts/tool.ts"],"sourcesContent":["/**\n * artifact_tool + content_reader library factories.\n *\n * The library owns the LangChain wiring (schema, description, response\n * shape) and the action dispatch; the runtime supplies a handler bundle\n * matching the `ArtifactWriteHandlers` / `ContentReadHandlers` interface.\n *\n * This keeps 800+ LOC of host-specific handler logic (S3 adapters, file\n * model CRUD, syntax checkers, line utils) out of the library while\n * still centralizing the tool surface every runtime shares.\n */\n\nimport { tool, DynamicStructuredTool } from '@langchain/core/tools';\nimport {\n  artifactToolSchema,\n  contentReaderSchema,\n  ARTIFACT_TOOL_NAME,\n  CONTENT_READER_NAME,\n} from './schema';\nimport type {\n  ArtifactToolConfig,\n  ContentReaderToolConfig,\n  ArtifactToolScope,\n  ArtifactToolResult,\n  WriteArgs,\n  EditArgs,\n  VerifyArgs,\n  DeleteArgs,\n  ReadArgs,\n  SearchArgs,\n  ListArgs,\n  InfoArgs,\n  ContentIdResolver,\n} from './types';\n\nconst DEFAULT_ARTIFACT_DESCRIPTION = `Author content artifacts that render live in the host's preview panel — this tool does NOT produce downloadable files (use execute_code for those).\n\nActions:\n- write: Create a new artifact. Write a COMPLETE file in one call. The \\`name\\` field MUST include the file extension — it routes the preview (.tsx, .html, .mmd, .svg, .csv, .json, .dot, .md, .drawio).\n- verify: Check an artifact for syntax errors. REQUIRED as the next step after every write/edit on code files — do not render until verify passes.\n- edit: Surgical string replacement — provide old_str (exact match) and new_str. Works on all file types.\n- delete: Remove an artifact and its backing file.\n\nArtifacts are persisted by the host. No manual save needed.`;\n\nconst DEFAULT_CONTENT_READER_DESCRIPTION = `Read and navigate stored content — artifacts authored by artifact_tool, large tool results auto-cached by the host, uploaded file attachments, and code blocks.\n\nRead-only surface. Use write/edit tools (artifact_tool, execute_code) to mutate.\n\nActions:\n- read: Return line ranges from a specific content_id.\n- search: Regex search across a specific content_id with paginated matches.\n- list: Enumerate every content entry currently stored.\n- info: Metadata (size, kind, creation time) for a specific content_id.`;\n\n/**\n * Optional content_id self-healing — if the runtime supplies a resolver,\n * we pre-resolve the ID on every action that takes one so nicknames\n * (e.g., \"Dashboard\") map to canonical IDs.\n */\nasync function resolveContentIdIfPresent(\n  resolver: ContentIdResolver | undefined,\n  id: string | undefined,\n  scope: ArtifactToolScope,\n  logger?: { debug: (msg: string) => void },\n): Promise<string | undefined> {\n  if (!resolver || !id) return id;\n  const out = await resolver.resolve(id, scope);\n  if (!out) return id;\n  if (out.resolvedId !== id) {\n    logger?.debug(\n      `[artifact] resolved \"${id}\" → \"${out.resolvedId}\"${out.resolvedName ? ` (\"${out.resolvedName}\")` : ''}`,\n    );\n  }\n  return out.resolvedId;\n}\n\n// ─── Writer tool (artifact_tool) ─────────────────────────────────────────\n\nexport function createArtifactTool(\n  config: ArtifactToolConfig,\n): DynamicStructuredTool {\n  const { handlers, getScope, resolver, logger, descriptionOverride } = config;\n\n  return tool(\n    async (rawInput, runnableConfig): Promise<ArtifactToolResult> => {\n      const scope = getScope(runnableConfig);\n      if (!scope) {\n        logger?.warn('[artifact_tool] no scope resolved from runnableConfig');\n        return ['Error: No conversation context available', {}];\n      }\n\n      const input = rawInput as {\n        action: 'write' | 'edit' | 'verify' | 'delete';\n        content_id?: string;\n        content?: string;\n        name?: string;\n        old_str?: string;\n        new_str?: string;\n        replace_all?: boolean;\n      };\n\n      const resolvedContentId = await resolveContentIdIfPresent(\n        resolver,\n        input.content_id,\n        scope,\n        logger,\n      );\n\n      const started = Date.now();\n      try {\n        switch (input.action) {\n          case 'write': {\n            const args: WriteArgs = {\n              action: 'write',\n              content_id: resolvedContentId,\n              content: input.content ?? '',\n              name: input.name,\n            };\n            if (!args.content) return ['Error: write requires content', {}];\n            return await handlers.write(args, scope);\n          }\n          case 'edit': {\n            if (!resolvedContentId) return ['Error: edit requires content_id', {}];\n            const args: EditArgs = {\n              action: 'edit',\n              content_id: resolvedContentId,\n              old_str: input.old_str ?? '',\n              new_str: input.new_str ?? '',\n              replace_all: input.replace_all,\n            };\n            if (!args.old_str) return ['Error: edit requires old_str', {}];\n            return await handlers.edit(args, scope);\n          }\n          case 'verify': {\n            if (!resolvedContentId) return ['Error: verify requires content_id', {}];\n            const args: VerifyArgs = {\n              action: 'verify',\n              content_id: resolvedContentId,\n            };\n            return await handlers.verify(args, scope);\n          }\n          case 'delete': {\n            if (!resolvedContentId) return ['Error: delete requires content_id', {}];\n            const args: DeleteArgs = {\n              action: 'delete',\n              content_id: resolvedContentId,\n            };\n            return await handlers.delete(args, scope);\n          }\n          default:\n            return [`Unknown action: ${(input as { action: string }).action}`, {}];\n        }\n      } catch (err) {\n        const e = err instanceof Error ? err : new Error(String(err));\n        logger?.error('[artifact_tool] handler threw', {\n          action: input.action,\n          contentId: resolvedContentId,\n          error: e.message,\n          elapsed: `${Date.now() - started}ms`,\n        });\n        return [`Error: ${e.message}`, {}];\n      }\n    },\n    {\n      name: ARTIFACT_TOOL_NAME,\n      responseFormat: 'content_and_artifact',\n      description: descriptionOverride ?? DEFAULT_ARTIFACT_DESCRIPTION,\n      schema: artifactToolSchema,\n    },\n  );\n}\n\n// ─── Reader tool (content_reader) ────────────────────────────────────────\n\nexport function createContentReaderTool(\n  config: ContentReaderToolConfig,\n): DynamicStructuredTool {\n  const { handlers, getScope, resolver, logger, descriptionOverride } = config;\n\n  return tool(\n    async (rawInput, runnableConfig): Promise<ArtifactToolResult> => {\n      const scope = getScope(runnableConfig);\n      if (!scope) {\n        logger?.warn('[content_reader] no scope resolved from runnableConfig');\n        return ['Error: No conversation context available', {}];\n      }\n\n      const input = rawInput as {\n        action: 'read' | 'search' | 'list' | 'info';\n        content_id?: string;\n        start_line?: number;\n        end_line?: number;\n        pattern?: string;\n        flags?: string;\n        context?: number;\n        offset?: number;\n        limit?: number;\n      };\n\n      const resolvedContentId = await resolveContentIdIfPresent(\n        resolver,\n        input.content_id,\n        scope,\n        logger,\n      );\n\n      const started = Date.now();\n      try {\n        switch (input.action) {\n          case 'read': {\n            if (!resolvedContentId) return ['Error: read requires content_id', {}];\n            const args: ReadArgs = {\n              action: 'read',\n              content_id: resolvedContentId,\n              start_line: input.start_line,\n              end_line: input.end_line,\n              offset: input.offset,\n              limit: input.limit,\n            };\n            return await handlers.read(args, scope);\n          }\n          case 'search': {\n            if (!resolvedContentId) return ['Error: search requires content_id', {}];\n            if (!input.pattern) return ['Error: search requires pattern', {}];\n            const args: SearchArgs = {\n              action: 'search',\n              content_id: resolvedContentId,\n              pattern: input.pattern,\n              flags: input.flags,\n              context: input.context,\n              offset: input.offset,\n              limit: input.limit,\n            };\n            return await handlers.search(args, scope);\n          }\n          case 'list': {\n            const args: ListArgs = { action: 'list' };\n            return await handlers.list(args, scope);\n          }\n          case 'info': {\n            if (!resolvedContentId) return ['Error: info requires content_id', {}];\n            const args: InfoArgs = {\n              action: 'info',\n              content_id: resolvedContentId,\n            };\n            return await handlers.info(args, scope);\n          }\n          default:\n            return [`Unknown action: ${(input as { action: string }).action}`, {}];\n        }\n      } catch (err) {\n        const e = err instanceof Error ? err : new Error(String(err));\n        logger?.error('[content_reader] handler threw', {\n          action: input.action,\n          contentId: resolvedContentId,\n          error: e.message,\n          elapsed: `${Date.now() - started}ms`,\n        });\n        return [`Error: ${e.message}`, {}];\n      }\n    },\n    {\n      name: CONTENT_READER_NAME,\n      responseFormat: 'content_and_artifact',\n      description: descriptionOverride ?? DEFAULT_CONTENT_READER_DESCRIPTION,\n      schema: contentReaderSchema,\n    },\n  );\n}\n\nexport {\n  ARTIFACT_TOOL_NAME,\n  CONTENT_READER_NAME,\n  ARTIFACT_WRITE_ACTIONS,\n  CONTENT_READ_ACTIONS,\n} from './schema';\n"],"names":["tool","ARTIFACT_TOOL_NAME","artifactToolSchema","CONTENT_READER_NAME","contentReaderSchema"],"mappings":"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"}
+{"version":3,"file":"tool.cjs","sources":["../../../../src/tools/artifacts/tool.ts"],"sourcesContent":["/**\n * artifact_tool + content_reader library factories.\n *\n * The library owns the LangChain wiring (schema, description, response\n * shape) and the action dispatch; the runtime supplies a handler bundle\n * matching the `ArtifactWriteHandlers` / `ContentReadHandlers` interface.\n *\n * This keeps 800+ LOC of host-specific handler logic (S3 adapters, file\n * model CRUD, syntax checkers, line utils) out of the library while\n * still centralizing the tool surface every runtime shares.\n */\n\nimport { tool, DynamicStructuredTool } from '@langchain/core/tools';\nimport {\n  artifactToolSchema,\n  contentReaderSchema,\n  ARTIFACT_TOOL_NAME,\n  CONTENT_READER_NAME,\n} from './schema';\nimport type {\n  ArtifactToolConfig,\n  ContentReaderToolConfig,\n  ArtifactToolScope,\n  ArtifactToolResult,\n  WriteArgs,\n  EditArgs,\n  VerifyArgs,\n  DeleteArgs,\n  ReadArgs,\n  SearchArgs,\n  ListArgs,\n  InfoArgs,\n  ContentIdResolver,\n} from './types';\n\nconst DEFAULT_ARTIFACT_DESCRIPTION = `Author content artifacts that render live in the host's preview panel — this tool does NOT produce downloadable files (use execute_code for those).\n\nActions:\n- write: Create a new artifact. Write a COMPLETE file in one call. The \\`name\\` field MUST include the file extension — it routes the preview (.tsx, .html, .mmd, .svg, .csv, .json, .dot, .md, .drawio).\n- verify: Check an artifact for syntax errors. REQUIRED as the next step after every write/edit on code files — do not render until verify passes.\n- edit: Surgical string replacement — provide old_str (exact match) and new_str. Works on all file types.\n- delete: Remove an artifact and its backing file.\n\nArtifacts are persisted by the host. No manual save needed.`;\n\nconst DEFAULT_CONTENT_READER_DESCRIPTION = `Read and navigate stored content — artifacts authored by artifact_tool, large tool results auto-cached by the host, uploaded file attachments, and code blocks.\n\nRead-only surface. Use write/edit tools (artifact_tool, execute_code) to mutate.\n\nActions:\n- read: Return line ranges from a specific content_id.\n- search: Regex search across a specific content_id with paginated matches.\n- list: Enumerate every content entry currently stored.\n- info: Metadata (size, kind, creation time) for a specific content_id.`;\n\n/**\n * Optional content_id self-healing — if the runtime supplies a resolver,\n * we pre-resolve the ID on every action that takes one so nicknames\n * (e.g., \"Dashboard\") map to canonical IDs.\n */\nasync function resolveContentIdIfPresent(\n  resolver: ContentIdResolver | undefined,\n  id: string | undefined,\n  scope: ArtifactToolScope,\n  logger?: { debug: (msg: string) => void }\n): Promise<string | undefined> {\n  if (!resolver || !id) return id;\n  const out = await resolver.resolve(id, scope);\n  if (!out) return id;\n  if (out.resolvedId !== id) {\n    logger?.debug(\n      `[artifact] resolved \"${id}\" → \"${out.resolvedId}\"${out.resolvedName ? ` (\"${out.resolvedName}\")` : ''}`\n    );\n  }\n  return out.resolvedId;\n}\n\n// ─── Writer tool (artifact_tool) ─────────────────────────────────────────\n\nexport function createArtifactTool(\n  config: ArtifactToolConfig\n): DynamicStructuredTool {\n  const { handlers, getScope, resolver, logger, descriptionOverride } = config;\n\n  return tool(\n    async (rawInput, runnableConfig): Promise<ArtifactToolResult> => {\n      const scope = getScope(runnableConfig);\n      if (!scope) {\n        logger?.warn('[artifact_tool] no scope resolved from runnableConfig');\n        return ['Error: No conversation context available', {}];\n      }\n\n      const input = rawInput as {\n        action: 'write' | 'edit' | 'verify' | 'delete';\n        content_id?: string;\n        content?: string;\n        name?: string;\n        old_str?: string;\n        new_str?: string;\n        replace_all?: boolean;\n      };\n\n      const resolvedContentId = await resolveContentIdIfPresent(\n        resolver,\n        input.content_id,\n        scope,\n        logger\n      );\n\n      const started = Date.now();\n      try {\n        switch (input.action) {\n          case 'write': {\n            const args: WriteArgs = {\n              action: 'write',\n              content_id: resolvedContentId,\n              content: input.content ?? '',\n              name: input.name,\n            };\n            if (!args.content) return ['Error: write requires content', {}];\n            return await handlers.write(args, scope);\n          }\n          case 'edit': {\n            if (!resolvedContentId)\n              return ['Error: edit requires content_id', {}];\n            const args: EditArgs = {\n              action: 'edit',\n              content_id: resolvedContentId,\n              old_str: input.old_str ?? '',\n              new_str: input.new_str ?? '',\n              replace_all: input.replace_all,\n            };\n            if (!args.old_str) return ['Error: edit requires old_str', {}];\n            return await handlers.edit(args, scope);\n          }\n          case 'verify': {\n            if (!resolvedContentId)\n              return ['Error: verify requires content_id', {}];\n            const args: VerifyArgs = {\n              action: 'verify',\n              content_id: resolvedContentId,\n            };\n            return await handlers.verify(args, scope);\n          }\n          case 'delete': {\n            if (!resolvedContentId)\n              return ['Error: delete requires content_id', {}];\n            const args: DeleteArgs = {\n              action: 'delete',\n              content_id: resolvedContentId,\n            };\n            return await handlers.delete(args, scope);\n          }\n          default:\n            return [\n              `Unknown action: ${(input as { action: string }).action}`,\n              {},\n            ];\n        }\n      } catch (err) {\n        const e = err instanceof Error ? err : new Error(String(err));\n        logger?.error('[artifact_tool] handler threw', {\n          action: input.action,\n          contentId: resolvedContentId,\n          error: e.message,\n          elapsed: `${Date.now() - started}ms`,\n        });\n        return [`Error: ${e.message}`, {}];\n      }\n    },\n    {\n      name: ARTIFACT_TOOL_NAME,\n      responseFormat: 'content_and_artifact',\n      description: descriptionOverride ?? DEFAULT_ARTIFACT_DESCRIPTION,\n      schema: artifactToolSchema,\n    }\n  );\n}\n\n// ─── Reader tool (content_reader) ────────────────────────────────────────\n\nexport function createContentReaderTool(\n  config: ContentReaderToolConfig\n): DynamicStructuredTool {\n  const { handlers, getScope, resolver, logger, descriptionOverride } = config;\n\n  return tool(\n    async (rawInput, runnableConfig): Promise<ArtifactToolResult> => {\n      const scope = getScope(runnableConfig);\n      if (!scope) {\n        logger?.warn('[content_reader] no scope resolved from runnableConfig');\n        return ['Error: No conversation context available', {}];\n      }\n\n      const input = rawInput as {\n        action: 'read' | 'search' | 'list' | 'info';\n        content_id?: string;\n        start_line?: number;\n        end_line?: number;\n        pattern?: string;\n        flags?: string;\n        context?: number;\n        offset?: number;\n        limit?: number;\n      };\n\n      const resolvedContentId = await resolveContentIdIfPresent(\n        resolver,\n        input.content_id,\n        scope,\n        logger\n      );\n\n      const started = Date.now();\n      try {\n        switch (input.action) {\n          case 'read': {\n            if (!resolvedContentId)\n              return ['Error: read requires content_id', {}];\n            const args: ReadArgs = {\n              action: 'read',\n              content_id: resolvedContentId,\n              start_line: input.start_line,\n              end_line: input.end_line,\n              offset: input.offset,\n              limit: input.limit,\n            };\n            return await handlers.read(args, scope);\n          }\n          case 'search': {\n            if (!resolvedContentId)\n              return ['Error: search requires content_id', {}];\n            if (!input.pattern) return ['Error: search requires pattern', {}];\n            const args: SearchArgs = {\n              action: 'search',\n              content_id: resolvedContentId,\n              pattern: input.pattern,\n              flags: input.flags,\n              context: input.context,\n              offset: input.offset,\n              limit: input.limit,\n            };\n            return await handlers.search(args, scope);\n          }\n          case 'list': {\n            const args: ListArgs = { action: 'list' };\n            return await handlers.list(args, scope);\n          }\n          case 'info': {\n            if (!resolvedContentId)\n              return ['Error: info requires content_id', {}];\n            const args: InfoArgs = {\n              action: 'info',\n              content_id: resolvedContentId,\n            };\n            return await handlers.info(args, scope);\n          }\n          default:\n            return [\n              `Unknown action: ${(input as { action: string }).action}`,\n              {},\n            ];\n        }\n      } catch (err) {\n        const e = err instanceof Error ? err : new Error(String(err));\n        logger?.error('[content_reader] handler threw', {\n          action: input.action,\n          contentId: resolvedContentId,\n          error: e.message,\n          elapsed: `${Date.now() - started}ms`,\n        });\n        return [`Error: ${e.message}`, {}];\n      }\n    },\n    {\n      name: CONTENT_READER_NAME,\n      responseFormat: 'content_and_artifact',\n      description: descriptionOverride ?? DEFAULT_CONTENT_READER_DESCRIPTION,\n      schema: contentReaderSchema,\n    }\n  );\n}\n\nexport {\n  ARTIFACT_TOOL_NAME,\n  CONTENT_READER_NAME,\n  ARTIFACT_WRITE_ACTIONS,\n  CONTENT_READ_ACTIONS,\n} from './schema';\n"],"names":["tool","ARTIFACT_TOOL_NAME","artifactToolSchema","CONTENT_READER_NAME","contentReaderSchema"],"mappings":"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"}

package/dist/esm/providers/tools-server/ToolsServerCapabilityProvider.mjs

@@ -111,6 +111,10 @@ function normalizeEntry(entry) {
             icon: entry.icon,
             category: entry.category,
             tags: entry.tags,
+            // Governance — hosts use these to gate UI/role/environment.
+            hidden: entry.hidden,
+            admin: entry.admin,
+            env: entry.env,
         },
     };
 }

package/dist/esm/providers/tools-server/ToolsServerCapabilityProvider.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"ToolsServerCapabilityProvider.mjs","sources":["../../../../src/providers/tools-server/ToolsServerCapabilityProvider.ts"],"sourcesContent":["/**\n * ToolsServerCapabilityProvider — capabilities sourced from a tools-server\n * HTTP endpoint.\n *\n * Fetches the manifest via GET /manifest, builds proxy StructuredTools via\n * POST /execute/:tool. Manifest is cached (TTL-configurable) so repeated\n * init cycles don't refetch.\n *\n * See docs/architecture-capability-layer.md for the design rationale.\n */\n\nimport type { AxiosInstance } from 'axios';\nimport type { StructuredToolInterface } from '@langchain/core/tools';\nimport {\n  CapabilityKind,\n  type Capability,\n  type CapabilityFilter,\n  type CapabilityProvider,\n  type CredentialMap,\n} from '@/providers/types';\nimport {\n  createHttpClient,\n  type HttpClientConfig,\n  assertOk,\n} from '@/utils/httpClient';\nimport {\n  ManifestCache,\n  filterToCacheKey,\n  applyFilter,\n} from '@/utils/toolManifest';\nimport { buildProxyTool } from '@/tools/proxyTool';\n\n/** Configuration for ToolsServerCapabilityProvider. */\nexport interface ToolsServerConfig {\n  /** Tools-server base URL (e.g., https://tools.illuma.ai or http://localhost:3500). */\n  baseUrl: string;\n  /** API key sent as x-api-key header on all requests. Required. */\n  apiKey: string;\n  /** Optional override for manifest path. Defaults to `/manifest`. */\n  manifestPath?: string;\n  /** Optional override for execute path template. Defaults to `/execute/:name`. */\n  executePath?: string;\n  /** Request timeout in ms. Defaults to 30_000. */\n  timeoutMs?: number;\n  /** Manifest cache TTL in ms. 0 disables. Defaults to 60_000 (1 min). */\n  manifestTtlMs?: number;\n  /** Optional pre-built axios instance (for testing). */\n  client?: AxiosInstance;\n  /** Optional proxy override (defaults to process.env.PROXY). */\n  proxy?: string | null;\n}\n\n/**\n * Shape of a single entry from tools-server's /manifest response.\n *\n * Matches the tools-server ManifestToolEntry type. We define our own here\n * to avoid cross-package coupling — the shape is a stable HTTP contract.\n */\ninterface ToolsServerManifestEntry {\n  pluginKey: string;\n  name: string;\n  description: string;\n  icon?: string;\n  authConfig?: Array<{\n    authField: string;\n    label?: string;\n    description?: string;\n    source?: string;\n    required?: boolean;\n    prod?: boolean;\n    admin?: boolean;\n    hide?: boolean;\n  }>;\n  /** Input schema as JSON Schema (tools-server emits `schema`). */\n  schema?: unknown;\n  /** Legacy alias accepted for backwards compatibility. */\n  jsonSchema?: unknown;\n  category?: string;\n  tags?: string[];\n  toolkit?: string;\n  endpoint?: string;\n}\n\nexport class ToolsServerCapabilityProvider implements CapabilityProvider {\n  readonly providerId: string;\n  private readonly client: AxiosInstance;\n  private readonly manifestPath: string;\n  private readonly executePath: string;\n  private readonly cache: ManifestCache;\n\n  constructor(private readonly config: ToolsServerConfig) {\n    const {\n      baseUrl,\n      apiKey,\n      manifestPath = '/manifest',\n      executePath = '/execute/:name',\n      timeoutMs = 30_000,\n      manifestTtlMs = 60_000,\n      client,\n      proxy,\n    } = config;\n\n    if (!baseUrl) {\n      throw new Error('ToolsServerCapabilityProvider: baseUrl is required');\n    }\n    if (!apiKey) {\n      throw new Error('ToolsServerCapabilityProvider: apiKey is required');\n    }\n\n    this.providerId = `tools-server:${baseUrl}`;\n    this.manifestPath = manifestPath;\n    this.executePath = executePath;\n    this.cache = new ManifestCache({ ttlMs: manifestTtlMs });\n\n    if (client) {\n      this.client = client;\n    } else {\n      const httpConfig: HttpClientConfig = {\n        baseURL: baseUrl,\n        apiKey,\n        timeoutMs,\n        proxy,\n      };\n      this.client = createHttpClient(httpConfig);\n    }\n  }\n\n  async fetchManifest(filter?: CapabilityFilter): Promise<Capability[]> {\n    const cacheKey = filterToCacheKey(filter);\n    const cached = this.cache.get(cacheKey);\n    if (cached) {\n      // DEBUG: cache hit (remove after stabilization)\n      // eslint-disable-next-line no-console\n      console.debug(\n        `[${this.providerId}] manifest cache hit — ${cached.length} caps`\n      );\n      return cached;\n    }\n\n    // DEBUG\n    // eslint-disable-next-line no-console\n    console.debug(\n      `[${this.providerId}] fetching manifest from ${this.manifestPath}`\n    );\n\n    const res = await this.client.get<ToolsServerManifestEntry[]>(\n      this.manifestPath\n    );\n    assertOk(res.status, this.manifestPath, res.data);\n\n    const entries = Array.isArray(res.data) ? res.data : [];\n    const capabilities: Capability[] = entries.map((entry) =>\n      normalizeEntry(entry)\n    );\n\n    // Apply filter before caching the full list separately so unfiltered\n    // refetches don't re-hit the network.\n    const fullCacheKey = filterToCacheKey();\n    this.cache.set(fullCacheKey, capabilities);\n\n    const filtered = applyFilter(capabilities, filter);\n    if (cacheKey !== fullCacheKey) {\n      this.cache.set(cacheKey, filtered);\n    }\n\n    // DEBUG\n    // eslint-disable-next-line no-console\n    console.debug(\n      `[${this.providerId}] manifest loaded — ${capabilities.length} caps, ${filtered.length} after filter`\n    );\n\n    return filtered;\n  }\n\n  async createRunnables(\n    capabilities: Capability[],\n    credentials: CredentialMap\n  ): Promise<StructuredToolInterface[]> {\n    return capabilities.map((cap) =>\n      buildProxyTool(cap, credentials, {\n        client: this.client,\n        executePath: this.executePath,\n      })\n    );\n  }\n\n  /** Force a manifest refresh on next fetchManifest call. */\n  invalidateCache(): void {\n    this.cache.clear();\n  }\n}\n\n/**\n * Translate a raw tools-server manifest entry into a typed Capability.\n * Defensive — tools-server may add fields; we pull only what we need.\n */\nfunction normalizeEntry(entry: ToolsServerManifestEntry): Capability {\n  return {\n    kind: CapabilityKind.TOOL,\n    name: entry.pluginKey,\n    description: entry.description ?? '',\n    schema: entry.schema ?? entry.jsonSchema,\n    authConfig: (entry.authConfig ?? []).map((ac) => ({\n      authField: ac.authField,\n      label: ac.label,\n      description: ac.description,\n      required: ac.required,\n      prod: ac.prod,\n      admin: ac.admin,\n      hide: ac.hide,\n      // Source is a string in wire format; downstream consumers coerce to AuthSource.\n      source: ac.source as Capability['authConfig'][number]['source'],\n    })),\n    metadata: {\n      icon: entry.icon,\n      category: entry.category,\n      tags: entry.tags,\n    },\n  };\n}\n"],"names":[],"mappings":"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"}
+{"version":3,"file":"ToolsServerCapabilityProvider.mjs","sources":["../../../../src/providers/tools-server/ToolsServerCapabilityProvider.ts"],"sourcesContent":["/**\n * ToolsServerCapabilityProvider — capabilities sourced from a tools-server\n * HTTP endpoint.\n *\n * Fetches the manifest via GET /manifest, builds proxy StructuredTools via\n * POST /execute/:tool. Manifest is cached (TTL-configurable) so repeated\n * init cycles don't refetch.\n *\n * See docs/architecture-capability-layer.md for the design rationale.\n */\n\nimport type { AxiosInstance } from 'axios';\nimport type { StructuredToolInterface } from '@langchain/core/tools';\nimport {\n  CapabilityKind,\n  type Capability,\n  type CapabilityFilter,\n  type CapabilityProvider,\n  type CredentialMap,\n} from '@/providers/types';\nimport {\n  createHttpClient,\n  type HttpClientConfig,\n  assertOk,\n} from '@/utils/httpClient';\nimport {\n  ManifestCache,\n  filterToCacheKey,\n  applyFilter,\n} from '@/utils/toolManifest';\nimport { buildProxyTool } from '@/tools/proxyTool';\n\n/** Configuration for ToolsServerCapabilityProvider. */\nexport interface ToolsServerConfig {\n  /** Tools-server base URL (e.g., https://tools.illuma.ai or http://localhost:3500). */\n  baseUrl: string;\n  /** API key sent as x-api-key header on all requests. Required. */\n  apiKey: string;\n  /** Optional override for manifest path. Defaults to `/manifest`. */\n  manifestPath?: string;\n  /** Optional override for execute path template. Defaults to `/execute/:name`. */\n  executePath?: string;\n  /** Request timeout in ms. Defaults to 30_000. */\n  timeoutMs?: number;\n  /** Manifest cache TTL in ms. 0 disables. Defaults to 60_000 (1 min). */\n  manifestTtlMs?: number;\n  /** Optional pre-built axios instance (for testing). */\n  client?: AxiosInstance;\n  /** Optional proxy override (defaults to process.env.PROXY). */\n  proxy?: string | null;\n}\n\n/**\n * Shape of a single entry from tools-server's /manifest response.\n *\n * Matches the tools-server ManifestToolEntry type. We define our own here\n * to avoid cross-package coupling — the shape is a stable HTTP contract.\n */\ninterface ToolsServerManifestEntry {\n  pluginKey: string;\n  name: string;\n  description: string;\n  icon?: string;\n  authConfig?: Array<{\n    authField: string;\n    label?: string;\n    description?: string;\n    source?: string;\n    required?: boolean;\n    prod?: boolean;\n    admin?: boolean;\n    hide?: boolean;\n  }>;\n  /** Input schema as JSON Schema (tools-server emits `schema`). */\n  schema?: unknown;\n  /** Legacy alias accepted for backwards compatibility. */\n  jsonSchema?: unknown;\n  category?: string;\n  tags?: string[];\n  toolkit?: string;\n  endpoint?: string;\n  /** Governance flags forwarded by tools-server getManifest(). */\n  hidden?: boolean;\n  admin?: boolean;\n  env?: Array<'development' | 'production' | 'test' | 'staging'>;\n}\n\nexport class ToolsServerCapabilityProvider implements CapabilityProvider {\n  readonly providerId: string;\n  private readonly client: AxiosInstance;\n  private readonly manifestPath: string;\n  private readonly executePath: string;\n  private readonly cache: ManifestCache;\n\n  constructor(private readonly config: ToolsServerConfig) {\n    const {\n      baseUrl,\n      apiKey,\n      manifestPath = '/manifest',\n      executePath = '/execute/:name',\n      timeoutMs = 30_000,\n      manifestTtlMs = 60_000,\n      client,\n      proxy,\n    } = config;\n\n    if (!baseUrl) {\n      throw new Error('ToolsServerCapabilityProvider: baseUrl is required');\n    }\n    if (!apiKey) {\n      throw new Error('ToolsServerCapabilityProvider: apiKey is required');\n    }\n\n    this.providerId = `tools-server:${baseUrl}`;\n    this.manifestPath = manifestPath;\n    this.executePath = executePath;\n    this.cache = new ManifestCache({ ttlMs: manifestTtlMs });\n\n    if (client) {\n      this.client = client;\n    } else {\n      const httpConfig: HttpClientConfig = {\n        baseURL: baseUrl,\n        apiKey,\n        timeoutMs,\n        proxy,\n      };\n      this.client = createHttpClient(httpConfig);\n    }\n  }\n\n  async fetchManifest(filter?: CapabilityFilter): Promise<Capability[]> {\n    const cacheKey = filterToCacheKey(filter);\n    const cached = this.cache.get(cacheKey);\n    if (cached) {\n      // DEBUG: cache hit (remove after stabilization)\n      // eslint-disable-next-line no-console\n      console.debug(\n        `[${this.providerId}] manifest cache hit — ${cached.length} caps`\n      );\n      return cached;\n    }\n\n    // DEBUG\n    // eslint-disable-next-line no-console\n    console.debug(\n      `[${this.providerId}] fetching manifest from ${this.manifestPath}`\n    );\n\n    const res = await this.client.get<ToolsServerManifestEntry[]>(\n      this.manifestPath\n    );\n    assertOk(res.status, this.manifestPath, res.data);\n\n    const entries = Array.isArray(res.data) ? res.data : [];\n    const capabilities: Capability[] = entries.map((entry) =>\n      normalizeEntry(entry)\n    );\n\n    // Apply filter before caching the full list separately so unfiltered\n    // refetches don't re-hit the network.\n    const fullCacheKey = filterToCacheKey();\n    this.cache.set(fullCacheKey, capabilities);\n\n    const filtered = applyFilter(capabilities, filter);\n    if (cacheKey !== fullCacheKey) {\n      this.cache.set(cacheKey, filtered);\n    }\n\n    // DEBUG\n    // eslint-disable-next-line no-console\n    console.debug(\n      `[${this.providerId}] manifest loaded — ${capabilities.length} caps, ${filtered.length} after filter`\n    );\n\n    return filtered;\n  }\n\n  async createRunnables(\n    capabilities: Capability[],\n    credentials: CredentialMap\n  ): Promise<StructuredToolInterface[]> {\n    return capabilities.map((cap) =>\n      buildProxyTool(cap, credentials, {\n        client: this.client,\n        executePath: this.executePath,\n      })\n    );\n  }\n\n  /** Force a manifest refresh on next fetchManifest call. */\n  invalidateCache(): void {\n    this.cache.clear();\n  }\n}\n\n/**\n * Translate a raw tools-server manifest entry into a typed Capability.\n * Defensive — tools-server may add fields; we pull only what we need.\n */\nfunction normalizeEntry(entry: ToolsServerManifestEntry): Capability {\n  return {\n    kind: CapabilityKind.TOOL,\n    name: entry.pluginKey,\n    description: entry.description ?? '',\n    schema: entry.schema ?? entry.jsonSchema,\n    authConfig: (entry.authConfig ?? []).map((ac) => ({\n      authField: ac.authField,\n      label: ac.label,\n      description: ac.description,\n      required: ac.required,\n      prod: ac.prod,\n      admin: ac.admin,\n      hide: ac.hide,\n      // Source is a string in wire format; downstream consumers coerce to AuthSource.\n      source: ac.source as Capability['authConfig'][number]['source'],\n    })),\n    metadata: {\n      icon: entry.icon,\n      category: entry.category,\n      tags: entry.tags,\n      // Governance — hosts use these to gate UI/role/environment.\n      hidden: entry.hidden,\n      admin: entry.admin,\n      env: entry.env,\n    },\n  };\n}\n"],"names":[],"mappings":"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"}

package/dist/esm/providers/types.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"types.mjs","sources":["../../../src/providers/types.ts"],"sourcesContent":["/**\n * CapabilityProvider types — the abstraction that lets agents consume tools,\n * skills, and MCP-backed capabilities through a single interface regardless\n * of where they come from.\n *\n * Design principles:\n *   1. Source-agnostic — providers are distinguished by WHERE they come from\n *      (tools-server, skill store, MCP server), not by the backend service\n *      any individual tool calls.\n *   2. Credential-agnostic — providers receive a flat credentialMap from the\n *      host; they don't know about user settings, databases, OAuth flows.\n *   3. Extension-ready — the shape reserves slots for upcoming patterns\n *      (skills injectedMessages, ToolCall.auth/expires_at, skill sessions)\n *      so when those land we don't refactor the core.\n */\n\nimport type { StructuredToolInterface } from '@langchain/core/tools';\n\n/**\n * Kind of capability. Today only TOOL is implemented; SKILL and MCP are\n * reserved — SkillCapabilityProvider + MCPCapabilityProvider will populate\n * them in later phases. Keeping the enum from day one prevents a breaking\n * change when those ship.\n */\nexport enum CapabilityKind {\n  TOOL = 'tool',\n  SKILL = 'skill',\n  MCP = 'mcp',\n  /**\n   * Remote agent reachable over the A2A (Agent-to-Agent) protocol.\n   * The library's `A2ACapabilityProvider` is a client for this kind —\n   * invoking an A2A capability sends a JSON-RPC `tasks/send` to the\n   * remote agent's endpoint.\n   */\n  A2A = 'a2a',\n}\n\n/**\n * Where an auth credential comes from. Used by hosts to decide whether to\n * forward the credential per-request or let the capability provider resolve\n * it from its own environment.\n */\nexport enum AuthSource {\n  /** Resolved by the capability provider itself from its environment. Host never sends. */\n  SERVER = 'server',\n  /** User-configured value stored in the host's credential store. Host forwards per-request. */\n  USER = 'user',\n  /** Active OAuth/session token. Host forwards per-request from active session. */\n  FORWARDED = 'forwarded',\n}\n\n/**\n * One entry in a capability's auth config. Describes a single credential\n * the capability needs. The `source` field tells the host how to resolve\n * the value; the `prod`/`admin`/`hide` flags control UI visibility.\n */\nexport interface AuthConfigEntry {\n  /** Environment-variable-style name (e.g., \"OPENAI_API_KEY\"). Stable identifier. */\n  authField: string;\n  /** Human-readable label for UI. */\n  label?: string;\n  /** Optional description of how to obtain the credential. */\n  description?: string;\n  /** Where the value comes from. Defaults to USER if unspecified. */\n  source?: AuthSource;\n  /** True if the credential is required for the capability to function. */\n  required?: boolean;\n  /** Platform-managed in production — never prompt user. */\n  prod?: boolean;\n  /** Only admins can configure. */\n  admin?: boolean;\n  /** Never show in any UI (used when source === SERVER). */\n  hide?: boolean;\n}\n\n/**\n * Arbitrary metadata attached to a capability. Extension point.\n *\n * Fields prefixed with \"Reserved for\" are not populated today but exist in\n * the type so upstream patterns (skills, auth expiration, sessions) can\n * drop in without a schema migration.\n */\nexport interface CapabilityMetadata {\n  /** Icon URL or path relative to the provider's static asset root. */\n  icon?: string;\n  /** Category for UI grouping (e.g., \"search\", \"image\", \"finance\"). */\n  category?: string;\n  /** Free-form tags for filtering / search. */\n  tags?: string[];\n\n  // --- Reserved for upstream patterns (not populated today) ---\n\n  /** Reserved for upstream `fix/auth-events` — auth mode declared by tool. */\n  auth?: string;\n  /** Reserved for upstream `fix/auth-events` — Unix timestamp for token expiration. */\n  expires_at?: number;\n  /** Reserved for upstream skills — capability returns injected messages on execute. */\n  injectedMessages?: boolean;\n  /** Reserved for upstream skills — capability consumes ToolSessionMap state. */\n  sessionAware?: boolean;\n}\n\n/**\n * A single capability — a tool, skill, or MCP-backed operation that an agent\n * can invoke. The shape mirrors common plugin-manifest conventions so the\n * same entry can round-trip between an upstream catalog and a host registry.\n */\nexport interface Capability {\n  /** What kind of capability this is. Controls how it's invoked downstream. */\n  kind: CapabilityKind;\n  /**\n   * Stable unique identifier. For tools this is the pluginKey\n   * (e.g., \"dalle\", \"wikipedia\"). For skills this is the skill's `name`.\n   * Used everywhere the capability is referenced.\n   */\n  name: string;\n  /** Human-readable description for the LLM and UI. */\n  description: string;\n  /**\n   * Input schema as JSON Schema. For tools this comes from the Zod schema\n   * passed through `zodToJsonSchema`. Optional for capabilities with no\n   * input (e.g., parameter-less skills).\n   */\n  schema?: unknown;\n  /** Credential requirements. */\n  authConfig: AuthConfigEntry[];\n  /** Extension metadata. See CapabilityMetadata. */\n  metadata: CapabilityMetadata;\n}\n\n/** Filter for fetchManifest. All fields optional; missing = no filter. */\nexport interface CapabilityFilter {\n  kind?: CapabilityKind;\n  tags?: string[];\n  /** Restrict to capabilities whose `name` is in this list. */\n  names?: string[];\n}\n\n/**\n * A flat credential map: authField → value.\n *\n * The host is responsible for resolving values (from env vars, user\n * settings, OAuth sessions, etc.) before passing to the provider. The\n * provider does not inspect the origin — it just forwards to the tool.\n */\nexport type CredentialMap = Record<string, string>;\n\n/**\n * The core interface. All concrete providers implement this.\n *\n * Providers are identified by `providerId` for logging/debug. They fetch\n * their own manifest and build LangChain-compatible runnables from it.\n *\n * Lifetime: a provider may be instantiated once at startup (e.g., tools-\n * server pointing at a stable URL) or per-user (e.g., MCP with per-user\n * OAuth). The interface is agnostic.\n */\nexport interface CapabilityProvider {\n  /** Stable identifier for this provider instance (e.g., \"tools-server:https://...\"). */\n  readonly providerId: string;\n\n  /**\n   * Return the list of capabilities this provider exposes.\n   *\n   * Implementations may cache the manifest — the contract is that the\n   * returned list reflects the provider's current view of available\n   * capabilities.\n   *\n   * @param filter optional filter to scope the result\n   */\n  fetchManifest(filter?: CapabilityFilter): Promise<Capability[]>;\n\n  /**\n   * Build LangChain StructuredTools from a set of capabilities using the\n   * caller-supplied credentials.\n   *\n   * Called at agent init. The returned tools are bound to the LLM and\n   * invoked during the graph's tool-calling loop.\n   *\n   * @param capabilities the subset of capabilities the agent wants to use\n   * @param credentials credential values keyed by authField\n   */\n  createRunnables(\n    capabilities: Capability[],\n    credentials: CredentialMap\n  ): Promise<StructuredToolInterface[]>;\n}\n"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;AAcG;AAIH;;;;;AAKG;IACS;AAAZ,CAAA,UAAY,cAAc,EAAA;AACxB,IAAA,cAAA,CAAA,MAAA,CAAA,GAAA,MAAa;AACb,IAAA,cAAA,CAAA,OAAA,CAAA,GAAA,OAAe;AACf,IAAA,cAAA,CAAA,KAAA,CAAA,GAAA,KAAW;AACX;;;;;AAKG;AACH,IAAA,cAAA,CAAA,KAAA,CAAA,GAAA,KAAW;AACb,CAAC,EAXW,cAAc,KAAd,cAAc,GAAA,EAAA,CAAA,CAAA;AAa1B;;;;AAIG;IACS;AAAZ,CAAA,UAAY,UAAU,EAAA;;AAEpB,IAAA,UAAA,CAAA,QAAA,CAAA,GAAA,QAAiB;;AAEjB,IAAA,UAAA,CAAA,MAAA,CAAA,GAAA,MAAa;;AAEb,IAAA,UAAA,CAAA,WAAA,CAAA,GAAA,WAAuB;AACzB,CAAC,EAPW,UAAU,KAAV,UAAU,GAAA,EAAA,CAAA,CAAA;;;;"}
+{"version":3,"file":"types.mjs","sources":["../../../src/providers/types.ts"],"sourcesContent":["/**\n * CapabilityProvider types — the abstraction that lets agents consume tools,\n * skills, and MCP-backed capabilities through a single interface regardless\n * of where they come from.\n *\n * Design principles:\n *   1. Source-agnostic — providers are distinguished by WHERE they come from\n *      (tools-server, skill store, MCP server), not by the backend service\n *      any individual tool calls.\n *   2. Credential-agnostic — providers receive a flat credentialMap from the\n *      host; they don't know about user settings, databases, OAuth flows.\n *   3. Extension-ready — the shape reserves slots for upcoming patterns\n *      (skills injectedMessages, ToolCall.auth/expires_at, skill sessions)\n *      so when those land we don't refactor the core.\n */\n\nimport type { StructuredToolInterface } from '@langchain/core/tools';\n\n/**\n * Kind of capability. Today only TOOL is implemented; SKILL and MCP are\n * reserved — SkillCapabilityProvider + MCPCapabilityProvider will populate\n * them in later phases. Keeping the enum from day one prevents a breaking\n * change when those ship.\n */\nexport enum CapabilityKind {\n  TOOL = 'tool',\n  SKILL = 'skill',\n  MCP = 'mcp',\n  /**\n   * Remote agent reachable over the A2A (Agent-to-Agent) protocol.\n   * The library's `A2ACapabilityProvider` is a client for this kind —\n   * invoking an A2A capability sends a JSON-RPC `tasks/send` to the\n   * remote agent's endpoint.\n   */\n  A2A = 'a2a',\n}\n\n/**\n * Where an auth credential comes from. Used by hosts to decide whether to\n * forward the credential per-request or let the capability provider resolve\n * it from its own environment.\n */\nexport enum AuthSource {\n  /** Resolved by the capability provider itself from its environment. Host never sends. */\n  SERVER = 'server',\n  /** User-configured value stored in the host's credential store. Host forwards per-request. */\n  USER = 'user',\n  /** Active OAuth/session token. Host forwards per-request from active session. */\n  FORWARDED = 'forwarded',\n}\n\n/**\n * One entry in a capability's auth config. Describes a single credential\n * the capability needs. The `source` field tells the host how to resolve\n * the value; the `prod`/`admin`/`hide` flags control UI visibility.\n */\nexport interface AuthConfigEntry {\n  /** Environment-variable-style name (e.g., \"OPENAI_API_KEY\"). Stable identifier. */\n  authField: string;\n  /** Human-readable label for UI. */\n  label?: string;\n  /** Optional description of how to obtain the credential. */\n  description?: string;\n  /** Where the value comes from. Defaults to USER if unspecified. */\n  source?: AuthSource;\n  /** True if the credential is required for the capability to function. */\n  required?: boolean;\n  /** Platform-managed in production — never prompt user. */\n  prod?: boolean;\n  /** Only admins can configure. */\n  admin?: boolean;\n  /** Never show in any UI (used when source === SERVER). */\n  hide?: boolean;\n}\n\n/**\n * Arbitrary metadata attached to a capability. Extension point.\n *\n * Fields prefixed with \"Reserved for\" are not populated today but exist in\n * the type so upstream patterns (skills, auth expiration, sessions) can\n * drop in without a schema migration.\n */\nexport interface CapabilityMetadata {\n  /** Icon URL or path relative to the provider's static asset root. */\n  icon?: string;\n  /** Category for UI grouping (e.g., \"search\", \"image\", \"finance\"). */\n  category?: string;\n  /** Free-form tags for filtering / search. */\n  tags?: string[];\n\n  // --- Governance flags ------------------------------------------------\n\n  /**\n   * When true, hosts omit this capability from user-facing pickers\n   * (Agent Builder, tool dropdown). Still invokable when a saved agent\n   * references it by name.\n   */\n  hidden?: boolean;\n  /** When true, only admin-role users can enable or invoke this capability. */\n  admin?: boolean;\n  /**\n   * Deployment-stage restriction. When set, hosts whose deployment stage\n   * isn't in the array should hide the capability (e.g., a prod host\n   * shouldn't surface a tool with `env: ['development']`).\n   */\n  env?: Array<'development' | 'production' | 'test' | 'staging'>;\n\n  // --- Reserved for upstream patterns (not populated today) ---\n\n  /** Reserved for upstream `fix/auth-events` — auth mode declared by tool. */\n  auth?: string;\n  /** Reserved for upstream `fix/auth-events` — Unix timestamp for token expiration. */\n  expires_at?: number;\n  /** Reserved for upstream skills — capability returns injected messages on execute. */\n  injectedMessages?: boolean;\n  /** Reserved for upstream skills — capability consumes ToolSessionMap state. */\n  sessionAware?: boolean;\n}\n\n/**\n * A single capability — a tool, skill, or MCP-backed operation that an agent\n * can invoke. The shape mirrors common plugin-manifest conventions so the\n * same entry can round-trip between an upstream catalog and a host registry.\n */\nexport interface Capability {\n  /** What kind of capability this is. Controls how it's invoked downstream. */\n  kind: CapabilityKind;\n  /**\n   * Stable unique identifier. For tools this is the pluginKey\n   * (e.g., \"dalle\", \"wikipedia\"). For skills this is the skill's `name`.\n   * Used everywhere the capability is referenced.\n   */\n  name: string;\n  /** Human-readable description for the LLM and UI. */\n  description: string;\n  /**\n   * Input schema as JSON Schema. For tools this comes from the Zod schema\n   * passed through `zodToJsonSchema`. Optional for capabilities with no\n   * input (e.g., parameter-less skills).\n   */\n  schema?: unknown;\n  /** Credential requirements. */\n  authConfig: AuthConfigEntry[];\n  /** Extension metadata. See CapabilityMetadata. */\n  metadata: CapabilityMetadata;\n}\n\n/** Filter for fetchManifest. All fields optional; missing = no filter. */\nexport interface CapabilityFilter {\n  kind?: CapabilityKind;\n  tags?: string[];\n  /** Restrict to capabilities whose `name` is in this list. */\n  names?: string[];\n}\n\n/**\n * A flat credential map: authField → value.\n *\n * The host is responsible for resolving values (from env vars, user\n * settings, OAuth sessions, etc.) before passing to the provider. The\n * provider does not inspect the origin — it just forwards to the tool.\n */\nexport type CredentialMap = Record<string, string>;\n\n/**\n * The core interface. All concrete providers implement this.\n *\n * Providers are identified by `providerId` for logging/debug. They fetch\n * their own manifest and build LangChain-compatible runnables from it.\n *\n * Lifetime: a provider may be instantiated once at startup (e.g., tools-\n * server pointing at a stable URL) or per-user (e.g., MCP with per-user\n * OAuth). The interface is agnostic.\n */\nexport interface CapabilityProvider {\n  /** Stable identifier for this provider instance (e.g., \"tools-server:https://...\"). */\n  readonly providerId: string;\n\n  /**\n   * Return the list of capabilities this provider exposes.\n   *\n   * Implementations may cache the manifest — the contract is that the\n   * returned list reflects the provider's current view of available\n   * capabilities.\n   *\n   * @param filter optional filter to scope the result\n   */\n  fetchManifest(filter?: CapabilityFilter): Promise<Capability[]>;\n\n  /**\n   * Build LangChain StructuredTools from a set of capabilities using the\n   * caller-supplied credentials.\n   *\n   * Called at agent init. The returned tools are bound to the LLM and\n   * invoked during the graph's tool-calling loop.\n   *\n   * @param capabilities the subset of capabilities the agent wants to use\n   * @param credentials credential values keyed by authField\n   */\n  createRunnables(\n    capabilities: Capability[],\n    credentials: CredentialMap\n  ): Promise<StructuredToolInterface[]>;\n}\n"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;AAcG;AAIH;;;;;AAKG;IACS;AAAZ,CAAA,UAAY,cAAc,EAAA;AACxB,IAAA,cAAA,CAAA,MAAA,CAAA,GAAA,MAAa;AACb,IAAA,cAAA,CAAA,OAAA,CAAA,GAAA,OAAe;AACf,IAAA,cAAA,CAAA,KAAA,CAAA,GAAA,KAAW;AACX;;;;;AAKG;AACH,IAAA,cAAA,CAAA,KAAA,CAAA,GAAA,KAAW;AACb,CAAC,EAXW,cAAc,KAAd,cAAc,GAAA,EAAA,CAAA,CAAA;AAa1B;;;;AAIG;IACS;AAAZ,CAAA,UAAY,UAAU,EAAA;;AAEpB,IAAA,UAAA,CAAA,QAAA,CAAA,GAAA,QAAiB;;AAEjB,IAAA,UAAA,CAAA,MAAA,CAAA,GAAA,MAAa;;AAEb,IAAA,UAAA,CAAA,WAAA,CAAA,GAAA,WAAuB;AACzB,CAAC,EAPW,UAAU,KAAV,UAAU,GAAA,EAAA,CAAA,CAAA;;;;"}

package/dist/esm/tools/artifacts/schema.mjs

@@ -1,6 +1,11 @@
 import { z } from 'zod';
 
-const ARTIFACT_WRITE_ACTIONS = ['write', 'edit', 'verify', 'delete'];
+const ARTIFACT_WRITE_ACTIONS = [
+    'write',
+    'edit',
+    'verify',
+    'delete',
+];
 const CONTENT_READ_ACTIONS = ['read', 'search', 'list', 'info'];
 const artifactToolSchema = z.object({
     action: z
@@ -24,7 +29,10 @@ const artifactToolSchema = z.object({
         .string()
         .optional()
         .describe('Exact string to find and replace (required for edit).'),
-    new_str: z.string().optional().describe('Replacement string (required for edit).'),
+    new_str: z
+        .string()
+        .optional()
+        .describe('Replacement string (required for edit).'),
     replace_all: z
         .boolean()
         .optional()
@@ -42,12 +50,27 @@ const contentReaderSchema = z.object({
     start_line: z.number().optional().describe('1-based start line for reading.'),
     end_line: z.number().optional().describe('1-based end line (inclusive).'),
     // search
-    pattern: z.string().optional().describe('Regex pattern (required for search).'),
-    flags: z.string().optional().describe('Regex flags (e.g., "i" for case-insensitive).'),
-    context: z.number().optional().describe('Lines of context around each match.'),
+    pattern: z
+        .string()
+        .optional()
+        .describe('Regex pattern (required for search).'),
+    flags: z
+        .string()
+        .optional()
+        .describe('Regex flags (e.g., "i" for case-insensitive).'),
+    context: z
+        .number()
+        .optional()
+        .describe('Lines of context around each match.'),
     // shared pagination
-    offset: z.number().optional().describe('Offset for read or search pagination.'),
-    limit: z.number().optional().describe('Max lines (read) or matches (search).'),
+    offset: z
+        .number()
+        .optional()
+        .describe('Offset for read or search pagination.'),
+    limit: z
+        .number()
+        .optional()
+        .describe('Max lines (read) or matches (search).'),
 });
 const ARTIFACT_TOOL_NAME = 'artifact_tool';
 const CONTENT_READER_NAME = 'content_reader';

package/dist/esm/tools/artifacts/schema.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"schema.mjs","sources":["../../../../src/tools/artifacts/schema.ts"],"sourcesContent":["import { z } from 'zod';\n\nexport const ARTIFACT_WRITE_ACTIONS = ['write', 'edit', 'verify', 'delete'] as const;\nexport const CONTENT_READ_ACTIONS = ['read', 'search', 'list', 'info'] as const;\n\nexport const artifactToolSchema = z.object({\n  action: z\n    .enum(ARTIFACT_WRITE_ACTIONS)\n    .describe(\n      'Authoring action: write (create/overwrite), edit (str_replace), verify (syntax check), delete (remove).',\n    ),\n  content_id: z\n    .string()\n    .optional()\n    .describe(\n      'ID of the artifact entry. Required for edit/verify/delete; optional for write (supply to overwrite an existing entry).',\n    ),\n\n  // write\n  content: z\n    .string()\n    .optional()\n    .describe('Full file content (required for write action).'),\n  name: z\n    .string()\n    .optional()\n    .describe(\n      'Filename for the new entry (required when creating). MUST include the correct file extension — the extension drives the preview template.',\n    ),\n\n  // edit (str_replace)\n  old_str: z\n    .string()\n    .optional()\n    .describe('Exact string to find and replace (required for edit).'),\n  new_str: z.string().optional().describe('Replacement string (required for edit).'),\n  replace_all: z\n    .boolean()\n    .optional()\n    .describe(\n      'edit: when true, replaces every occurrence of old_str. When false (default) and old_str matches more than one location, the edit is refused.',\n    ),\n});\n\nexport const contentReaderSchema = z.object({\n  action: z\n    .enum(CONTENT_READ_ACTIONS)\n    .describe(\n      'Read-only action: read (lines), search (regex), list (all entries), info (metadata).',\n    ),\n  content_id: z\n    .string()\n    .optional()\n    .describe(\n      'ID of the content entry. Required for read/search/info. Omit for list.',\n    ),\n\n  // read pagination\n  start_line: z.number().optional().describe('1-based start line for reading.'),\n  end_line: z.number().optional().describe('1-based end line (inclusive).'),\n\n  // search\n  pattern: z.string().optional().describe('Regex pattern (required for search).'),\n  flags: z.string().optional().describe('Regex flags (e.g., \"i\" for case-insensitive).'),\n  context: z.number().optional().describe('Lines of context around each match.'),\n\n  // shared pagination\n  offset: z.number().optional().describe('Offset for read or search pagination.'),\n  limit: z.number().optional().describe('Max lines (read) or matches (search).'),\n});\n\nexport const ARTIFACT_TOOL_NAME = 'artifact_tool';\nexport const CONTENT_READER_NAME = 'content_reader';\n\nexport type ArtifactToolInput = z.infer<typeof artifactToolSchema>;\nexport type ContentReaderInput = z.infer<typeof contentReaderSchema>;\n"],"names":[],"mappings":";;AAEO,MAAM,sBAAsB,GAAG,CAAC,OAAO,EAAE,MAAM,EAAE,QAAQ,EAAE,QAAQ;AACnE,MAAM,oBAAoB,GAAG,CAAC,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,MAAM;AAE9D,MAAM,kBAAkB,GAAG,CAAC,CAAC,MAAM,CAAC;AACzC,IAAA,MAAM,EAAE;SACL,IAAI,CAAC,sBAAsB;SAC3B,QAAQ,CACP,yGAAyG,CAC1G;AACH,IAAA,UAAU,EAAE;AACT,SAAA,MAAM;AACN,SAAA,QAAQ;SACR,QAAQ,CACP,wHAAwH,CACzH;;AAGH,IAAA,OAAO,EAAE;AACN,SAAA,MAAM;AACN,SAAA,QAAQ;SACR,QAAQ,CAAC,gDAAgD,CAAC;AAC7D,IAAA,IAAI,EAAE;AACH,SAAA,MAAM;AACN,SAAA,QAAQ;SACR,QAAQ,CACP,2IAA2I,CAC5I;;AAGH,IAAA,OAAO,EAAE;AACN,SAAA,MAAM;AACN,SAAA,QAAQ;SACR,QAAQ,CAAC,uDAAuD,CAAC;AACpE,IAAA,OAAO,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE,CAAC,QAAQ,CAAC,yCAAyC,CAAC;AAClF,IAAA,WAAW,EAAE;AACV,SAAA,OAAO;AACP,SAAA,QAAQ;SACR,QAAQ,CACP,8IAA8I,CAC/I;AACJ,CAAA;AAEM,MAAM,mBAAmB,GAAG,CAAC,CAAC,MAAM,CAAC;AAC1C,IAAA,MAAM,EAAE;SACL,IAAI,CAAC,oBAAoB;SACzB,QAAQ,CACP,sFAAsF,CACvF;AACH,IAAA,UAAU,EAAE;AACT,SAAA,MAAM;AACN,SAAA,QAAQ;SACR,QAAQ,CACP,wEAAwE,CACzE;;AAGH,IAAA,UAAU,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE,CAAC,QAAQ,CAAC,iCAAiC,CAAC;AAC7E,IAAA,QAAQ,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE,CAAC,QAAQ,CAAC,+BAA+B,CAAC;;AAGzE,IAAA,OAAO,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE,CAAC,QAAQ,CAAC,sCAAsC,CAAC;AAC/E,IAAA,KAAK,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE,CAAC,QAAQ,CAAC,+CAA+C,CAAC;AACtF,IAAA,OAAO,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE,CAAC,QAAQ,CAAC,qCAAqC,CAAC;;AAG9E,IAAA,MAAM,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE,CAAC,QAAQ,CAAC,uCAAuC,CAAC;AAC/E,IAAA,KAAK,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE,CAAC,QAAQ,CAAC,uCAAuC,CAAC;AAC/E,CAAA;AAEM,MAAM,kBAAkB,GAAG;AAC3B,MAAM,mBAAmB,GAAG;;;;"}
+{"version":3,"file":"schema.mjs","sources":["../../../../src/tools/artifacts/schema.ts"],"sourcesContent":["import { z } from 'zod';\n\nexport const ARTIFACT_WRITE_ACTIONS = [\n  'write',\n  'edit',\n  'verify',\n  'delete',\n] as const;\nexport const CONTENT_READ_ACTIONS = ['read', 'search', 'list', 'info'] as const;\n\nexport const artifactToolSchema = z.object({\n  action: z\n    .enum(ARTIFACT_WRITE_ACTIONS)\n    .describe(\n      'Authoring action: write (create/overwrite), edit (str_replace), verify (syntax check), delete (remove).'\n    ),\n  content_id: z\n    .string()\n    .optional()\n    .describe(\n      'ID of the artifact entry. Required for edit/verify/delete; optional for write (supply to overwrite an existing entry).'\n    ),\n\n  // write\n  content: z\n    .string()\n    .optional()\n    .describe('Full file content (required for write action).'),\n  name: z\n    .string()\n    .optional()\n    .describe(\n      'Filename for the new entry (required when creating). MUST include the correct file extension — the extension drives the preview template.'\n    ),\n\n  // edit (str_replace)\n  old_str: z\n    .string()\n    .optional()\n    .describe('Exact string to find and replace (required for edit).'),\n  new_str: z\n    .string()\n    .optional()\n    .describe('Replacement string (required for edit).'),\n  replace_all: z\n    .boolean()\n    .optional()\n    .describe(\n      'edit: when true, replaces every occurrence of old_str. When false (default) and old_str matches more than one location, the edit is refused.'\n    ),\n});\n\nexport const contentReaderSchema = z.object({\n  action: z\n    .enum(CONTENT_READ_ACTIONS)\n    .describe(\n      'Read-only action: read (lines), search (regex), list (all entries), info (metadata).'\n    ),\n  content_id: z\n    .string()\n    .optional()\n    .describe(\n      'ID of the content entry. Required for read/search/info. Omit for list.'\n    ),\n\n  // read pagination\n  start_line: z.number().optional().describe('1-based start line for reading.'),\n  end_line: z.number().optional().describe('1-based end line (inclusive).'),\n\n  // search\n  pattern: z\n    .string()\n    .optional()\n    .describe('Regex pattern (required for search).'),\n  flags: z\n    .string()\n    .optional()\n    .describe('Regex flags (e.g., \"i\" for case-insensitive).'),\n  context: z\n    .number()\n    .optional()\n    .describe('Lines of context around each match.'),\n\n  // shared pagination\n  offset: z\n    .number()\n    .optional()\n    .describe('Offset for read or search pagination.'),\n  limit: z\n    .number()\n    .optional()\n    .describe('Max lines (read) or matches (search).'),\n});\n\nexport const ARTIFACT_TOOL_NAME = 'artifact_tool';\nexport const CONTENT_READER_NAME = 'content_reader';\n\nexport type ArtifactToolInput = z.infer<typeof artifactToolSchema>;\nexport type ContentReaderInput = z.infer<typeof contentReaderSchema>;\n"],"names":[],"mappings":";;AAEO,MAAM,sBAAsB,GAAG;IACpC,OAAO;IACP,MAAM;IACN,QAAQ;IACR,QAAQ;;AAEH,MAAM,oBAAoB,GAAG,CAAC,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,MAAM;AAE9D,MAAM,kBAAkB,GAAG,CAAC,CAAC,MAAM,CAAC;AACzC,IAAA,MAAM,EAAE;SACL,IAAI,CAAC,sBAAsB;SAC3B,QAAQ,CACP,yGAAyG,CAC1G;AACH,IAAA,UAAU,EAAE;AACT,SAAA,MAAM;AACN,SAAA,QAAQ;SACR,QAAQ,CACP,wHAAwH,CACzH;;AAGH,IAAA,OAAO,EAAE;AACN,SAAA,MAAM;AACN,SAAA,QAAQ;SACR,QAAQ,CAAC,gDAAgD,CAAC;AAC7D,IAAA,IAAI,EAAE;AACH,SAAA,MAAM;AACN,SAAA,QAAQ;SACR,QAAQ,CACP,2IAA2I,CAC5I;;AAGH,IAAA,OAAO,EAAE;AACN,SAAA,MAAM;AACN,SAAA,QAAQ;SACR,QAAQ,CAAC,uDAAuD,CAAC;AACpE,IAAA,OAAO,EAAE;AACN,SAAA,MAAM;AACN,SAAA,QAAQ;SACR,QAAQ,CAAC,yCAAyC,CAAC;AACtD,IAAA,WAAW,EAAE;AACV,SAAA,OAAO;AACP,SAAA,QAAQ;SACR,QAAQ,CACP,8IAA8I,CAC/I;AACJ,CAAA;AAEM,MAAM,mBAAmB,GAAG,CAAC,CAAC,MAAM,CAAC;AAC1C,IAAA,MAAM,EAAE;SACL,IAAI,CAAC,oBAAoB;SACzB,QAAQ,CACP,sFAAsF,CACvF;AACH,IAAA,UAAU,EAAE;AACT,SAAA,MAAM;AACN,SAAA,QAAQ;SACR,QAAQ,CACP,wEAAwE,CACzE;;AAGH,IAAA,UAAU,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE,CAAC,QAAQ,CAAC,iCAAiC,CAAC;AAC7E,IAAA,QAAQ,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE,CAAC,QAAQ,CAAC,+BAA+B,CAAC;;AAGzE,IAAA,OAAO,EAAE;AACN,SAAA,MAAM;AACN,SAAA,QAAQ;SACR,QAAQ,CAAC,sCAAsC,CAAC;AACnD,IAAA,KAAK,EAAE;AACJ,SAAA,MAAM;AACN,SAAA,QAAQ;SACR,QAAQ,CAAC,+CAA+C,CAAC;AAC5D,IAAA,OAAO,EAAE;AACN,SAAA,MAAM;AACN,SAAA,QAAQ;SACR,QAAQ,CAAC,qCAAqC,CAAC;;AAGlD,IAAA,MAAM,EAAE;AACL,SAAA,MAAM;AACN,SAAA,QAAQ;SACR,QAAQ,CAAC,uCAAuC,CAAC;AACpD,IAAA,KAAK,EAAE;AACJ,SAAA,MAAM;AACN,SAAA,QAAQ;SACR,QAAQ,CAAC,uCAAuC,CAAC;AACrD,CAAA;AAEM,MAAM,kBAAkB,GAAG;AAC3B,MAAM,mBAAmB,GAAG;;;;"}

package/dist/esm/tools/artifacts/tool.mjs

@@ -105,7 +105,10 @@ function createArtifactTool(config) {
                     return await handlers.delete(args, scope);
                 }
                 default:
-                    return [`Unknown action: ${input.action}`, {}];
+                    return [
+                        `Unknown action: ${input.action}`,
+                        {},
+                    ];
             }
         }
         catch (err) {
@@ -182,7 +185,10 @@ function createContentReaderTool(config) {
                     return await handlers.info(args, scope);
                 }
                 default:
-                    return [`Unknown action: ${input.action}`, {}];
+                    return [
+                        `Unknown action: ${input.action}`,
+                        {},
+                    ];
             }
         }
         catch (err) {

package/dist/esm/tools/artifacts/tool.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"tool.mjs","sources":["../../../../src/tools/artifacts/tool.ts"],"sourcesContent":["/**\n * artifact_tool + content_reader library factories.\n *\n * The library owns the LangChain wiring (schema, description, response\n * shape) and the action dispatch; the runtime supplies a handler bundle\n * matching the `ArtifactWriteHandlers` / `ContentReadHandlers` interface.\n *\n * This keeps 800+ LOC of host-specific handler logic (S3 adapters, file\n * model CRUD, syntax checkers, line utils) out of the library while\n * still centralizing the tool surface every runtime shares.\n */\n\nimport { tool, DynamicStructuredTool } from '@langchain/core/tools';\nimport {\n  artifactToolSchema,\n  contentReaderSchema,\n  ARTIFACT_TOOL_NAME,\n  CONTENT_READER_NAME,\n} from './schema';\nimport type {\n  ArtifactToolConfig,\n  ContentReaderToolConfig,\n  ArtifactToolScope,\n  ArtifactToolResult,\n  WriteArgs,\n  EditArgs,\n  VerifyArgs,\n  DeleteArgs,\n  ReadArgs,\n  SearchArgs,\n  ListArgs,\n  InfoArgs,\n  ContentIdResolver,\n} from './types';\n\nconst DEFAULT_ARTIFACT_DESCRIPTION = `Author content artifacts that render live in the host's preview panel — this tool does NOT produce downloadable files (use execute_code for those).\n\nActions:\n- write: Create a new artifact. Write a COMPLETE file in one call. The \\`name\\` field MUST include the file extension — it routes the preview (.tsx, .html, .mmd, .svg, .csv, .json, .dot, .md, .drawio).\n- verify: Check an artifact for syntax errors. REQUIRED as the next step after every write/edit on code files — do not render until verify passes.\n- edit: Surgical string replacement — provide old_str (exact match) and new_str. Works on all file types.\n- delete: Remove an artifact and its backing file.\n\nArtifacts are persisted by the host. No manual save needed.`;\n\nconst DEFAULT_CONTENT_READER_DESCRIPTION = `Read and navigate stored content — artifacts authored by artifact_tool, large tool results auto-cached by the host, uploaded file attachments, and code blocks.\n\nRead-only surface. Use write/edit tools (artifact_tool, execute_code) to mutate.\n\nActions:\n- read: Return line ranges from a specific content_id.\n- search: Regex search across a specific content_id with paginated matches.\n- list: Enumerate every content entry currently stored.\n- info: Metadata (size, kind, creation time) for a specific content_id.`;\n\n/**\n * Optional content_id self-healing — if the runtime supplies a resolver,\n * we pre-resolve the ID on every action that takes one so nicknames\n * (e.g., \"Dashboard\") map to canonical IDs.\n */\nasync function resolveContentIdIfPresent(\n  resolver: ContentIdResolver | undefined,\n  id: string | undefined,\n  scope: ArtifactToolScope,\n  logger?: { debug: (msg: string) => void },\n): Promise<string | undefined> {\n  if (!resolver || !id) return id;\n  const out = await resolver.resolve(id, scope);\n  if (!out) return id;\n  if (out.resolvedId !== id) {\n    logger?.debug(\n      `[artifact] resolved \"${id}\" → \"${out.resolvedId}\"${out.resolvedName ? ` (\"${out.resolvedName}\")` : ''}`,\n    );\n  }\n  return out.resolvedId;\n}\n\n// ─── Writer tool (artifact_tool) ─────────────────────────────────────────\n\nexport function createArtifactTool(\n  config: ArtifactToolConfig,\n): DynamicStructuredTool {\n  const { handlers, getScope, resolver, logger, descriptionOverride } = config;\n\n  return tool(\n    async (rawInput, runnableConfig): Promise<ArtifactToolResult> => {\n      const scope = getScope(runnableConfig);\n      if (!scope) {\n        logger?.warn('[artifact_tool] no scope resolved from runnableConfig');\n        return ['Error: No conversation context available', {}];\n      }\n\n      const input = rawInput as {\n        action: 'write' | 'edit' | 'verify' | 'delete';\n        content_id?: string;\n        content?: string;\n        name?: string;\n        old_str?: string;\n        new_str?: string;\n        replace_all?: boolean;\n      };\n\n      const resolvedContentId = await resolveContentIdIfPresent(\n        resolver,\n        input.content_id,\n        scope,\n        logger,\n      );\n\n      const started = Date.now();\n      try {\n        switch (input.action) {\n          case 'write': {\n            const args: WriteArgs = {\n              action: 'write',\n              content_id: resolvedContentId,\n              content: input.content ?? '',\n              name: input.name,\n            };\n            if (!args.content) return ['Error: write requires content', {}];\n            return await handlers.write(args, scope);\n          }\n          case 'edit': {\n            if (!resolvedContentId) return ['Error: edit requires content_id', {}];\n            const args: EditArgs = {\n              action: 'edit',\n              content_id: resolvedContentId,\n              old_str: input.old_str ?? '',\n              new_str: input.new_str ?? '',\n              replace_all: input.replace_all,\n            };\n            if (!args.old_str) return ['Error: edit requires old_str', {}];\n            return await handlers.edit(args, scope);\n          }\n          case 'verify': {\n            if (!resolvedContentId) return ['Error: verify requires content_id', {}];\n            const args: VerifyArgs = {\n              action: 'verify',\n              content_id: resolvedContentId,\n            };\n            return await handlers.verify(args, scope);\n          }\n          case 'delete': {\n            if (!resolvedContentId) return ['Error: delete requires content_id', {}];\n            const args: DeleteArgs = {\n              action: 'delete',\n              content_id: resolvedContentId,\n            };\n            return await handlers.delete(args, scope);\n          }\n          default:\n            return [`Unknown action: ${(input as { action: string }).action}`, {}];\n        }\n      } catch (err) {\n        const e = err instanceof Error ? err : new Error(String(err));\n        logger?.error('[artifact_tool] handler threw', {\n          action: input.action,\n          contentId: resolvedContentId,\n          error: e.message,\n          elapsed: `${Date.now() - started}ms`,\n        });\n        return [`Error: ${e.message}`, {}];\n      }\n    },\n    {\n      name: ARTIFACT_TOOL_NAME,\n      responseFormat: 'content_and_artifact',\n      description: descriptionOverride ?? DEFAULT_ARTIFACT_DESCRIPTION,\n      schema: artifactToolSchema,\n    },\n  );\n}\n\n// ─── Reader tool (content_reader) ────────────────────────────────────────\n\nexport function createContentReaderTool(\n  config: ContentReaderToolConfig,\n): DynamicStructuredTool {\n  const { handlers, getScope, resolver, logger, descriptionOverride } = config;\n\n  return tool(\n    async (rawInput, runnableConfig): Promise<ArtifactToolResult> => {\n      const scope = getScope(runnableConfig);\n      if (!scope) {\n        logger?.warn('[content_reader] no scope resolved from runnableConfig');\n        return ['Error: No conversation context available', {}];\n      }\n\n      const input = rawInput as {\n        action: 'read' | 'search' | 'list' | 'info';\n        content_id?: string;\n        start_line?: number;\n        end_line?: number;\n        pattern?: string;\n        flags?: string;\n        context?: number;\n        offset?: number;\n        limit?: number;\n      };\n\n      const resolvedContentId = await resolveContentIdIfPresent(\n        resolver,\n        input.content_id,\n        scope,\n        logger,\n      );\n\n      const started = Date.now();\n      try {\n        switch (input.action) {\n          case 'read': {\n            if (!resolvedContentId) return ['Error: read requires content_id', {}];\n            const args: ReadArgs = {\n              action: 'read',\n              content_id: resolvedContentId,\n              start_line: input.start_line,\n              end_line: input.end_line,\n              offset: input.offset,\n              limit: input.limit,\n            };\n            return await handlers.read(args, scope);\n          }\n          case 'search': {\n            if (!resolvedContentId) return ['Error: search requires content_id', {}];\n            if (!input.pattern) return ['Error: search requires pattern', {}];\n            const args: SearchArgs = {\n              action: 'search',\n              content_id: resolvedContentId,\n              pattern: input.pattern,\n              flags: input.flags,\n              context: input.context,\n              offset: input.offset,\n              limit: input.limit,\n            };\n            return await handlers.search(args, scope);\n          }\n          case 'list': {\n            const args: ListArgs = { action: 'list' };\n            return await handlers.list(args, scope);\n          }\n          case 'info': {\n            if (!resolvedContentId) return ['Error: info requires content_id', {}];\n            const args: InfoArgs = {\n              action: 'info',\n              content_id: resolvedContentId,\n            };\n            return await handlers.info(args, scope);\n          }\n          default:\n            return [`Unknown action: ${(input as { action: string }).action}`, {}];\n        }\n      } catch (err) {\n        const e = err instanceof Error ? err : new Error(String(err));\n        logger?.error('[content_reader] handler threw', {\n          action: input.action,\n          contentId: resolvedContentId,\n          error: e.message,\n          elapsed: `${Date.now() - started}ms`,\n        });\n        return [`Error: ${e.message}`, {}];\n      }\n    },\n    {\n      name: CONTENT_READER_NAME,\n      responseFormat: 'content_and_artifact',\n      description: descriptionOverride ?? DEFAULT_CONTENT_READER_DESCRIPTION,\n      schema: contentReaderSchema,\n    },\n  );\n}\n\nexport {\n  ARTIFACT_TOOL_NAME,\n  CONTENT_READER_NAME,\n  ARTIFACT_WRITE_ACTIONS,\n  CONTENT_READ_ACTIONS,\n} from './schema';\n"],"names":[],"mappings":"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"}
+{"version":3,"file":"tool.mjs","sources":["../../../../src/tools/artifacts/tool.ts"],"sourcesContent":["/**\n * artifact_tool + content_reader library factories.\n *\n * The library owns the LangChain wiring (schema, description, response\n * shape) and the action dispatch; the runtime supplies a handler bundle\n * matching the `ArtifactWriteHandlers` / `ContentReadHandlers` interface.\n *\n * This keeps 800+ LOC of host-specific handler logic (S3 adapters, file\n * model CRUD, syntax checkers, line utils) out of the library while\n * still centralizing the tool surface every runtime shares.\n */\n\nimport { tool, DynamicStructuredTool } from '@langchain/core/tools';\nimport {\n  artifactToolSchema,\n  contentReaderSchema,\n  ARTIFACT_TOOL_NAME,\n  CONTENT_READER_NAME,\n} from './schema';\nimport type {\n  ArtifactToolConfig,\n  ContentReaderToolConfig,\n  ArtifactToolScope,\n  ArtifactToolResult,\n  WriteArgs,\n  EditArgs,\n  VerifyArgs,\n  DeleteArgs,\n  ReadArgs,\n  SearchArgs,\n  ListArgs,\n  InfoArgs,\n  ContentIdResolver,\n} from './types';\n\nconst DEFAULT_ARTIFACT_DESCRIPTION = `Author content artifacts that render live in the host's preview panel — this tool does NOT produce downloadable files (use execute_code for those).\n\nActions:\n- write: Create a new artifact. Write a COMPLETE file in one call. The \\`name\\` field MUST include the file extension — it routes the preview (.tsx, .html, .mmd, .svg, .csv, .json, .dot, .md, .drawio).\n- verify: Check an artifact for syntax errors. REQUIRED as the next step after every write/edit on code files — do not render until verify passes.\n- edit: Surgical string replacement — provide old_str (exact match) and new_str. Works on all file types.\n- delete: Remove an artifact and its backing file.\n\nArtifacts are persisted by the host. No manual save needed.`;\n\nconst DEFAULT_CONTENT_READER_DESCRIPTION = `Read and navigate stored content — artifacts authored by artifact_tool, large tool results auto-cached by the host, uploaded file attachments, and code blocks.\n\nRead-only surface. Use write/edit tools (artifact_tool, execute_code) to mutate.\n\nActions:\n- read: Return line ranges from a specific content_id.\n- search: Regex search across a specific content_id with paginated matches.\n- list: Enumerate every content entry currently stored.\n- info: Metadata (size, kind, creation time) for a specific content_id.`;\n\n/**\n * Optional content_id self-healing — if the runtime supplies a resolver,\n * we pre-resolve the ID on every action that takes one so nicknames\n * (e.g., \"Dashboard\") map to canonical IDs.\n */\nasync function resolveContentIdIfPresent(\n  resolver: ContentIdResolver | undefined,\n  id: string | undefined,\n  scope: ArtifactToolScope,\n  logger?: { debug: (msg: string) => void }\n): Promise<string | undefined> {\n  if (!resolver || !id) return id;\n  const out = await resolver.resolve(id, scope);\n  if (!out) return id;\n  if (out.resolvedId !== id) {\n    logger?.debug(\n      `[artifact] resolved \"${id}\" → \"${out.resolvedId}\"${out.resolvedName ? ` (\"${out.resolvedName}\")` : ''}`\n    );\n  }\n  return out.resolvedId;\n}\n\n// ─── Writer tool (artifact_tool) ─────────────────────────────────────────\n\nexport function createArtifactTool(\n  config: ArtifactToolConfig\n): DynamicStructuredTool {\n  const { handlers, getScope, resolver, logger, descriptionOverride } = config;\n\n  return tool(\n    async (rawInput, runnableConfig): Promise<ArtifactToolResult> => {\n      const scope = getScope(runnableConfig);\n      if (!scope) {\n        logger?.warn('[artifact_tool] no scope resolved from runnableConfig');\n        return ['Error: No conversation context available', {}];\n      }\n\n      const input = rawInput as {\n        action: 'write' | 'edit' | 'verify' | 'delete';\n        content_id?: string;\n        content?: string;\n        name?: string;\n        old_str?: string;\n        new_str?: string;\n        replace_all?: boolean;\n      };\n\n      const resolvedContentId = await resolveContentIdIfPresent(\n        resolver,\n        input.content_id,\n        scope,\n        logger\n      );\n\n      const started = Date.now();\n      try {\n        switch (input.action) {\n          case 'write': {\n            const args: WriteArgs = {\n              action: 'write',\n              content_id: resolvedContentId,\n              content: input.content ?? '',\n              name: input.name,\n            };\n            if (!args.content) return ['Error: write requires content', {}];\n            return await handlers.write(args, scope);\n          }\n          case 'edit': {\n            if (!resolvedContentId)\n              return ['Error: edit requires content_id', {}];\n            const args: EditArgs = {\n              action: 'edit',\n              content_id: resolvedContentId,\n              old_str: input.old_str ?? '',\n              new_str: input.new_str ?? '',\n              replace_all: input.replace_all,\n            };\n            if (!args.old_str) return ['Error: edit requires old_str', {}];\n            return await handlers.edit(args, scope);\n          }\n          case 'verify': {\n            if (!resolvedContentId)\n              return ['Error: verify requires content_id', {}];\n            const args: VerifyArgs = {\n              action: 'verify',\n              content_id: resolvedContentId,\n            };\n            return await handlers.verify(args, scope);\n          }\n          case 'delete': {\n            if (!resolvedContentId)\n              return ['Error: delete requires content_id', {}];\n            const args: DeleteArgs = {\n              action: 'delete',\n              content_id: resolvedContentId,\n            };\n            return await handlers.delete(args, scope);\n          }\n          default:\n            return [\n              `Unknown action: ${(input as { action: string }).action}`,\n              {},\n            ];\n        }\n      } catch (err) {\n        const e = err instanceof Error ? err : new Error(String(err));\n        logger?.error('[artifact_tool] handler threw', {\n          action: input.action,\n          contentId: resolvedContentId,\n          error: e.message,\n          elapsed: `${Date.now() - started}ms`,\n        });\n        return [`Error: ${e.message}`, {}];\n      }\n    },\n    {\n      name: ARTIFACT_TOOL_NAME,\n      responseFormat: 'content_and_artifact',\n      description: descriptionOverride ?? DEFAULT_ARTIFACT_DESCRIPTION,\n      schema: artifactToolSchema,\n    }\n  );\n}\n\n// ─── Reader tool (content_reader) ────────────────────────────────────────\n\nexport function createContentReaderTool(\n  config: ContentReaderToolConfig\n): DynamicStructuredTool {\n  const { handlers, getScope, resolver, logger, descriptionOverride } = config;\n\n  return tool(\n    async (rawInput, runnableConfig): Promise<ArtifactToolResult> => {\n      const scope = getScope(runnableConfig);\n      if (!scope) {\n        logger?.warn('[content_reader] no scope resolved from runnableConfig');\n        return ['Error: No conversation context available', {}];\n      }\n\n      const input = rawInput as {\n        action: 'read' | 'search' | 'list' | 'info';\n        content_id?: string;\n        start_line?: number;\n        end_line?: number;\n        pattern?: string;\n        flags?: string;\n        context?: number;\n        offset?: number;\n        limit?: number;\n      };\n\n      const resolvedContentId = await resolveContentIdIfPresent(\n        resolver,\n        input.content_id,\n        scope,\n        logger\n      );\n\n      const started = Date.now();\n      try {\n        switch (input.action) {\n          case 'read': {\n            if (!resolvedContentId)\n              return ['Error: read requires content_id', {}];\n            const args: ReadArgs = {\n              action: 'read',\n              content_id: resolvedContentId,\n              start_line: input.start_line,\n              end_line: input.end_line,\n              offset: input.offset,\n              limit: input.limit,\n            };\n            return await handlers.read(args, scope);\n          }\n          case 'search': {\n            if (!resolvedContentId)\n              return ['Error: search requires content_id', {}];\n            if (!input.pattern) return ['Error: search requires pattern', {}];\n            const args: SearchArgs = {\n              action: 'search',\n              content_id: resolvedContentId,\n              pattern: input.pattern,\n              flags: input.flags,\n              context: input.context,\n              offset: input.offset,\n              limit: input.limit,\n            };\n            return await handlers.search(args, scope);\n          }\n          case 'list': {\n            const args: ListArgs = { action: 'list' };\n            return await handlers.list(args, scope);\n          }\n          case 'info': {\n            if (!resolvedContentId)\n              return ['Error: info requires content_id', {}];\n            const args: InfoArgs = {\n              action: 'info',\n              content_id: resolvedContentId,\n            };\n            return await handlers.info(args, scope);\n          }\n          default:\n            return [\n              `Unknown action: ${(input as { action: string }).action}`,\n              {},\n            ];\n        }\n      } catch (err) {\n        const e = err instanceof Error ? err : new Error(String(err));\n        logger?.error('[content_reader] handler threw', {\n          action: input.action,\n          contentId: resolvedContentId,\n          error: e.message,\n          elapsed: `${Date.now() - started}ms`,\n        });\n        return [`Error: ${e.message}`, {}];\n      }\n    },\n    {\n      name: CONTENT_READER_NAME,\n      responseFormat: 'content_and_artifact',\n      description: descriptionOverride ?? DEFAULT_CONTENT_READER_DESCRIPTION,\n      schema: contentReaderSchema,\n    }\n  );\n}\n\nexport {\n  ARTIFACT_TOOL_NAME,\n  CONTENT_READER_NAME,\n  ARTIFACT_WRITE_ACTIONS,\n  CONTENT_READ_ACTIONS,\n} from './schema';\n"],"names":[],"mappings":"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"}

package/dist/types/providers/types.d.ts

@@ -82,6 +82,20 @@ export interface CapabilityMetadata {
     category?: string;
     /** Free-form tags for filtering / search. */
     tags?: string[];
+    /**
+     * When true, hosts omit this capability from user-facing pickers
+     * (Agent Builder, tool dropdown). Still invokable when a saved agent
+     * references it by name.
+     */
+    hidden?: boolean;
+    /** When true, only admin-role users can enable or invoke this capability. */
+    admin?: boolean;
+    /**
+     * Deployment-stage restriction. When set, hosts whose deployment stage
+     * isn't in the array should hide the capability (e.g., a prod host
+     * shouldn't surface a tool with `env: ['development']`).
+     */
+    env?: Array<'development' | 'production' | 'test' | 'staging'>;
     /** Reserved for upstream `fix/auth-events` — auth mode declared by tool. */
     auth?: string;
     /** Reserved for upstream `fix/auth-events` — Unix timestamp for token expiration. */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@illuma-ai/agents",
-  "version": "1.4.0-alpha.3",
+  "version": "1.4.0-alpha.4",
   "main": "./dist/cjs/main.cjs",
   "module": "./dist/esm/main.mjs",
   "types": "./dist/types/index.d.ts",

package/src/providers/tools-server/ToolsServerCapabilityProvider.ts

@@ -79,6 +79,10 @@ interface ToolsServerManifestEntry {
   tags?: string[];
   toolkit?: string;
   endpoint?: string;
+  /** Governance flags forwarded by tools-server getManifest(). */
+  hidden?: boolean;
+  admin?: boolean;
+  env?: Array<'development' | 'production' | 'test' | 'staging'>;
 }
 
 export class ToolsServerCapabilityProvider implements CapabilityProvider {
@@ -215,6 +219,10 @@ function normalizeEntry(entry: ToolsServerManifestEntry): Capability {
       icon: entry.icon,
       category: entry.category,
       tags: entry.tags,
+      // Governance — hosts use these to gate UI/role/environment.
+      hidden: entry.hidden,
+      admin: entry.admin,
+      env: entry.env,
     },
   };
 }

package/src/providers/types.ts

@@ -88,6 +88,23 @@ export interface CapabilityMetadata {
   /** Free-form tags for filtering / search. */
   tags?: string[];
 
+  // --- Governance flags ------------------------------------------------
+
+  /**
+   * When true, hosts omit this capability from user-facing pickers
+   * (Agent Builder, tool dropdown). Still invokable when a saved agent
+   * references it by name.
+   */
+  hidden?: boolean;
+  /** When true, only admin-role users can enable or invoke this capability. */
+  admin?: boolean;
+  /**
+   * Deployment-stage restriction. When set, hosts whose deployment stage
+   * isn't in the array should hide the capability (e.g., a prod host
+   * shouldn't surface a tool with `env: ['development']`).
+   */
+  env?: Array<'development' | 'production' | 'test' | 'staging'>;
+
   // --- Reserved for upstream patterns (not populated today) ---
 
   /** Reserved for upstream `fix/auth-events` — auth mode declared by tool. */

package/src/tools/artifacts/__tests__/tool.test.ts

@@ -10,10 +10,7 @@
  * We verify each of those paths here with mock handlers.
  */
 
-import {
-  createArtifactTool,
-  createContentReaderTool,
-} from '../tool';
+import { createArtifactTool, createContentReaderTool } from '../tool';
 import type {
   ArtifactWriteHandlers,
   ContentReadHandlers,
@@ -105,10 +102,14 @@ describe('createArtifactTool', () => {
     await t.invoke({ action: 'write', content: 'hello', name: 'doc.md' });
     expect(handlers.write).toHaveBeenCalledTimes(1);
     expect(handlers._calls[0].args).toEqual(
-      expect.objectContaining({ action: 'write', content: 'hello', name: 'doc.md' }),
+      expect.objectContaining({
+        action: 'write',
+        content: 'hello',
+        name: 'doc.md',
+      })
     );
     expect(handlers._calls[0].scope).toEqual(
-      expect.objectContaining({ conversationId: 'conv-1' }),
+      expect.objectContaining({ conversationId: 'conv-1' })
     );
   });
 
@@ -131,17 +132,26 @@ describe('createArtifactTool', () => {
       getScope: makeScope,
     });
     const e = await t.invoke({ action: 'edit', old_str: 'a', new_str: 'b' });
-    expect(String(Array.isArray(e) ? e[0] : e)).toMatch(/edit requires content_id/i);
+    expect(String(Array.isArray(e) ? e[0] : e)).toMatch(
+      /edit requires content_id/i
+    );
     const v = await t.invoke({ action: 'verify' });
-    expect(String(Array.isArray(v) ? v[0] : v)).toMatch(/verify requires content_id/i);
+    expect(String(Array.isArray(v) ? v[0] : v)).toMatch(
+      /verify requires content_id/i
+    );
     const d = await t.invoke({ action: 'delete' });
-    expect(String(Array.isArray(d) ? d[0] : d)).toMatch(/delete requires content_id/i);
+    expect(String(Array.isArray(d) ? d[0] : d)).toMatch(
+      /delete requires content_id/i
+    );
   });
 
   it('applies the resolver before dispatching to handler', async () => {
     const handlers = makeWriteHandlers();
     const resolver: ContentIdResolver = {
-      resolve: jest.fn(async (id) => ({ resolvedId: `canonical:${id}`, resolvedName: 'X' })),
+      resolve: jest.fn(async (id) => ({
+        resolvedId: `canonical:${id}`,
+        resolvedName: 'X',
+      })),
     };
     const t = createArtifactTool({
       handlers,
@@ -155,7 +165,7 @@ describe('createArtifactTool', () => {
       new_str: 'b',
     });
     expect(handlers._calls[0].args).toEqual(
-      expect.objectContaining({ content_id: 'canonical:nickname' }),
+      expect.objectContaining({ content_id: 'canonical:nickname' })
     );
   });
 
@@ -202,11 +212,17 @@ describe('createContentReaderTool', () => {
       getScope: makeScope,
     });
     const r = await t.invoke({ action: 'read' });
-    expect(String(Array.isArray(r) ? r[0] : r)).toMatch(/read requires content_id/i);
+    expect(String(Array.isArray(r) ? r[0] : r)).toMatch(
+      /read requires content_id/i
+    );
     const i = await t.invoke({ action: 'info' });
-    expect(String(Array.isArray(i) ? i[0] : i)).toMatch(/info requires content_id/i);
+    expect(String(Array.isArray(i) ? i[0] : i)).toMatch(
+      /info requires content_id/i
+    );
     const s = await t.invoke({ action: 'search', pattern: 'p' });
-    expect(String(Array.isArray(s) ? s[0] : s)).toMatch(/search requires content_id/i);
+    expect(String(Array.isArray(s) ? s[0] : s)).toMatch(
+      /search requires content_id/i
+    );
   });
 
   it('rejects search without pattern even when content_id is given', async () => {
@@ -237,7 +253,7 @@ describe('createContentReaderTool', () => {
         content_id: 'c-1',
         start_line: 10,
         end_line: 50,
-      }),
+      })
     );
   });
 });

package/src/tools/artifacts/schema.ts

@@ -1,19 +1,24 @@
 import { z } from 'zod';
 
-export const ARTIFACT_WRITE_ACTIONS = ['write', 'edit', 'verify', 'delete'] as const;
+export const ARTIFACT_WRITE_ACTIONS = [
+  'write',
+  'edit',
+  'verify',
+  'delete',
+] as const;
 export const CONTENT_READ_ACTIONS = ['read', 'search', 'list', 'info'] as const;
 
 export const artifactToolSchema = z.object({
   action: z
     .enum(ARTIFACT_WRITE_ACTIONS)
     .describe(
-      'Authoring action: write (create/overwrite), edit (str_replace), verify (syntax check), delete (remove).',
+      'Authoring action: write (create/overwrite), edit (str_replace), verify (syntax check), delete (remove).'
     ),
   content_id: z
     .string()
     .optional()
     .describe(
-      'ID of the artifact entry. Required for edit/verify/delete; optional for write (supply to overwrite an existing entry).',
+      'ID of the artifact entry. Required for edit/verify/delete; optional for write (supply to overwrite an existing entry).'
     ),
 
   // write
@@ -25,7 +30,7 @@ export const artifactToolSchema = z.object({
     .string()
     .optional()
     .describe(
-      'Filename for the new entry (required when creating). MUST include the correct file extension — the extension drives the preview template.',
+      'Filename for the new entry (required when creating). MUST include the correct file extension — the extension drives the preview template.'
     ),
 
   // edit (str_replace)
@@ -33,12 +38,15 @@ export const artifactToolSchema = z.object({
     .string()
     .optional()
     .describe('Exact string to find and replace (required for edit).'),
-  new_str: z.string().optional().describe('Replacement string (required for edit).'),
+  new_str: z
+    .string()
+    .optional()
+    .describe('Replacement string (required for edit).'),
   replace_all: z
     .boolean()
     .optional()
     .describe(
-      'edit: when true, replaces every occurrence of old_str. When false (default) and old_str matches more than one location, the edit is refused.',
+      'edit: when true, replaces every occurrence of old_str. When false (default) and old_str matches more than one location, the edit is refused.'
     ),
 });
 
@@ -46,13 +54,13 @@ export const contentReaderSchema = z.object({
   action: z
     .enum(CONTENT_READ_ACTIONS)
     .describe(
-      'Read-only action: read (lines), search (regex), list (all entries), info (metadata).',
+      'Read-only action: read (lines), search (regex), list (all entries), info (metadata).'
     ),
   content_id: z
     .string()
     .optional()
     .describe(
-      'ID of the content entry. Required for read/search/info. Omit for list.',
+      'ID of the content entry. Required for read/search/info. Omit for list.'
     ),
 
   // read pagination
@@ -60,13 +68,28 @@ export const contentReaderSchema = z.object({
   end_line: z.number().optional().describe('1-based end line (inclusive).'),
 
   // search
-  pattern: z.string().optional().describe('Regex pattern (required for search).'),
-  flags: z.string().optional().describe('Regex flags (e.g., "i" for case-insensitive).'),
-  context: z.number().optional().describe('Lines of context around each match.'),
+  pattern: z
+    .string()
+    .optional()
+    .describe('Regex pattern (required for search).'),
+  flags: z
+    .string()
+    .optional()
+    .describe('Regex flags (e.g., "i" for case-insensitive).'),
+  context: z
+    .number()
+    .optional()
+    .describe('Lines of context around each match.'),
 
   // shared pagination
-  offset: z.number().optional().describe('Offset for read or search pagination.'),
-  limit: z.number().optional().describe('Max lines (read) or matches (search).'),
+  offset: z
+    .number()
+    .optional()
+    .describe('Offset for read or search pagination.'),
+  limit: z
+    .number()
+    .optional()
+    .describe('Max lines (read) or matches (search).'),
 });
 
 export const ARTIFACT_TOOL_NAME = 'artifact_tool';

package/src/tools/artifacts/tool.ts

@@ -62,14 +62,14 @@ async function resolveContentIdIfPresent(
   resolver: ContentIdResolver | undefined,
   id: string | undefined,
   scope: ArtifactToolScope,
-  logger?: { debug: (msg: string) => void },
+  logger?: { debug: (msg: string) => void }
 ): Promise<string | undefined> {
   if (!resolver || !id) return id;
   const out = await resolver.resolve(id, scope);
   if (!out) return id;
   if (out.resolvedId !== id) {
     logger?.debug(
-      `[artifact] resolved "${id}" → "${out.resolvedId}"${out.resolvedName ? ` ("${out.resolvedName}")` : ''}`,
+      `[artifact] resolved "${id}" → "${out.resolvedId}"${out.resolvedName ? ` ("${out.resolvedName}")` : ''}`
     );
   }
   return out.resolvedId;
@@ -78,7 +78,7 @@ async function resolveContentIdIfPresent(
 // ─── Writer tool (artifact_tool) ─────────────────────────────────────────
 
 export function createArtifactTool(
-  config: ArtifactToolConfig,
+  config: ArtifactToolConfig
 ): DynamicStructuredTool {
   const { handlers, getScope, resolver, logger, descriptionOverride } = config;
 
@@ -104,7 +104,7 @@ export function createArtifactTool(
         resolver,
         input.content_id,
         scope,
-        logger,
+        logger
       );
 
       const started = Date.now();
@@ -121,7 +121,8 @@ export function createArtifactTool(
             return await handlers.write(args, scope);
           }
           case 'edit': {
-            if (!resolvedContentId) return ['Error: edit requires content_id', {}];
+            if (!resolvedContentId)
+              return ['Error: edit requires content_id', {}];
             const args: EditArgs = {
               action: 'edit',
               content_id: resolvedContentId,
@@ -133,7 +134,8 @@ export function createArtifactTool(
             return await handlers.edit(args, scope);
           }
           case 'verify': {
-            if (!resolvedContentId) return ['Error: verify requires content_id', {}];
+            if (!resolvedContentId)
+              return ['Error: verify requires content_id', {}];
             const args: VerifyArgs = {
               action: 'verify',
               content_id: resolvedContentId,
@@ -141,7 +143,8 @@ export function createArtifactTool(
             return await handlers.verify(args, scope);
           }
           case 'delete': {
-            if (!resolvedContentId) return ['Error: delete requires content_id', {}];
+            if (!resolvedContentId)
+              return ['Error: delete requires content_id', {}];
             const args: DeleteArgs = {
               action: 'delete',
               content_id: resolvedContentId,
@@ -149,7 +152,10 @@ export function createArtifactTool(
             return await handlers.delete(args, scope);
           }
           default:
-            return [`Unknown action: ${(input as { action: string }).action}`, {}];
+            return [
+              `Unknown action: ${(input as { action: string }).action}`,
+              {},
+            ];
         }
       } catch (err) {
         const e = err instanceof Error ? err : new Error(String(err));
@@ -167,14 +173,14 @@ export function createArtifactTool(
       responseFormat: 'content_and_artifact',
       description: descriptionOverride ?? DEFAULT_ARTIFACT_DESCRIPTION,
       schema: artifactToolSchema,
-    },
+    }
   );
 }
 
 // ─── Reader tool (content_reader) ────────────────────────────────────────
 
 export function createContentReaderTool(
-  config: ContentReaderToolConfig,
+  config: ContentReaderToolConfig
 ): DynamicStructuredTool {
   const { handlers, getScope, resolver, logger, descriptionOverride } = config;
 
@@ -202,14 +208,15 @@ export function createContentReaderTool(
         resolver,
         input.content_id,
         scope,
-        logger,
+        logger
       );
 
       const started = Date.now();
       try {
         switch (input.action) {
           case 'read': {
-            if (!resolvedContentId) return ['Error: read requires content_id', {}];
+            if (!resolvedContentId)
+              return ['Error: read requires content_id', {}];
             const args: ReadArgs = {
               action: 'read',
               content_id: resolvedContentId,
@@ -221,7 +228,8 @@ export function createContentReaderTool(
             return await handlers.read(args, scope);
           }
           case 'search': {
-            if (!resolvedContentId) return ['Error: search requires content_id', {}];
+            if (!resolvedContentId)
+              return ['Error: search requires content_id', {}];
             if (!input.pattern) return ['Error: search requires pattern', {}];
             const args: SearchArgs = {
               action: 'search',
@@ -239,7 +247,8 @@ export function createContentReaderTool(
             return await handlers.list(args, scope);
           }
           case 'info': {
-            if (!resolvedContentId) return ['Error: info requires content_id', {}];
+            if (!resolvedContentId)
+              return ['Error: info requires content_id', {}];
             const args: InfoArgs = {
               action: 'info',
               content_id: resolvedContentId,
@@ -247,7 +256,10 @@ export function createContentReaderTool(
             return await handlers.info(args, scope);
           }
           default:
-            return [`Unknown action: ${(input as { action: string }).action}`, {}];
+            return [
+              `Unknown action: ${(input as { action: string }).action}`,
+              {},
+            ];
         }
       } catch (err) {
         const e = err instanceof Error ? err : new Error(String(err));
@@ -265,7 +277,7 @@ export function createContentReaderTool(
       responseFormat: 'content_and_artifact',
       description: descriptionOverride ?? DEFAULT_CONTENT_READER_DESCRIPTION,
       schema: contentReaderSchema,
-    },
+    }
   );
 }
 

package/src/tools/artifacts/types.ts

@@ -83,7 +83,11 @@ export interface InfoArgs {
   content_id: string;
 }
 
-export type ArtifactWriteAction = WriteArgs | EditArgs | VerifyArgs | DeleteArgs;
+export type ArtifactWriteAction =
+  | WriteArgs
+  | EditArgs
+  | VerifyArgs
+  | DeleteArgs;
 export type ArtifactReadAction = ReadArgs | SearchArgs | ListArgs | InfoArgs;
 
 // ─── Handler bundles ──────────────────────────────────────────────────────
@@ -92,14 +96,23 @@ export type ArtifactReadAction = ReadArgs | SearchArgs | ListArgs | InfoArgs;
 export interface ArtifactWriteHandlers {
   write(args: WriteArgs, scope: ArtifactToolScope): Promise<ArtifactToolResult>;
   edit(args: EditArgs, scope: ArtifactToolScope): Promise<ArtifactToolResult>;
-  verify(args: VerifyArgs, scope: ArtifactToolScope): Promise<ArtifactToolResult>;
-  delete(args: DeleteArgs, scope: ArtifactToolScope): Promise<ArtifactToolResult>;
+  verify(
+    args: VerifyArgs,
+    scope: ArtifactToolScope
+  ): Promise<ArtifactToolResult>;
+  delete(
+    args: DeleteArgs,
+    scope: ArtifactToolScope
+  ): Promise<ArtifactToolResult>;
 }
 
 /** Reader-surface handlers — invoked by `content_reader`. */
 export interface ContentReadHandlers {
   read(args: ReadArgs, scope: ArtifactToolScope): Promise<ArtifactToolResult>;
-  search(args: SearchArgs, scope: ArtifactToolScope): Promise<ArtifactToolResult>;
+  search(
+    args: SearchArgs,
+    scope: ArtifactToolScope
+  ): Promise<ArtifactToolResult>;
   list(args: ListArgs, scope: ArtifactToolScope): Promise<ArtifactToolResult>;
   info(args: InfoArgs, scope: ArtifactToolScope): Promise<ArtifactToolResult>;
 }
@@ -112,7 +125,7 @@ export interface ContentReadHandlers {
 export interface ContentIdResolver {
   resolve(
     id: string,
-    scope: ArtifactToolScope,
+    scope: ArtifactToolScope
   ): Promise<{ resolvedId: string; resolvedName?: string } | null>;
 }