@finalai/agents 0.10.0 → 0.12.0

package/dist/modules/cli/publish.mjs

@@ -1,92 +0,0 @@
-import { isClientError } from "../agent-client/errors.mjs";
-import { DefinitionRepositoryKind } from "../agent-client/index.mjs";
-import { compileAndPrint } from "./build.mjs";
-import { fileChanges, readLocalFiles } from "./files.mjs";
-import { errorLines, publishResultLines } from "./output.mjs";
-const remoteFiles = async (args) => {
-  try {
-    const listing = await args.client.definitions.files({
-      definition: args.definition.id,
-      ref: args.branch
-    });
-    return {
-      commitSha: listing.commitSha,
-      files: Object.fromEntries(listing.files.map((file) => [file.path, file.content]))
-    };
-  } catch (cause) {
-    if (isClientError(cause) && cause.status === 404) return { commitSha: null, files: {} };
-    throw cause;
-  }
-};
-const commitCheckout = async (args) => {
-  const { client, output, message } = args.publish;
-  const remote = await remoteFiles({ client, definition: args.definition, branch: args.branch });
-  const changes = fileChanges({ local: args.local, remote: remote.files });
-  if (changes.length === 0 && remote.commitSha != null) {
-    output.stdout(`no changes; publishing ${args.branch} at ${remote.commitSha}`);
-    return remote.commitSha;
-  }
-  const request = {
-    definition: args.definition.id,
-    files: changes,
-    message,
-    branch: args.branch
-  };
-  if (remote.commitSha != null) request.parentSha = remote.commitSha;
-  const committed = await client.definitions.commit(request);
-  const deleted = changes.filter((change) => change.content == null).length;
-  output.stdout(
-    `committed ${committed.commitSha} to ${committed.branch} (${changes.length - deleted} written, ${deleted} deleted)`
-  );
-  return committed.commitSha;
-};
-const runPublish = async (args) => {
-  const { client, output } = args;
-  try {
-    const local = await readLocalFiles({ dir: args.dir, listFiles: args.listFiles });
-    for (const problem of local.problems) output.stderr(`error: ${problem}`);
-    if (local.problems.length > 0) return 1;
-    const compiled = await compileAndPrint({ source: { files: local.files }, client, output });
-    if (!compiled.ok) {
-      output.stderr("error: the agent did not compile; nothing was published");
-      return 1;
-    }
-    const definition = await client.definitions.get({ definition: args.agent });
-    const repository = definition.repository;
-    const kind = repository?.kind ?? DefinitionRepositoryKind.CodeStorage;
-    const branch = repository?.defaultBranch ?? "main";
-    let ref;
-    if (kind === DefinitionRepositoryKind.GitHub) {
-      ref = args.ref ?? branch;
-    } else if (kind === DefinitionRepositoryKind.CodeStorage) {
-      if (args.ref != null) {
-        output.stderr(
-          "error: --ref applies to GitHub-backed agents; this agent is published from the checkout"
-        );
-        return 1;
-      }
-      ref = await commitCheckout({ publish: args, definition, branch, local: local.files });
-    } else {
-      output.stderr(`error: ${args.agent} uses a repository kind this CLI does not know`);
-      return 1;
-    }
-    const request = {
-      definition: definition.id,
-      ref
-    };
-    if (args.note != null) request.note = args.note;
-    if (args.activate != null) request.activate = args.activate;
-    const result = await client.definitions.publish(request);
-    for (const line of publishResultLines(result)) output.stdout(line);
-    if (args.activate === false)
-      output.stdout("source-only: the live agent, routes, and schedules are unchanged");
-    return 0;
-  } catch (cause) {
-    for (const line of errorLines(cause)) output.stderr(line);
-    return 1;
-  }
-};
-export {
-  runPublish
-};
-//# sourceMappingURL=publish.mjs.map

package/dist/modules/cli/publish.mjs.map

