@finalai/final-agent-provider 0.10.1 → 0.12.0

package/README.md

@@ -1,41 +1,130 @@
 # @finalai/final-agent-provider
 
-Provider helpers for harnesses, computer and device sandboxes, the Final room, and
-external channels. Import helpers from `/harnesses`, `/sandboxes`, or `/channels/final`.
-`/connections` provides `defineFinalConnection` for session-scoped Final MCP access.
-
-Optional Node ACP adapters are exposed under `/runtime/*`. Sandbox adapters use
-the public Computers and Device APIs; the Computers transport is shared with
-`@finalai/computers`. Runtime configuration and credentials are injected.
-
-The `computer` and `device` sandboxes authenticate with the context's
-`credentials.computersAccess()` and `credentials.deviceAccess()` (`{ baseUrl, token }`);
-without them they fail with `credential_missing`.
-
-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.
-
-## Hosted model references
-
-The serverless Final, Pi, Codex and Claude helpers accept model strings, including provider-qualified references such as `openrouter/deepseek/deepseek-v4.1-flash`. Existing short model IDs remain valid aliases when the installed platform catalog supports them. The SDK checks printable ASCII reference syntax (up to 200 characters); the installed platform selects defaults, validates availability and supplies model picker suggestions. Omitting `model` inherits the platform default. Host integrators must now handle `serverless*ConfigSchema.parse(...).model` being undefined and resolve the default before dispatch. Local compilation does not fetch a model catalog.
-
-Adding a model on an already-supported provider API requires a platform catalog update, not an SDK release. Native nanocode models must use an engine policy the platform supports. New provider protocols still require an integration.
-
-The `modelZod(ids)` and `modelJson(ids, defaultId)` helpers retain explicit restrictions for third-party harness authors who choose to supply them.
-
-SDK 0.2.0 removes `@finalai/agents/models` and `@finalai/final-agent-provider/harnesses/models`, including their model arrays, defaults, model-ID unions and pricing helpers. Use string model references and the installed platform’s harness description for current candidates and defaults. Pricing belongs to the hosting platform. The protocol-level `ModelVendor` enum remains available from `@finalai/final-agent-provider/harnesses`.
+Final's harness and ACP adapter definitions, the general harness provider,
+sandbox providers and MCP gateway integration, as a caller provides them to an
+agent.
+
+## Harness settings
+
+`/harnesses` exports one settings builder per Final harness. Each returns plain
+harness settings, `{ harness, configuration, environment? }`, the wire form a
+caller passes as `provide.harness`:
+
+```ts
+import {
+  apiKey,
+  finalCredits,
+  serverlessNanocodeClaude,
+  subscription,
+} from '@finalai/final-agent-provider/harnesses';
+
+serverlessNanocodeClaude({
+  model: 'claude-opus-5-5',
+  inference: [subscription(), apiKey('ANTHROPIC_API_KEY'), finalCredits()],
+});
+```
+
+- `FinalHarness` names the definitions as settings reach them, qualified by
+  Final's publisher handle (`final/pi`); `FinalHarnessName` is the name each is
+  published under. `final`, `pi`, `nanocode-claude` and
+  `nanocode-codex` run as worker programs (`serverlessFinal`, `serverlessPi`,
+  `serverlessNanocodeClaude`, `serverlessNanocodeCodex`); `claude-code` and
+  `codex` run as processes on a machine (`claudeCode`, `codex`); `acp-agent` is
+  any agent that already speaks ACP v2 with Final's ACP extensions, reached at its
+  URL with no adapter (`acpAgent({ url, hop })`).
+- `inference` is one source or an ordered list (`subscription`, `apiKey`,
+  `finalCredits`, `harnessLogin`); a single source is stored as a one-item list.
+- Worker harnesses require `model`, an open reference the harness validates
+  (`openrouter/deepseek/deepseek-v4.1-flash` included). There is no default model.
+- `permissionMode` is `ask`, `review` or `auto`, within the agent's ceiling; each
+  harness's adapter maps it to its program's own mode.
+- `environment` is the sandbox the harness runs in, or `atUrl({ url, hop })` for
+  an ACP endpoint already running it (`hop` names the project secret holding its
+  bearer token). Absent, a process harness runs in the sandbox provided for
+  `shell`, and the client gives a worker harness a sandbox created from
+  `workers()`, owned by the session or conversation.
+
+Instructions, skills and tool policy come from the agent's document, never from
+harness settings.
+
+## Definitions and the general provider
+
+Each harness is a definition (`FINAL_HARNESS_DEFINITIONS`): its configuration
+schema, the features it supports, the lowest permission it can be held to, the
+inference it can use, what it uses natively where it runs, its default ACP
+adapter, and how it runs (a worker program, or a process command derived from
+its configuration). Each ACP adapter (`FINAL_ACP_ADAPTERS`) maps one harness
+interface to ACP v2 and Final's ACP extensions:
+
+| Adapter           | Adapts                              | Runs as                                                        |
+| ----------------- | ----------------------------------- | -------------------------------------------------------------- |
+| `pi-acp`          | `pi`, `final`                       | worker program `pi`                                            |
+| `nanocode-acp`    | `nanocode-claude`, `nanocode-codex` | worker program `nanocode`                                      |
+| `claude-code-acp` | `claude-code`                       | `npx -y @finalai/acp-adapter-claude-code -- <harness command>` |
+| `codex-acp`       | `codex`                             | `npx -y @finalai/acp-adapter-codex -- <harness command>`       |
+
+Pi has no process adapter, so it runs only as a worker program or at a URL.
+`acp-agent` speaks ACP v2 itself and has no run entry: it runs only at a URL.
+
+`validateHarnessConfiguration` (from `@finalai/agent-provider`) checks harness
+settings' configuration against a definition: its configuration schema with the
+shared `final://schemas/*` fragments, its lowest permission and the inference it
+can use.
+
+`/provider` is the general harness provider, one self-contained module built
+with `defineHarnessProvider` on the public provider contract. It starts
+adapter(harness) in the environment (a process over the sandbox's process
+streams, or a worker program on a worker runtime) and hands over the ACP
+stream, or hands over the URL of an endpoint already running. It refuses an
+adapter that does not implement Final's ACP extensions (observe, authorMeta,
+resumeReplay, afterSeqReplay), and every endpoint it hands over must advertise
+them in `initialize`.
+
+`/catalog` exports all of it as documents to publish: `finalCatalog` holds the
+harness definitions, the adapter definitions and the provider.
+
+## Sandboxes
+
+`/sandboxes` exports environments as plain data:
+`project.sandboxes.create(computer({ image }), { setup })`.
+
+- `computer({ image, build, machine, region, idleTimeoutSeconds })`: a Final
+  computer from the public Computers API. `build` steps are baked into a base once.
+- `device({ deviceId })` or `device({ pairing })`: a person's own computer running
+  Final Device. It takes no sandbox setup.
+- `workers()`: Final's Workers runtime, where the worker harnesses run. It runs
+  only their worker programs, offers the model no files or shell, and takes no
+  sandbox setup.
+- `defineSandboxSetup` describes what should be on any provider's machine
+  (repositories, variables, steps, services, commands, network, notes); the
+  platform applies it after the provider attaches.
+
+The providers (`/sandboxes/computer`, `/sandboxes/device`) follow the resource
+lifecycle: `create` records a sandbox and boots nothing, `attach` reports whether
+the disk is new and whether the machine booted, then `detach`, `park` and `delete`.
+They take the API's origin (`computersApiUrl`, `deviceApiUrl`) and authenticate
+with the provider's platform identity for it (`ctx.identity`), which the
+registration must be granted. A `computer` with no `idleTimeoutSeconds` outlasts
+the platform's idle parking (`ctx.lifecycle.parkAfterIdleMs`) by five minutes.
+
+`/sandboxes/local` (Node only) is the sandbox a client serves from its own
+process: files under one directory and commands run in it, confined to that
+directory, inheriting only a short list of environment variables.
+
+## Final's MCP gateway
+
+`finalGateway({ url })` from `/integrations` is the create-integration request
+for Final's MCP gateway: `project.integrations.create(finalGateway({ url }))`,
+where `url` is the gateway's MCP endpoint, for example
+`https://gateway.example.com/api/mcp/tools`. The URL is required; the platform
+resolves no placeholder for it. It authenticates with the platform's identity
+assertion for the calling session.
 
 ## Durable processes
 
 The `computer` and `device` sandboxes offer durable processes
