@finalai/agents 0.8.0

package/examples/custom-harness/agent.ts

@@ -0,0 +1,154 @@
+import {
+  credentials,
+  defineAgent,
+  defineHarness,
+  type AuthoredHarnessEndpointIface,
+} from '@finalai/agents';
+import { type JsonValue, type SecretReaderIface } from '@finalai/agent-provider';
+import * as z from 'zod';
+
+const FLEET_ORIGIN = 'https://fleet.acme.dev';
+const FLEET_SECRET = 'acme-fleet-key';
+
+type FleetConfig = {
+  region: string;
+  apiKeySecret: typeof FLEET_SECRET;
+  credentials: JsonValue;
+};
+
+interface FleetRequestArgsIface {
+  secrets: SecretReaderIface;
+  path: string;
+  method: 'GET' | 'POST' | 'DELETE';
+  body?: unknown;
+}
+
+const requestFleet = async (args: FleetRequestArgsIface): Promise<string> => {
+  const token = await args.secrets.get(FLEET_SECRET);
+  if (token == null) throw new Error(`Missing secret ${FLEET_SECRET}`);
+  const response = await fetch(`${FLEET_ORIGIN}${args.path}`, {
+    method: args.method,
+    headers: { authorization: `Bearer ${token}`, 'content-type': 'application/json' },
+    body: args.body == null ? undefined : JSON.stringify(args.body),
+    signal: AbortSignal.timeout(30_000),
+  });
+  const text = await response.text();
+  if (!response.ok) throw new Error(`Fleet request failed (${response.status})`);
+  return text;
+};
+
+const fleetEndpointSchema = z.object({
+  id: z.string().min(1),
+  generation: z.number().int().nonnegative(),
+  wsUrl: z.url().refine((value) => {
+    const url = new URL(value);
+    return url.protocol === 'wss:' && url.host === new URL(FLEET_ORIGIN).host;
+  }),
+  token: z.string().min(1),
+});
+
+const endpointFrom = (text: string): AuthoredHarnessEndpointIface => {
+  const endpoint = fleetEndpointSchema.parse(JSON.parse(text));
+  return {
+    ref: { harnessSessionRef: endpoint.id, generation: endpoint.generation },
+    transport: 'ws',
+    url: endpoint.wsUrl,
+    headers: { authorization: `Bearer ${endpoint.token}` },
+  };
+};
+
+const fleetHealthSchema = z.object({ ok: z.boolean(), detail: z.string().optional() });
+
+export const acmeFleet = defineHarness<FleetConfig>({
+  describe: async () => ({
+    configSchema: {
+      type: 'object',
+      properties: {
+        region: { type: 'string' },
+        apiKeySecret: { const: FLEET_SECRET },
+        credentials: { $ref: 'final://schemas/credential-policy' },
+      },
+      required: ['region', 'apiKeySecret', 'credentials'],
+      additionalProperties: false,
+    },
+    acp: { transports: ['ws'], mcp: ['http'] },
+    inference: { kinds: ['harness-owned'], delivery: 'at-open' },
+    supports: {
+      observe: false,
+      resumeReplay: true,
+      fork: false,
+      authorMeta: false,
+      nativeToolPolicy: false,
+    },
+    promptWhileRunning: 'queue',
+    sessionSurvivesDisconnect: true,
+  }),
+  open: async ({ sessionId, harnessSessionId, config, mcpServers, secrets }) =>
+    endpointFrom(
+      await requestFleet({
+        secrets,
+        path: '/sessions',
+        method: 'POST',
+        body: {
+          sessionId,
+          idempotencyKey: harnessSessionId,
+          region: config.region,
+          program: 'claude-code',
+          mcpServers,
+        },
+      }),
+    ),
+  resume: async ({ ref, lastSeq, mcpServers, secrets }) =>
+    endpointFrom(
+      await requestFleet({
+        secrets,
+        path: `/sessions/${encodeURIComponent(ref.harnessSessionRef)}/resume`,
+        method: 'POST',
+        body: { generation: ref.generation, lastSeq, mcpServers },
+      }),
+    ),
+  park: async ({ ref, secrets }) => {
+    await requestFleet({
+      secrets,
+      path: `/sessions/${encodeURIComponent(ref.harnessSessionRef)}/pause`,
+      method: 'POST',
+      body: { generation: ref.generation },
+    });
+  },
+  close: async ({ ref, secrets, force }) => {
+    await requestFleet({
+      secrets,
+      path: `/sessions/${encodeURIComponent(ref.harnessSessionRef)}`,
+      method: 'DELETE',
+      body: { generation: ref.generation, force },
+    });
+  },
+  health: async ({ ref, secrets }) => {
+    try {
+      return fleetHealthSchema.parse(
+        JSON.parse(
+          await requestFleet({
+            secrets,
+            path: `/sessions/${encodeURIComponent(ref.harnessSessionRef)}/health`,
+            method: 'GET',
+          }),
+        ),
+      );
+    } catch (cause) {
+      return { ok: false, detail: cause instanceof Error ? cause.message : String(cause) };
+    }
+  },
+});
+
+export default defineAgent({
+  name: 'Release Scout',
+  secrets: [FLEET_SECRET],
+  harness: acmeFleet({
+    region: 'eu',
+    apiKeySecret: FLEET_SECRET,
+    credentials: credentials.chain({
+      payer: 'agent-owner',
+      tryInOrder: [credentials.harness()],
+    }),
+  }),
+});

