@finalai/agent-definition 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

@@ -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-JPY4L2UJ.ts → chunk-3YAKMWV4.ts}

@@ -1,15 +1,15 @@
 import {
   BaseCapability,
   providerRefSchema
-} from "./chunk-OWC6SFFF.ts";
-import {
-  jsonObjectSchema,
-  jsonSchemaSchema
-} from "./chunk-7QP2CKPI.ts";
+} from "./chunk-OO67EO5E.ts";
 import {
   CredentialDelivery,
   InferenceCredentialKind
-} from "./chunk-HNPUTP35.ts";
+} from "./chunk-GCFSHHH2.ts";
+import {
+  jsonObjectSchema,
+  jsonSchemaSchema
+} from "./chunk-4X2DS5BR.ts";
 import {
   array,
   boolean,
@@ -22,7 +22,7 @@ import {
   record,
   string,
   union
-} from "./chunk-HGW4YHAY.ts";
+} from "./chunk-3K4C4SVG.ts";
 
 // ../agent-provider/src/schemas.ts
 var SCHEMA_IDS = {

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-5IZTHCGZ.ts}

@@ -1,17 +1,17 @@
 import {
   toolLabelSchema
-} from "./chunk-TATN3PYK.ts";
-import {
-  jsonSchemaDeclarationError
-} from "./chunk-GNR7XBPN.ts";
+} from "./chunk-2ZRYQO4Q.ts";
 import {
   lowerApproval
-} from "./chunk-7VSSVZM4.ts";
+} from "./chunk-BEFBCBUL.ts";
+import {
+  jsonSchemaDeclarationError
+} from "./chunk-W6DOJA4W.ts";
 import {
   authoredKindOf,
   pendingExportName,
   pendingIndexOf
-} from "./chunk-XHKPWT3G.ts";
+} from "./chunk-QJ26GEUM.ts";
 import {
   authoredRecordSchema,
   authoredValueSchema,
@@ -26,7 +26,7 @@ import {
   isString,
   messageOf,
   optionalValueSchema
-} from "./chunk-JIPNTA56.ts";
+} from "./chunk-TM36NO3C.ts";
 import {
   ZodType,
   array,
@@ -39,7 +39,7 @@ import {
   toJSONSchema,
   union,
   url
-} from "./chunk-HGW4YHAY.ts";
+} from "./chunk-3K4C4SVG.ts";
 
 // src/runtime/lower.ts
 var IssueSeverity = /* @__PURE__ */ ((IssueSeverity2) => {

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 */);

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

@@ -1,18 +1,18 @@
 import {
   ToolApproval
-} from "./chunk-OWC6SFFF.ts";
+} from "./chunk-OO67EO5E.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-HFS4KLEL.ts → chunk-D3SB4CCB.ts}

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

package/dist/compiler-assets/{chunk-EVQIK62B.ts → chunk-FHKYXT3F.ts}