-(`SandboxCapability.DurableProcesses`: `spawn({ durable: true })` and `attachProcess`) on
-write and execute bindings. A ref names the sandbox, the process and its boot (and, on a
+(`SandboxCapability.DurableProcesses`: `spawn({ durable: true })` and `attachProcess`) to
+grants that run commands. A ref names the sandbox, the process and its boot (and, on a
 Device, the lease generation), so a ref from another sandbox, boot or generation attaches
 to nothing. A dropped handle stops polling and never terminates the process; `timeoutMs`
 is enforced by the computer or Device itself.
@@ -52,19 +141,9 @@ is enforced by the computer or Device itself.
 
 ## Workspace Device egress
 
-`/sandboxes/egress` supplies provider-neutral Linux TCP/UDP/DNS routing through approved Final Devices. Hosts compose `createWorkspaceDeviceNetworking({ api, needed })` through the generic provider `networking` option. They supply stable logical workspace identity, durable networking registration, the current actor, and the raw privileged sandbox session. Preserve the direct policy before boot fencing; restore it on Disable. Configure and Disable ask for consent by default.
-
-The [integration reference](WORKSPACE-EGRESS.md) specifies required hooks, boot/resume fallback, binding authority, teardown, MCP transports, failure behavior, prerequisites, and provider acceptance. Read it before enabling this capability. Final Computer and Daytona use their public APIs; custom providers can compose the same controller and manager.
-
-In 0.4, passive Computer recovery follows the read-only viewer contract even without
-a networking extension. Use ordinary resume for execution. The bundled adapters
-cache deferred setup failures per handle; reconnect to retry rather than replaying
-partially completed user setup commands on each MCP poll.
+`/sandboxes/egress` supplies provider-neutral Linux TCP/UDP/DNS routing through approved Final Devices. Hosts compose `createWorkspaceDeviceNetworking({ api, access, needed })` through the generic provider `networking` option. A sandbox's id is its workspace identity; hosts supply durable networking registration, the current actor, and the raw privileged sandbox session. Preserve the direct policy before boot fencing; restore it on Disable. Configure and Disable ask for consent by default.
 
-## Authored channels
+The [integration reference](WORKSPACE-EGRESS.md) specifies required hooks, boot/resume fallback, grant authority, teardown, MCP transports, failure behavior, prerequisites, and provider acceptance. Read it before enabling this capability. Final Computer and Daytona use their public APIs; custom providers can compose the same controller and manager.
 
-External integrations are ordinary authored modules built with `defineChannel`
-from `@finalai/agent-provider`. The SDK provides scoped platform capabilities and
-opaque credential operations; application implementations live with their source.
-Final chat customization uses `finalChannel` from `/channels/final` and is compiled
-into the authored bundle in the same way as other customization code.
+A passive attach serves a read-only viewer and never boots or changes the
+computer; use an ordinary attach for execution.

package/WORKSPACE-EGRESS.md

@@ -17,7 +17,7 @@ const daytona = createDaytonaSandboxProvider({ networking });
 
 The factories are exported from `/sandboxes/egress`, `/sandboxes/computer`, and
 `@finalai/daytona-agent-provider/sandboxes/daytona`, respectively. Keep the trusted
-Device access in the context's credentials. A custom provider accepts
+Device access through the extension's configured `access`. A custom provider accepts
 the same generic extension: call `enabled`, validate its workspace identity, call
 `prepare` before provider fencing, and use `attachSandboxNetworking` after
 obtaining its raw handle. Supply the saved policy, restore/fence callbacks,
@@ -25,8 +25,8 @@ namespace existence check and deferred setup. Physical teardown calls `suspend`
 even if another cleanup step fails. Providers needing earlier namespace setup can
 use `controller` and `withSandboxNetworking` directly, as Final Computer does.
 
-The context's `credentials.deviceAccess({ actingUserId })` returns the Device API
-origin and a token. Device
+The extension's configured `access({ organizationId, projectId, actingUserId })`
+returns the Device API origin and a token. Device
 operations use the current actor; background lease reconciliation may use the stored
 lease owner instead of a present turn author. Hosts must authorize both forms of work.
 Admission, policy persistence, and cleanup also make trusted service calls with
@@ -35,7 +35,7 @@ accepted by those service endpoints for that case, separate from user-bound gran
 Returning `null` refuses the call before HTTP; a user-token-only configuration cannot
 start or clean up networked workspaces. Its host must add service authentication
 before enabling this extension. The SDK never reuses a user's cached grant for a
-service call or another user: it asks the context's credentials on every call.
+service call or another user: it asks the configured access on every call.
 
 The extension owns Device authorization, enrollment, helper installation, leases
 and failover. Providers need no Device networking implementation. Its generic
@@ -49,7 +49,7 @@ an older API rejecting the field cannot silently grant longer access.
 
 1. Assign one stable host-owned identity per logical workspace and persist whether networking is managed. Supply that identity to start, resume, editors and teardown.
 2. Save the actual direct policy before a boot fence. Prefer a provider fence; explicitly unsupported providers use the logged startup-window fallback.
-3. Construct the manager with the raw session and privileged executor, then declare its policy on the provider handle with its binding access and current-actor reader.
+3. Construct the manager with the raw session and privileged executor, then declare its policy on the provider handle with the connection's grant and current-actor reader.
 4. Detach on runtime shutdown. On physical stop/deletion, attempt fencing, lease cleanup and provider cleanup independently; retain saved desired settings for recreation.
 
 Inject the Device API URL, trusted Device credential callback, stable workspace ID, current acting user, and the raw Linux sandbox session. Pass that unguarded session into `createWorkspaceEgressManager`, then use `withWorkspaceEgress` to declare its execution policy and lifecycle hooks on the returned handle. `withWorkspaceEgress` constructs a checked handle through the generic SDK constructor, so direct callers are safe too. `defineSandboxProvider` automatically adds any host admission policy on start and resume without reinstalling the Device policy. Using a guarded session for privileged controller execution recursively deadlocks. `/sandboxes/egress-bootstrap` exports the exact controller source for custom privileged executors and manual acceptance. Custom executors run `python3 -I -c source source` with JSON on stdin, or execute a root-owned file providing `__file__`; the source argument permits persistence for later controller launches.
@@ -60,13 +60,13 @@ Supply the extension's `enabled` predicate through `createWorkspaceDeviceNetwork
 
 Before creating or booting a fenced namespace, call `preserveWorkspaceNetworkPolicy` with its actual current provider policy. This atomically saves only a missing policy; a temporary boot fence must never replace a saved choice. Both providers call the extension's `prepare` hook for durable create-if-absent behavior, and its `suspend` hook during physical teardown. The Final Device extension implements those hooks through the Device API. The initialization endpoint is deliberately separate: an older Device API rejects boot before changing provider policy rather than misinterpreting the operation as a policy update.
 
-Custom networking hooks own resources allocated before they reject and must clean up those resources. A failed attachment must not revoke another binding’s shared lease. The Device API must expire provisioning leases whose create acknowledgement is lost; a client cannot revoke an ID it never received, and cannot activate it without the acknowledged enrollment.
+Custom networking hooks own resources allocated before they reject and must clean up those resources. A failed attachment must not revoke another connection’s shared lease. The Device API must expire provisioning leases whose create acknowledgement is lost; a client cannot revoke an ID it never received, and cannot activate it without the acknowledged enrollment.
 
 Adapters must supply `afterGuard` to restore restrictive saved policies or undo an outer fence. Missing restoration refuses Configure/Disable rather than acknowledging an unrestricted direct route. Provider instances retain remembered managed-workspace and prepared-policy identifiers for their lifetime; include that inventory in host capacity planning. Durable host registration remains required across process replacement.
 
 ## Boot, resume and saved policy
 
-Prefer provider networking fences before boot or rebase, then apply the transport policy only after the manager guards the namespace. Daytona defaults to a structured-warning fallback only when the account explicitly rejects custom networking; `workspaceNetworkingBootFence: true` requires the provider fence, and `false` deliberately selects command-readiness protection. Startup/resumed background traffic before controller initialization is outside the fallback guarantee. A fresh managed read binding records the intended policy before creation, then stays fenced until a write binding recovers it. Existing running read bindings remain passive. Read bindings cannot wake a managed paused/stopped Computer or stopped/archived Daytona workspace; a write binding must resume it through guarded initialization. Pass the host’s logical `session.workspaceId` through every lifecycle call. Generic `sandboxWorkspaceId` derives conversation/target identity across replacement bindings when absent; provider resource names remain private. New session workspaces use binding-derived identities and the guide's initial policy. Missing or unreadable provider policy is denied. Fallback identities escape delimiters; Device egress identities must fit the 256-character protocol limit without restricting ordinary sandbox identities; supply a bounded host identity for longer provider names. Disable before capturing an image; do not clone a live managed identity.
+Prefer provider networking fences before boot or rebase, then apply the transport policy only after the manager guards the namespace. Daytona defaults to a structured-warning fallback only when the account explicitly rejects custom networking; `workspaceNetworkingBootFence: true` requires the provider fence, and `false` deliberately selects command-readiness protection. Startup/resumed background traffic before controller initialization is outside the fallback guarantee. A connection whose grant does not both write files and run commands is passive for networking: it records nothing, never recovers a route, and cannot wake a managed paused/stopped Computer or stopped/archived Daytona sandbox; a connection whose grant does both must resume it through guarded initialization. A sandbox's id is its workspace identity for Device egress; provider resource names remain private. A new sandbox starts from its setup's network policy. Missing or unreadable provider policy is denied. Fallback identities escape delimiters; Device egress identities must fit the 256-character protocol limit without restricting ordinary sandbox identities; supply a bounded host identity for longer provider names. Disable before capturing an image; do not clone a live managed identity.
 
 Device configuration and Disable ask for approval by default through the public sandbox tool policy, and can be explicitly preauthorized. Consent selects the Device’s destination controls, including private access; provider destination allowlists do not constrain traffic inside the tunnel. Retain the saved direct-access policy and restore it on Disable. Unknown initial policy prevents configuration because restoration would be undefined. Disable before changing the saved direct-access policy. In-tunnel destination allowlists are unsupported. Configure failures intentionally retain a blocked route and desired settings until successful configuration or explicit disable; they never silently restore direct access.
 
@@ -93,13 +93,13 @@ A workspace shares one network namespace; checks on new operations do not isolat
 already-running processes by user. The Linux firewall independently enforces
 physical-egress denial.
 
-## Authority, bindings and shutdown
+## Authority, grants and shutdown
 
-Device Configure/Disable require write access and lifecycle authority. Direct network-policy operations require execute or write access plus lifecycle authority; read bindings cannot mutate networking. MCP projections enforce tool consent; hosts exposing handle RPC must install their own operation-consent hook. Configure and Disable default to Ask. Only exact `network.egress.configure`/`network.egress.disable` action preauthorization can waive the default; broad lifecycle/network Allow cannot. Status honors `network.egress.status` and `egress` policy. MCP hosts pass lifecycle authority and action input to the policy-key helper, then use `resolveSandboxToolPolicy` so any applicable Ask wins for Configure/Disable. Status retains ordinary first-match read-policy precedence for `network.egress.status` and `egress`. This release exposes status on write/lifecycle bindings. Foreground actor changes suspend as the currently acting user, including a trusted userless host, and block until an explicit route choice; background bindings do not revoke another actor's chosen route. Userless execution cannot inherit someone else's Device access.
+Device Configure/Disable require write access and lifecycle authority. Direct network-policy operations require execute or write access plus lifecycle authority; a grant without files write and shell execute cannot mutate networking. MCP projections enforce tool consent; hosts exposing handle RPC must install their own operation-consent hook. Configure and Disable default to Ask. Only exact `network.egress.configure`/`network.egress.disable` action preauthorization can waive the default; broad lifecycle/network Allow cannot. Status honors `network.egress.status` and `egress` policy. MCP hosts pass lifecycle authority and action input to the policy-key helper, then use `resolveSandboxToolPolicy` so any applicable Ask wins for Configure/Disable. Status retains ordinary first-match read-policy precedence for `network.egress.status` and `egress`. This release exposes status to grants that write files and run commands, with lifecycle authority. Foreground actor changes suspend as the currently acting user, including a trusted userless host, and block until an explicit route choice; background connections do not revoke another actor's chosen route. Userless execution cannot inherit someone else's Device access.
 
-Read bindings skip recovery and deferred setup. Pass binding access to `withWorkspaceEgress`; never initialize a manager for a read binding. They may inspect files but cannot repair a blocked route or run setup. A write binding must configure or explicitly disable first. Networking changes do not run deferred repository/setup work; that runs before the next guarded execution, write, or foreground MCP endpoint/channel acquisition.
+Passive connections skip recovery and deferred setup. Pass the connection's grant to `withWorkspaceEgress`; never initialize a manager for a passive connection. They may inspect files but cannot repair a blocked route or run setup. A connection whose grant writes files and runs commands must configure or explicitly disable first. Networking changes do not run deferred repository/setup work; that runs before the next guarded execution, write, or foreground MCP endpoint/channel acquisition.
 
-The manager owns renewal; failure observers cannot interrupt networking or claim cleanup. Editor access by another actor is refused before changing the owner’s route. A successful direct-policy retry clears a previous provider-update failure, including for userless workspaces. `close()` detaches a handle; runtime shutdown must not disrupt another binding sharing the workspace. `close(true)` attempts the namespace fence and suspends every lease for an explicit workspace stop/deletion, even if its cached lease has been replaced. Failure cleanup revokes only a lease that this handle created. Provider teardown independently attempts the fence, resource cleanup and lease revocation, and reports failures after cleanup. Removing boot admission must still permit teardown; hosts distinguish it with the predicate's `teardown` flag. Desired settings survive stop and lease expiry.
+The manager owns renewal; failure observers cannot interrupt networking or claim cleanup. Editor access by another actor is refused before changing the owner’s route. A successful direct-policy retry clears a previous provider-update failure, including for userless workspaces. `close()` detaches a handle; runtime shutdown must not disrupt another connection sharing the workspace. `close(true)` attempts the namespace fence and suspends every lease for an explicit workspace stop/deletion, even if its cached lease has been replaced. Failure cleanup revokes only a lease that this handle created. Provider teardown independently attempts the fence, resource cleanup and lease revocation, and reports failures after cleanup. Removing boot admission must still permit teardown; hosts distinguish it with the predicate's `teardown` flag. Desired settings survive stop and lease expiry.
 
 Teardown preserves the current provider policy before applying a fence. If eligibility or initial-policy persistence is unavailable for an unknown workspace, teardown still stops the resource, attempts suspension, and reports the error; it does not overwrite an unrelated policy. Host-managed boot waits for eligibility and saved policy recovery. Managed Computer creation and write/resume disable automatic wake. Passive read attachments do not change provider settings; migrate existing resources through a write attachment before relying on managed wake protection. Daytona’s preferred-fence fallback retains the documented startup window.
 

package/dist/modules/catalog.d.mts

@@ -0,0 +1,9 @@
+import type { DefinedHarnessProviderIface } from '@finalai/agent-definition/authoring';
+import type { AcpAdapterDefinitionIface, HarnessDefinitionIface } from '@finalai/agent-provider';
+import { FinalHarnessName, type FinalAcpAdapter } from "./harnesses/names.mjs";
+export interface FinalCatalogIface {
+    harnesses: Record<FinalHarnessName, HarnessDefinitionIface>;
+    adapters: Record<FinalAcpAdapter, AcpAdapterDefinitionIface>;
+    provider: DefinedHarnessProviderIface;
+}
+export declare const finalCatalog: FinalCatalogIface;

package/dist/modules/catalog.mjs

@@ -0,0 +1,21 @@
+import { FINAL_ACP_ADAPTERS } from "./harnesses/adapters.mjs";
+import { FINAL_HARNESS_DEFINITIONS } from "./harnesses/definitions.mjs";
+import { FinalHarness, FinalHarnessName } from "./harnesses/names.mjs";
+import { GENERAL_HARNESS_PROVIDER } from "./provider/index.mjs";
+const finalCatalog = {
+  harnesses: {
+    [FinalHarnessName.Final]: FINAL_HARNESS_DEFINITIONS[FinalHarness.Final],
+    [FinalHarnessName.Pi]: FINAL_HARNESS_DEFINITIONS[FinalHarness.Pi],
+    [FinalHarnessName.NanocodeClaude]: FINAL_HARNESS_DEFINITIONS[FinalHarness.NanocodeClaude],
+    [FinalHarnessName.NanocodeCodex]: FINAL_HARNESS_DEFINITIONS[FinalHarness.NanocodeCodex],
+    [FinalHarnessName.ClaudeCode]: FINAL_HARNESS_DEFINITIONS[FinalHarness.ClaudeCode],
+    [FinalHarnessName.Codex]: FINAL_HARNESS_DEFINITIONS[FinalHarness.Codex],
+    [FinalHarnessName.AcpAgent]: FINAL_HARNESS_DEFINITIONS[FinalHarness.AcpAgent]
+  },
+  adapters: FINAL_ACP_ADAPTERS,
+  provider: GENERAL_HARNESS_PROVIDER
+};
+export {
+  finalCatalog
+};
+//# sourceMappingURL=catalog.mjs.map

package/dist/modules/catalog.mjs.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../../../../src/catalog.ts"],
+  "sourcesContent": ["import type { DefinedHarnessProviderIface } from '@finalai/agent-definition/authoring';\nimport type { AcpAdapterDefinitionIface, HarnessDefinitionIface } from '@finalai/agent-provider';\nimport { FINAL_ACP_ADAPTERS } from \"./harnesses/adapters.mjs\";\nimport { FINAL_HARNESS_DEFINITIONS } from \"./harnesses/definitions.mjs\";\nimport { FinalHarness, FinalHarnessName, type FinalAcpAdapter } from \"./harnesses/names.mjs\";\nimport { GENERAL_HARNESS_PROVIDER } from \"./provider/index.mjs\";\n\n// Everything Final publishes for harnesses, as documents: its harness and ACP\n// adapter definitions by the names they are published under (settings reach\n// them qualified, `final/<name>`), and the general provider that runs any\n// definition carrying no provider of its own.\nexport interface FinalCatalogIface {\n  harnesses: Record<FinalHarnessName, HarnessDefinitionIface>;\n  adapters: Record<FinalAcpAdapter, AcpAdapterDefinitionIface>;\n  provider: DefinedHarnessProviderIface;\n}\n\nexport const finalCatalog: FinalCatalogIface = {\n  harnesses: {\n    [FinalHarnessName.Final]: FINAL_HARNESS_DEFINITIONS[FinalHarness.Final],\n    [FinalHarnessName.Pi]: FINAL_HARNESS_DEFINITIONS[FinalHarness.Pi],\n    [FinalHarnessName.NanocodeClaude]: FINAL_HARNESS_DEFINITIONS[FinalHarness.NanocodeClaude],\n    [FinalHarnessName.NanocodeCodex]: FINAL_HARNESS_DEFINITIONS[FinalHarness.NanocodeCodex],\n    [FinalHarnessName.ClaudeCode]: FINAL_HARNESS_DEFINITIONS[FinalHarness.ClaudeCode],\n    [FinalHarnessName.Codex]: FINAL_HARNESS_DEFINITIONS[FinalHarness.Codex],\n    [FinalHarnessName.AcpAgent]: FINAL_HARNESS_DEFINITIONS[FinalHarness.AcpAgent],\n  },\n  adapters: FINAL_ACP_ADAPTERS,\n  provider: GENERAL_HARNESS_PROVIDER,\n};\n"],
+  "mappings": "AAEA,SAAS,0BAA0B;AACnC,SAAS,iCAAiC;AAC1C,SAAS,cAAc,wBAA8C;AACrE,SAAS,gCAAgC;AAYlC,MAAM,eAAkC;AAAA,EAC7C,WAAW;AAAA,IACT,CAAC,iBAAiB,KAAK,GAAG,0BAA0B,aAAa,KAAK;AAAA,IACtE,CAAC,iBAAiB,EAAE,GAAG,0BAA0B,aAAa,EAAE;AAAA,IAChE,CAAC,iBAAiB,cAAc,GAAG,0BAA0B,aAAa,cAAc;AAAA,IACxF,CAAC,iBAAiB,aAAa,GAAG,0BAA0B,aAAa,aAAa;AAAA,IACtF,CAAC,iBAAiB,UAAU,GAAG,0BAA0B,aAAa,UAAU;AAAA,IAChF,CAAC,iBAAiB,KAAK,GAAG,0BAA0B,aAAa,KAAK;AAAA,IACtE,CAAC,iBAAiB,QAAQ,GAAG,0BAA0B,aAAa,QAAQ;AAAA,EAC9E;AAAA,EACA,UAAU;AAAA,EACV,UAAU;AACZ;",
+  "names": []
+}

