@finalai/agents 0.1.3 → 0.1.4

package/HOSTING.md

@@ -66,6 +66,75 @@ other hosted connection. `binding`
 selects another name. Existing explicit `url` calls remain static and compatible;
 they always point at that URL. There is no Final-specific compiler rewrite.
 
+## Connection tool policy
+
+`tools.allow`, `tools.deny` and `tools.approval` keys are tool names or `*`
+patterns, so a definition can scope a connection whose tool list it does not know:
+
+```ts
+export default defineFinalConnection({
+  tools: {
+    allow: ['github.*', 'list_goals'],
+    deny: ['github.delete_repo'],
+    approval: { 'github.delete_*': always() },
+  },
+});
+```
+
+`*` matches any run of characters; everything else matches literally. `deny` wins
+over `allow`. The most specific key governs a tool: an exact name, else the matching
+pattern with the most literal characters, with ties resolved toward `ask`. Hosts
+enforce this through `isToolExposed` and `toolApprovalOf` from
+`@finalai/agent-provider`, and look up a tool's input-approval predicate under the
+key `resolveToolApprovalKey` returns.
+
+## Loaded and searchable tools
+
+A connection that can expose many tools, such as Final's with every service the
+person has connected, can name the ones the harness should list up front:
+
+```ts
+export default defineFinalConnection({
+  tools: { load: ['list_goals', 'get_goal', 'draft_goal', 'notify_user'] },
+});
+```
+
+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.
+
+## Selecting tools by annotation
+
+`tools.allow` and `tools.deny` entries can be MCP annotation selectors as well as
+tool names, so a definition can scope tools it cannot name in advance:
+
+```ts
+export default defineFinalConnection({
+  tools: {
+    allow: ['list_goals', 'draft_goal', { readOnlyHint: true }],
+    deny: [{ destructiveHint: true, readOnlyHint: false }],
+  },
+});
+```
+
+A selector matches when every hint it sets equals the tool's hint, reading hints the
+tool omits as the MCP spec's defaults (not read-only, destructive, not idempotent,
+open world). The annotations come from the connection's server, so select on them
+only for servers trusted to classify their own tools.
+
+Selectors lower to `allowAnnotations` (each with the connection default approval and
+input predicate) and `denyAnnotations`. A host exposes a tool when nothing in `deny`
+or `denyAnnotations` matches it and either an `approvals` key (name or pattern)
+governs it, `approvals` is null, or `toolAnnotationRuleFor` finds a rule; a tool an
+`approvals` key governs keeps that approval, otherwise it runs under the rule's. `tools.approval` overrides apply only to
+named tools.
+
 ## Resources and provider packages
 
 `HostedBindingsIface` is the shared `@finalai/agent-provider` contract. Hosting

package/dist/modules/public.d.mts

@@ -1,7 +1,7 @@
 export { CredentialOwner, CredentialPayer, DELETE, GET, HookEvent, POST, PUT, SandboxWire, WS, always, baseTools, credentials, defineAgent, defineChannel, disableChannel, defineProviderChannel, defineDynamic, defineHarness, defineHostedConnection, defineHook, defineInstructions, defineMcpClientConnection, defineSandbox, defineSandboxProvider, defineSchedule, defineSkill, defineTool, harnessHost, never, toolResultFrom, whenInput, } from "./authoring/index.mjs";
 export type { AgentDefinitionInputIface, AgentSessionInfoIface, ApprovalPolicyIface, AuthoredChannelDefinitionIface, AuthoredHarnessCloseContextIface, AuthoredHarnessDescriptionIface, AuthoredHarnessEndpointIface, AuthoredHarnessHealthIface, AuthoredHarnessIface, AuthoredHarnessOpenArgsIface, AuthoredHarnessRefContextIface, AuthoredHarnessResumeArgsIface, BaseToolsValueIface, ConversationInfoIface, CredentialNode, CredentialPolicyIface, DefinedAuthoredHarnessIface, DefinedToolIface, DynamicDefinitionIface, DynamicResolveContextIface, DynamicSentinelIface, FinalPlatformClientIface, HarnessHostIface, HookContextIface, HookDefinitionIface, HookEventIface, HostedConnectionDefinitionIface, McpClientConnectionDefinitionIface, SandboxSelectorContextIface, ScheduleInputIface, SkillDefinitionIface, ToolContextIface, ToolDefinitionIface, } from "./authoring/index.mjs";
 export * from "./authoring/providers.mjs";