@@ -6,15 +6,15 @@ import {
   resolvedAgentManifestSchema,
   sandboxBindingSchema,
   skillBundleSchema
-} from "./chunk-OWC6SFFF.ts";
-import {
-  jsonObjectSchema,
-  jsonValueSchema
-} from "./chunk-7QP2CKPI.ts";
+} from "./chunk-OO67EO5E.ts";
 import {
   findDynamicSlots,
   isDynamicSlot
-} from "./chunk-SKTNMUO7.ts";
+} from "./chunk-MSE7X5YG.ts";
+import {
+  jsonObjectSchema,
+  jsonValueSchema
+} from "./chunk-4X2DS5BR.ts";
 import {
   _null,
   array,
@@ -22,7 +22,7 @@ import {
   number,
   record,
   string
-} from "./chunk-HGW4YHAY.ts";
+} from "./chunk-3K4C4SVG.ts";
 
 // src/resolve.ts
 var SlotValueKind = /* @__PURE__ */ ((SlotValueKind2) => {
@@ -157,6 +157,10 @@ var resolveManifestDetailed = async (args) => {
   for (const found of slots) {
     const subscribed = found.slot.$dynamic.events.includes(args.event);
     const raw = subscribed ? await args.resolve(found.slot, found.path) : args.previous?.[found.path] ?? null;
+    if ((found.slot.$dynamic.requiredBindings?.length ?? 0) > 0 && raw == null)
+      throw new Error(
+        `Required hosted bindings for ${found.path} did not resolve: ${found.slot.$dynamic.requiredBindings?.map((item) => item.name).join(", ")}`
+      );
     if (subscribed) checkEnvironmentProvider(args.manifest, found.path, raw);
     normalized[found.path] = validateSlotValue(found.path, raw) ?? FIELD_DEFAULTS.get(found.path) ?? null;
     values[found.path] = slotKindOf(found.path) === "sandbox-environment" /* SandboxEnvironment */ ? raw : normalized[found.path] ?? null;

package/dist/compiler-assets/{chunk-HNPUTP35.ts → chunk-GCFSHHH2.ts}

@@ -1,6 +1,6 @@
 import {
   DynamicEvent
-} from "./chunk-SKTNMUO7.ts";
+} from "./chunk-MSE7X5YG.ts";
 import {
   array,
   literal,
@@ -8,7 +8,7 @@ import {
   object,
   string,
   union
-} from "./chunk-HGW4YHAY.ts";
+} from "./chunk-3K4C4SVG.ts";
 
 // ../agent-provider/src/credentials.ts
 var CredentialPayer = /* @__PURE__ */ ((CredentialPayer2) => {

package/dist/compiler-assets/{chunk-MZMSKIKU.ts → chunk-I6U47R5U.ts}

@@ -13,16 +13,22 @@ import {
   note,
   sandboxProviderNameOf,
   toJson
-} from "./chunk-ZDLVA6XF.ts";
+} from "./chunk-5IZTHCGZ.ts";
 import {
   AGENT_DYNAMIC_PREFIX,
   namedExportName
 } from "./chunk-NMYHO2QN.ts";
+import {
+  hostedBindingRequirementSchema
+} from "./chunk-MSE7X5YG.ts";
+import {
+  jsonValueSchema
+} from "./chunk-4X2DS5BR.ts";
 import {
   authoredKindOf,
   pendingEntries,
   pendingExportName
-} from "./chunk-XHKPWT3G.ts";
+} from "./chunk-QJ26GEUM.ts";
 import {
   entriesOf,
   fieldOf,
@@ -33,11 +39,11 @@ import {
   isString,
   messageOf,
   stringOrNull
-} from "./chunk-JIPNTA56.ts";
+} from "./chunk-TM36NO3C.ts";
 import {
   array,
   string
-} from "./chunk-HGW4YHAY.ts";
+} from "./chunk-3K4C4SVG.ts";
 
 // src/runtime/describe.ts
 var describeDynamic = (value) => {
@@ -63,7 +69,8 @@ var describeDynamic = (value) => {
     events: dynamicEventsOf(value),
     description: stringOrNull(fieldOf(value, "description")),
     preview: stringOrNull(fieldOf(value, "preview")),
-    provider: hint
+    provider: hint,
+    requiredBindings: array(hostedBindingRequirementSchema).parse(fieldOf(value, "requiredBindings") ?? [])
   };
 };
 var collectAgentDynamics = (agent) => {
@@ -90,6 +97,8 @@ var dynamicSlot = (value, path) => {
   const slot = { resolver: `${AGENT_DYNAMIC_PREFIX}${path}`, events: described.events };
   if (described.description != null) slot["description"] = described.description;
   if (described.preview != null) slot["preview"] = described.preview;
+  if ((described.requiredBindings?.length ?? 0) > 0)
+    slot["requiredBindings"] = jsonValueSchema.parse(described.requiredBindings);
   return { $dynamic: slot };
 };
 var isDefinedHarnessLike = (value) => isCallable(value) && isCallable(fieldOf(value, "describe")) && isCallable(fieldOf(value, "open"));

package/dist/compiler-assets/{chunk-5BK6FVRE.ts → chunk-IF6MR7JF.ts}

@@ -1,7 +1,7 @@
 import {
   jsonObjectSchema,
   jsonValueSchema
-} from "./chunk-7QP2CKPI.ts";
+} from "./chunk-4X2DS5BR.ts";
 import {
   _null,
   array,
@@ -11,7 +11,7 @@ import {
   object,
   string,
   union
-} from "./chunk-HGW4YHAY.ts";
+} from "./chunk-3K4C4SVG.ts";
 
 // ../agent-provider/src/channel.ts
 var ConversationKind = /* @__PURE__ */ ((ConversationKind2) => {

package/dist/compiler-assets/{chunk-LUSAAV4L.ts → chunk-IZGOMT7K.ts}

@@ -1,9 +1,9 @@
 import {
   awaitableOpenRequest
-} from "./chunk-CWWRTRWW.ts";
+} from "./chunk-4E5HECVD.ts";
 import {
   stamp
-} from "./chunk-XHKPWT3G.ts";
+} from "./chunk-QJ26GEUM.ts";
 
 // ../agent-provider/src/sandbox/types.ts
 var defineSandboxProvider = (definition) => ({

package/dist/compiler-assets/{chunk-GTUZOATD.ts → chunk-JGQ2KAN7.ts}

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

package/dist/compiler-assets/chunk-JXJPBM5W.ts

@@ -0,0 +1,61 @@
+import {
+  mcpAuthSchema
+} from "./chunk-OO67EO5E.ts";
+import {
+  defineDynamic
+} from "./chunk-PFLSBTJA.ts";
+import {
+  requireHostedBinding
+} from "./chunk-MSE7X5YG.ts";
+import {
+  jsonObjectSchema
+} from "./chunk-4X2DS5BR.ts";
+import {
+  stamp
+} from "./chunk-QJ26GEUM.ts";
+import {
+  record,
+  strictObject,
+  string,
+  toJSONSchema
+} from "./chunk-3K4C4SVG.ts";
+
+// src/authoring/connections.ts
+var defineMcpClientConnection = (definition) => stamp({ ...definition }, "connection" /* Connection */);
+var hostedConnectionSchema = strictObject({
+  url: string().url(),
+  auth: mcpAuthSchema.nullable().optional(),
+  headers: record(string(), string()).optional()
+});
+var defineHostedConnection = (definition) => {
+  const { binding, description, tools, approval } = definition;
+  if (binding.trim().length === 0) throw new Error("Hosted connection binding must not be empty");
+  return defineDynamic({
+    description: definition.description ?? `Hosted connection ${binding}`,
+    preview: `Resolved by hosting from ${binding}`,
+    requiredBindings: [
+      { name: binding, schema: jsonObjectSchema.parse(toJSONSchema(hostedConnectionSchema)) }
+    ],
+    events: {
+      "session.started": async (_event, ctx) => {
+        const value = await requireHostedBinding({ bindings: ctx.bindings, name: binding });
+        const parsed = hostedConnectionSchema.safeParse(value);
+        if (!parsed.success)
+          throw new Error(`Hosted connection ${binding} has invalid configuration`);
+        const { auth, ...transport } = parsed.data;
+        return defineMcpClientConnection({
+          ...transport,
+          description,
+          tools,
+          approval,
+          ...auth == null ? {} : { auth }
+        });
+      }
+    }
+  });
+};
+
+export {
+  defineMcpClientConnection,
+  defineHostedConnection
+};

package/dist/compiler-assets/{chunk-NYTOYKKF.ts → chunk-K6D7ZK74.ts}

@@ -1,13 +1,13 @@
 import {
   credentials
-} from "./chunk-HNPUTP35.ts";
+} from "./chunk-GCFSHHH2.ts";
 import {
   DynamicEvent
-} from "./chunk-SKTNMUO7.ts";
+} from "./chunk-MSE7X5YG.ts";
 import {
   isAuthored,
   registerPending
-} from "./chunk-XHKPWT3G.ts";
+} from "./chunk-QJ26GEUM.ts";
 
 // src/authoring/credentials.ts
 var DYNAMIC_EVENTS = Object.values(DynamicEvent);

package/dist/compiler-assets/{chunk-WMXMVFHM.ts → chunk-K7V4IMOB.ts}

@@ -1,15 +1,15 @@
 import {
   jsonObjectSchema
-} from "./chunk-7QP2CKPI.ts";
+} from "./chunk-4X2DS5BR.ts";
 import {
   stamp
-} from "./chunk-XHKPWT3G.ts";
+} from "./chunk-QJ26GEUM.ts";
 import {
   array,
   nativeEnum,
   object,
   string
-} from "./chunk-HGW4YHAY.ts";
+} from "./chunk-3K4C4SVG.ts";
 
 // ../agent-provider/src/channel-context.ts
 var ChannelPrincipalType = /* @__PURE__ */ ((ChannelPrincipalType2) => {

package/dist/compiler-assets/{chunk-VHXHUU7L.ts → chunk-LHMUAIYJ.ts}

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