package/dist/modules/harnesses/acp-agent.d.mts

@@ -0,0 +1,4 @@
+import { type HarnessDefinitionIface, type HarnessSettingsIface } from '@finalai/agent-provider';
+import { type AtUrlInputIface } from "./names.mjs";
+export declare const ACP_AGENT_HARNESS: HarnessDefinitionIface;
+export declare const acpAgent: (input: AtUrlInputIface) => HarnessSettingsIface;

package/dist/modules/harnesses/acp-agent.mjs

@@ -0,0 +1,35 @@
+import { defineHarness } from "@finalai/agent-definition/authoring";
+import {
+  ACP_V2_INTERFACE,
+  CredentialDelivery,
+  HarnessFeature,
+  InferenceSourceKind,
+  McpTransportKind,
+  PermissionLevel,
+  PromptWhileRunning
+} from "@finalai/agent-provider";
+import { configObjectJson, harnessSettings } from "./config-fields.mjs";
+import { atUrl, FinalHarness } from "./names.mjs";
+const ACP_AGENT_HARNESS = defineHarness({
+  title: "ACP agent",
+  description: "An agent that speaks ACP v2 with Final's ACP extensions, at its URL.",
+  configurationSchema: configObjectJson({ title: "ACP agent", properties: {} }),
+  features: [HarnessFeature.McpTools],
+  // Final cannot hold an agent it does not run to asking first.
+  lowestPermission: PermissionLevel.Auto,
+  inference: { kinds: [InferenceSourceKind.Harness], delivery: CredentialDelivery.AtOpen },
+  interface: ACP_V2_INTERFACE,
+  adapter: null,
+  run: {},
+  mcp: [McpTransportKind.Http],
+  // The extensions every endpoint Final dials must advertise.
+  supports: { observe: true, resumeReplay: true, authorMeta: true, fork: false },
+  promptWhileRunning: PromptWhileRunning.Queue,
+  sessionSurvivesDisconnect: false
+});
+const acpAgent = (input) => harnessSettings({ harness: FinalHarness.AcpAgent, configuration: {}, environment: atUrl(input) });
+export {
+  ACP_AGENT_HARNESS,
+  acpAgent
+};
+//# sourceMappingURL=acp-agent.mjs.map

