@finalai/agent-definition 0.1.2 → 0.1.4

package/HOSTING.md

@@ -0,0 +1,234 @@
+# Portable agent definitions and hosted bindings
+
+An agent declares behavior and logical resources. Hosting supplies endpoints,
+resource identifiers, and credential references. The same compiled source can
+resolve against dev and production configuration without source edits.
+
+## Selecting a deployment
+
+```sh
+export FINAL_API_HOST=https://agent-session.primary-dev.final.ai/api
+export FINAL_API_KEY=<dev-organization-key>
+pnpm exec final-agents build ./agent
+pnpm exec final-agents publish ./agent --agent my-agent
+```
+
+Choose production by changing the host and organization key. `--host` overrides
+`FINAL_API_HOST`; without either, the existing production default remains. Build
+compiles locally and optionally checks installed-harness compatibility. Publish
+compiles again and sends source/release requests to the selected deployment.
+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 connections
+
+```ts
+import { defineHostedConnection } from '@finalai/agents';
+
+export default defineHostedConnection({
+  binding: 'issue-tracker',
+  tools: { allow: ['read_issue'], deny: ['delete_issue'] },
+});
+```
+
+`issue-tracker` is an example configuration name, not a built-in service.
+Hosting configures it with non-secret JSON:
+
+```json
+{
+  "url": "https://issues.dev.example/mcp",
+  "auth": { "secretKey": "ISSUE_TRACKER_TOKEN", "headerName": null },
+  "headers": { "X-Workspace": "development" }
+}
+```
+
+Production supplies another value under the same name. The helper uses an ordinary
+`defineDynamic` connection at `session.started`, then the usual HTTP MCP lowering,
+validation, permissions, and credential broker. Hosting supplies transport settings,
+not tool policies. URL, authentication references, transport headers belong to hosting; the hosted helper does
+not accept authored overrides for these fields. Referenced secrets still need the agent's secret allowlist and normal
+authorization. Actual tokens must not be returned in configuration headers.
+
+Final uses the same generic helper:
+
+```ts
+import { defineFinalConnection } from '@finalai/agents';
+
+export default defineFinalConnection({
+  tools: { deny: ['create_agent_session'] },
+});
+```
+
+This resolves the `final` binding. Hosting supplies its URL and
+`auth: { kind: 'final-session' }`, just as it supplies authentication for any
+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
+implements `get(name)` to return scoped JSON or null. `requireHostedBinding` rejects
+missing hosting, absent names, and invalid JSON without an environment fallback.
+Names are configuration keys, not global permissions or inferred URLs.
+
+Tools, hooks, dynamic resolvers, sandbox selectors, and harness/sandbox/channel
+provider contexts expose an optional `bindings` reader. A third-party resolver can
+use the same reader for model or resource configuration:
+
+```ts
+import { defineDynamic, requireHostedBinding } from '@finalai/agents';
+
+export const model = defineDynamic({
+  requiredBindings: [{ name: 'primary-model', schema: { type: 'string', minLength: 1 } }],
+  description: 'The deployment model',
+  preview: 'Resolved from primary-model',
+  events: {
+    'session.started': async (_event, ctx) =>
+      requireHostedBinding({ bindings: ctx.bindings, name: 'primary-model' }),
+  },
+});
+```
+
+Use that value in a harness configuration supporting dynamic models. A resource
+binding can similarly contain a repository, guide slug, device ID, or non-secret
+SDK base URL; the consumer validates the resource-specific schema. Literal IDs,
+custom URLs, and external credential choices are never silently rewritten.
+
+Installed providers already accept factory configuration injected by hosting.
+Keep supplying deployment service URLs there. Computer/WebSocket clients retain
+explicit configuration; a hosted provider can obtain it through this shared reader.
+Package versions stay pinned. Packages do not read a global DEV/PROD flag.
+
+## Declared requirements and user experience
+
+`defineHostedConnection` declares its binding name and JSON configuration schema
+in the compiled dynamic slot automatically. Other dynamic consumers declare
+`requiredBindings` as in the model example. Hosts can inspect these requirements
+without running authored resolvers. Repeated names must satisfy every declared
+schema; names are looked up once per preflight.
+
+Before accepting a release, hosting calls
+`validateHostedBindings({ manifest, bindings })` with a reader scoped to the
+selected deployment, organization, and agent. Hosts compiling source can instead
+pass `hostedBindings` to `compile`; failed preflight returns error diagnostics and
+no manifest or bundle. An offline build can still compile and expose requirements
+without accessing deployment configuration. The CLI does not yet fetch binding
+configuration itself: server-side publication must enable this preflight.
+
+When dev is selected, lookups use only dev configuration. A missing dev binding
+fails even if production has the same name; never retry against production or
+substitute a production default. Changing the CLI host selects where to publish;
+the runtime reader comes from that deployment, not from the author's environment.
+Explicit authored URLs retain their literal destination.
+
+Authors keep one source definition. Operators configure its named connections
+and resources once in each deployment. End users start the agent as usual; an
+unconfigured required resource produces a configuration failure instead of a
+session silently missing tools. Dynamic handlers validate declared requirements
+before running. Shared manifest resolution rejects null results for required slots,
+even if a host catches a resolver exception and returns null. Hosts must propagate
+that failure to startup. Session-started values stay pinned across turns and resume.
+
+This PR adds no configuration UI. A host can use the compiled requirements to show
+which names need configuration and return an actionable deployment-specific error.
+
+## Host integration
+
+These packages implement contracts and authored runtime behavior, not a deployment
+configuration store or RPC service. Existing hosting needs to:
+
+1. Resolve names within the authorized deployment, organization, and agent; never
+   expose the process environment or an unrestricted cross-tenant registry.
+2. Inject `bindings` into lifecycle resolution and the tool/hook/selector/provider
+   contexts using it. Dynamic approval evaluation and tool reconstruction after
+   isolate eviction need the same reader. Readers and tokens are not persisted in
+   boundary snapshots.
+3. Configure `final` with that deployment's approved MCP endpoint. The ordinary
+   broker continues restricting `final-session` grants to that endpoint.
+4. Return non-secret configuration and credential references, with normal provider,
+   secret, resource, and organization authorization.
+5. Run the release preflight above and validate again before starting a new
+   session. Treat failed required-binding resolution as a startup/configuration error, not
+   an omitted connection or a fallback to production. Preserve existing runtime
+   revisions when publication fails.
+6. Retain session-started resolved values across turns/resume; resolve new sessions
+   against their own deployment.
+
+Optional readers preserve source compatibility with existing hosts. Definitions
+requesting bindings fail clearly if hosting does not provide them. Installing these
+packages alone does not change Final's deployed service wiring or provision secrets.
+
+New compiles emit manifest version 3, so older hosts reject them rather than
+stripping required-binding metadata. Updated readers still accept persisted
+version 2 revisions. Upgrade hosting before publishing newly compiled agents.

