@finalai/agents 0.10.0 → 0.12.0

package/examples/release-scout/README.md

@@ -1,13 +1,21 @@
-# Release Scout client
+# Release Scout
 
-`client.ts` exports separate operations so you choose which account mutations to run. Install `@finalai/agents` in a Node 26 project and import `connect`, `directSession`, `directConversation`, `groupConversation`, or `publish`. Create and publish Release Scout first; groups also require Deploy Bot. User participant IDs come from `client.people.all()`.
+One agent with one tool of each kind, and three ways to start it.
 
-Every function accepts an abort signal. Decisions are reported for the caller to inspect: answer a permission with `conversation.respond({ decisionId, optionId })`, choosing an actual option from the decision, or answer an elicitation with its ACP outcome. No example approves a request automatically. Use `conversation.cancel()` to stop every agent in a room; `client.close()` stops local subscriptions and releases owned realtime connections.
+- `agent.ts` defines the agent. `lookup_release_notes` is a serverless tool: its
+  source is part of the agent's data and it runs on Final's runtime.
+  `find_order` is an in-process tool: it uses this app's database (`db.ts`) and
+  runs in the process that created the session.
+- `run.ts` is the smallest caller. It provides a harness and the `issues`
+  integration and leaves `compute` out, so the model's files and shell run in
+  the script's own process. When the script exits the session carries on, and
+  `find_order` and the shell report themselves unavailable.
+- `run-on-a-computer.ts` moves files and shell to a cloud computer with a
+  sandbox setup. Where the tools run does not change.
+- `by-name.ts` fetches the published agent by name. A fetched agent is data
+  only, so its in-process tool cannot run there and the call fails with
+  `requirements_unmet`, naming `find_order`.
 
-Definition publication compiles the repository ref and activates its definition schedules and channels. It is an explicit operation. Use `definitions.compile()` or `definitions.testRevision()` for an unpublished snapshot. `schedules.runNow({ agent: 'release-scout', key: 'daily-digest' })` triggers an existing schedule. `client.acp.connect({ agent: 'release-scout' })` opens a native ACP client connection.
-
-The published package includes this client and the complete authored definition under `examples/release-scout/agent/`. It declares billing in the harness credential chain and includes sandbox setup, instructions, skills, an authored tool, the Linear connection, a schedule, a hook and the GitHub webhook. Supply the declared secrets and provider credentials before publishing it.
-
-Git and `gh` are pre-authenticated in the sandbox.
-
-Conversation deliveries include session and turn ids. The example reconstructs each response with `session.response(turnId)` and waits for its durable completion, so a blank or failed turn cannot leave it waiting for a missed conversation event. Read receipts again with `conversation.deliveries({ messageId })` after a reconnect or for a delivery admitted under the queue policy.
+Publish it with `final-agents publish examples/release-scout/agent.ts --name release-scout`
+(with `FINAL_API_KEY` and `FINAL_PROJECT_ID` set), and print its document with
+`final-agents print examples/release-scout/agent.ts`.

package/examples/release-scout/agent.ts

@@ -0,0 +1,41 @@
+import { defineAgent, defineInProcessTool, defineServerlessTool, markdown } from '@finalai/agents';
+import { FinalHarness } from '@finalai/agents/harnesses';
+import * as z from 'zod';
+import { orders } from './db.js';
+
+// Self-contained, so it runs on Final's runtime: it keeps working when this app is not running.
+const lookupReleaseNotes = defineServerlessTool({
+  description: 'Fetch the published notes for a release.',
+  inputSchema: z.object({ version: z.string() }),
+  execute: async ({ version }) => {
+    const response = await fetch(`https://releases.example.com/${version}.md`);
+    return { found: response.ok, notes: response.ok ? await response.text() : null };
+  },
+});
+
+// Uses this app's database connection, so it runs in the process that created the session.
+const findOrder = defineInProcessTool({
+  description: 'Look up an order by id.',
+  inputSchema: z.object({ id: z.string() }),
+  execute: async ({ id }) => orders.find(id),
+});
+
+export const agent = defineAgent({
+  name: 'Release Scout',
+  instructions: markdown('./instructions.md', { from: import.meta.url }),
+  // The key is the tool's name.
+  tools: { lookup_release_notes: lookupReleaseNotes, find_order: findOrder },
+  require: {
+    harness: {
+      // A limit: binding.
+      permissionMode: 'ask',
+      // A hint: binds nobody.
+      recommended: { harness: FinalHarness.Pi, model: 'gpt-6.1-sol', reasoning: 'high' },
+    },
+    // Keyed by capability: what the model drives.
+    compute: { files: 'write', shell: 'execute' },
+    integrations: {
+      issues: { description: 'Issue tracker', tools: { deny: ['delete_*'] } },
+    },
+  },
+});