package/dist/modules/harnesses/acp-agent.mjs.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../../../../../src/harnesses/acp-agent.ts"],
+  "sourcesContent": ["import { defineHarness } from '@finalai/agent-definition/authoring';\nimport {\n  ACP_V2_INTERFACE,\n  CredentialDelivery,\n  HarnessFeature,\n  InferenceSourceKind,\n  McpTransportKind,\n  PermissionLevel,\n  PromptWhileRunning,\n  type HarnessDefinitionIface,\n  type HarnessSettingsIface,\n} from '@finalai/agent-provider';\nimport { configObjectJson, harnessSettings } from \"./config-fields.mjs\";\nimport { atUrl, FinalHarness, type AtUrlInputIface } from \"./names.mjs\";\n\n// Any agent that already speaks ACP v2 with Final's ACP extensions, running\n// elsewhere: it needs no adapter, nothing is started, and it is reached at its\n// URL (an `atUrl` environment). It brings its own model access and is told\n// nothing about Final's credentials; what it does beyond ACP is its own, so\n// the definition promises no more than ACP and the required extensions give.\n\nexport const ACP_AGENT_HARNESS: HarnessDefinitionIface = defineHarness({\n  title: 'ACP agent',\n  description: \"An agent that speaks ACP v2 with Final's ACP extensions, at its URL.\",\n  configurationSchema: configObjectJson({ title: 'ACP agent', properties: {} }),\n  features: [HarnessFeature.McpTools],\n  // Final cannot hold an agent it does not run to asking first.\n  lowestPermission: PermissionLevel.Auto,\n  inference: { kinds: [InferenceSourceKind.Harness], delivery: CredentialDelivery.AtOpen },\n  interface: ACP_V2_INTERFACE,\n  adapter: null,\n  run: {},\n  mcp: [McpTransportKind.Http],\n  // The extensions every endpoint Final dials must advertise.\n  supports: { observe: true, resumeReplay: true, authorMeta: true, fork: false },\n  promptWhileRunning: PromptWhileRunning.Queue,\n  sessionSurvivesDisconnect: false,\n});\n\n// An ACP agent at `url`; `hop` names the project secret holding its bearer token.\nexport const acpAgent = (input: AtUrlInputIface): HarnessSettingsIface =>\n  harnessSettings({ harness: FinalHarness.AcpAgent, configuration: {}, environment: atUrl(input) });\n"],
+  "mappings": "AAAA,SAAS,qBAAqB;AAC9B;AAAA,EACE;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,OAGK;AACP,SAAS,kBAAkB,uBAAuB;AAClD,SAAS,OAAO,oBAA0C;AAQnD,MAAM,oBAA4C,cAAc;AAAA,EACrE,OAAO;AAAA,EACP,aAAa;AAAA,EACb,qBAAqB,iBAAiB,EAAE,OAAO,aAAa,YAAY,CAAC,EAAE,CAAC;AAAA,EAC5E,UAAU,CAAC,eAAe,QAAQ;AAAA;AAAA,EAElC,kBAAkB,gBAAgB;AAAA,EAClC,WAAW,EAAE,OAAO,CAAC,oBAAoB,OAAO,GAAG,UAAU,mBAAmB,OAAO;AAAA,EACvF,WAAW;AAAA,EACX,SAAS;AAAA,EACT,KAAK,CAAC;AAAA,EACN,KAAK,CAAC,iBAAiB,IAAI;AAAA;AAAA,EAE3B,UAAU,EAAE,SAAS,MAAM,cAAc,MAAM,YAAY,MAAM,MAAM,MAAM;AAAA,EAC7E,oBAAoB,mBAAmB;AAAA,EACvC,2BAA2B;AAC7B,CAAC;AAGM,MAAM,WAAW,CAAC,UACvB,gBAAgB,EAAE,SAAS,aAAa,UAAU,eAAe,CAAC,GAAG,aAAa,MAAM,KAAK,EAAE,CAAC;",
+  "names": []
+}