@@ -1,7 +0,0 @@
-{
-  "version": 3,
-  "sources": ["../../../../../src/cli/publish.ts"],
-  "sourcesContent": ["import type { AgentClientIface } from \"../agent-client/client.mjs\";\nimport { isClientError } from \"../agent-client/errors.mjs\";\nimport { DefinitionRepositoryKind, type DefinitionIface } from \"../agent-client/index.mjs\";\nimport { compileAndPrint } from \"./build.mjs\";\nimport { fileChanges, readLocalFiles, type ListFiles } from \"./files.mjs\";\nimport { errorLines, publishResultLines, type OutputIface } from \"./output.mjs\";\n\n// `final agents publish`: compiles the checkout\n// locally, commits it to the agent's default branch, and publishes that\n// commit. A GitHub-backed definition is not committed to; its ref (the\n// default branch unless given) is published as-is.\n\nexport interface PublishArgsIface {\n  dir: string;\n  // Definition slug or id.\n  agent: string;\n  // GitHub-backed definitions only.\n  ref: string | null;\n  message: string;\n  note: string | null;\n  activate?: boolean;\n  client: AgentClientIface;\n  listFiles: ListFiles;\n  output: OutputIface;\n}\n\n// The default branch's files and head; an empty repository has neither.\nconst remoteFiles = async (args: {\n  client: AgentClientIface;\n  definition: DefinitionIface;\n  branch: string;\n}): Promise<{ commitSha: string | null; files: Record<string, string> }> => {\n  try {\n    const listing = await args.client.definitions.files({\n      definition: args.definition.id,\n      ref: args.branch,\n    });\n    return {\n      commitSha: listing.commitSha,\n      files: Object.fromEntries(listing.files.map((file) => [file.path, file.content])),\n    };\n  } catch (cause) {\n    if (isClientError(cause) && cause.status === 404) return { commitSha: null, files: {} };\n    throw cause;\n  }\n};\n\nconst commitCheckout = async (args: {\n  publish: PublishArgsIface;\n  definition: DefinitionIface;\n  branch: string;\n  local: Record<string, string>;\n}): Promise<string> => {\n  const { client, output, message } = args.publish;\n  const remote = await remoteFiles({ client, definition: args.definition, branch: args.branch });\n  const changes = fileChanges({ local: args.local, remote: remote.files });\n  if (changes.length === 0 && remote.commitSha != null) {\n    output.stdout(`no changes; publishing ${args.branch} at ${remote.commitSha}`);\n    return remote.commitSha;\n  }\n  const request: Parameters<AgentClientIface['definitions']['commit']>[0] = {\n    definition: args.definition.id,\n    files: changes,\n    message,\n    branch: args.branch,\n  };\n  // The commit fails if the branch moved since it was read.\n  if (remote.commitSha != null) request.parentSha = remote.commitSha;\n  const committed = await client.definitions.commit(request);\n  const deleted = changes.filter((change) => change.content == null).length;\n  output.stdout(\n    `committed ${committed.commitSha} to ${committed.branch} (${changes.length - deleted} written, ${deleted} deleted)`,\n  );\n  return committed.commitSha;\n};\n\nexport const runPublish = async (args: PublishArgsIface): Promise<number> => {\n  const { client, output } = args;\n  try {\n    const local = await readLocalFiles({ dir: args.dir, listFiles: args.listFiles });\n    for (const problem of local.problems) output.stderr(`error: ${problem}`);\n    if (local.problems.length > 0) return 1;\n\n    // What the platform compiles is the committed files, so compile those.\n    const compiled = await compileAndPrint({ source: { files: local.files }, client, output });\n    if (!compiled.ok) {\n      output.stderr('error: the agent did not compile; nothing was published');\n      return 1;\n    }\n\n    const definition = await client.definitions.get({ definition: args.agent });\n    const repository = definition.repository;\n    const kind = repository?.kind ?? DefinitionRepositoryKind.CodeStorage;\n    const branch = repository?.defaultBranch ?? 'main';\n    let ref: string;\n    if (kind === DefinitionRepositoryKind.GitHub) {\n      ref = args.ref ?? branch;\n    } else if (kind === DefinitionRepositoryKind.CodeStorage) {\n      if (args.ref != null) {\n        output.stderr(\n          'error: --ref applies to GitHub-backed agents; this agent is published from the checkout',\n        );\n        return 1;\n      }\n      ref = await commitCheckout({ publish: args, definition, branch, local: local.files });\n    } else {\n      output.stderr(`error: ${args.agent} uses a repository kind this CLI does not know`);\n      return 1;\n    }\n\n    const request: Parameters<AgentClientIface['definitions']['publish']>[0] = {\n      definition: definition.id,\n      ref,\n    };\n    if (args.note != null) request.note = args.note;\n    if (args.activate != null) request.activate = args.activate;\n    const result = await client.definitions.publish(request);\n    for (const line of publishResultLines(result)) output.stdout(line);\n    if (args.activate === false)\n      output.stdout('source-only: the live agent, routes, and schedules are unchanged');\n    return 0;\n  } catch (cause) {\n    for (const line of errorLines(cause)) output.stderr(line);\n    return 1;\n  }\n};\n"],
-  "mappings": "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",
-  "names": []
-}