package/examples/release-scout/by-name.ts

@@ -0,0 +1,43 @@
+import { createClient, isRequirementsUnmetError } from '@finalai/agents/client';
+import {
+  apiKey,
+  finalCredits,
+  serverlessNanocodeClaude,
+  subscription,
+} from '@finalai/agents/harnesses';
+
+// An agent is always an object. When all you have is a name, fetch it: the
+// result is data only. Release Scout's `find_order` is an in-process tool, and
+// this process does not hold its code, so starting it fails and names the tool.
+// An agent meant to be started by callers that only fetch it uses serverless tools.
+
+const key = process.env.FINAL_API_KEY;
+const projectId = process.env.FINAL_PROJECT_ID;
+if (key == null || projectId == null) throw new Error('Set FINAL_API_KEY and FINAL_PROJECT_ID');
+
+// A server never lends its own process to an agent: an omitted capability fails instead.
+const client = createClient({ auth: { apiKey: key }, localCompute: false });
+const project = client.project({ id: projectId });
+
+const agent = await project.agents.get({ name: 'release-scout' });
+const linear = await project.integrations.get({ name: 'linear' });
+const box = await project.sandboxes.get(process.env.SANDBOX_ID ?? 'asbx_missing');
+
+try {
+  await project.sessions.create({
+    agent,
+    provide: {
+      harness: serverlessNanocodeClaude({
+        model: 'claude-opus-5-5',
+        // This person's subscription, else the project's key, else Final's metered inference.
+        inference: [subscription(), apiKey('ANTHROPIC_API_KEY'), finalCredits()],
+      }),
+      compute: { files: box, shell: box },
+      integrations: { issues: linear },
+    },
+    message: 'Did 2.4.1 ship?',
+  });
+} catch (cause) {
+  if (!isRequirementsUnmetError(cause)) throw cause;
+  for (const item of cause.requirements) console.log(`${item.kind} ${item.name}: ${item.problem}`);
+}

package/examples/release-scout/db.ts

@@ -0,0 +1,6 @@
+// Stands in for the application's own database connection.
+const rows = new Map([['ord_1', { id: 'ord_1', version: '2.4.1', status: 'shipped' }]]);
+
+export const orders = {
+  find: async (id: string) => rows.get(id) ?? null,
+};

package/examples/release-scout/instructions.md

@@ -0,0 +1,5 @@
+You answer questions about releases.
+
+Read a release's published notes before saying whether a change shipped, and
+link the issue that tracked it when there is one. Check an order with
+`find_order` when someone asks whether their order has the fix.

package/examples/release-scout/run-on-a-computer.ts

@@ -0,0 +1,49 @@
+import { createClient } from '@finalai/agents/client';
+import { finalCredits, serverlessPi } from '@finalai/agents/harnesses';
+import { computer, defineSandboxSetup } from '@finalai/agents/sandboxes';
+import { agent } from './agent.js';
+
+// The same agent with the model's files and shell on a cloud computer. Where its
+// tools run does not change.
+
+const apiKey = process.env.FINAL_API_KEY;
+const projectId = process.env.FINAL_PROJECT_ID;
+if (apiKey == null || projectId == null) throw new Error('Set FINAL_API_KEY and FINAL_PROJECT_ID');
+
+const client = createClient({ auth: { apiKey } });
+const project = client.project({ id: projectId });
+
+// Provider-neutral: what should be on the machine.
+const setup = defineSandboxSetup({
+  repositories: [{ alias: 'app', repository: 'acme/app', ref: 'main' }],
+  variables: { NPM_TOKEN: { secret: 'NPM_TOKEN' } },
+  steps: [{ cwd: 'app', run: 'pnpm install' }],
+});
+const box = await project.sandboxes.create(
+  computer({ image: 'docker.io/library/node:26-bookworm' }),
+  {
+    setup,
+  },
+);
+const linear = await project.integrations.get({ name: 'linear' });
+// Pi itself runs as a worker program, in a Workers sandbox the session owns (created for you).
+
+try {
+  const { response } = await project.sessions.create({
+    agent,
+    provide: {
+      harness: serverlessPi({
+        model: 'gpt-6.1-sol',
+        reasoning: 'high',
+        inference: finalCredits(),
+      }),
+      // Must be the same sandbox.
+      compute: { files: box, shell: box },
+      integrations: { issues: linear },
+    },
+    message: 'Did 2.4.1 ship?',
+  });
+  console.log(await response?.text());
+} finally {
+  await box.delete();
+}

