@finalai/agent-definition 0.1.4 → 0.1.5

package/HOSTING.md

@@ -21,6 +21,24 @@ Neither rewrites authored URLs. A GitHub-backed definition uses remote source;
 push edits before explicitly publishing a ref. Caller API keys never become agent
 credentials merely because they were used to publish.
 
+## Hosted model resolution (SDK 0.2.0)
+
+Hosted Final, Pi, Codex and Claude configurations accept string model references.
+`serverless*ConfigSchema.parse(...).model` can be undefined: the host must choose
+its catalog default, resolve aliases and validate availability before dispatch.
+The host owns current candidates, runtime capabilities and dated prices, and
+advertises picker choices through its harness descriptions. Compilation remains
+offline and checks reference syntax.
+
+SDK 0.2.0 removes `@finalai/agents/models` and
+`@finalai/final-agent-provider/harnesses/models`, including their model arrays,
+defaults, model-ID unions and pricing helpers. Migrate callers to string model
+references and host-owned discovery, metadata and pricing.
+
+Publish the SDK release before upgrading host dependencies. Ship the host's
+catalog/default implementation together with its SDK dependency upgrade; a host
+that only changes the dependency will lose the old default and catalog APIs.
+
 ## Hosted connections
 
 ```ts
@@ -99,15 +117,37 @@ export default defineFinalConnection({
 });
 ```
 
-Without `load`, the harness lists every exposed tool, as before. With it, the host
-lists only the loaded tools and must keep every other exposed tool reachable: it
-serves a search over the connection's remaining exposed tools (name, description,
-input schema) and a call that runs a found tool by its real name, with the same
-exposure and approval checks as a direct call. A host may instead add a found tool
-to the list and send `notifications/tools/list_changed`; harnesses that ignore that
-notification still need the call path. `load: []` leaves every tool to search.
-Entries are tool names or `*` patterns. `isToolLoaded` from `@finalai/agent-provider`
-applies the rule after exposure.
+With `load`, the host lists only the loaded tools and must keep every other exposed
+tool reachable: it serves a search over the connection's remaining exposed tools
+(name, description, input schema) and a call that runs a found tool by its real
+name, with the same exposure and approval checks as a direct call. A host may
+instead add a found tool to the list and send `notifications/tools/list_changed`;
+harnesses that ignore that notification still need the call path. `load: []`
+leaves every tool to search. Entries are tool names or `*` patterns.
+`isToolLoaded` from `@finalai/agent-provider` applies the rule after exposure.
+
+Without `load`, the harness lists the connection's exposed tools except:
+
+- **Connector tools.** A server can label a tool with the connector it belongs to
+  in the tool's `_meta`:
+  `{ "ai.final/connector": { "namespace": "salesforce", "name": "Salesforce" } }`.
+  The namespace identifies the connector (unique within the server's tools); the
+  name is for display, and two connectors may share one. Final's server labels
+  every connector tool with the namespace and name of the install it comes from.
+  The host never lists labelled tools up front. Its search tool names each
+  connector and how many tools it has, so the agent knows what is connected
+  without any of those definitions in its context, and searches for the tools it
+  needs. A `load` entry that names a labelled tool still lists it.
+- **Tools past a size limit.** When a connection exposes more unlabelled tools
+  than the host lists directly (100 in Final's host), those are searched too.
+
+A harness that declares `supports.deferredToolSearch` defers and searches tools
+itself, so the host lists every exposed tool to it and serves no search.
+
+A host's search should name the connectors it covers and accept a connector's
+namespace to narrow to. Once a host has listed its search and call tools, it keeps answering them for
+that harness even if the connection stops hiding tools, unless the connection
+then lists its own tool by one of those names.
 
 ## Selecting tools by annotation
 

package/dist/compiler-assets/{chunk-RIEMTCTV.ts → chunk-5PWY25HA.ts}

@@ -68,7 +68,7 @@ var SHARED_SCHEMAS = {
   [SCHEMA_IDS.modelPicker]: {
     $id: SCHEMA_IDS.modelPicker,
     title: "Model",
-    // The harness supplies the enum: { $ref: model-picker, enum: [...] }.
+    // The harness or hosting platform supplies reference constraints and picker choices.
     type: "string",
     "x-final-widget": "model-picker"
   },
@@ -263,7 +263,8 @@ var harnessDescriptionSchema = object({
     nativeToolPolicy: boolean().optional(),
     // Defers and searches MCP tools itself (a harness-native tool search): the
     // host lists every exposed tool, ignoring connections' `tools.load`, and
-    // adds no search of its own. Absent: the host applies `load` and serves search.
+    // adds no search of its own. Absent: the host lists what `load` (or, without
+    // it, HOSTING.md's defaults) leaves listed and serves search for the rest.
     deferredToolSearch: boolean().optional()
   }),
   promptWhileRunning: nativeEnum(PromptWhileRunning).default(DEFAULT_PROMPT_WHILE_RUNNING),

package/dist/compiler-assets/{chunk-Z5TO7RSJ.ts → chunk-RSWGFPNZ.ts}

@@ -1,6 +1,6 @@
 import {
   harnessDescriptionSchema
-} from "./chunk-RIEMTCTV.ts";
+} from "./chunk-5PWY25HA.ts";
 import {
   bundleRef
 } from "./chunk-APU2VKLW.ts";

package/dist/compiler-assets/src/authoring/harness.ts

@@ -1,8 +1,8 @@
 import {
   completeHarnessDescription,
   defineHarness
-} from "../../chunk-Z5TO7RSJ.ts";
-import "../../chunk-RIEMTCTV.ts";
+} from "../../chunk-RSWGFPNZ.ts";
+import "../../chunk-5PWY25HA.ts";
 import "../../chunk-APU2VKLW.ts";
 import "../../chunk-GCFSHHH2.ts";
 import "../../chunk-MSE7X5YG.ts";

package/dist/compiler-assets/src/authoring/index.ts

@@ -2,7 +2,7 @@ import "../../chunk-RMIQJHSL.ts";
 import {
   completeHarnessDescription,
   defineHarness
-} from "../../chunk-Z5TO7RSJ.ts";
+} from "../../chunk-RSWGFPNZ.ts";
 import {
   HookEvent,
   defineHook
@@ -15,11 +15,11 @@ import {
   defineSandbox,
   defineSandboxProvider,
   harnessHost
-} from "../../chunk-IZGOMT7K.ts";
+} from "../../chunk-B5RJDCXZ.ts";
 import "../../chunk-4E5HECVD.ts";
 import {
   SandboxWire
-} from "../../chunk-RIEMTCTV.ts";
+} from "../../chunk-5PWY25HA.ts";
 import {
   defineSchedule
 } from "../../chunk-JGQ2KAN7.ts";