package/examples/custom-sandbox/README.md

@@ -0,0 +1,12 @@
+# Custom sandbox provider
+
+This example uses `@finalai/agents` for authoring and
+`@finalai/agent-provider/sandbox` for the sandbox implementation. Build it with:
+
+```sh
+final-agents build ./examples/custom-sandbox
+```
+
+`sandbox.ts` exports a provider and its named target. `agent.ts` binds file and shell capabilities to that target, with billing explicitly in the harness configuration. The provider exposes file and shell operations through the SDK's streaming handle RPC and MCP adapters.
+
+The in-memory backend is a small, ephemeral reference implementation with a limited command set. Its files last only while the resumed handle is live. A persistent provider implements these same methods over its backend API: `prepare` returns the preparation artifact, `start` returns serializable backend state, and `resume` reconnects to that state. The SDK contract and conformance tools are available at `@finalai/agent-provider`, `@finalai/agent-provider/sandbox`, and `@finalai/agent-provider/conformance`.

package/examples/custom-sandbox/agent.ts

@@ -0,0 +1,14 @@
+import { baseTools, credentials, defineAgent } from '@finalai/agents';
+import { serverlessPi } from '@finalai/agents/harnesses';
+import { scratch } from './sandbox';
+
+export default defineAgent({
+  name: 'Scratch agent',
+  harness: serverlessPi({
+    credentials: credentials.chain({
+      payer: 'organization',
+      tryInOrder: [credentials.platform()],
+    }),
+  }),
+  tools: baseTools({ shell: scratch, files: scratch }),
+});

package/examples/custom-sandbox/sandbox.ts

@@ -0,0 +1,22 @@
+import { defineSandboxProvider } from '@finalai/agents';
+import { createMemorySandbox } from '@finalai/agent-provider/sandbox';
+
+// An ephemeral reference provider. Persistent providers reconnect to their backend in resume.
+const handle = () => ({
+  sandbox: createMemorySandbox({ cwd: '/workspace' }),
+  onSandboxStop: async () => {},
+  onSandboxDelete: async () => {},
+  onRuntimeShutdown: async () => {},
+});
+
+export const scratchProvider = defineSandboxProvider({
+  name: 'scratch',
+  environment: () => ({
+    artifactKey: async () => 'scratch-v1',
+    prepare: async () => ({}),
+    start: async () => ({ handle: handle(), state: {} }),
+    resume: async () => handle(),
+  }),
+});
+
+export const scratch = scratchProvider.environment();

package/examples/release-scout/README.md

@@ -0,0 +1,11 @@
+# Release Scout client
+
+`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()`.
+
+Every function accepts an abort signal. Pending requests are reported for the caller to inspect: answer a permission with `conversation.respond({ pendingId, optionId })`, choosing an actual option from the pending request, 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.
+
+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.
+
+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.

package/examples/release-scout/agent/agent.ts

@@ -0,0 +1,22 @@
+import { baseTools, credentials, defineAgent } from '@finalai/agents';
+import { serverlessPi } from '@finalai/agents/harnesses';
+import { computer } from './sandbox';
+
+export default defineAgent({
+  name: 'Release Scout',
+  description: 'Answers release questions, runs checks, posts the daily digest.',
+  // Read by tools/lookup_release_notes.ts and channels/github.ts; linear-token
+  // comes from connections/linear.ts.
+  secrets: ['github-token', 'github-webhook-secret'],
+  // Off unless declared; each capability is bound to a named sandbox target.
+  tools: baseTools({ shell: computer, files: computer }),
+  harness: serverlessPi({
+    model: 'gpt-6-sol',
+    reasoning: 'medium',
+    credentials: credentials.chain({
+      payer: 'organization',
+      tryInOrder: [credentials.apiKey({ owner: 'organization' }), credentials.platform()],
+    }),
+    permissionMode: 'ask',
+  }),
+});