package/examples/release-scout/run.ts

@@ -0,0 +1,38 @@
+import { createClient } from '@finalai/agents/client';
+import { finalCredits, serverlessPi } from '@finalai/agents/harnesses';
+import { oauth } from '@finalai/agents/integrations';
+import { agent } from './agent.js';
+
+// The smallest caller. Nothing is provided under `compute`, so the model's files
+// and shell run in this script's process, on this machine. `find_order` runs
+// here too; `lookup_release_notes` runs on Final's runtime from the agent's data.
+
+const apiKey = process.env.FINAL_API_KEY;
+const projectId = process.env.FINAL_PROJECT_ID;
+if (apiKey == null || projectId == null) throw new Error('Set FINAL_API_KEY and FINAL_PROJECT_ID');
+
+const client = createClient({ auth: { apiKey } });
+// Everything below belongs to this project.
+const project = client.project({ id: projectId });
+
+const linear = await project.integrations.create({
+  name: 'linear',
+  mcp: { url: 'https://mcp.linear.app/mcp' },
+  auth: oauth({ credential: 'shared' }),
+});
+
+// Pi runs as a worker program, in a Workers sandbox the session owns (created for you).
+const { response } = await project.sessions.create({
+  agent,
+  provide: {
+    harness: serverlessPi({
+      model: 'gpt-6.1-sol',
+      reasoning: 'high',
+      inference: finalCredits(),
+    }),
+    integrations: { issues: linear },
+  },
+  message: 'Did 2.4.1 ship?',
+});
+// Leaving out `harness` or `issues` makes the call fail with `requirements_unmet`, naming what is missing.
+console.log(await response?.text());

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@finalai/agents",
-  "version": "0.10.0",
+  "version": "0.12.0",
   "private": false,
   "description": "Agent authoring, client APIs, and CLI.",
   "license": "Apache-2.0",
@@ -13,8 +13,7 @@
     "README.md",
     "LICENSE",
     "NOTICE",