package/dist/modules/compile.d.mts

@@ -1,3 +0,0 @@
-import type { CompileOptionsIface, CompileResultIface } from '@finalai/agent-definition/compiler';
-export declare const compile: (options: CompileOptionsIface) => Promise<CompileResultIface>;
-export type { CompatibilityReportIface, CompiledBundleIface, CompileOptionsIface, CompileResultIface, DiagnosticCode, DiagnosticIface, DiagnosticSeverity, HarnessDescriptionContextIface, } from '@finalai/agent-definition/compiler';

package/dist/modules/compile.mjs

@@ -1,58 +0,0 @@
-import { fileURLToPath } from "node:url";
-const compile = async (options) => {
-  const finalAuthoringModules = [
-    "harnesses",
-    "harnesses/config-fields",
-    "harnesses/serverless-final",
-    "harnesses/serverless-pi",
-    "harnesses/serverless-nanocode-codex",
-    "harnesses/serverless-nanocode-claude",
-    "harnesses/remote-pi",
-    "harnesses/remote-codex",
-    "harnesses/remote-claude-code",
-    "harnesses/remote-acp",
-    "harnesses/local-stdio",
-    "sandboxes",
-    "sandboxes/computer",
-    "sandboxes/device",
-    "sandboxes/environment",
-    "connections",
-    "channels/final",
-    "channel-factories"
-  ].map((path) => "@finalai/final-agent-provider/" + path);
-  const providerModules = {
-    ...Object.fromEntries(
-      finalAuthoringModules.map((specifier) => [
-        specifier,
-        fileURLToPath(import.meta.resolve(specifier))
-      ])
-    ),
-    "@finalai/agents": fileURLToPath(import.meta.resolve("@finalai/agents/authoring")),
-    "@finalai/agents/harnesses": fileURLToPath(
-      import.meta.resolve("@finalai/final-agent-provider/harnesses")
-    ),
-    "@finalai/agents/sandboxes": fileURLToPath(
-      import.meta.resolve("@finalai/final-agent-provider/sandboxes")
-    ),
-    "@finalai/agents/channels/final": fileURLToPath(
-      import.meta.resolve("@finalai/final-agent-provider/channels/final")
-    ),
-    ...options.providerModules
-  };
-  return (await import("@finalai/agent-definition/compiler")).compile({
-    defaultFiles: {
-      "channels/final.ts": "import { finalChannel } from '@finalai/agents/channels/final'; export default finalChannel();"
-    },
-    ...options,
-    providerModules,
-    installedSandboxProviders: {
-      computer: "@finalai/final-agent-provider/sandboxes/computer",
-      device: "@finalai/final-agent-provider/sandboxes/device",
-      ...options.installedSandboxProviders
-    }
-  });
-};
-export {
-  compile
-};
-//# sourceMappingURL=compile.mjs.map

package/dist/modules/compile.mjs.map