package/examples/release-scout/agent/channels/github-signature.ts

@@ -0,0 +1,27 @@
+// A helper next to the channel (no default export, so not a channel itself).
+export const verifyGithubSignature = async (
+  request: Request,
+  body: string,
+  secret: string | null,
+): Promise<boolean> => {
+  const signature = request.headers.get('x-hub-signature-256');
+  if (
+    secret == null ||
+    secret.length === 0 ||
+    signature == null ||
+    !/^sha256=[a-f0-9]{64}$/i.test(signature)
+  )
+    return false;
+  const digest = Uint8Array.from(signature.slice(7).match(/.{2}/g) ?? [], (byte) =>
+    Number.parseInt(byte, 16),
+  );
+  const encoder = new TextEncoder();
+  const key = await crypto.subtle.importKey(
+    'raw',
+    encoder.encode(secret),
+    { name: 'HMAC', hash: 'SHA-256' },
+    false,
+    ['verify'],
+  );
+  return crypto.subtle.verify('HMAC', key, digest, encoder.encode(body));
+};

package/examples/release-scout/agent/channels/github.ts

@@ -0,0 +1,38 @@
+import { defineChannel, POST } from '@finalai/agents/channels';
+import * as z from 'zod';
+import { verifyGithubSignature } from './github-signature';
+
+const actionSchema = z.object({ action: z.string() });
+const releaseEventSchema = actionSchema.extend({ release: z.object({ tag_name: z.string() }) });
+
+export default defineChannel({
+  routes: [
+    POST('/webhook', async ({ request, secrets, receive }) => {
+      const body = await request.text();
+      if (
+        !(await verifyGithubSignature(request, body, await secrets.get('github-webhook-secret')))
+      ) {
+        return new Response(null, { status: 401 });
+      }
+      let raw: unknown;
+      try {
+        raw = JSON.parse(body);
+      } catch {
+        return new Response(null, { status: 400 });
+      }
+      const action = actionSchema.safeParse(raw);
+      if (!action.success) return new Response(null, { status: 400 });
+      if (action.data.action !== 'published') return new Response(null, { status: 204 });
+      const parsed = releaseEventSchema.safeParse(raw);
+      if (!parsed.success) return new Response(null, { status: 400 });
+      await receive({
+        target: { kind: 'bound-conversation' },
+        content: [
+          { type: 'text', text: `GitHub release published: ${parsed.data.release.tag_name}` },
+        ],
+      });
+      return new Response(null, { status: 202 });
+    }),
+  ],
+  turnPolicy: 'steer',
+});

package/examples/release-scout/agent/connections/linear.ts

@@ -0,0 +1,9 @@
+import { defineMcpClientConnection } from '@finalai/agents';
+import { always } from '@finalai/agents/approval';
+
+export default defineMcpClientConnection({
+  url: 'https://mcp.linear.app/mcp',
+  // Bearer from the secrets manager; the secret never reaches the harness.
+  auth: { secretKey: 'linear-token', headerName: null },
+  tools: { allow: ['search_issues', 'create_issue'], approval: { create_issue: always() } },
+});

package/examples/release-scout/agent/hooks/audit.ts

@@ -0,0 +1,24 @@
+import { defineHook } from '@finalai/agents/hooks';
+import { toolResultFrom } from '@finalai/agents/tools';
+import lookupReleaseNotes from '../tools/lookup_release_notes';
+
+export default defineHook({
+  events: {
+    async 'turn.ended'(event, ctx) {
+      if (event.data.stopReason === 'error') {
+        await ctx.final.post({ text: 'Something went wrong on my side; I have logged it.' });
+      }
+    },
+    async tool_call_update(event) {
+      const notes = toolResultFrom(event, lookupReleaseNotes);
+      if (notes?.found === false)
+        console.warn('release notes missing', { tag: event.data.rawInput['tag'] });
+    },
+    async '*'(event, ctx) {
+      await fetch('https://audit.internal/events', {
+        method: 'POST',
+        body: JSON.stringify({ id: event.meta.id, session: ctx.session.id, type: event.type }),
+      });
+    },
+  },
+});

package/examples/release-scout/agent/instructions/org-context.ts