package/dist/modules/harnesses/adapters.d.mts

@@ -0,0 +1,7 @@
+import { type AcpAdapterDefinitionIface } from '@finalai/agent-provider';
+import { FinalAcpAdapter } from "./names.mjs";
+export declare const PI_ACP_ADAPTER: AcpAdapterDefinitionIface;
+export declare const NANOCODE_ACP_ADAPTER: AcpAdapterDefinitionIface;
+export declare const CLAUDE_CODE_ACP_ADAPTER: AcpAdapterDefinitionIface;
+export declare const CODEX_ACP_ADAPTER: AcpAdapterDefinitionIface;
+export declare const FINAL_ACP_ADAPTERS: Record<FinalAcpAdapter, AcpAdapterDefinitionIface>;

package/dist/modules/harnesses/adapters.mjs

@@ -0,0 +1,74 @@
+import { defineAcpAdapter } from "@finalai/agent-definition/authoring";
+import { FinalExtension } from "@finalai/agent-provider";
+import { REQUIRED_FINAL_EXTENSIONS } from "../provider/general.mjs";
+import { FinalAcpAdapter, FinalHarnessInterface } from "./names.mjs";
+const PI_ACP_ADAPTER = defineAcpAdapter({
+  title: "Pi ACP adapter",
+  description: "Maps the Pi agent loop (Pi and the Final harness) to ACP v2 on a worker runtime.",
+  adapts: [FinalHarnessInterface.PiAgent],
+  run: { worker: { program: "pi" } },
+  extensions: [...REQUIRED_FINAL_EXTENSIONS]
+});
+const NANOCODE_ACP_ADAPTER = defineAcpAdapter({
+  title: "nanocode ACP adapter",
+  description: "Maps nanocode's Claude and Codex engines to ACP v2 on a worker runtime.",
+  adapts: [FinalHarnessInterface.Nanocode],
+  run: { worker: { program: "nanocode" } },
+  extensions: [...REQUIRED_FINAL_EXTENSIONS]
+});
+const permissionArgs = {
+  when: "configuration.permissionMode",
+  args: ["--permission-mode", "{{configuration.permissionMode}}"]
+};
+const CLAUDE_CODE_ACP_ADAPTER = defineAcpAdapter({
+  title: "Claude Code ACP adapter",
+  description: "Runs Claude Code through the Claude Agent SDK and speaks ACP v2 on stdio.",
+  adapts: [FinalHarnessInterface.ClaudeAgentSdk],
+  run: {
+    process: {
+      command: "npx",
+      args: [
+        "-y",
+        "@finalai/acp-adapter-claude-code",
+        permissionArgs,
+        "--",
+        "{{harness.command}}",
+        { spread: "harness.args" }
+      ]
+    }
+  },
+  extensions: [...REQUIRED_FINAL_EXTENSIONS, FinalExtension.Fork]
+});
+const CODEX_ACP_ADAPTER = defineAcpAdapter({
+  title: "Codex ACP adapter",
+  description: "Runs the Codex app-server and speaks ACP v2 on stdio.",
+  adapts: [FinalHarnessInterface.CodexAppServer],
+  run: {
+    process: {
+      command: "npx",
+      args: [
+        "-y",
+        "@finalai/acp-adapter-codex",
+        permissionArgs,
+        "--",
+        "{{harness.command}}",
+        { spread: "harness.args" }
+      ]
+    }
+  },
+  extensions: [...REQUIRED_FINAL_EXTENSIONS]
+});
+const FINAL_ACP_ADAPTERS = {
+  [FinalAcpAdapter.Pi]: PI_ACP_ADAPTER,
+  [FinalAcpAdapter.Nanocode]: NANOCODE_ACP_ADAPTER,
+  [FinalAcpAdapter.ClaudeCode]: CLAUDE_CODE_ACP_ADAPTER,
+  [FinalAcpAdapter.Codex]: CODEX_ACP_ADAPTER
+};
+export {
+  CLAUDE_CODE_ACP_ADAPTER,
+  CODEX_ACP_ADAPTER,
+  FINAL_ACP_ADAPTERS,
+  NANOCODE_ACP_ADAPTER,
+  PI_ACP_ADAPTER
+};
+//# sourceMappingURL=adapters.mjs.map

