@finalai/daytona-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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@finalai/daytona-agent-provider",
-  "version": "0.1.2",
+  "version": "0.1.3",
   "private": false,
   "description": "Daytona's provider package: the daytona sandbox over Daytona's public API, implementing only the public sandbox provider contract.",
   "license": "Apache-2.0",
@@ -9,6 +9,7 @@
     "README.md",
     "LICENSE",
     "NOTICE",
+    "HOSTING.md",
     "THIRD_PARTY_NOTICES.md"
   ],
   "type": "module",
@@ -36,7 +37,7 @@
     "registry": "https://registry.npmjs.org/"
   },
   "dependencies": {
-    "@finalai/agent-provider": "0.1.2",
+    "@finalai/agent-provider": "0.1.3",
     "zod": "4.6.5"
   },
   "engines": {