@@ -1,7 +0,0 @@
-{
-  "version": 3,
-  "sources": ["../../../../src/compile.ts"],
-  "sourcesContent": ["import type { CompileOptionsIface, CompileResultIface } from '@finalai/agent-definition/compiler';\nimport { fileURLToPath } from 'node:url';\nexport const compile = async (options: CompileOptionsIface): Promise<CompileResultIface> => {\n  const finalAuthoringModules = [\n    'harnesses',\n    'harnesses/config-fields',\n    'harnesses/serverless-final',\n    'harnesses/serverless-pi',\n    'harnesses/serverless-nanocode-codex',\n    'harnesses/serverless-nanocode-claude',\n    'harnesses/remote-pi',\n    'harnesses/remote-codex',\n    'harnesses/remote-claude-code',\n    'harnesses/remote-acp',\n    'harnesses/local-stdio',\n    'sandboxes',\n    'sandboxes/computer',\n    'sandboxes/device',\n    'sandboxes/environment',\n    'connections',\n    'channels/final',\n    'channel-factories',\n  ].map((path) => '@finalai/final-agent-provider/' + path);\n  const providerModules = {\n    ...Object.fromEntries(\n      finalAuthoringModules.map((specifier) => [\n        specifier,\n        fileURLToPath(import.meta.resolve(specifier)),\n      ]),\n    ),\n    '@finalai/agents': fileURLToPath(import.meta.resolve('@finalai/agents/authoring')),\n    '@finalai/agents/harnesses': fileURLToPath(\n      import.meta.resolve('@finalai/final-agent-provider/harnesses'),\n    ),\n    '@finalai/agents/sandboxes': fileURLToPath(\n      import.meta.resolve('@finalai/final-agent-provider/sandboxes'),\n    ),\n    '@finalai/agents/channels/final': fileURLToPath(\n      import.meta.resolve('@finalai/final-agent-provider/channels/final'),\n    ),\n    ...options.providerModules,\n  };\n  return (await import('@finalai/agent-definition/compiler')).compile({\n    defaultFiles: {\n      'channels/final.ts':\n        \"import { finalChannel } from '@finalai/agents/channels/final'; export default finalChannel();\",\n    },\n    ...options,\n    providerModules,\n    installedSandboxProviders: {\n      computer: '@finalai/final-agent-provider/sandboxes/computer',\n      device: '@finalai/final-agent-provider/sandboxes/device',\n      ...options.installedSandboxProviders,\n    },\n  });\n};\nexport type {\n  CompatibilityReportIface,\n  CompiledBundleIface,\n  CompileOptionsIface,\n  CompileResultIface,\n  DiagnosticCode,\n  DiagnosticIface,\n  DiagnosticSeverity,\n  HarnessDescriptionContextIface,\n} from '@finalai/agent-definition/compiler';\n"],
-  "mappings": "AACA,SAAS,qBAAqB;AACvB,MAAM,UAAU,OAAO,YAA8D;AAC1F,QAAM,wBAAwB;AAAA,IAC5B;AAAA,IACA;AAAA,IACA;AAAA,IACA;AAAA,IACA;AAAA,IACA;AAAA,IACA;AAAA,IACA;AAAA,IACA;AAAA,IACA;AAAA,IACA;AAAA,IACA;AAAA,IACA;AAAA,IACA;AAAA,IACA;AAAA,IACA;AAAA,IACA;AAAA,IACA;AAAA,EACF,EAAE,IAAI,CAAC,SAAS,mCAAmC,IAAI;AACvD,QAAM,kBAAkB;AAAA,IACtB,GAAG,OAAO;AAAA,MACR,sBAAsB,IAAI,CAAC,cAAc;AAAA,QACvC;AAAA,QACA,cAAc,YAAY,QAAQ,SAAS,CAAC;AAAA,MAC9C,CAAC;AAAA,IACH;AAAA,IACA,mBAAmB,cAAc,YAAY,QAAQ,2BAA2B,CAAC;AAAA,IACjF,6BAA6B;AAAA,MAC3B,YAAY,QAAQ,yCAAyC;AAAA,IAC/D;AAAA,IACA,6BAA6B;AAAA,MAC3B,YAAY,QAAQ,yCAAyC;AAAA,IAC/D;AAAA,IACA,kCAAkC;AAAA,MAChC,YAAY,QAAQ,8CAA8C;AAAA,IACpE;AAAA,IACA,GAAG,QAAQ;AAAA,EACb;AACA,UAAQ,MAAM,OAAO,oCAAoC,GAAG,QAAQ;AAAA,IAClE,cAAc;AAAA,MACZ,qBACE;AAAA,IACJ;AAAA,IACA,GAAG;AAAA,IACH;AAAA,IACA,2BAA2B;AAAA,MACzB,UAAU;AAAA,MACV,QAAQ;AAAA,MACR,GAAG,QAAQ;AAAA,IACb;AAAA,EACF,CAAC;AACH;",
-  "names": []
-}

package/dist/modules/index.browser.d.mts

@@ -1,4 +0,0 @@
-export type { CompatibilityReportIface, CompiledBundleIface, CompileOptionsIface, CompileResultIface, DiagnosticCode, DiagnosticIface, DiagnosticSeverity, HarnessDescriptionContextIface, } from "./compile.mjs";
-export * from "./public.mjs";
-import type { CompileOptionsIface, CompileResultIface } from "./compile.mjs";
-export declare const compile: (_options: CompileOptionsIface) => Promise<CompileResultIface>;

package/dist/modules/index.browser.mjs

@@ -1,8 +0,0 @@
-export * from "./public.mjs";
-const compile = async (_options) => {
-  throw new Error("Agent directory compilation requires Node.js.");
-};
-export {
-  compile
-};
-//# sourceMappingURL=index.browser.mjs.map

package/dist/modules/index.browser.mjs.map

