@finalai/final-agent-provider 0.1.2 → 0.1.3

package/HOSTING.md

@@ -0,0 +1,165 @@
+# 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.
+
+## 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

@@ -10,3 +10,9 @@ the public Computers and Device APIs; the Computers transport is shared with
 
 Authoring helpers produce manifest bindings. Select the matching `/runtime/*`
 adapter when connecting your own CLI or ACP endpoint.
+
+`defineFinalConnection()` requests the host's `final` binding at session start,
+using the generic `defineHostedConnection` implementation. Its session grant still
+goes through the usual credential broker. Existing calls with an explicit `url`
+remain static. Hosts without a binding reader cannot run URL-free definitions;
+see the repository's [hosting guide](HOSTING.md) for wiring requirements.

package/dist/modules/connections.d.mts

@@ -1,7 +1,11 @@
-import { type McpClientConnectionDefinitionIface } from '@finalai/agent-definition/authoring';
+import { type DynamicSentinelIface, type HostedConnectionDefinitionIface, type McpClientConnectionDefinitionIface } from '@finalai/agent-definition/authoring';
 export type FinalConnectionDefinitionIface = Omit<McpClientConnectionDefinitionIface, 'auth'>;
-export declare const defineFinalConnection: <TConnection extends FinalConnectionDefinitionIface>(definition: TConnection) => TConnection & {
+export interface FinalHostedConnectionDefinitionIface extends Omit<HostedConnectionDefinitionIface, 'binding'> {
+    readonly binding?: string;
+}
+export declare function defineFinalConnection<TConnection extends FinalConnectionDefinitionIface>(definition: TConnection): TConnection & {
     readonly auth: {
-        readonly kind: "final-session";
+        readonly kind: 'final-session';
     };
 };
+export declare function defineFinalConnection(definition?: FinalHostedConnectionDefinitionIface): DynamicSentinelIface<McpClientConnectionDefinitionIface>;

package/dist/modules/connections.mjs

@@ -1,7 +1,15 @@
 import {
-  defineMcpClientConnection
+  defineMcpClientConnection,
+  defineHostedConnection
 } from "@finalai/agent-definition/authoring";
-const defineFinalConnection = (definition) => defineMcpClientConnection({ ...definition, auth: { kind: "final-session" } });
+function defineFinalConnection(definition = {}) {
+  if ("url" in definition)
+    return defineMcpClientConnection({ ...definition, auth: { kind: "final-session" } });
+  return defineHostedConnection({
+    ...definition,
+    binding: definition.binding ?? "final"
+  });
+}
 export {
   defineFinalConnection
 };

package/dist/modules/connections.mjs.map

@@ -1,7 +1,7 @@
 {
   "version": 3,
   "sources": ["../../../../src/connections.ts"],
-  "sourcesContent": ["import {\n  defineMcpClientConnection,\n  type McpClientConnectionDefinitionIface,\n} from '@finalai/agent-definition/authoring';\n\nexport type FinalConnectionDefinitionIface = Omit<McpClientConnectionDefinitionIface, 'auth'>;\n\n// `connections/final.ts`: Final's MCP server as an ordinary connection. The\n// session service's broker resolves `final-session` auth to a grant scoped to\n// the calling session, which Final's MCP server runs the tools as.\nexport const defineFinalConnection = <TConnection extends FinalConnectionDefinitionIface>(\n  definition: TConnection,\n): TConnection & { readonly auth: { readonly kind: 'final-session' } } =>\n  defineMcpClientConnection({ ...definition, auth: { kind: 'final-session' } });\n"],
-  "mappings": "AAAA;AAAA,EACE;AAAA,OAEK;AAOA,MAAM,wBAAwB,CACnC,eAEA,0BAA0B,EAAE,GAAG,YAAY,MAAM,EAAE,MAAM,gBAAgB,EAAE,CAAC;",
+  "sourcesContent": ["import {\n  defineMcpClientConnection,\n  defineHostedConnection,\n  type DynamicSentinelIface,\n  type HostedConnectionDefinitionIface,\n  type McpClientConnectionDefinitionIface,\n} from '@finalai/agent-definition/authoring';\n\nexport type FinalConnectionDefinitionIface = Omit<McpClientConnectionDefinitionIface, 'auth'>;\n\nexport interface FinalHostedConnectionDefinitionIface extends Omit<\n  HostedConnectionDefinitionIface,\n  'binding'\n> {\n  readonly binding?: string;\n}\n\n// `connections/final.ts`: Final's MCP server as an ordinary connection. The\n// session service's broker resolves `final-session` auth to a grant scoped to\n// the calling session, which Final's MCP server runs the tools as.\nexport function defineFinalConnection<TConnection extends FinalConnectionDefinitionIface>(\n  definition: TConnection,\n): TConnection & { readonly auth: { readonly kind: 'final-session' } };\nexport function defineFinalConnection(\n  definition?: FinalHostedConnectionDefinitionIface,\n): DynamicSentinelIface<McpClientConnectionDefinitionIface>;\nexport function defineFinalConnection(\n  definition: FinalConnectionDefinitionIface | FinalHostedConnectionDefinitionIface = {},\n): McpClientConnectionDefinitionIface | DynamicSentinelIface<McpClientConnectionDefinitionIface> {\n  if ('url' in definition)\n    return defineMcpClientConnection({ ...definition, auth: { kind: 'final-session' } });\n  return defineHostedConnection({\n    ...definition,\n    binding: definition.binding ?? 'final',\n  });\n}\n"],
+  "mappings": "AAAA;AAAA,EACE;AAAA,EACA;AAAA,OAIK;AAoBA,SAAS,sBACd,aAAoF,CAAC,GACU;AAC/F,MAAI,SAAS;AACX,WAAO,0BAA0B,EAAE,GAAG,YAAY,MAAM,EAAE,MAAM,gBAAgB,EAAE,CAAC;AACrF,SAAO,uBAAuB;AAAA,IAC5B,GAAG;AAAA,IACH,SAAS,WAAW,WAAW;AAAA,EACjC,CAAC;AACH;",
   "names": []
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@finalai/final-agent-provider",
-  "version": "0.1.2",
+  "version": "0.1.3",
   "private": false,
   "description": "Final's provider package: serverless, remote and local harnesses; the computer and device sandboxes; the messaging, schedule and event channels.",
   "license": "Apache-2.0",
@@ -9,6 +9,7 @@
     "README.md",
     "LICENSE",
     "NOTICE",
+    "HOSTING.md",
     "THIRD_PARTY_NOTICES.md"
   ],
   "type": "module",
@@ -212,14 +213,14 @@
   },
   "dependencies": {
     "@agentclientprotocol/sdk": "1.8.0",
-    "@finalai/acp-session": "0.1.2",
-    "@finalai/agent-protocol": "0.1.2",
-    "@finalai/agent-provider": "0.1.2",
-    "@finalai/computers": "0.1.2",
-    "@finalai/websockets": "0.1.2",
+    "@finalai/acp-session": "0.1.3",
+    "@finalai/agent-protocol": "0.1.3",
+    "@finalai/agent-provider": "0.1.3",
+    "@finalai/computers": "0.1.3",
+    "@finalai/websockets": "0.1.3",
     "ws": "^8.21.3",
     "zod": "4.6.5",
-    "@finalai/agent-definition": "0.1.2"
+    "@finalai/agent-definition": "0.1.3"
   },
   "engines": {
     "node": ">=26"