package/dist/modules/harnesses/adapters.mjs.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../../../../../src/harnesses/adapters.ts"],
+  "sourcesContent": ["import { defineAcpAdapter } from '@finalai/agent-definition/authoring';\nimport { FinalExtension, type AcpAdapterDefinitionIface } from '@finalai/agent-provider';\nimport { REQUIRED_FINAL_EXTENSIONS } from \"../provider/general.mjs\";\nimport { FinalAcpAdapter, FinalHarnessInterface } from \"./names.mjs\";\n\n// Final's ACP adapters. Each implements ACP v2 and Final's ACP extensions and\n// advertises them in `initialize`; the general harness provider refuses an\n// adapter that does not (../provider/general.ts). Fork is optional.\n\n// The worker runtime's engines that map a harness program to ACP v2. The\n// worker program started is the engine; the harness's own program comes in\n// its input (`{ harness: { program }, configuration }`).\nexport const PI_ACP_ADAPTER: AcpAdapterDefinitionIface = defineAcpAdapter({\n  title: 'Pi ACP adapter',\n  description: 'Maps the Pi agent loop (Pi and the Final harness) to ACP v2 on a worker runtime.',\n  adapts: [FinalHarnessInterface.PiAgent],\n  run: { worker: { program: 'pi' } },\n  extensions: [...REQUIRED_FINAL_EXTENSIONS],\n});\n\nexport const NANOCODE_ACP_ADAPTER: AcpAdapterDefinitionIface = defineAcpAdapter({\n  title: 'nanocode ACP adapter',\n  description: \"Maps nanocode's Claude and Codex engines to ACP v2 on a worker runtime.\",\n  adapts: [FinalHarnessInterface.Nanocode],\n  run: { worker: { program: 'nanocode' } },\n  extensions: [...REQUIRED_FINAL_EXTENSIONS],\n});\n\n// The process adapters are published packages. Each takes the harness's\n// command line after `--` and launches it as the program it adapts; the\n// permission level is Final's (`ask`, `review`, `auto`), mapped by the\n// adapter onto the program's own modes.\nconst permissionArgs = {\n  when: 'configuration.permissionMode',\n  args: ['--permission-mode', '{{configuration.permissionMode}}'],\n};\n\nexport const CLAUDE_CODE_ACP_ADAPTER: AcpAdapterDefinitionIface = defineAcpAdapter({\n  title: 'Claude Code ACP adapter',\n  description: 'Runs Claude Code through the Claude Agent SDK and speaks ACP v2 on stdio.',\n  adapts: [FinalHarnessInterface.ClaudeAgentSdk],\n  run: {\n    process: {\n      command: 'npx',\n      args: [\n        '-y',\n        '@finalai/acp-adapter-claude-code',\n        permissionArgs,\n        '--',\n        '{{harness.command}}',\n        { spread: 'harness.args' },\n      ],\n    },\n  },\n  extensions: [...REQUIRED_FINAL_EXTENSIONS, FinalExtension.Fork],\n});\n\nexport const CODEX_ACP_ADAPTER: AcpAdapterDefinitionIface = defineAcpAdapter({\n  title: 'Codex ACP adapter',\n  description: 'Runs the Codex app-server and speaks ACP v2 on stdio.',\n  adapts: [FinalHarnessInterface.CodexAppServer],\n  run: {\n    process: {\n      command: 'npx',\n      args: [\n        '-y',\n        '@finalai/acp-adapter-codex',\n        permissionArgs,\n        '--',\n        '{{harness.command}}',\n        { spread: 'harness.args' },\n      ],\n    },\n  },\n  extensions: [...REQUIRED_FINAL_EXTENSIONS],\n});\n\nexport const FINAL_ACP_ADAPTERS: Record<FinalAcpAdapter, AcpAdapterDefinitionIface> = {\n  [FinalAcpAdapter.Pi]: PI_ACP_ADAPTER,\n  [FinalAcpAdapter.Nanocode]: NANOCODE_ACP_ADAPTER,\n  [FinalAcpAdapter.ClaudeCode]: CLAUDE_CODE_ACP_ADAPTER,\n  [FinalAcpAdapter.Codex]: CODEX_ACP_ADAPTER,\n};\n"],
+  "mappings": "AAAA,SAAS,wBAAwB;AACjC,SAAS,sBAAsD;AAC/D,SAAS,iCAAiC;AAC1C,SAAS,iBAAiB,6BAA6B;AAShD,MAAM,iBAA4C,iBAAiB;AAAA,EACxE,OAAO;AAAA,EACP,aAAa;AAAA,EACb,QAAQ,CAAC,sBAAsB,OAAO;AAAA,EACtC,KAAK,EAAE,QAAQ,EAAE,SAAS,KAAK,EAAE;AAAA,EACjC,YAAY,CAAC,GAAG,yBAAyB;AAC3C,CAAC;AAEM,MAAM,uBAAkD,iBAAiB;AAAA,EAC9E,OAAO;AAAA,EACP,aAAa;AAAA,EACb,QAAQ,CAAC,sBAAsB,QAAQ;AAAA,EACvC,KAAK,EAAE,QAAQ,EAAE,SAAS,WAAW,EAAE;AAAA,EACvC,YAAY,CAAC,GAAG,yBAAyB;AAC3C,CAAC;AAMD,MAAM,iBAAiB;AAAA,EACrB,MAAM;AAAA,EACN,MAAM,CAAC,qBAAqB,kCAAkC;AAChE;AAEO,MAAM,0BAAqD,iBAAiB;AAAA,EACjF,OAAO;AAAA,EACP,aAAa;AAAA,EACb,QAAQ,CAAC,sBAAsB,cAAc;AAAA,EAC7C,KAAK;AAAA,IACH,SAAS;AAAA,MACP,SAAS;AAAA,MACT,MAAM;AAAA,QACJ;AAAA,QACA;AAAA,QACA;AAAA,QACA;AAAA,QACA;AAAA,QACA,EAAE,QAAQ,eAAe;AAAA,MAC3B;AAAA,IACF;AAAA,EACF;AAAA,EACA,YAAY,CAAC,GAAG,2BAA2B,eAAe,IAAI;AAChE,CAAC;AAEM,MAAM,oBAA+C,iBAAiB;AAAA,EAC3E,OAAO;AAAA,EACP,aAAa;AAAA,EACb,QAAQ,CAAC,sBAAsB,cAAc;AAAA,EAC7C,KAAK;AAAA,IACH,SAAS;AAAA,MACP,SAAS;AAAA,MACT,MAAM;AAAA,QACJ;AAAA,QACA;AAAA,QACA;AAAA,QACA;AAAA,QACA;AAAA,QACA,EAAE,QAAQ,eAAe;AAAA,MAC3B;AAAA,IACF;AAAA,EACF;AAAA,EACA,YAAY,CAAC,GAAG,yBAAyB;AAC3C,CAAC;AAEM,MAAM,qBAAyE;AAAA,EACpF,CAAC,gBAAgB,EAAE,GAAG;AAAA,EACtB,CAAC,gBAAgB,QAAQ,GAAG;AAAA,EAC5B,CAAC,gBAAgB,UAAU,GAAG;AAAA,EAC9B,CAAC,gBAAgB,KAAK,GAAG;AAC3B;",
+  "names": []
+}