package/dist/compiler-assets/src/authoring/sandbox.ts

@@ -3,11 +3,11 @@ import {
   defineSandbox,
   defineSandboxProvider,
   harnessHost
-} from "../../chunk-IZGOMT7K.ts";
+} from "../../chunk-B5RJDCXZ.ts";
 import "../../chunk-4E5HECVD.ts";
 import {
   SandboxWire
-} from "../../chunk-RIEMTCTV.ts";
+} from "../../chunk-5PWY25HA.ts";
 import "../../chunk-APU2VKLW.ts";
 import "../../chunk-GCFSHHH2.ts";
 import "../../chunk-MSE7X5YG.ts";

package/dist/compiler-assets/src/compatibility.ts

@@ -3,7 +3,7 @@ import {
   SHARED_SCHEMAS,
   deliveredHarnessConfig,
   referencedSharedSchemas
-} from "../chunk-RIEMTCTV.ts";
+} from "../chunk-5PWY25HA.ts";
 import {
   BaseCapability,
   formatProviderRef

package/dist/compiler-assets/src/index.ts

@@ -15,7 +15,7 @@ import "../chunk-RMIQJHSL.ts";
 import {
   completeHarnessDescription,
   defineHarness
-} from "../chunk-Z5TO7RSJ.ts";
+} from "../chunk-RSWGFPNZ.ts";
 import {
   HookEvent,
   defineHook
@@ -28,11 +28,11 @@ import {
   defineSandbox,
   defineSandboxProvider,
   harnessHost
-} from "../chunk-IZGOMT7K.ts";
+} from "../chunk-B5RJDCXZ.ts";
 import "../chunk-4E5HECVD.ts";
 import {
   SandboxWire
-} from "../chunk-RIEMTCTV.ts";
+} from "../chunk-5PWY25HA.ts";
 import {
   defineSchedule
 } from "../chunk-JGQ2KAN7.ts";