@@ -1,7 +0,0 @@
-{
-  "version": 3,
-  "sources": ["../../../../src/index.browser.ts"],
-  "sourcesContent": ["export type {\n  CompatibilityReportIface,\n  CompiledBundleIface,\n  CompileOptionsIface,\n  CompileResultIface,\n  DiagnosticCode,\n  DiagnosticIface,\n  DiagnosticSeverity,\n  HarnessDescriptionContextIface,\n} from \"./compile.mjs\";\nexport * from \"./public.mjs\";\nimport type { CompileOptionsIface, CompileResultIface } from \"./compile.mjs\";\n\nexport const compile = async (_options: CompileOptionsIface): Promise<CompileResultIface> => {\n  throw new Error('Agent directory compilation requires Node.js.');\n};\n"],
-  "mappings": "AAUA,cAAc;AAGP,MAAM,UAAU,OAAO,aAA+D;AAC3F,QAAM,IAAI,MAAM,+CAA+C;AACjE;",
-  "names": []
-}

package/examples/custom-harness/README.md

@@ -1,16 +0,0 @@
-# Custom harness fleet
-
-`agent.ts` demonstrates binding an agent to a custom harness fleet. Replace the sample fleet origin with your fleet and implement its API before publishing. The named `acmeFleet` export lets another definition import the same binding.
-
-The sample fleet uses its own model login. Billing policy is explicit in definition source; Final MCP and other tool credentials remain independently owned at their MCP hosts. The `acme-fleet-key` secret authenticates hosting operations and must be declared and supplied before publication.
-
-The fleet API contract is:
-
-- `POST /sessions`: create or recover by `idempotencyKey`, accepting `sessionId`, `region`, `program` and materialized `mcpServers`.
-- `POST /sessions/:id/resume`: accept the saved `generation`, `lastSeq` and fresh `mcpServers`, then return an endpoint for the existing session.
-- Both return `{ id, generation, wsUrl, token }`. The WebSocket must be on the fleet's origin and speak ACP v2. Session IDs remain stable, generations are nonnegative, and the native runtime preserves running work and open requests through reconnect. Replay must agree with the declared `resumeReplay` capability.
-- `POST /sessions/:id/pause`: persist state before parking; retries are idempotent.
-- `DELETE /sessions/:id`: accept `generation` and `force`; persist state on graceful close, abort promptly when forced, and succeed for an already closed session.
-- `GET /sessions/:id/health`: return `{ ok, detail? }` from the actual runtime state.
-
-All routes require a bearer hosting secret. Endpoint tokens authorize only the returned ACP session. The fleet must pass the MCP servers through the installed program's public surface, retain its own settings/login, accept prompts while running under its queue policy, and implement the public conformance cases before use. This example supplies every lifecycle callback; it does not provision that external fleet.

package/examples/custom-harness/agent.ts

@@ -1,154 +0,0 @@
-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

@@ -1,12 +0,0 @@
-# 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

@@ -1,14 +0,0 @@
-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

@@ -1,24 +0,0 @@
-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 () => ({}),
-    // A memory sandbox runs as soon as it exists.
-    awaitRunning: async () => {},
-    start: async () => ({ handle: handle(), state: {} }),
-    resume: async () => handle(),
-  }),
-});
-
-export const scratch = scratchProvider.environment();

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

@@ -1,22 +0,0 @@
-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

@@ -1,27 +0,0 @@
-// 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

@@ -1,32 +0,0 @@
-import { defineChannel } from '@finalai/agent-provider';
-import { verifyGithubSignature } from './github-signature';
-export default defineChannel({
-  name: 'release-events',
-  config: { secret: 'github-webhook-secret', signatureHeader: 'x-final-signature' },
-  credentials: { app: null, secrets: ['github-webhook-secret'] },
-  identity: { kind: 'none' },
-  places: { kinds: ['webhook'] },
-  receive: async () => ({ accepted: true }),
-  routes: [
-    {
-      method: 'POST',
-      path: '/webhook',
-      handler: async (ctx) => {
-        const body = await ctx.request.text();
-        const headers = new Headers(ctx.request.headers);
-        const signature = headers.get('x-final-signature');
-        if (signature != null) headers.set('x-hub-signature-256', signature);
-        if (
-          !(await verifyGithubSignature(
-            new Request(ctx.request.url, { headers }),
-            body,
-            await ctx.credentials.secret('github-webhook-secret'),
-          ))
-        )
-          return new Response(null, { status: 401 });
-        await ctx.receive(JSON.parse(body));
-        return new Response(null, { status: 202 });
-      },
-    },
-  ],
-});

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

@@ -1,9 +0,0 @@
-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

@@ -1,24 +0,0 @@
-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.example.com/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

@@ -1,26 +0,0 @@
-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.example.com/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

@@ -1,2 +0,0 @@
-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

@@ -1,20 +0,0 @@
-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: ['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

@@ -1,7 +0,0 @@
----
-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

@@ -1,8 +0,0 @@
----
-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

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