package/dist/modules/harnesses/claude-code.d.mts

@@ -0,0 +1,14 @@
+import { type HarnessDefinitionIface, type HarnessEnvironmentIface, type HarnessSettingsIface } from '@finalai/agent-provider';
+import { type InferenceInput, type PermissionInput } from "./config-fields.mjs";
+export declare const CLAUDE_CODE_NATIVE_TOOLS: {
+    files: string[];
+    shell: string[];
+};
+export declare const CLAUDE_CODE_HARNESS: HarnessDefinitionIface;
+export interface ClaudeCodeInputIface {
+    model?: string;
+    inference?: InferenceInput;
+    permissionMode?: PermissionInput;
+    environment?: HarnessEnvironmentIface;
+}
+export declare const claudeCode: ({ environment, ...configuration }?: ClaudeCodeInputIface) => HarnessSettingsIface;

package/dist/modules/harnesses/claude-code.mjs

@@ -0,0 +1,79 @@
+import { defineHarness } from "@finalai/agent-definition/authoring";
+import {
+  CredentialDelivery,
+  HarnessFeature,
+  InferenceSourceKind,
+  McpTransportKind,
+  PermissionLevel,
+  PromptWhileRunning,
+  SandboxWire
+} from "@finalai/agent-provider";
+import {
+  configObjectJson,
+  harnessSettings,
+  inferenceJson,
+  permissionModeJson
+} from "./config-fields.mjs";
+import { ModelVendor } from "./model-reference.mjs";
+import { FinalAcpAdapter, FinalHarness, FinalHarnessInterface } from "./names.mjs";
+const CLAUDE_CODE_NATIVE_TOOLS = {
+  files: ["Read", "Write", "Edit", "Glob", "Grep", "NotebookEdit"],
+  shell: ["Bash", "BashOutput", "KillShell"]
+};
+const CLAUDE_CODE_HARNESS = defineHarness({
+  title: "Claude Code",
+  description: "Claude Code, run as a process on the machine it works on.",
+  configurationSchema: configObjectJson({
+    title: "Claude Code",
+    properties: {
+      model: { $ref: "final://schemas/model-picker", type: "string", minLength: 1 },
+      inference: inferenceJson(),
+      permissionMode: permissionModeJson()
+    }
+  }),
+  // Claude Code takes no skills, and its allow-lists cannot carry an agent's
+  // per-tool approvals.
+  features: [HarnessFeature.McpTools, HarnessFeature.SystemInstructions],
+  lowestPermission: PermissionLevel.Ask,
+  inference: {
+    vendors: [ModelVendor.Anthropic],
+    kinds: [
+      InferenceSourceKind.Harness,
+      InferenceSourceKind.Subscription,
+      InferenceSourceKind.ApiKey,
+      InferenceSourceKind.Final
+    ],
+    delivery: CredentialDelivery.AtOpen
+  },
+  native: {
+    files: { tools: CLAUDE_CODE_NATIVE_TOOLS.files },
+    shell: { tools: CLAUDE_CODE_NATIVE_TOOLS.shell }
+  },
+  interface: FinalHarnessInterface.ClaudeAgentSdk,
+  adapter: FinalAcpAdapter.ClaudeCode,
+  run: {
+    process: {
+      command: "claude",
+      args: [{ when: "configuration.model", args: ["--model", "{{configuration.model}}"] }]
+    }
+  },
+  // The adapter proxies every MCP server it is handed (acp ones over the ACP connection)
+  // and reports full tool results.
+  mcp: [McpTransportKind.Acp, McpTransportKind.Http, McpTransportKind.Stdio],
+  consumes: [SandboxWire.Mcp],
+  supports: { observe: true, resumeReplay: true, fork: true, authorMeta: true },
+  // The adapter pushes it into the running query; Claude Code takes it at its next step; one idle ends both.
+  promptWhileRunning: PromptWhileRunning.Inject,
+  // Its stdio belongs to the session service's connection to the sandbox.
+  sessionSurvivesDisconnect: false
+});
+const claudeCode = ({
+  environment,
+  ...configuration
+} = {}) => harnessSettings({ harness: FinalHarness.ClaudeCode, configuration, environment });
+export {
+  CLAUDE_CODE_HARNESS,
+  CLAUDE_CODE_NATIVE_TOOLS,
+  claudeCode
+};
+//# sourceMappingURL=claude-code.mjs.map