package/dist/modules/authoring/connections.mjs.map

@@ -1,7 +1,7 @@
 {
   "version": 3,
   "sources": ["../../../../../src/authoring/connections.ts"],
-  "sourcesContent": ["import type { ApprovalPolicyIface } from \"./approval.mjs\";\nimport { AuthoredKind, stamp } from \"./brand.mjs\";\nimport { jsonObjectSchema, mcpAuthSchema, requireHostedBinding } from '@finalai/agent-provider';\nimport * as z from 'zod';\nimport { defineDynamic, type DynamicSentinelIface } from \"./dynamic.mjs\";\n\n// An MCP connection. Secrets are references by\n// name: the MCP host injects them, so they never reach the harness. Final's\n// own MCP server is an ordinary connection with `auth: { kind: 'final-session' }`.\n\nexport type McpConnectionAuthIface =\n  // Sent as `Authorization: Bearer <secret>` when headerName is null.\n  | { readonly secretKey: string; readonly headerName: string | null }\n  | { readonly kind: 'final-session' };\n\n// Selects tools by the MCP annotations their server reports, reading omitted\n// hints as the spec's defaults: `{ readOnlyHint: true }` matches only tools\n// the server marks read-only. Use with servers you trust to classify tools.\nexport interface McpToolAnnotationSelectorIface {\n  readonly readOnlyHint?: boolean;\n  readonly destructiveHint?: boolean;\n  readonly idempotentHint?: boolean;\n  readonly openWorldHint?: boolean;\n}\n\nexport type McpToolSelector = string | McpToolAnnotationSelectorIface;\n\n// Entries and keys are tool names or `*` patterns (`github.*`), and allow and\n// deny entries may also be annotation selectors; the most specific matching\n// key governs a tool.\nexport interface McpConnectionToolsIface {\n  // Only these tools are exposed; omit to expose every tool the server lists.\n  // Annotation-selected tools run under the connection's default approval.\n  readonly allow?: readonly McpToolSelector[];\n  // These tools are hidden, whatever `allow` says.\n  readonly deny?: readonly McpToolSelector[];\n  // Per-tool approval; tools not listed use the connection's `approval`.\n  readonly approval?: Readonly<Record<string, ApprovalPolicyIface<never>>>;\n  // Exposed tools (names or `*` patterns) the harness lists up front; the rest\n  // stay reachable through the host's tool search. Omit to list every exposed tool.\n  readonly load?: readonly string[];\n}\n\nexport interface McpClientConnectionDefinitionIface {\n  readonly url: string;\n  readonly description?: string;\n  readonly auth?: McpConnectionAuthIface;\n  readonly headers?: Readonly<Record<string, string>>;\n  readonly tools?: McpConnectionToolsIface;\n  // Default approval for every tool of this connection.\n  readonly approval?: ApprovalPolicyIface<never>;\n  readonly protocolVersionDiscovery?: boolean;\n  readonly instanceKey?: string;\n}\n\nexport const defineMcpClientConnection = <TConnection extends McpClientConnectionDefinitionIface>(\n  definition: TConnection,\n): TConnection => stamp({ ...definition }, AuthoredKind.Connection);\n\nexport interface HostedConnectionDefinitionIface extends Omit<\n  McpClientConnectionDefinitionIface,\n  'url' | 'auth' | 'headers' | 'protocolVersionDiscovery' | 'instanceKey'\n> {\n  readonly binding: string;\n}\n\nconst hostedConnectionSchema = z.strictObject({\n  url: z.string().url(),\n  auth: mcpAuthSchema.nullable().optional(),\n  headers: z.record(z.string(), z.string()).optional(),\n});\n\n// Built-in and third-party bindings use the ordinary dynamic connection path.\nexport const defineHostedConnection = (\n  definition: HostedConnectionDefinitionIface,\n): DynamicSentinelIface<McpClientConnectionDefinitionIface> => {\n  const { binding, description, tools, approval } = definition;\n  if (binding.trim().length === 0) throw new Error('Hosted connection binding must not be empty');\n  return defineDynamic({\n    description: definition.description ?? `Hosted connection ${binding}`,\n    preview: `Resolved by hosting from ${binding}`,\n    requiredBindings: [\n      { name: binding, schema: jsonObjectSchema.parse(z.toJSONSchema(hostedConnectionSchema)) },\n    ],\n    events: {\n      'session.started': async (_event, ctx) => {\n        const value = await requireHostedBinding({ bindings: ctx.bindings, name: binding });\n        const parsed = hostedConnectionSchema.safeParse(value);\n        if (!parsed.success)\n          throw new Error(`Hosted connection ${binding} has invalid configuration`);\n        const { auth, ...transport } = parsed.data;\n        return defineMcpClientConnection({\n          ...transport,\n          description,\n          tools,\n          approval,\n          ...(auth == null ? {} : { auth }),\n        });\n      },\n    },\n  });\n};\n"],
-  "mappings": "AACA,SAAS,cAAc,aAAa;AACpC,SAAS,kBAAkB,eAAe,4BAA4B;AACtE,YAAY,OAAO;AACnB,SAAS,qBAAgD;AAmDlD,MAAM,4BAA4B,CACvC,eACgB,MAAM,EAAE,GAAG,WAAW,GAAG,aAAa,UAAU;AASlE,MAAM,yBAAyB,EAAE,aAAa;AAAA,EAC5C,KAAK,EAAE,OAAO,EAAE,IAAI;AAAA,EACpB,MAAM,cAAc,SAAS,EAAE,SAAS;AAAA,EACxC,SAAS,EAAE,OAAO,EAAE,OAAO,GAAG,EAAE,OAAO,CAAC,EAAE,SAAS;AACrD,CAAC;AAGM,MAAM,yBAAyB,CACpC,eAC6D;AAC7D,QAAM,EAAE,SAAS,aAAa,OAAO,SAAS,IAAI;AAClD,MAAI,QAAQ,KAAK,EAAE,WAAW,EAAG,OAAM,IAAI,MAAM,6CAA6C;AAC9F,SAAO,cAAc;AAAA,IACnB,aAAa,WAAW,eAAe,qBAAqB,OAAO;AAAA,IACnE,SAAS,4BAA4B,OAAO;AAAA,IAC5C,kBAAkB;AAAA,MAChB,EAAE,MAAM,SAAS,QAAQ,iBAAiB,MAAM,EAAE,aAAa,sBAAsB,CAAC,EAAE;AAAA,IAC1F;AAAA,IACA,QAAQ;AAAA,MACN,mBAAmB,OAAO,QAAQ,QAAQ;AACxC,cAAM,QAAQ,MAAM,qBAAqB,EAAE,UAAU,IAAI,UAAU,MAAM,QAAQ,CAAC;AAClF,cAAM,SAAS,uBAAuB,UAAU,KAAK;AACrD,YAAI,CAAC,OAAO;AACV,gBAAM,IAAI,MAAM,qBAAqB,OAAO,4BAA4B;AAC1E,cAAM,EAAE,MAAM,GAAG,UAAU,IAAI,OAAO;AACtC,eAAO,0BAA0B;AAAA,UAC/B,GAAG;AAAA,UACH;AAAA,UACA;AAAA,UACA;AAAA,UACA,GAAI,QAAQ,OAAO,CAAC,IAAI,EAAE,KAAK;AAAA,QACjC,CAAC;AAAA,MACH;AAAA,IACF;AAAA,EACF,CAAC;AACH;",
+  "sourcesContent": ["import type { ApprovalPolicyIface } from \"./approval.mjs\";\nimport { AuthoredKind, stamp } from \"./brand.mjs\";\nimport { jsonObjectSchema, mcpAuthSchema, requireHostedBinding } from '@finalai/agent-provider';\nimport * as z from 'zod';\nimport { defineDynamic, type DynamicSentinelIface } from \"./dynamic.mjs\";\n\n// An MCP connection. Secrets are references by\n// name: the MCP host injects them, so they never reach the harness. Final's\n// own MCP server is an ordinary connection with `auth: { kind: 'final-session' }`.\n\nexport type McpConnectionAuthIface =\n  // Sent as `Authorization: Bearer <secret>` when headerName is null.\n  | { readonly secretKey: string; readonly headerName: string | null }\n  | { readonly kind: 'final-session' };\n\n// Selects tools by the MCP annotations their server reports, reading omitted\n// hints as the spec's defaults: `{ readOnlyHint: true }` matches only tools\n// the server marks read-only. Use with servers you trust to classify tools.\nexport interface McpToolAnnotationSelectorIface {\n  readonly readOnlyHint?: boolean;\n  readonly destructiveHint?: boolean;\n  readonly idempotentHint?: boolean;\n  readonly openWorldHint?: boolean;\n}\n\nexport type McpToolSelector = string | McpToolAnnotationSelectorIface;\n\n// Entries and keys are tool names or `*` patterns (`github.*`), and allow and\n// deny entries may also be annotation selectors; the most specific matching\n// key governs a tool.\nexport interface McpConnectionToolsIface {\n  // Only these tools are exposed; omit to expose every tool the server lists.\n  // Annotation-selected tools run under the connection's default approval.\n  readonly allow?: readonly McpToolSelector[];\n  // These tools are hidden, whatever `allow` says.\n  readonly deny?: readonly McpToolSelector[];\n  // Per-tool approval; tools not listed use the connection's `approval`.\n  readonly approval?: Readonly<Record<string, ApprovalPolicyIface<never>>>;\n  // Exposed tools (names or `*` patterns) the harness lists up front; the rest\n  // stay reachable through the host's tool search. Omitted, the harness lists\n  // every exposed tool except connector tools and tools past the\n  // host's size limit (HOSTING.md \"Loaded and searchable tools\").\n  readonly load?: readonly string[];\n}\n\nexport interface McpClientConnectionDefinitionIface {\n  readonly url: string;\n  readonly description?: string;\n  readonly auth?: McpConnectionAuthIface;\n  readonly headers?: Readonly<Record<string, string>>;\n  readonly tools?: McpConnectionToolsIface;\n  // Default approval for every tool of this connection.\n  readonly approval?: ApprovalPolicyIface<never>;\n  readonly protocolVersionDiscovery?: boolean;\n  readonly instanceKey?: string;\n}\n\nexport const defineMcpClientConnection = <TConnection extends McpClientConnectionDefinitionIface>(\n  definition: TConnection,\n): TConnection => stamp({ ...definition }, AuthoredKind.Connection);\n\nexport interface HostedConnectionDefinitionIface extends Omit<\n  McpClientConnectionDefinitionIface,\n  'url' | 'auth' | 'headers' | 'protocolVersionDiscovery' | 'instanceKey'\n> {\n  readonly binding: string;\n}\n\nconst hostedConnectionSchema = z.strictObject({\n  url: z.string().url(),\n  auth: mcpAuthSchema.nullable().optional(),\n  headers: z.record(z.string(), z.string()).optional(),\n});\n\n// Built-in and third-party bindings use the ordinary dynamic connection path.\nexport const defineHostedConnection = (\n  definition: HostedConnectionDefinitionIface,\n): DynamicSentinelIface<McpClientConnectionDefinitionIface> => {\n  const { binding, description, tools, approval } = definition;\n  if (binding.trim().length === 0) throw new Error('Hosted connection binding must not be empty');\n  return defineDynamic({\n    description: definition.description ?? `Hosted connection ${binding}`,\n    preview: `Resolved by hosting from ${binding}`,\n    requiredBindings: [\n      { name: binding, schema: jsonObjectSchema.parse(z.toJSONSchema(hostedConnectionSchema)) },\n    ],\n    events: {\n      'session.started': async (_event, ctx) => {\n        const value = await requireHostedBinding({ bindings: ctx.bindings, name: binding });\n        const parsed = hostedConnectionSchema.safeParse(value);\n        if (!parsed.success)\n          throw new Error(`Hosted connection ${binding} has invalid configuration`);\n        const { auth, ...transport } = parsed.data;\n        return defineMcpClientConnection({\n          ...transport,\n          description,\n          tools,\n          approval,\n          ...(auth == null ? {} : { auth }),\n        });\n      },\n    },\n  });\n};\n"],
+  "mappings": "AACA,SAAS,cAAc,aAAa;AACpC,SAAS,kBAAkB,eAAe,4BAA4B;AACtE,YAAY,OAAO;AACnB,SAAS,qBAAgD;AAqDlD,MAAM,4BAA4B,CACvC,eACgB,MAAM,EAAE,GAAG,WAAW,GAAG,aAAa,UAAU;AASlE,MAAM,yBAAyB,EAAE,aAAa;AAAA,EAC5C,KAAK,EAAE,OAAO,EAAE,IAAI;AAAA,EACpB,MAAM,cAAc,SAAS,EAAE,SAAS;AAAA,EACxC,SAAS,EAAE,OAAO,EAAE,OAAO,GAAG,EAAE,OAAO,CAAC,EAAE,SAAS;AACrD,CAAC;AAGM,MAAM,yBAAyB,CACpC,eAC6D;AAC7D,QAAM,EAAE,SAAS,aAAa,OAAO,SAAS,IAAI;AAClD,MAAI,QAAQ,KAAK,EAAE,WAAW,EAAG,OAAM,IAAI,MAAM,6CAA6C;AAC9F,SAAO,cAAc;AAAA,IACnB,aAAa,WAAW,eAAe,qBAAqB,OAAO;AAAA,IACnE,SAAS,4BAA4B,OAAO;AAAA,IAC5C,kBAAkB;AAAA,MAChB,EAAE,MAAM,SAAS,QAAQ,iBAAiB,MAAM,EAAE,aAAa,sBAAsB,CAAC,EAAE;AAAA,IAC1F;AAAA,IACA,QAAQ;AAAA,MACN,mBAAmB,OAAO,QAAQ,QAAQ;AACxC,cAAM,QAAQ,MAAM,qBAAqB,EAAE,UAAU,IAAI,UAAU,MAAM,QAAQ,CAAC;AAClF,cAAM,SAAS,uBAAuB,UAAU,KAAK;AACrD,YAAI,CAAC,OAAO;AACV,gBAAM,IAAI,MAAM,qBAAqB,OAAO,4BAA4B;AAC1E,cAAM,EAAE,MAAM,GAAG,UAAU,IAAI,OAAO;AACtC,eAAO,0BAA0B;AAAA,UAC/B,GAAG;AAAA,UACH;AAAA,UACA;AAAA,UACA;AAAA,UACA,GAAI,QAAQ,OAAO,CAAC,IAAI,EAAE,KAAK;AAAA,QACjC,CAAC;AAAA,MACH;AAAA,IACF;AAAA,EACF,CAAC;AACH;",
   "names": []
 }

package/fixtures/release-scout/agent/sandbox.ts

@@ -7,7 +7,7 @@ export const computer = computerSetupGuide({
   ref: 'release-scout-dev',
   version: 'latest',
   repositories: [{ alias: 'app', repository: 'final/app', ref: 'main' }],
-  variables: ['GITHUB_TOKEN', 'NPM_TOKEN'],
+  variables: ['NPM_TOKEN'],
   workspace: 'session',
   networkPolicy: 'allow-all',
 });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@finalai/agent-definition",
-  "version": "0.1.4",
+  "version": "0.1.5",
   "private": false,
   "description": "Provider-independent agent authoring, manifest schemas, directory compiler, and harness compatibility reports.",
   "license": "Apache-2.0",
@@ -76,7 +76,7 @@
   },
   "dependencies": {
     "@finalai/agent-protocol": "0.1.4",
-    "@finalai/agent-provider": "0.1.4",
+    "@finalai/agent-provider": "0.1.6",
     "ajv": "^8.20.0",
     "ajv-formats": "^3.0.1",
     "croner": "^10.0.1",