-export type { AgentManifestIface, ChannelDefinitionIface, ChannelPlatformIface, ChannelSocketIface, HarnessDescriptionIface, HarnessEndpointIface, HarnessIface, HarnessSessionRefIface, HostedBindingsIface, McpChannelIface, NetworkSandboxSessionIface, ResolvedAgentManifestIface, RouteDefinitionIface, SandboxMcpEndpoint, SandboxPrepareContextIface, SandboxProcessIface, SandboxProviderHandleIface, SandboxProviderIface, SandboxProviderImplementationIface, SandboxSessionIface, SandboxStartContextIface, ScreenSessionIface, } from '@finalai/agent-provider';
+export type { AgentAvatarIface, AvatarMedia, AvatarState, AgentManifestIface, ChannelDefinitionIface, ChannelPlatformIface, ChannelSocketIface, HarnessDescriptionIface, HarnessEndpointIface, HarnessIface, HarnessSessionRefIface, HostedBindingsIface, McpChannelIface, NetworkSandboxSessionIface, ResolvedAgentManifestIface, RouteDefinitionIface, SandboxMcpEndpoint, SandboxPrepareContextIface, SandboxProcessIface, SandboxProviderHandleIface, SandboxProviderIface, SandboxProviderImplementationIface, SandboxSessionIface, SandboxStartContextIface, ScreenSessionIface, } from '@finalai/agent-provider';
 export { requireHostedBinding } from '@finalai/agent-provider';
 export { validateHostedBindings } from '@finalai/agent-definition';
 export type { HostedBindingRequirementIface } from '@finalai/agent-provider';

package/dist/modules/public.mjs.map