-    "HOSTING.md",
-    "THIRD_PARTY_NOTICES.md"
+    "HOSTING.md"
   ],
   "type": "module",
   "sideEffects": [
@@ -24,8 +23,8 @@
   "exports": {
     ".": {
       "types": "./dist/modules/index.d.mts",
-      "node": "./dist/modules/index.mjs",
-      "default": "./dist/modules/index.browser.mjs"
+      "import": "./dist/modules/index.mjs",
+      "default": "./dist/modules/index.mjs"
     },
     "./client": {
       "types": "./dist/modules/agent-client/index.d.mts",
@@ -37,10 +36,20 @@
       "import": "./dist/modules/agent-client/acp.mjs",
       "default": "./dist/modules/agent-client/acp.mjs"
     },
-    "./instructions": {
-      "types": "./dist/modules/authoring/instructions.d.mts",
-      "import": "./dist/modules/authoring/instructions.mjs",
-      "default": "./dist/modules/authoring/instructions.mjs"
+    "./client/http": {
+      "types": "./dist/modules/agent-client/http.d.mts",
+      "import": "./dist/modules/agent-client/http.mjs",
+      "default": "./dist/modules/agent-client/http.mjs"
+    },
+    "./client/local-host": {
+      "types": "./dist/modules/agent-client/local-host-protocol.d.mts",
+      "import": "./dist/modules/agent-client/local-host-protocol.mjs",
+      "default": "./dist/modules/agent-client/local-host-protocol.mjs"
+    },
+    "./client/sandbox-uri": {
+      "types": "./dist/modules/agent-client/sandbox-uri.d.mts",
+      "import": "./dist/modules/agent-client/sandbox-uri.mjs",
+      "default": "./dist/modules/agent-client/sandbox-uri.mjs"
     },
     "./approval": {
       "types": "./dist/modules/authoring/approval.d.mts",
@@ -62,6 +71,11 @@
       "import": "./dist/modules/authoring/channels.mjs",
       "default": "./dist/modules/authoring/channels.mjs"
     },
+    "./channels/final": {
+      "types": "./dist/modules/authoring/final-channel.d.mts",
+      "import": "./dist/modules/authoring/final-channel.mjs",
+      "default": "./dist/modules/authoring/final-channel.mjs"
+    },
     "./harnesses": {
       "types": "./dist/modules/harnesses.d.mts",
       "import": "./dist/modules/harnesses.mjs",
@@ -72,21 +86,20 @@
       "import": "./dist/modules/sandboxes.mjs",
       "default": "./dist/modules/sandboxes.mjs"
     },
-    "./package.json": "./package.json",
-    "./channels/final": {
-      "types": "./dist/modules/authoring/final-channel.d.mts",
-      "import": "./dist/modules/authoring/final-channel.mjs",
-      "default": "./dist/modules/authoring/final-channel.mjs"
+    "./integrations": {
+      "types": "./dist/modules/integrations.d.mts",
+      "import": "./dist/modules/integrations.mjs",
+      "default": "./dist/modules/integrations.mjs"
     },
-    "./client/http": {
-      "types": "./dist/modules/agent-client/http.d.mts",
-      "import": "./dist/modules/agent-client/http.mjs",
-      "default": "./dist/modules/agent-client/http.mjs"
+    "./verify": {
+      "types": "./dist/modules/verify.d.mts",
+      "import": "./dist/modules/verify.mjs",
+      "default": "./dist/modules/verify.mjs"
     },
-    "./client/sandbox-uri": {
-      "types": "./dist/modules/agent-client/sandbox-uri.d.mts",
-      "import": "./dist/modules/agent-client/sandbox-uri.mjs",
-      "default": "./dist/modules/agent-client/sandbox-uri.mjs"
+    "./webhooks": {
+      "types": "./dist/modules/webhooks.d.mts",
+      "import": "./dist/modules/webhooks.mjs",
+      "default": "./dist/modules/webhooks.mjs"
     },
     "./testing": {
       "types": "./dist/modules/agent-client/test-fakes.d.mts",
@@ -97,7 +110,8 @@
       "types": "./dist/modules/public.d.mts",
       "import": "./dist/modules/public.mjs",
       "default": "./dist/modules/public.mjs"
-    }
+    },
+    "./package.json": "./package.json"
   },
   "publishConfig": {
     "access": "public",
@@ -105,11 +119,11 @@
   },
   "dependencies": {
     "@agentclientprotocol/sdk": "1.8.0",
-    "@finalai/agent-definition": "0.7.0",
-    "@finalai/agent-protocol": "0.8.0",
-    "@finalai/agent-provider": "0.8.0",
-    "@finalai/final-agent-provider": "0.9.0",
-    "@finalai/websockets": "0.1.7",
+    "@finalai/agent-definition": "0.9.0",
+    "@finalai/agent-protocol": "0.9.0",
+    "@finalai/agent-provider": "0.10.0",
+    "@finalai/final-agent-provider": "0.11.0",
+    "@finalai/websockets": "0.1.8",
     "ws": "^8.21.3",
     "zod": "4.6.6"
   },

package/dist/modules/agent-client/build.d.mts

@@ -1,110 +0,0 @@
-import { type CommitDefinitionRequestIface, type CommitResultIface, type CompatibilityReportIface, type CompileResultIface, type ComputerSetupGuideDetailIface, type ComputerSetupGuideIface, type ComputerSetupGuideVersionIface, type CreateDefinitionRequestIface, type CredentialPolicyPreviewIface, type DefinitionChannelIface, type DefinitionCloneUrlIface, type DefinitionFilesIface, type DefinitionIface, type PreviewCredentialPolicyRequestIface, type ProviderEntryIface, type PublishComputerSetupGuideRequestIface, type PublishResultIface, type RevisionDiffIface, type RevisionIface, type ScheduleIface, type ScheduleRunResultIface, type UpdateScheduleRequestIface } from '@finalai/agent-protocol/agent-platform';
-import { type ClientContextIface, type SignalOptionsIface } from "./context.mjs";
-export interface DefinitionRefIface extends SignalOptionsIface {
-    /** Definition id or slug. */
-    definition: string;
-}
-export interface DefinitionsApiIface {
-    /** Compiles a draft into an immutable test snapshot without publishing or activating schedules/channels. */
-    testRevision: (args: DefinitionRefIface & {
-        ref: string;
-    }) => Promise<RevisionIface>;
-    previewCredentialPolicy: (args: DefinitionRefIface & PreviewCredentialPolicyRequestIface) => Promise<CredentialPolicyPreviewIface>;
-    /**
-     * With `projectId`, its definitions and those inherited from its ancestors. Without it,
-     * everything the caller can access (an API key: its parent project and every project it is
-     * granted; a person: every project they can read).
-     */
-    list: (options?: SignalOptionsIface & {
-        cursor?: string;
-        limit?: number;
-        projectId?: string;
-    }) => Promise<{
-        definitions: DefinitionIface[];
-        nextCursor: string | null;
-    }>;
-    /**
-     * Creates the definition in `projectId` (editors of that project); omitted, the API key's parent
-     * project (a signed-in person's: My Work).
-     */
-    create: (args: CreateDefinitionRequestIface & SignalOptionsIface) => Promise<DefinitionIface>;
-    get: (args: DefinitionRefIface) => Promise<DefinitionIface>;
-    /** Compiles the directory at `ref` server-side without publishing. */
-    compile: (args: DefinitionRefIface & {
-        ref: string;
-        harness?: string;
-    }) => Promise<CompileResultIface>;
-    commit: (args: DefinitionRefIface & CommitDefinitionRequestIface) => Promise<CommitResultIface>;
-    /** Publishes an immutable revision; activate:false leaves the live agent unchanged. */
-    publish: (args: DefinitionRefIface & {
-        ref: string;
-        note?: string;
-        activate?: boolean;
-    }) => Promise<PublishResultIface>;
-    /** The agent directory's files at `ref` (default branch when omitted). */
-    files: (args: DefinitionRefIface & {
-        ref?: string;
-    }) => Promise<DefinitionFilesIface>;
-    revisions: (args: DefinitionRefIface & {
-        cursor?: string;
-    }) => Promise<{
-        revisions: RevisionIface[];
-        nextCursor: string | null;
-    }>;
-    /**
-     * What changed in the compiled manifest between two revisions (revision ids
-     * or numbers); `to` defaults to the current revision.
-     */
-    revisionDiff: (args: DefinitionRefIface & {
-        from: string | number;
-        to?: string | number;
-    }) => Promise<RevisionDiffIface>;
-    compatibility: (args: DefinitionRefIface & {
-        harness: string;
-        ref?: string;
-    }) => Promise<CompatibilityReportIface>;
-    /** The agent's live channel bindings and their public route URLs. */
-    channels: (args: DefinitionRefIface) => Promise<DefinitionChannelIface[]>;
-    /**
-     * Archives the definition: it leaves listings, its schedules and channel
-     * bindings stop, and new sessions are refused. Its repository is kept.
-     */
-    archive: (args: DefinitionRefIface) => Promise<DefinitionIface>;
-    /**
-     * A short-lived, read-only git remote for a Final-hosted repository, for
-     * `git clone` (editors of the definition's project).
-     */
-    cloneUrl: (args: DefinitionRefIface) => Promise<DefinitionCloneUrlIface>;
-}
-export interface ProvidersApiIface {
-    list: (options?: SignalOptionsIface) => Promise<ProviderEntryIface[]>;
-}
-export interface ComputerSetupGuidesApiIface {
-    list: (options?: SignalOptionsIface) => Promise<ComputerSetupGuideIface[]>;
-    /** Guide by slug or id, with its versions. */
-    get: (ref: string, options?: SignalOptionsIface) => Promise<ComputerSetupGuideDetailIface>;
-    /** Publishes a new version (creating the guide on first publish). */
-    publish: (args: PublishComputerSetupGuideRequestIface & SignalOptionsIface) => Promise<{
-        guide: ComputerSetupGuideIface;
-        version: ComputerSetupGuideVersionIface;
-    }>;
-}
-export type ScheduleRef = {
-    scheduleId: string;
-} | {
-    agent: string;
-    key: string;
-};
-export interface SchedulesApiIface {
-    list: (options?: SignalOptionsIface & {
-        agent?: string;
-    }) => Promise<ScheduleIface[]>;
-    runNow: (args: ScheduleRef & SignalOptionsIface) => Promise<ScheduleRunResultIface>;
-    update: (args: {
-        scheduleId: string;
-    } & UpdateScheduleRequestIface & SignalOptionsIface) => Promise<ScheduleIface>;
-}
-export declare const createDefinitionsApi: ({ http }: ClientContextIface) => DefinitionsApiIface;
-export declare const createProvidersApi: ({ http }: ClientContextIface) => ProvidersApiIface;
-export declare const createComputerSetupGuidesApi: ({ http, }: ClientContextIface) => ComputerSetupGuidesApiIface;
-export declare const createSchedulesApi: ({ http }: ClientContextIface) => SchedulesApiIface;