package/README.md

@@ -14,3 +14,10 @@ resolves those convenience entrypoints for the generic compiler.
 
 Custom provider contracts and sandbox implementation helpers are available directly
 from `@finalai/agent-provider` and `@finalai/agent-provider/sandbox`.
+
+`defineHostedConnection` resolves a named transport through the existing dynamic
+connection lifecycle. `DynamicResolveContextIface.bindings` is the optional shared
+host reader; use `requireHostedBinding` for configuration and logical resource
+references. Missing required bindings reject resolution. No environment URLs are
+chosen by the compiler. Dynamic approval/tool reconstruction must receive the same
+reader from hosting. See the repository's [hosting guide](HOSTING.md).

package/dist/compiler-assets/{chunk-TATN3PYK.ts → chunk-2ZRYQO4Q.ts}

@@ -1,14 +1,14 @@
 import {
   resultMatchesSchema
-} from "./chunk-GNR7XBPN.ts";
+} from "./chunk-W6DOJA4W.ts";
 import {
   stamp
-} from "./chunk-XHKPWT3G.ts";
+} from "./chunk-QJ26GEUM.ts";
 import {
   callableSchema,
   isObjectLike,
   optionalValueSchema
-} from "./chunk-JIPNTA56.ts";
+} from "./chunk-TM36NO3C.ts";
 import {
   array,
   boolean,
@@ -16,7 +16,7 @@ import {
   object,
   string,
   union
-} from "./chunk-HGW4YHAY.ts";
+} from "./chunk-3K4C4SVG.ts";
 
 // src/authoring/tools.ts
 var toolLabelSchema = union([

package/dist/compiler-assets/{chunk-HGW4YHAY.ts → chunk-3K4C4SVG.ts}

@@ -6449,6 +6449,14 @@ function object(shape, params) {
   };
   return new ZodObject(def);
 }
+function strictObject(shape, params) {
+  return new ZodObject({
+    type: "object",
+    shape,
+    catchall: never(),
+    ...util_exports.normalizeParams(params)
+  });
+}
 function looseObject(shape, params) {
   return new ZodObject({
     type: "object",
@@ -6851,6 +6859,7 @@ export {
   unknown,
   array,
   object,
+  strictObject,
   looseObject,
   union,
   discriminatedUnion,

package/dist/compiler-assets/{chunk-7VSSVZM4.ts → chunk-4A66SVBJ.ts}

@@ -1,18 +1,18 @@
 import {
   ToolApproval
-} from "./chunk-OWC6SFFF.ts";
+} from "./chunk-APU2VKLW.ts";
 import {
   authoredKindOf,
   stamp
-} from "./chunk-XHKPWT3G.ts";
+} from "./chunk-QJ26GEUM.ts";
 import {
   callableSchema
-} from "./chunk-JIPNTA56.ts";
+} from "./chunk-TM36NO3C.ts";
 import {
   nativeEnum,
   object,
   string
-} from "./chunk-HGW4YHAY.ts";
+} from "./chunk-3K4C4SVG.ts";
 
 // src/authoring/approval.ts
 var policy = (value, note = null) => stamp({ policy: value, note }, "approval" /* Approval */);

package/dist/compiler-assets/{chunk-CWWRTRWW.ts → chunk-4E5HECVD.ts}

@@ -7,7 +7,7 @@ import {
   object,
   string,
   unknown
-} from "./chunk-HGW4YHAY.ts";
+} from "./chunk-3K4C4SVG.ts";
 
 // ../agent-provider/src/sandbox/open-scope.ts
 var openRequestFieldsSchema = looseObject({

package/dist/compiler-assets/{chunk-7QP2CKPI.ts → chunk-4X2DS5BR.ts}

@@ -7,7 +7,7 @@ import {
   record,
   string,
   union
-} from "./chunk-HGW4YHAY.ts";
+} from "./chunk-3K4C4SVG.ts";
 
 // ../agent-provider/src/json.ts
 var jsonValueSchema = lazy(

package/dist/compiler-assets/{chunk-ZDLVA6XF.ts → chunk-5NTKRRMC.ts}

@@ -1,17 +1,20 @@
 import {
   toolLabelSchema
-} from "./chunk-TATN3PYK.ts";
-import {
-  jsonSchemaDeclarationError
-} from "./chunk-GNR7XBPN.ts";
+} from "./chunk-2ZRYQO4Q.ts";
 import {
   lowerApproval
-} from "./chunk-7VSSVZM4.ts";
+} from "./chunk-4A66SVBJ.ts";
+import {
+  toolAnnotationSelectorSchema
+} from "./chunk-APU2VKLW.ts";
+import {
+  jsonSchemaDeclarationError
+} from "./chunk-W6DOJA4W.ts";
 import {
   authoredKindOf,
   pendingExportName,
   pendingIndexOf
-} from "./chunk-XHKPWT3G.ts";
+} from "./chunk-QJ26GEUM.ts";
 import {
   authoredRecordSchema,
   authoredValueSchema,
@@ -26,7 +29,7 @@ import {
   isString,
   messageOf,
   optionalValueSchema
-} from "./chunk-JIPNTA56.ts";
+} from "./chunk-TM36NO3C.ts";
 import {
   ZodType,
   array,
@@ -38,8 +41,38 @@ import {
   string,
   toJSONSchema,
   union,
+  unknown,
   url
-} from "./chunk-HGW4YHAY.ts";
+} from "./chunk-3K4C4SVG.ts";
+
+// ../agent-provider/src/tool-patterns.ts
+var TOOL_PATTERN_WILDCARD = "*";
+var toolPatternMatches = (pattern, name) => {
+  let patternIndex = 0;
+  let nameIndex = 0;
+  let starIndex = -1;
+  let resumeIndex = 0;
+  while (nameIndex < name.length) {
+    const char = pattern[patternIndex];
+    if (char === TOOL_PATTERN_WILDCARD) {
+      starIndex = patternIndex;
+      resumeIndex = nameIndex;
+      patternIndex += 1;
+    } else if (char != null && char === name[nameIndex]) {
+      patternIndex += 1;
+      nameIndex += 1;
+    } else if (starIndex !== -1) {
+      patternIndex = starIndex + 1;
+      resumeIndex += 1;
+      nameIndex = resumeIndex;
+    } else {
+      return false;
+    }
+  }
+  while (pattern[patternIndex] === TOOL_PATTERN_WILDCARD) patternIndex += 1;
+  return patternIndex === pattern.length;
+};
+var isToolDenied = (deny, name) => deny?.some((pattern) => toolPatternMatches(pattern, name)) === true;
 
 // src/runtime/lower.ts
 var IssueSeverity = /* @__PURE__ */ ((IssueSeverity2) => {
@@ -236,9 +269,10 @@ var authoredConnectionSchema = looseObject({
   approval: optionalValueSchema,
   toolCall: optionalValueSchema,
   tools: looseObject({
-    allow: array(string()).optional(),
-    deny: array(string()).optional(),
-    approval: authoredRecordSchema.optional()
+    allow: array(unknown()).optional(),
+    deny: array(unknown()).optional(),
+    approval: authoredRecordSchema.optional(),
+    load: array(string()).optional()
   }).optional()
 });
 var connectionAuthSchema = union([
@@ -263,6 +297,25 @@ var lowerAuth = (value, path, issues) => {
   );
   return null;
 };
+var splitToolEntries = (args) => {
+  const names = [];
+  const selectors = [];
+  for (const entry of args.entries) {
+    if (isString(entry)) {
+      names.push(entry);
+      continue;
+    }
+    const parsed = toolAnnotationSelectorSchema.safeParse(entry);
+    if (parsed.success) selectors.push(parsed.data);
+    else
+      args.issues.push(
+        error(
+          `${args.label} entries must be tool names, * patterns, or annotation selectors such as { readOnlyHint: true }`
+        )
+      );
+  }
+  return { names, selectors };
+};
 var lowerConnection = (args) => {
   const issues = [];
   const path = `connection ${args.key}`;
@@ -301,12 +354,29 @@ var lowerConnection = (args) => {
   const overrides = Object.fromEntries(overrideEntries);
   const inputApprovals = Object.fromEntries(inputApprovalEntries);
   for (const key of staticOverrideKeys) delete inputApprovals[key];
-  const defaultPolicy = overrides["*"] ?? defaultApproval.policy;
-  const allow = tools?.allow ?? null;
+  const defaultPolicy = overrides[TOOL_PATTERN_WILDCARD] ?? defaultApproval.policy;
+  const allowEntries = tools?.allow == null ? null : splitToolEntries({ entries: tools.allow, label: `${path} tools.allow`, issues });
+  const allow = allowEntries?.names ?? null;
+  const allowSelectors = allowEntries?.selectors ?? [];
+  const denyEntries = splitToolEntries({
+    entries: tools?.deny ?? [],
+    label: `${path} tools.deny`,
+    issues
+  });
+  const deny = denyEntries.names;
+  const authoredEntries = {
+    allow: allow ?? [],
+    deny,
+    approval: Object.keys(overrides)
+  };
+  for (const [field, entries] of Object.entries(authoredEntries)) {
+    if (entries.some((entry) => entry.trim().length === 0))
+      issues.push(error(`${path} tools.${field} entries must be tool names or * patterns`));
+  }
+  const inherited = Object.hasOwn(inputApprovals, "*") ? inputApprovals["*"] : void 0;
   let approvals = null;
   if (allow != null) {
     approvals = Object.fromEntries(allow.map((tool) => [tool, overrides[tool] ?? defaultPolicy]));
-    const inherited = Object.hasOwn(inputApprovals, "*") ? inputApprovals["*"] : void 0;
     if (inherited != null) {
       for (const tool of allow) {
         if (!Object.hasOwn(overrides, tool))
@@ -319,20 +389,33 @@ var lowerConnection = (args) => {
       }
     }
     for (const tool of Object.keys(overrides)) {
-      if (!allow.includes(tool)) {
-        issues.push(
-          warning(`${path} sets an approval for ${tool}, which tools.allow does not expose`)
-        );
+      if (tool === TOOL_PATTERN_WILDCARD || allow.includes(tool)) continue;
+      if (allow.some((pattern) => toolPatternMatches(pattern, tool))) {
+        approvals[tool] = overrides[tool] ?? defaultPolicy;
+        continue;
       }
+      issues.push(
+        warning(
+          allowSelectors.length > 0 ? `${path} sets an approval for ${tool}, which tools.allow does not name; approvals apply only to named tools` : `${path} sets an approval for ${tool}, which tools.allow does not expose`
+        )
+      );
     }
   } else if (defaultApproval.policy === "ask" /* Ask */ || Object.keys(overrides).length > 0) {
     approvals = { "*": defaultApproval.policy, ...overrides };
   }
-  const deny = tools?.deny ?? [];
-  for (const tool of deny) {
-    if (Object.hasOwn(overrides, tool))
+  for (const tool of Object.keys(overrides)) {
+    if (tool !== TOOL_PATTERN_WILDCARD && isToolDenied(deny, tool))
       issues.push(warning(`${path} sets an approval for ${tool}, which tools.deny hides`));
   }
+  const load = tools?.load ?? null;
+  if (load?.some((tool) => tool.trim().length === 0) === true)
+    issues.push(error(`${path} tools.load entries must be tool names or * patterns`));
+  for (const tool of load ?? []) {
+    if (isToolDenied(deny, tool))
+      issues.push(warning(`${path} loads ${tool}, which tools.deny hides`));
+    else if (allow != null && allowSelectors.length === 0 && !allow.some((pattern) => toolPatternMatches(pattern, tool)))
+      issues.push(warning(`${path} loads ${tool}, which tools.allow does not expose`));
+  }
   if (connection?.toolCall != null)
     issues.push(error(`${path} uses toolCall.providedArguments, which is not supported`));
   const binding = {
@@ -344,6 +427,14 @@ var lowerConnection = (args) => {
     approvals
   };
   if (deny.length > 0) binding.deny = [...new Set(deny)];
+  if (load != null) binding.load = [...new Set(load)];
+  if (allowSelectors.length > 0)
+    binding.allowAnnotations = allowSelectors.map((match) => ({
+      match,
+      approval: defaultPolicy,
+      ...inherited == null ? {} : { inputApproval: inherited }
+    }));
+  if (denyEntries.selectors.length > 0) binding.denyAnnotations = denyEntries.selectors;
   if (Object.keys(inputApprovals).length > 0) binding.inputApprovals = inputApprovals;
   return { binding, issues };
 };

package/dist/compiler-assets/{chunk-2CZRHOLL.ts → chunk-7XUPKRZU.ts}

@@ -1,6 +1,6 @@
 import {
   stamp
-} from "./chunk-XHKPWT3G.ts";
+} from "./chunk-QJ26GEUM.ts";
 
 // src/authoring/agent.ts
 var defineAgent = (definition) => stamp({ ...definition }, "agent" /* Agent */);