@@ -0,0 +1,26 @@
+import { defineDynamic } from '@finalai/agents';
+import { defineInstructions } from '@finalai/agents/instructions';
+import * as z from 'zod';
+
+const calendarSchema = z.object({ nextRelease: z.string(), onCall: z.string() });
+
+export default defineDynamic({
+  // Only needed because the value is unknown until a session starts and Build
+  // still has to show something in this fragment's slot.
+  description: "Adds the organization's release calendar and current on-call.",
+  preview: 'Release calendar: 2.4.1 on 2026-10-10. On-call: @mina.',
+  events: {
+    'session.started': async (_event, ctx) => {
+      const url = new URL('https://ops.internal/calendar');
+      url.searchParams.set('org', ctx.session.organizationId);
+      const res = await fetch(url);
+      const text = await res.text();
+      if (!res.ok) throw new Error(`Release calendar request failed (${res.status})`);
+      const { nextRelease, onCall } = calendarSchema.parse(JSON.parse(text));
+      return defineInstructions({
+        role: 'user',
+        content: `Release calendar: ${nextRelease}. On-call: ${onCall}.`,
+      });
+    },
+  },
+});

package/examples/release-scout/agent/instructions.md

@@ -0,0 +1,2 @@
+You are Release Scout for the Final engineering team. Be brief. Cite release tags.
+When asked to verify something, run it rather than guessing.

package/examples/release-scout/agent/sandbox.ts

@@ -0,0 +1,20 @@
+import { defineSandbox } from '@finalai/agents';
+import { computerSetupGuide } from '@finalai/agents/sandboxes';
+
+// A saved guide by reference. Everything after
+// ref/version overrides the saved version's defaults.
+export const computer = computerSetupGuide({
+  ref: 'release-scout-dev',
+  version: 'latest',
+  repositories: [{ alias: 'app', repository: 'final/app', ref: 'main' }],
+  variables: ['GITHUB_TOKEN', 'NPM_TOKEN'],
+  workspace: 'session',
+  networkPolicy: 'allow-all',
+});
+
+// The default export opens the target named `computer` for each session.
+export default defineSandbox(async ({ session }) => {
+  const sandbox = await computer.open({ access: 'write' });
+  await sandbox.writeTextFile({ path: '.final/session', content: session.id });
+  return sandbox;
+});

package/examples/release-scout/agent/schedules/daily-digest.md

@@ -0,0 +1,7 @@
+---
+cron: '0 9 * * 1-5'
+timezone: America/Los_Angeles
+target: owner-direct
+---
+
+Summarize what shipped in the last 24 hours and anything blocking the next release.

package/examples/release-scout/agent/skills/triage/SKILL.md

@@ -0,0 +1,8 @@
+---
+name: triage
+description: Triage a failing release check into a Linear issue with owner and severity.
+---
+
+1. Reproduce the failure in the computer (`shell`) before filing anything.
+2. Search Linear for an existing issue with `search_issues`.
+3. File with `create_issue` only when nothing matches; include the release tag and the failing command.

package/examples/release-scout/agent/skills/triage/checklist.md

@@ -0,0 +1,3 @@
+- Release tag
+- Failing command and exit code
+- First bad commit, if bisected

package/examples/release-scout/agent/tools/lookup_release_notes.ts

@@ -0,0 +1,24 @@
+import { defineTool } from '@finalai/agents';
+import { never } from '@finalai/agents/approval';
+import * as z from 'zod';
+
+const releaseSchema = z.object({ body: z.string().nullable(), published_at: z.string() });
+
+export default defineTool({
+  description: 'Fetch the release notes for a version tag.',
+  inputSchema: z.object({ tag: z.string().regex(/^\d+\.\d+\.\d+$/) }),
+  approval: never(),
+  async execute({ tag }, ctx) {
+    const token = await ctx.secrets.get('github-token');
+    if (token == null) throw new Error('Missing secret github-token');
+    const res = await fetch(`https://api.github.com/repos/final/app/releases/tags/v${tag}`, {
+      headers: { authorization: `Bearer ${token}` },
+      signal: ctx.abortSignal,
+    });
+    const text = await res.text();
+    if (res.status === 404) return { found: false };
+    if (!res.ok) throw new Error(`Release notes request failed (${res.status})`);
+    const { body, published_at } = releaseSchema.parse(JSON.parse(text));
+    return { found: true, publishedAt: published_at, notes: body ?? '' };
+  },
+});

package/examples/release-scout/client.ts