@@ -1,7 +1,7 @@
 {
   "version": 3,
   "sources": ["../../../../src/public.ts"],
-  "sourcesContent": ["// Agent authoring.\nexport {\n  CredentialOwner,\n  CredentialPayer,\n  DELETE,\n  GET,\n  HookEvent,\n  POST,\n  PUT,\n  SandboxWire,\n  WS,\n  always,\n  baseTools,\n  credentials,\n  defineAgent,\n  defineChannel,\n  disableChannel,\n  defineProviderChannel,\n  defineDynamic,\n  defineHarness,\n  defineHostedConnection,\n  defineHook,\n  defineInstructions,\n  defineMcpClientConnection,\n  defineSandbox,\n  defineSandboxProvider,\n  defineSchedule,\n  defineSkill,\n  defineTool,\n  harnessHost,\n  never,\n  toolResultFrom,\n  whenInput,\n} from \"./authoring/index.mjs\";\nexport type {\n  AgentDefinitionInputIface,\n  AgentSessionInfoIface,\n  ApprovalPolicyIface,\n  AuthoredChannelDefinitionIface,\n  AuthoredHarnessCloseContextIface,\n  AuthoredHarnessDescriptionIface,\n  AuthoredHarnessEndpointIface,\n  AuthoredHarnessHealthIface,\n  AuthoredHarnessIface,\n  AuthoredHarnessOpenArgsIface,\n  AuthoredHarnessRefContextIface,\n  AuthoredHarnessResumeArgsIface,\n  BaseToolsValueIface,\n  ConversationInfoIface,\n  CredentialNode,\n  CredentialPolicyIface,\n  DefinedAuthoredHarnessIface,\n  DefinedToolIface,\n  DynamicDefinitionIface,\n  DynamicResolveContextIface,\n  DynamicSentinelIface,\n  FinalPlatformClientIface,\n  HarnessHostIface,\n  HookContextIface,\n  HookDefinitionIface,\n  HookEventIface,\n  HostedConnectionDefinitionIface,\n  McpClientConnectionDefinitionIface,\n  SandboxSelectorContextIface,\n  ScheduleInputIface,\n  SkillDefinitionIface,\n  ToolContextIface,\n  ToolDefinitionIface,\n} from \"./authoring/index.mjs\";\nexport * from \"./authoring/providers.mjs\";\n\nexport type {\n  AgentManifestIface,\n  ChannelDefinitionIface,\n  ChannelPlatformIface,\n  ChannelSocketIface,\n  HarnessDescriptionIface,\n  HarnessEndpointIface,\n  HarnessIface,\n  HarnessSessionRefIface,\n  HostedBindingsIface,\n  McpChannelIface,\n  NetworkSandboxSessionIface,\n  ResolvedAgentManifestIface,\n  RouteDefinitionIface,\n  SandboxMcpEndpoint,\n  SandboxPrepareContextIface,\n  SandboxProcessIface,\n  SandboxProviderHandleIface,\n  SandboxProviderIface,\n  SandboxProviderImplementationIface,\n  SandboxSessionIface,\n  SandboxStartContextIface,\n  ScreenSessionIface,\n} from '@finalai/agent-provider';\n\nexport { requireHostedBinding } from '@finalai/agent-provider';\nexport { validateHostedBindings } from '@finalai/agent-definition';\nexport type { HostedBindingRequirementIface } from '@finalai/agent-provider';\n\nexport { defineFinalConnection } from '@finalai/final-agent-provider/connections';\nexport type {\n  FinalConnectionDefinitionIface,\n  FinalHostedConnectionDefinitionIface,\n} from '@finalai/final-agent-provider/connections';\n"],
-  "mappings": "AACA;AAAA,EACE;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,OACK;AAoCP,cAAc;AA2Bd,SAAS,4BAA4B;AACrC,SAAS,8BAA8B;AAGvC,SAAS,6BAA6B;",
+  "sourcesContent": ["// Agent authoring.\nexport {\n  CredentialOwner,\n  CredentialPayer,\n  DELETE,\n  GET,\n  HookEvent,\n  POST,\n  PUT,\n  SandboxWire,\n  WS,\n  always,\n  baseTools,\n  credentials,\n  defineAgent,\n  defineChannel,\n  disableChannel,\n  defineProviderChannel,\n  defineDynamic,\n  defineHarness,\n  defineHostedConnection,\n  defineHook,\n  defineInstructions,\n  defineMcpClientConnection,\n  defineSandbox,\n  defineSandboxProvider,\n  defineSchedule,\n  defineSkill,\n  defineTool,\n  harnessHost,\n  never,\n  toolResultFrom,\n  whenInput,\n} from \"./authoring/index.mjs\";\nexport type {\n  AgentDefinitionInputIface,\n  AgentSessionInfoIface,\n  ApprovalPolicyIface,\n  AuthoredChannelDefinitionIface,\n  AuthoredHarnessCloseContextIface,\n  AuthoredHarnessDescriptionIface,\n  AuthoredHarnessEndpointIface,\n  AuthoredHarnessHealthIface,\n  AuthoredHarnessIface,\n  AuthoredHarnessOpenArgsIface,\n  AuthoredHarnessRefContextIface,\n  AuthoredHarnessResumeArgsIface,\n  BaseToolsValueIface,\n  ConversationInfoIface,\n  CredentialNode,\n  CredentialPolicyIface,\n  DefinedAuthoredHarnessIface,\n  DefinedToolIface,\n  DynamicDefinitionIface,\n  DynamicResolveContextIface,\n  DynamicSentinelIface,\n  FinalPlatformClientIface,\n  HarnessHostIface,\n  HookContextIface,\n  HookDefinitionIface,\n  HookEventIface,\n  HostedConnectionDefinitionIface,\n  McpClientConnectionDefinitionIface,\n  SandboxSelectorContextIface,\n  ScheduleInputIface,\n  SkillDefinitionIface,\n  ToolContextIface,\n  ToolDefinitionIface,\n} from \"./authoring/index.mjs\";\nexport * from \"./authoring/providers.mjs\";\n\nexport type {\n  AgentAvatarIface,\n  AvatarMedia,\n  AvatarState,\n  AgentManifestIface,\n  ChannelDefinitionIface,\n  ChannelPlatformIface,\n  ChannelSocketIface,\n  HarnessDescriptionIface,\n  HarnessEndpointIface,\n  HarnessIface,\n  HarnessSessionRefIface,\n  HostedBindingsIface,\n  McpChannelIface,\n  NetworkSandboxSessionIface,\n  ResolvedAgentManifestIface,\n  RouteDefinitionIface,\n  SandboxMcpEndpoint,\n  SandboxPrepareContextIface,\n  SandboxProcessIface,\n  SandboxProviderHandleIface,\n  SandboxProviderIface,\n  SandboxProviderImplementationIface,\n  SandboxSessionIface,\n  SandboxStartContextIface,\n  ScreenSessionIface,\n} from '@finalai/agent-provider';\n\nexport { requireHostedBinding } from '@finalai/agent-provider';\nexport { validateHostedBindings } from '@finalai/agent-definition';\nexport type { HostedBindingRequirementIface } from '@finalai/agent-provider';\n\nexport { defineFinalConnection } from '@finalai/final-agent-provider/connections';\nexport type {\n  FinalConnectionDefinitionIface,\n  FinalHostedConnectionDefinitionIface,\n} from '@finalai/final-agent-provider/connections';\n"],
+  "mappings": "AACA;AAAA,EACE;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,OACK;AAoCP,cAAc;AA8Bd,SAAS,4BAA4B;AACrC,SAAS,8BAA8B;AAGvC,SAAS,6BAA6B;",
   "names": []
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@finalai/agents",
-  "version": "0.1.3",
+  "version": "0.1.4",
   "private": false,
   "description": "Agent authoring, client APIs, and CLI.",
   "license": "Apache-2.0",
@@ -110,11 +110,11 @@
   },
   "dependencies": {
     "@agentclientprotocol/sdk": "1.8.0",
-    "@finalai/agent-definition": "0.1.3",
-    "@finalai/agent-protocol": "0.1.3",
-    "@finalai/agent-provider": "0.1.3",
-    "@finalai/final-agent-provider": "0.1.3",
-    "@finalai/websockets": "0.1.3",
+    "@finalai/agent-definition": "0.1.4",
+    "@finalai/agent-protocol": "0.1.4",
+    "@finalai/agent-provider": "0.1.4",
+    "@finalai/final-agent-provider": "0.1.4",
+    "@finalai/websockets": "0.1.4",
     "ws": "^8.21.3",
     "zod": "4.6.5"
   },