package/dist/modules/harnesses/claude-code.mjs.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../../../../../src/harnesses/claude-code.ts"],
+  "sourcesContent": ["import { defineHarness } from '@finalai/agent-definition/authoring';\nimport {\n  CredentialDelivery,\n  HarnessFeature,\n  InferenceSourceKind,\n  McpTransportKind,\n  PermissionLevel,\n  PromptWhileRunning,\n  SandboxWire,\n  type HarnessDefinitionIface,\n  type HarnessEnvironmentIface,\n  type HarnessSettingsIface,\n} from '@finalai/agent-provider';\nimport {\n  configObjectJson,\n  harnessSettings,\n  inferenceJson,\n  permissionModeJson,\n  type InferenceInput,\n  type PermissionInput,\n} from \"./config-fields.mjs\";\nimport { ModelVendor } from \"./model-reference.mjs\";\nimport { FinalAcpAdapter, FinalHarness, FinalHarnessInterface } from \"./names.mjs\";\n\n// Claude Code as a process on a machine (a computer, a device, your own host),\n// behind Final's ACP adapter on the Claude Agent SDK. Its own file and shell\n// tools work on the machine it runs on, which is therefore the sandbox\n// provided for `files` and `shell`; provided screens reach it as the sandbox\n// MCP projection.\n\nexport const CLAUDE_CODE_NATIVE_TOOLS = {\n  files: ['Read', 'Write', 'Edit', 'Glob', 'Grep', 'NotebookEdit'],\n  shell: ['Bash', 'BashOutput', 'KillShell'],\n};\n\nexport const CLAUDE_CODE_HARNESS: HarnessDefinitionIface = defineHarness({\n  title: 'Claude Code',\n  description: 'Claude Code, run as a process on the machine it works on.',\n  configurationSchema: configObjectJson({\n    title: 'Claude Code',\n    properties: {\n      model: { $ref: 'final://schemas/model-picker', type: 'string', minLength: 1 },\n      inference: inferenceJson(),\n      permissionMode: permissionModeJson(),\n    },\n  }),\n  // Claude Code takes no skills, and its allow-lists cannot carry an agent's\n  // per-tool approvals.\n  features: [HarnessFeature.McpTools, HarnessFeature.SystemInstructions],\n  lowestPermission: PermissionLevel.Ask,\n  inference: {\n    vendors: [ModelVendor.Anthropic],\n    kinds: [\n      InferenceSourceKind.Harness,\n      InferenceSourceKind.Subscription,\n      InferenceSourceKind.ApiKey,\n      InferenceSourceKind.Final,\n    ],\n    delivery: CredentialDelivery.AtOpen,\n  },\n  native: {\n    files: { tools: CLAUDE_CODE_NATIVE_TOOLS.files },\n    shell: { tools: CLAUDE_CODE_NATIVE_TOOLS.shell },\n  },\n  interface: FinalHarnessInterface.ClaudeAgentSdk,\n  adapter: FinalAcpAdapter.ClaudeCode,\n  run: {\n    process: {\n      command: 'claude',\n      args: [{ when: 'configuration.model', args: ['--model', '{{configuration.model}}'] }],\n    },\n  },\n  // The adapter proxies every MCP server it is handed (acp ones over the ACP connection)\n  // and reports full tool results.\n  mcp: [McpTransportKind.Acp, McpTransportKind.Http, McpTransportKind.Stdio],\n  consumes: [SandboxWire.Mcp],\n  supports: { observe: true, resumeReplay: true, fork: true, authorMeta: true },\n  // The adapter pushes it into the running query; Claude Code takes it at its next step; one idle ends both.\n  promptWhileRunning: PromptWhileRunning.Inject,\n  // Its stdio belongs to the session service's connection to the sandbox.\n  sessionSurvivesDisconnect: false,\n});\n\nexport interface ClaudeCodeInputIface {\n  model?: string;\n  // Absent: only the CLI's own login on the machine.\n  inference?: InferenceInput;\n  permissionMode?: PermissionInput;\n  // The sandbox it runs in (absent: the one provided for `shell`), or an ACP\n  // endpoint already running it: `atUrl({ url, hop })`.\n  environment?: HarnessEnvironmentIface;\n}\n\nexport const claudeCode = ({\n  environment,\n  ...configuration\n}: ClaudeCodeInputIface = {}): HarnessSettingsIface =>\n  harnessSettings({ harness: FinalHarness.ClaudeCode, configuration, environment });\n"],
+  "mappings": "AAAA,SAAS,qBAAqB;AAC9B;AAAA,EACE;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,OAIK;AACP;AAAA,EACE;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,OAGK;AACP,SAAS,mBAAmB;AAC5B,SAAS,iBAAiB,cAAc,6BAA6B;AAQ9D,MAAM,2BAA2B;AAAA,EACtC,OAAO,CAAC,QAAQ,SAAS,QAAQ,QAAQ,QAAQ,cAAc;AAAA,EAC/D,OAAO,CAAC,QAAQ,cAAc,WAAW;AAC3C;AAEO,MAAM,sBAA8C,cAAc;AAAA,EACvE,OAAO;AAAA,EACP,aAAa;AAAA,EACb,qBAAqB,iBAAiB;AAAA,IACpC,OAAO;AAAA,IACP,YAAY;AAAA,MACV,OAAO,EAAE,MAAM,gCAAgC,MAAM,UAAU,WAAW,EAAE;AAAA,MAC5E,WAAW,cAAc;AAAA,MACzB,gBAAgB,mBAAmB;AAAA,IACrC;AAAA,EACF,CAAC;AAAA;AAAA;AAAA,EAGD,UAAU,CAAC,eAAe,UAAU,eAAe,kBAAkB;AAAA,EACrE,kBAAkB,gBAAgB;AAAA,EAClC,WAAW;AAAA,IACT,SAAS,CAAC,YAAY,SAAS;AAAA,IAC/B,OAAO;AAAA,MACL,oBAAoB;AAAA,MACpB,oBAAoB;AAAA,MACpB,oBAAoB;AAAA,MACpB,oBAAoB;AAAA,IACtB;AAAA,IACA,UAAU,mBAAmB;AAAA,EAC/B;AAAA,EACA,QAAQ;AAAA,IACN,OAAO,EAAE,OAAO,yBAAyB,MAAM;AAAA,IAC/C,OAAO,EAAE,OAAO,yBAAyB,MAAM;AAAA,EACjD;AAAA,EACA,WAAW,sBAAsB;AAAA,EACjC,SAAS,gBAAgB;AAAA,EACzB,KAAK;AAAA,IACH,SAAS;AAAA,MACP,SAAS;AAAA,MACT,MAAM,CAAC,EAAE,MAAM,uBAAuB,MAAM,CAAC,WAAW,yBAAyB,EAAE,CAAC;AAAA,IACtF;AAAA,EACF;AAAA;AAAA;AAAA,EAGA,KAAK,CAAC,iBAAiB,KAAK,iBAAiB,MAAM,iBAAiB,KAAK;AAAA,EACzE,UAAU,CAAC,YAAY,GAAG;AAAA,EAC1B,UAAU,EAAE,SAAS,MAAM,cAAc,MAAM,MAAM,MAAM,YAAY,KAAK;AAAA;AAAA,EAE5E,oBAAoB,mBAAmB;AAAA;AAAA,EAEvC,2BAA2B;AAC7B,CAAC;AAYM,MAAM,aAAa,CAAC;AAAA,EACzB;AAAA,EACA,GAAG;AACL,IAA0B,CAAC,MACzB,gBAAgB,EAAE,SAAS,aAAa,YAAY,eAAe,YAAY,CAAC;",
+  "names": []
+}

package/dist/modules/harnesses/codex.d.mts

@@ -0,0 +1,12 @@
+import { type HarnessDefinitionIface, type HarnessEnvironmentIface, type HarnessSettingsIface } from '@finalai/agent-provider';
+import { ReasoningLevel, type InferenceInput, type PermissionInput } from "./config-fields.mjs";
+export declare const CODEX_APP_SERVER_REASONING_LEVELS: readonly [ReasoningLevel.Minimal, ReasoningLevel.Low, ReasoningLevel.Medium, ReasoningLevel.High];
+export declare const CODEX_HARNESS: HarnessDefinitionIface;
+export interface CodexInputIface {
+    model?: string;
+    reasoning?: (typeof CODEX_APP_SERVER_REASONING_LEVELS)[number] | `${(typeof CODEX_APP_SERVER_REASONING_LEVELS)[number]}`;
+    inference?: InferenceInput;
+    permissionMode?: PermissionInput;
+    environment?: HarnessEnvironmentIface;
+}
+export declare const codex: ({ environment, ...configuration }?: CodexInputIface) => HarnessSettingsIface;