@@ -0,0 +1,123 @@
+import {
+  createClient,
+  sessionUpdateOf,
+  SystemParticipantKind,
+  textOf,
+  type AgentClientIface,
+} from '@finalai/agents/client';
+import 'zod/compile';
+
+export const directSession = async (client: AgentClientIface, signal?: AbortSignal) => {
+  const { handle, response } = await client.sessions.create({
+    agent: 'release-scout',
+    message: 'Did 2.4.1 ship?',
+    signal,
+  });
+  try {
+    if (response == null) throw new Error('The initial message must create a response');
+    for await (const event of response.stream({ signal })) {
+      const update = sessionUpdateOf(event);
+      if (update?.sessionUpdate === 'agent_message_chunk') process.stdout.write(textOf(update));
+      if (event.pendingId != null) console.log('Awaiting a decision:', event.pendingId);
+    }
+    console.log((await response.result({ signal })).stopReason);
+    await handle.observe('The release was moved to Friday.', { signal });
+    return await handle.manifest({ signal });
+  } finally {
+    // Close cleanup has its own lifetime, even when the prompt was aborted.
+    await handle.close();
+  }
+};
+
+// The source must be idle on a harness with native forks, such as remote Claude Code.
+export const forkNativeSession = (
+  client: AgentClientIface,
+  args: {
+    sourceSessionId: string;
+    idempotencyKey: string;
+    signal?: AbortSignal;
+  },
+) =>
+  client.sessions.attach(args.sourceSessionId).fork({
+    idempotencyKey: args.idempotencyKey,
+    title: 'Alternative investigation',
+    signal: args.signal,
+  });
+
+export const directConversation = async (client: AgentClientIface, signal?: AbortSignal) => {
+  const direct = await client.conversations.direct({ agent: 'release-scout', signal });
+  const sent = await direct.send('Did 2.4.1 ship?', { signal });
+  // Durable delivery receipts also cover blank replies and a turn completed before subscribe.
+  for (const delivery of sent.deliveries) {
+    if (delivery.sessionId == null || delivery.turnId == null) continue;
+    const session = client.sessions.attach(delivery.sessionId);
+    const response = await session.response(delivery.turnId, { signal });
+    for await (const event of response.stream({ signal })) {
+      const update = sessionUpdateOf(event);
+      if (update?.sessionUpdate === 'agent_message_chunk') process.stdout.write(textOf(update));
+      if (event.pendingId != null) console.log('Decision required:', event.pendingId);
+    }
+    console.log((await response.result({ signal })).stopReason);
+  }
+  const page = await direct.messages({ limit: 50, signal });
+  const last = page.messages.at(-1);
+  if (last != null) await direct.markRead({ throughSeq: last.seq }, { signal });
+  return direct;
+};
+
+export const groupConversation = async (
+  client: AgentClientIface,
+  userId: string,
+  signal?: AbortSignal,
+) => {
+  const group = await client.conversations.create({
+    kind: 'group',
+    title: '#releases',
+    signal,
+    participants: [{ user: userId }, { agent: 'release-scout', routingMode: 'default' }],
+  });
+  const bot = await group.addParticipant(
+    { agent: 'deploy-bot', routingMode: 'mention' },
+    { signal },
+  );
+  await group.send('Go ahead with the release.', { mentions: [bot.id], signal });
+  return group;
+};
+
+export const publish = async (client: AgentClientIface, signal?: AbortSignal) => {
+  const report = await client.definitions.compatibility({
+    definition: 'release-scout',
+    harness: '@finalai/final-agent-provider/harnesses/serverless-pi',
+    signal,
+  });
+  const revision = await client.definitions.publish({
+    definition: 'release-scout',
+    ref: 'main',
+    signal,
+  });
+  return { report, revision, guides: await client.computerSetupGuides.list({ signal }) };
+};
+
+export const connect = (args: { host: string; apiKey: string }) =>
+  createClient({
+    host: args.host,
+    auth: { apiKey: args.apiKey },
+    headers: () => ({ 'x-request-source': 'release-scout-example' }),
+  });
+
+// Called by an external job after its work finishes; repeat the same event id on retry.
+export const postBuildResult = async (args: {
+  client: AgentClientIface;
+  conversationId: string;
+  runId: string;
+  text: string;
+  signal?: AbortSignal;
+}) =>
+  args.client.conversations.get(args.conversationId).postEvent(
+    {
+      source: { kind: SystemParticipantKind.Tool, id: 'release-build' },
+      eventId: `${args.runId}:completed`,
+      text: args.text,
+    },
+    { signal: args.signal },
+  );