@finalai/agents 0.11.0 → 0.12.0

package/README.md

@@ -1,43 +1,228 @@
 # @finalai/agents
 
-SDK for defining, publishing, and using agents. Authoring helpers are implemented in
-`@finalai/agent-definition`; Final-specific bindings come from
-`@finalai/final-agent-provider`.
+SDK for defining agents and starting them. An agent is a value that lists every
+part explicitly and states what it requires; whoever starts it provides the
+rest. Nothing is built or deployed: the agent's document travels with the call
+that starts it.
 
 ```ts
-import { defineAgent } from '@finalai/agents';
-import { serverlessPi } from '@finalai/agents/harnesses';
+// agent.ts
+import { defineAgent, defineInProcessTool, defineServerlessTool, markdown } from '@finalai/agents';
+import { FinalHarness } from '@finalai/agents/harnesses';
+import * as z from 'zod';
+import { orders } from './db.js';
 
-export default defineAgent({
-  name: 'Assistant',
-  harness: serverlessPi({
-    credentials: { payer: 'agent-owner', tryInOrder: [{ kind: 'platform' }] },
-  }),
+// Self-contained, so it runs on Final's runtime even 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, 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 }),
+  tools: { lookup_release_notes: lookupReleaseNotes, find_order: findOrder },
+  require: {
+    harness: {
+      permissionMode: 'ask', // a limit: binding
+      recommended: { harness: FinalHarness.Pi, model: 'gpt-6.1-sol' }, // a hint
+    },
+    compute: { files: 'write', shell: 'execute' }, // keyed by capability
+    integrations: {
+      issues: { description: 'Issue tracker', tools: { deny: ['delete_*'] } },
+    },
+  },
 });
 ```
 
-Use `@finalai/agents/client` for definitions, sessions, conversations, approvals,
-attachments, schedules, sandbox access, and realtime. Use `final-agents --help`
-for CLI commands. Compilation requires Node 26 and ships its assets through
-`agent-definition`.
+```ts
+// run.ts
+import { createClient } from '@finalai/agents/client';
+import { finalCredits, serverlessPi } from '@finalai/agents/harnesses';
+import { oauth } from '@finalai/agents/integrations';
+import { agent } from './agent.js';
+
+const client = createClient({ auth: { apiKey: process.env.FINAL_API_KEY } });
+const project = client.project({ id: 'prj_01JENGINEERING' });
+
+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',
+      inference: finalCredits(),
+    }),
+    integrations: { issues: linear },
+  },
+  message: 'Did 2.4.1 ship?',
+});
+console.log(await response?.text());
+```
 
-Credential-chain declarations select which credentials an agent may use and in
-which order. Set the payer policy explicitly in the harness configuration.
+## Requirements and `provide`
 
-For custom provider implementations, import contracts from `@finalai/agent-provider`,
-sandbox adapters from `@finalai/agent-provider/sandbox`, and conformance tools from
-`@finalai/agent-provider/conformance`. Run a harness check with
-`final-agents conformance ./harness.ts`.
+| The agent declares                                      | The caller provides      | If not provided                                                                                     |
+| ------------------------------------------------------- | ------------------------ | --------------------------------------------------------------------------------------------------- |
+| `require.harness`: a permission ceiling, a hint         | harness settings, inline | the call fails; a harness is never optional                                                         |
+| `require.compute.<capability>`: the access it needs     | a sandbox per capability | `files` and `shell` run in the calling process; `computerUse` and `browserUse` fail unless optional |
+| `require.integrations.<slot>`: a description, a ceiling | an integration per slot  | the call fails, unless the slot is `optional: true` and its tools are simply absent                 |
 
-Use `FINAL_API_HOST` with `FINAL_API_KEY` to select a deployment once for build and
-publish; an explicit `--host` overrides it. Use `defineHostedConnection` for a named
-connection resolved by hosting at session start. `defineFinalConnection()` uses
-the same path with the `final` binding. Explicit URL declarations remain static.
-See the repository's [hosting guide](HOSTING.md) for provider contexts,
-resource lookup, and the required hosting integration.
+`provide` is a plain object on every call that starts work:
+`project.sessions.create`, `project.conversations.create` (per participant),
+`conversations.direct` and `.home`, `handle.addParticipant`,
+`handle.participants.provide(participantId, patch)` and
+`project.channels.install({ agents: { provide } })`. Sandbox and integration
+handles are sent as their ids. Before sending, the SDK runs the same
+requirements check the platform runs; anything missing throws a
+`requirements_unmet` error with the list (`isRequirementsUnmetError(cause)`,
+`cause.requirements`), and nothing is created.
 
-Local previews can use explicitly declared secrets from `AGENT_LOCAL_SECRETS_JSON`. Installed app operations and member and chat capabilities require an authenticated host. Embedders may supply the same opaque credential facade to `startDevServer`; raw application credentials are never exposed to authored modules.
+`sessions.create` and `conversations.create` take an `id` you choose, so a
+sandbox created first can be owned by the session or conversation it is for
+(`project.sandboxes.create(environment, { setup, ownedBy, idempotencyKey })`).
+`conversations.findHome()` and `findDirect({ agent })` look up without creating.
+
+## Where things run
+
+- **The model's files and shell** run on whatever sandbox is provided
+  (`computer(...)` and `device(...)` from `@finalai/agents/sandboxes`, or any
+  provider). Left out, they run in the process that created the session, on its
+  machine, over a connection the client opens to the platform.
+- **An in-process tool or hook** runs in the process that created the session
+  and can use anything that process holds. When that process exits the session
+  carries on and the tool reports itself unavailable.
+- **A serverless tool or hook** is self-contained: its source is part of the
+  agent's data and it runs on Final's runtime. It cannot import packages or use
+  outside variables; bundle a library into one module and pass it as `source`.
+
+The compute default is not safe for a server: a backend that leaves out `shell`
+gives the model a shell in that backend. A server provides every capability and
+creates its client with `createClient({ auth, localCompute: false })`, so an
+omission fails instead.
+
+An agent is always passed as an object: the value you defined, or one fetched
+with `project.agents.get({ name } | { id } | { hash })`. A fetched agent is data
+only; starting one that has in-process tools fails and names them.
+
+## Harnesses, inference and integrations
+
+`@finalai/agents/harnesses` builds harness settings for Final's harnesses
+(`serverlessPi`, `serverlessFinal`, `serverlessNanocodeClaude`,
+`serverlessNanocodeCodex` as worker programs; `claudeCode` and `codex` as a
+process on a machine, or `environment: atUrl({ url, hop })` for one already
+running) and the inference sources a harness pays with, first available wins:
+
+```ts
+serverlessNanocodeClaude({
+  model: 'claude-opus-5-5',
+  inference: [subscription(), apiKey('ANTHROPIC_API_KEY'), finalCredits()],
+});
+```
+
+`project.harnesses.check({ agent, harness })` says whether settings suit an
+agent and where the harness would run.
+
+A harness is data you can define and publish yourself, with the ACP adapter it
+runs behind when it does not speak ACP v2:
+
+```ts
+import {
+  CredentialDelivery,
+  defineHarness,
+  InferenceSourceKind,
+  PermissionLevel,
+} from '@finalai/agents';
+
+export const harness = defineHarness({
+  configurationSchema: { type: 'object', properties: { model: { type: 'string' } } },
+  features: [],
+  lowestPermission: PermissionLevel.Ask,
+  inference: { kinds: [InferenceSourceKind.ApiKey], delivery: CredentialDelivery.AtOpen },
+  native: { files: {}, shell: {} },
+  interface: 'my-cli-rpc',
+  adapter: 'my-cli-acp',
+  run: {
+    process: {
+      command: 'my-cli',
+      args: [
+        '--rpc',
+        { when: 'configuration.model', args: ['--model', '{{configuration.model}}'] },
+      ],
+    },
+  },
+});
+```
+
+`project.harnesses.publish({ harness, name })` and
+`project.acpAdapters.publish({ adapter, name })` give them names harness
+settings use (`{ harness: 'my-cli', environment: box }`).
+`project.harnesses.allowances` lists, allows and revokes the harnesses
+subscriptions may reach. A harness reached some other way (a hosted fleet)
+carries its own code: `defineHarness({ …, provider: defineHarnessProvider({ open,
+resume, park, close, health }) })`, self-contained like a serverless tool. `@finalai/agents/integrations` has the auth builders (`oauth`, `secret`,
+`platformIdentity`) and `finalGateway({ url })`. A person's own sign-in is never a
+requirement: the platform asks them on first use.
+
+## Publishing
+
+```sh
+final-agents print ./agent.ts                          # the document as JSON; calls nothing
+final-agents publish ./agent.ts --name release-scout   # FINAL_API_KEY, FINAL_PROJECT_ID
+final-agents publish ./harness.ts --name my-cli        # a harness or ACP adapter export
+```
+
+`publish` is `project.agents.publish({ agent, name })`: it stores the document
+by its content hash and points the name at it. `project.agents.parse(json)`
+reads a printed document back as an agent. `final-agents conformance ./harness.ts`
+runs the harness conformance kit.
+
+A project that claims a publisher handle (`project.publisher.claim({ handle })`)
+can make names public: `publish({ …, visibility: 'public' })`, or
+`project.publicNames.publish({ kind, name })`. Any organization then names them
+as `handle/name`, and `client.publishers.get(handle)` lists them.
+
+## Events and webhooks
+
+`project.events.list({ after })` reads what changed in a project and those
+below it, in commit order; `project.events.stream()` keeps polling.
+`project.eventSubscriptions.create({ url, kinds })` pushes the same events to
+your endpoint, signed per Standard Webhooks:
+
+```ts
+import { verifyWebhook } from '@finalai/agents/webhooks';
+
+const result = await verifyWebhook({
+  payload: await request.text(),
+  headers: request.headers,
+  secret,
+});
+if (!result.ok) return new Response(null, { status: 400 });
+for (const event of result.delivery.events) {
+  // Payloads are ids and state; read details through the API.
+}
+```
 
-Authored channel applications use `defineChannel` from `/channels` and compile into the published bundle. Use `bundleRef('channels/support')` in `agent.ts` to configure an existing channel module; its credentials and routes are derived from that module. Credential enums and opaque credential types are available from the same facade.
+`@finalai/agents/verify` verifies the tokens the platform signs: the
+platform-identity assertions your integrations and providers receive, and access tokens.
 
-`client.definitions.publish({ definition, ref, activate: false })` publishes an approved immutable source revision without changing the live agent, routes, listeners, or schedules. The CLI equivalent is `publish --no-activate`. Credential declarations still need normal administrator approval. Install an exported channel with `channel install <key> --revision <id> --project <id> --install <id>`; use `--replace` or `channelBindings.create({ ..., replace: true })` to explicitly update an active binding while retaining its ID and binding base URL. Omitted configuration preserves current settings during replacement; an explicit empty configuration resets to source defaults. New source publication never silently updates an installed revision pin.
+See [examples/release-scout](examples/release-scout) and the repository's
+[hosting guide](HOSTING.md) for what a platform implementing the API
+provides, including the local host connection.

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

@@ -0,0 +1,24 @@
+import { type AgentDocumentIface } from '@finalai/agent-provider/document';
+import type { InProcessCodeRegistryIface } from '@finalai/agent-provider/code-host';
+import { type AgentInfoIface, type AgentRefInputIface } from '@finalai/agent-protocol/agent-platform';
+/** What `defineAgent` returns; read through `AgentValueCodecIface`. */
+export type AgentValue = object;
+/** An agent as `sessions.create` and participants take it. */
+export type AgentInput = AgentInfoIface | AgentValue;
+/** How the SDK reads an agent value; a seam over `@finalai/agent-definition`. */
+export interface AgentValueCodecIface {
+    documentOf: (agent: AgentValue) => AgentDocumentIface | Promise<AgentDocumentIface>;
+    /** The bodies of its in-process tools, hooks and approval predicates. */
+    inProcessCodeOf: (agent: AgentValue) => InProcessCodeRegistryIface | Promise<InProcessCodeRegistryIface>;
+}
+export interface ResolvedAgentIface {
+    hash: string;
+    document: AgentDocumentIface;
+    /** The ref sent on the wire; the document travels with a value. */
+    ref: AgentRefInputIface;
+    /** Names of its tools and hooks whose code only runs in the creating process. */
+    inProcess: string[];
+    /** Null when this process does not hold the agent's code (a fetched agent). */
+    code: InProcessCodeRegistryIface | null;
+}
+export declare const resolveAgentInput: (agent: unknown, codec: AgentValueCodecIface) => Promise<ResolvedAgentIface>;

package/dist/modules/agent-client/agent-input.mjs

@@ -0,0 +1,46 @@
+import {
+  agentDocumentHash,
+  agentDocumentSchema,
+  inProcessCodeOf
+} from "@finalai/agent-provider/document";
+import { jsonObjectSchema } from "@finalai/agent-protocol";
+import {
+  agentInfoSchema
+} from "@finalai/agent-protocol/agent-platform";
+import { clientError, ClientErrorCode } from "./errors.mjs";
+const invalidAgent = (message) => clientError({ message, status: 0, code: ClientErrorCode.InvalidRequest });
+const resolveAgentInput = async (agent, codec) => {
+  if (typeof agent === "string")
+    throw invalidAgent(
+      `An agent is passed as an object, not the string "${agent}": pass the value you defined, or fetch it with project.agents.get({ name })`
+    );
+  if (agent == null || typeof agent !== "object")
+    throw invalidAgent("An agent is passed as the value you defined or one you fetched");
+  const fetched = agentInfoSchema.safeParse(agent);
+  if (fetched.success) {
+    const document2 = agentDocumentSchema.safeParse(fetched.data.document);
+    if (!document2.success)
+      throw invalidAgent(`The fetched agent's document is not valid: ${document2.error.message}`);
+    return {
+      hash: fetched.data.hash,
+      document: document2.data,
+      // A published agent is stored; one parsed from a printed document may not be.
+      ref: fetched.data.id == null ? { hash: fetched.data.hash, document: fetched.data.document } : { hash: fetched.data.hash },
+      inProcess: inProcessCodeOf(document2.data),
+      code: null
+    };
+  }
+  const document = await codec.documentOf(agent);
+  const hash = await agentDocumentHash(document);
+  return {
+    hash,
+    document,
+    ref: { hash, document: jsonObjectSchema.parse(JSON.parse(JSON.stringify(document))) },
+    inProcess: inProcessCodeOf(document),
+    code: await codec.inProcessCodeOf(agent)
+  };
+};
+export {
+  resolveAgentInput
+};
+//# sourceMappingURL=agent-input.mjs.map

package/dist/modules/agent-client/agent-input.mjs.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../../../../../src/agent-client/agent-input.ts"],
+  "sourcesContent": ["import {\n  agentDocumentHash,\n  agentDocumentSchema,\n  inProcessCodeOf,\n  type AgentDocumentIface,\n} from '@finalai/agent-provider/document';\nimport type { InProcessCodeRegistryIface } from '@finalai/agent-provider/code-host';\nimport { jsonObjectSchema } from '@finalai/agent-protocol';\nimport {\n  agentInfoSchema,\n  type AgentInfoIface,\n  type AgentRefInputIface,\n} from '@finalai/agent-protocol/agent-platform';\nimport { clientError, ClientErrorCode } from \"./errors.mjs\";\n\n// An agent is always passed as an object: a value the caller defined\n// (`defineAgent`), whose in-process code this process holds, or one fetched\n// with `project.agents.get`, which is data only.\n\n/** What `defineAgent` returns; read through `AgentValueCodecIface`. */\nexport type AgentValue = object;\n\n/** An agent as `sessions.create` and participants take it. */\nexport type AgentInput = AgentInfoIface | AgentValue;\n\n/** How the SDK reads an agent value; a seam over `@finalai/agent-definition`. */\nexport interface AgentValueCodecIface {\n  documentOf: (agent: AgentValue) => AgentDocumentIface | Promise<AgentDocumentIface>;\n  /** The bodies of its in-process tools, hooks and approval predicates. */\n  inProcessCodeOf: (\n    agent: AgentValue,\n  ) => InProcessCodeRegistryIface | Promise<InProcessCodeRegistryIface>;\n}\n\nexport interface ResolvedAgentIface {\n  hash: string;\n  document: AgentDocumentIface;\n  /** The ref sent on the wire; the document travels with a value. */\n  ref: AgentRefInputIface;\n  /** Names of its tools and hooks whose code only runs in the creating process. */\n  inProcess: string[];\n  /** Null when this process does not hold the agent's code (a fetched agent). */\n  code: InProcessCodeRegistryIface | null;\n}\n\nconst invalidAgent = (message: string) =>\n  clientError({ message, status: 0, code: ClientErrorCode.InvalidRequest });\n\nexport const resolveAgentInput = async (\n  agent: unknown,\n  codec: AgentValueCodecIface,\n): Promise<ResolvedAgentIface> => {\n  if (typeof agent === 'string')\n    throw invalidAgent(\n      `An agent is passed as an object, not the string \"${agent}\": pass the value you defined, or fetch it with project.agents.get({ name })`,\n    );\n  if (agent == null || typeof agent !== 'object')\n    throw invalidAgent('An agent is passed as the value you defined or one you fetched');\n  const fetched = agentInfoSchema.safeParse(agent);\n  if (fetched.success) {\n    const document = agentDocumentSchema.safeParse(fetched.data.document);\n    if (!document.success)\n      throw invalidAgent(`The fetched agent's document is not valid: ${document.error.message}`);\n    return {\n      hash: fetched.data.hash,\n      document: document.data,\n      // A published agent is stored; one parsed from a printed document may not be.\n      ref:\n        fetched.data.id == null\n          ? { hash: fetched.data.hash, document: fetched.data.document }\n          : { hash: fetched.data.hash },\n      inProcess: inProcessCodeOf(document.data),\n      code: null,\n    };\n  }\n  const document = await codec.documentOf(agent);\n  const hash = await agentDocumentHash(document);\n  return {\n    hash,\n    document,\n    ref: { hash, document: jsonObjectSchema.parse(JSON.parse(JSON.stringify(document))) },\n    inProcess: inProcessCodeOf(document),\n    code: await codec.inProcessCodeOf(agent),\n  };\n};\n"],
+  "mappings": "AAAA;AAAA,EACE;AAAA,EACA;AAAA,EACA;AAAA,OAEK;AAEP,SAAS,wBAAwB;AACjC;AAAA,EACE;AAAA,OAGK;AACP,SAAS,aAAa,uBAAuB;AAgC7C,MAAM,eAAe,CAAC,YACpB,YAAY,EAAE,SAAS,QAAQ,GAAG,MAAM,gBAAgB,eAAe,CAAC;AAEnE,MAAM,oBAAoB,OAC/B,OACA,UACgC;AAChC,MAAI,OAAO,UAAU;AACnB,UAAM;AAAA,MACJ,oDAAoD,KAAK;AAAA,IAC3D;AACF,MAAI,SAAS,QAAQ,OAAO,UAAU;AACpC,UAAM,aAAa,gEAAgE;AACrF,QAAM,UAAU,gBAAgB,UAAU,KAAK;AAC/C,MAAI,QAAQ,SAAS;AACnB,UAAMA,YAAW,oBAAoB,UAAU,QAAQ,KAAK,QAAQ;AACpE,QAAI,CAACA,UAAS;AACZ,YAAM,aAAa,8CAA8CA,UAAS,MAAM,OAAO,EAAE;AAC3F,WAAO;AAAA,MACL,MAAM,QAAQ,KAAK;AAAA,MACnB,UAAUA,UAAS;AAAA;AAAA,MAEnB,KACE,QAAQ,KAAK,MAAM,OACf,EAAE,MAAM,QAAQ,KAAK,MAAM,UAAU,QAAQ,KAAK,SAAS,IAC3D,EAAE,MAAM,QAAQ,KAAK,KAAK;AAAA,MAChC,WAAW,gBAAgBA,UAAS,IAAI;AAAA,MACxC,MAAM;AAAA,IACR;AAAA,EACF;AACA,QAAM,WAAW,MAAM,MAAM,WAAW,KAAK;AAC7C,QAAM,OAAO,MAAM,kBAAkB,QAAQ;AAC7C,SAAO;AAAA,IACL;AAAA,IACA;AAAA,IACA,KAAK,EAAE,MAAM,UAAU,iBAAiB,MAAM,KAAK,MAAM,KAAK,UAAU,QAAQ,CAAC,CAAC,EAAE;AAAA,IACpF,WAAW,gBAAgB,QAAQ;AAAA,IACnC,MAAM,MAAM,MAAM,gBAAgB,KAAK;AAAA,EACzC;AACF;",
+  "names": ["document"]
+}

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

@@ -1,7 +1,49 @@
-import { type ChannelRouteIface, type ChannelSeenPlaceIface, type ConnectChannelPlaceRequestIface, type CreateChannelBindingRequestIface, type CreateChannelBindingResponseIface } from '@finalai/agent-protocol/agent-platform';
-import { type ClientContextIface, type SignalOptionsIface } from "./context.mjs";
+import { type ChannelIface, type ChannelRouteIface, type ChannelSeenPlaceIface, type ConnectChannelPlaceRequestIface, type CreateChannelBindingResponseIface, type DefinitionVisibility, type PublishChannelResponseIface } from '@finalai/agent-protocol/agent-platform';
+import { type ClientContextIface, type EnumInput, type SignalOptionsIface } from "./context.mjs";
+import { type ProvideIface } from "./provide.mjs";
+/** A channel value's source, as `channels.publish({ channel })` sends it. */
+export interface ChannelSourceIface {
+    source: string;
+    export?: string;
+}
+/** How the SDK turns a channel value into its source; a seam over `@finalai/agent-definition`. */
+export type ChannelSourceOf = (channel: object) => ChannelSourceIface;
+export type PublishChannelArgsIface = {
+    name: string;
+    /** `public` also makes the name public under the project's publisher handle. */
+    visibility?: EnumInput<DefinitionVisibility>;
+} & SignalOptionsIface & ({
+    channel: object;
+} | {
+    source: string;
+    export?: string;
+});
+export interface InstallChannelArgsIface extends SignalOptionsIface {
+    /** A published channel (`channels.get`), or `{ name }` to install what the name points at now. */
+    channel: Pick<ChannelIface, 'hash'> | {
+        name: string;
+    };
+    connectorInstallId: string;
+    /** What an agent gets in every chat this install creates. */
+    agents: {
+        provide: ProvideIface;
+    };
+    /** Explicitly replace an existing install of the same connector. */
+    replace?: boolean;
+    /** Reaches only the channel's own code. */
+    config?: Record<string, unknown>;
+}
+export interface ProjectChannelsApiIface {
+    publish: (args: PublishChannelArgsIface) => Promise<PublishChannelResponseIface>;
+    get: (selector: ({
+        name: string;
+    } | {
+        hash: string;
+    }) & SignalOptionsIface) => Promise<ChannelIface>;
+    /** Fails with `requirements_unmet` unless `agents.provide` meets the answering agent's requirements. */
+    install: (args: InstallChannelArgsIface) => Promise<CreateChannelBindingResponseIface>;
+}
 export interface ChannelBindingsApiIface {
-    create(args: CreateChannelBindingRequestIface & SignalOptionsIface): Promise<CreateChannelBindingResponseIface>;
     places(args: {
         bindingId: string;
     } & SignalOptionsIface): Promise<ChannelSeenPlaceIface[]>;
@@ -20,4 +62,11 @@ export interface ChannelBindingsApiIface {
         ok: boolean;
     }>;
 }
+export declare const createProjectChannelsApi: (args: {
+    context: ClientContextIface;
+    projectId: string;
+    sourceOf: ChannelSourceOf;
+}) => ProjectChannelsApiIface;
 export declare const createChannelBindingsApi: (ctx: ClientContextIface) => ChannelBindingsApiIface;
+/** The default `ChannelSourceOf` when no codec is available. */
+export declare const noChannelSource: ChannelSourceOf;

package/dist/modules/agent-client/channels.mjs

@@ -1,22 +1,74 @@
 import {
   channelPlacesResponseSchema,
   channelRoutesResponseSchema,
+  channelSchema,
   connectChannelPlaceRequestSchema,
   connectChannelPlaceResponseSchema,
   createChannelBindingRequestSchema,
   createChannelBindingResponseSchema,
-  disconnectChannelRouteResponseSchema
+  disconnectChannelRouteResponseSchema,
+  publishChannelRequestSchema,
+  publishChannelResponseSchema
 } from "@finalai/agent-protocol/agent-platform";
-import { encodePath } from "./context.mjs";
+import {
+  encodePath
+} from "./context.mjs";
+import { clientError, ClientErrorCode } from "./errors.mjs";
 import { HttpMethod } from "./http.mjs";
+import { provideDocumentOf } from "./provide.mjs";
+const channelsPath = (projectId, suffix) => `/v1/projects/${encodePath(projectId)}/channels${suffix}`;
+const createProjectChannelsApi = (args) => {
+  const { http } = args.context;
+  return {
+    publish: (publish) => {
+      const source = "channel" in publish ? args.sourceOf(publish.channel) : {
+        source: publish.source,
+        ...publish.export == null ? {} : { export: publish.export }
+      };
+      return http.request({
+        method: HttpMethod.Post,
+        path: channelsPath(args.projectId, "/publish"),
+        body: {
+          schema: publishChannelRequestSchema,
+          value: { name: publish.name, ...source, visibility: publish.visibility }
+        },
+        response: publishChannelResponseSchema,
+        signal: publish.signal
+      });
+    },
+    get: ({ signal, ...selector }) => http.request({
+      method: HttpMethod.Get,
+      path: channelsPath(args.projectId, "/lookup"),
+      query: {
+        name: "name" in selector ? selector.name : void 0,
+        hash: "hash" in selector ? selector.hash : void 0
+      },
+      response: channelSchema,
+      signal
+    }),
+    install: (install) => {
+      const channel = "hash" in install.channel ? { hash: install.channel.hash } : { name: install.channel.name };
+      return http.request({
+        method: HttpMethod.Post,
+        path: "/v1/channel-bindings",
+        body: {
+          schema: createChannelBindingRequestSchema,
+          value: {
+            projectId: args.projectId,
+            channel,
+            connectorInstallId: install.connectorInstallId,
+            agents: { provide: provideDocumentOf(install.agents.provide) },
+            replace: install.replace,
+            config: install.config
+          }
+        },
+        response: createChannelBindingResponseSchema,
+        signal: install.signal
+      });
+    }
+  };
+};
 const createChannelBindingsApi = (ctx) => ({
-  create: ({ signal, ...body }) => ctx.http.request({
-    method: HttpMethod.Post,
-    path: "/v1/channel-bindings",
-    body: { schema: createChannelBindingRequestSchema, value: body },
-    response: createChannelBindingResponseSchema,
-    signal
-  }),
   places: async ({ bindingId, signal }) => (await ctx.http.request({
     method: HttpMethod.Get,
     path: `/v1/channel-bindings/${encodePath(bindingId)}/places`,
@@ -43,7 +95,16 @@ const createChannelBindingsApi = (ctx) => ({
     signal
   })
 });
+const noChannelSource = () => {
+  throw clientError({
+    message: "Publish a channel as `source`: this build cannot capture a channel value",
+    status: 0,
+    code: ClientErrorCode.InvalidRequest
+  });
+};
 export {
-  createChannelBindingsApi
+  createChannelBindingsApi,
+  createProjectChannelsApi,
+  noChannelSource
 };
 //# sourceMappingURL=channels.mjs.map

package/dist/modules/agent-client/channels.mjs.map

@@ -1,7 +1,7 @@
 {
   "version": 3,
   "sources": ["../../../../../src/agent-client/channels.ts"],
-  "sourcesContent": ["import {\n  channelPlacesResponseSchema,\n  channelRoutesResponseSchema,\n  connectChannelPlaceRequestSchema,\n  connectChannelPlaceResponseSchema,\n  createChannelBindingRequestSchema,\n  createChannelBindingResponseSchema,\n  disconnectChannelRouteResponseSchema,\n  type ChannelRouteIface,\n  type ChannelSeenPlaceIface,\n  type ConnectChannelPlaceRequestIface,\n  type CreateChannelBindingRequestIface,\n  type CreateChannelBindingResponseIface,\n} from '@finalai/agent-protocol/agent-platform';\nimport { encodePath, type ClientContextIface, type SignalOptionsIface } from \"./context.mjs\";\nimport { HttpMethod } from \"./http.mjs\";\nexport interface ChannelBindingsApiIface {\n  create(\n    args: CreateChannelBindingRequestIface & SignalOptionsIface,\n  ): Promise<CreateChannelBindingResponseIface>;\n  places(args: { bindingId: string } & SignalOptionsIface): Promise<ChannelSeenPlaceIface[]>;\n  routes(args: { conversationId: string } & SignalOptionsIface): Promise<ChannelRouteIface[]>;\n  connect(\n    args: ConnectChannelPlaceRequestIface & { conversationId: string } & SignalOptionsIface,\n  ): Promise<{ id: string }>;\n  disconnect(\n    args: { conversationId: string; routeId: string } & SignalOptionsIface,\n  ): Promise<{ ok: boolean }>;\n}\nexport const createChannelBindingsApi = (ctx: ClientContextIface): ChannelBindingsApiIface => ({\n  create: ({ signal, ...body }) =>\n    ctx.http.request({\n      method: HttpMethod.Post,\n      path: '/v1/channel-bindings',\n      body: { schema: createChannelBindingRequestSchema, value: body },\n      response: createChannelBindingResponseSchema,\n      signal,\n    }),\n  places: async ({ bindingId, signal }) =>\n    (\n      await ctx.http.request({\n        method: HttpMethod.Get,\n        path: `/v1/channel-bindings/${encodePath(bindingId)}/places`,\n        response: channelPlacesResponseSchema,\n        signal,\n      })\n    ).places,\n  routes: async ({ conversationId, signal }) =>\n    (\n      await ctx.http.request({\n        method: HttpMethod.Get,\n        path: `/v1/conversations/${encodePath(conversationId)}/channel-routes`,\n        response: channelRoutesResponseSchema,\n        signal,\n      })\n    ).routes,\n  connect: ({ conversationId, signal, ...body }) =>\n    ctx.http.request({\n      method: HttpMethod.Post,\n      path: `/v1/conversations/${encodePath(conversationId)}/channel-routes`,\n      body: { schema: connectChannelPlaceRequestSchema, value: body },\n      response: connectChannelPlaceResponseSchema,\n      signal,\n    }),\n  disconnect: ({ conversationId, routeId, signal }) =>\n    ctx.http.request({\n      method: HttpMethod.Delete,\n      path: `/v1/conversations/${encodePath(conversationId)}/channel-routes/${encodePath(routeId)}`,\n      response: disconnectChannelRouteResponseSchema,\n      signal,\n    }),\n});\n"],
-  "mappings": "AAAA;AAAA,EACE;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,OAMK;AACP,SAAS,kBAAoE;AAC7E,SAAS,kBAAkB;AAcpB,MAAM,2BAA2B,CAAC,SAAsD;AAAA,EAC7F,QAAQ,CAAC,EAAE,QAAQ,GAAG,KAAK,MACzB,IAAI,KAAK,QAAQ;AAAA,IACf,QAAQ,WAAW;AAAA,IACnB,MAAM;AAAA,IACN,MAAM,EAAE,QAAQ,mCAAmC,OAAO,KAAK;AAAA,IAC/D,UAAU;AAAA,IACV;AAAA,EACF,CAAC;AAAA,EACH,QAAQ,OAAO,EAAE,WAAW,OAAO,OAE/B,MAAM,IAAI,KAAK,QAAQ;AAAA,IACrB,QAAQ,WAAW;AAAA,IACnB,MAAM,wBAAwB,WAAW,SAAS,CAAC;AAAA,IACnD,UAAU;AAAA,IACV;AAAA,EACF,CAAC,GACD;AAAA,EACJ,QAAQ,OAAO,EAAE,gBAAgB,OAAO,OAEpC,MAAM,IAAI,KAAK,QAAQ;AAAA,IACrB,QAAQ,WAAW;AAAA,IACnB,MAAM,qBAAqB,WAAW,cAAc,CAAC;AAAA,IACrD,UAAU;AAAA,IACV;AAAA,EACF,CAAC,GACD;AAAA,EACJ,SAAS,CAAC,EAAE,gBAAgB,QAAQ,GAAG,KAAK,MAC1C,IAAI,KAAK,QAAQ;AAAA,IACf,QAAQ,WAAW;AAAA,IACnB,MAAM,qBAAqB,WAAW,cAAc,CAAC;AAAA,IACrD,MAAM,EAAE,QAAQ,kCAAkC,OAAO,KAAK;AAAA,IAC9D,UAAU;AAAA,IACV;AAAA,EACF,CAAC;AAAA,EACH,YAAY,CAAC,EAAE,gBAAgB,SAAS,OAAO,MAC7C,IAAI,KAAK,QAAQ;AAAA,IACf,QAAQ,WAAW;AAAA,IACnB,MAAM,qBAAqB,WAAW,cAAc,CAAC,mBAAmB,WAAW,OAAO,CAAC;AAAA,IAC3F,UAAU;AAAA,IACV;AAAA,EACF,CAAC;AACL;",
+  "sourcesContent": ["import {\n  channelPlacesResponseSchema,\n  channelRoutesResponseSchema,\n  channelSchema,\n  connectChannelPlaceRequestSchema,\n  connectChannelPlaceResponseSchema,\n  createChannelBindingRequestSchema,\n  createChannelBindingResponseSchema,\n  disconnectChannelRouteResponseSchema,\n  publishChannelRequestSchema,\n  publishChannelResponseSchema,\n  type ChannelIface,\n  type ChannelRouteIface,\n  type ChannelSeenPlaceIface,\n  type ConnectChannelPlaceRequestIface,\n  type CreateChannelBindingResponseIface,\n  type DefinitionVisibility,\n  type PublishChannelResponseIface,\n} from '@finalai/agent-protocol/agent-platform';\nimport {\n  encodePath,\n  type ClientContextIface,\n  type EnumInput,\n  type SignalOptionsIface,\n} from \"./context.mjs\";\nimport { clientError, ClientErrorCode } from \"./errors.mjs\";\nimport { HttpMethod } from \"./http.mjs\";\nimport { provideDocumentOf, type ProvideIface } from \"./provide.mjs\";\n\n// Channels connect a provider (Slack, email, a webhook) to a project's chats.\n// A channel is one self-contained module, published by name and stored by\n// content hash; its handlers always run on Final's serverless runtime.\n\n/** A channel value's source, as `channels.publish({ channel })` sends it. */\nexport interface ChannelSourceIface {\n  source: string;\n  export?: string;\n}\n\n/** How the SDK turns a channel value into its source; a seam over `@finalai/agent-definition`. */\nexport type ChannelSourceOf = (channel: object) => ChannelSourceIface;\n\nexport type PublishChannelArgsIface = {\n  name: string;\n  /** `public` also makes the name public under the project's publisher handle. */\n  visibility?: EnumInput<DefinitionVisibility>;\n} & SignalOptionsIface &\n  ({ channel: object } | { source: string; export?: string });\n\nexport interface InstallChannelArgsIface extends SignalOptionsIface {\n  /** A published channel (`channels.get`), or `{ name }` to install what the name points at now. */\n  channel: Pick<ChannelIface, 'hash'> | { name: string };\n  connectorInstallId: string;\n  /** What an agent gets in every chat this install creates. */\n  agents: { provide: ProvideIface };\n  /** Explicitly replace an existing install of the same connector. */\n  replace?: boolean;\n  /** Reaches only the channel's own code. */\n  config?: Record<string, unknown>;\n}\n\nexport interface ProjectChannelsApiIface {\n  publish: (args: PublishChannelArgsIface) => Promise<PublishChannelResponseIface>;\n  get: (\n    selector: ({ name: string } | { hash: string }) & SignalOptionsIface,\n  ) => Promise<ChannelIface>;\n  /** Fails with `requirements_unmet` unless `agents.provide` meets the answering agent's requirements. */\n  install: (args: InstallChannelArgsIface) => Promise<CreateChannelBindingResponseIface>;\n}\n\nexport interface ChannelBindingsApiIface {\n  places(args: { bindingId: string } & SignalOptionsIface): Promise<ChannelSeenPlaceIface[]>;\n  routes(args: { conversationId: string } & SignalOptionsIface): Promise<ChannelRouteIface[]>;\n  connect(\n    args: ConnectChannelPlaceRequestIface & { conversationId: string } & SignalOptionsIface,\n  ): Promise<{ id: string }>;\n  disconnect(\n    args: { conversationId: string; routeId: string } & SignalOptionsIface,\n  ): Promise<{ ok: boolean }>;\n}\n\nconst channelsPath = (projectId: string, suffix: string): string =>\n  `/v1/projects/${encodePath(projectId)}/channels${suffix}`;\n\nexport const createProjectChannelsApi = (args: {\n  context: ClientContextIface;\n  projectId: string;\n  sourceOf: ChannelSourceOf;\n}): ProjectChannelsApiIface => {\n  const { http } = args.context;\n  return {\n    publish: (publish) => {\n      const source: ChannelSourceIface =\n        'channel' in publish\n          ? args.sourceOf(publish.channel)\n          : {\n              source: publish.source,\n              ...(publish.export == null ? {} : { export: publish.export }),\n            };\n      return http.request({\n        method: HttpMethod.Post,\n        path: channelsPath(args.projectId, '/publish'),\n        body: {\n          schema: publishChannelRequestSchema,\n          value: { name: publish.name, ...source, visibility: publish.visibility },\n        },\n        response: publishChannelResponseSchema,\n        signal: publish.signal,\n      });\n    },\n    get: ({ signal, ...selector }) =>\n      http.request({\n        method: HttpMethod.Get,\n        path: channelsPath(args.projectId, '/lookup'),\n        query: {\n          name: 'name' in selector ? selector.name : undefined,\n          hash: 'hash' in selector ? selector.hash : undefined,\n        },\n        response: channelSchema,\n        signal,\n      }),\n    install: (install) => {\n      const channel =\n        'hash' in install.channel ? { hash: install.channel.hash } : { name: install.channel.name };\n      return http.request({\n        method: HttpMethod.Post,\n        path: '/v1/channel-bindings',\n        body: {\n          schema: createChannelBindingRequestSchema,\n          value: {\n            projectId: args.projectId,\n            channel,\n            connectorInstallId: install.connectorInstallId,\n            agents: { provide: provideDocumentOf(install.agents.provide) },\n            replace: install.replace,\n            config: install.config,\n          },\n        },\n        response: createChannelBindingResponseSchema,\n        signal: install.signal,\n      });\n    },\n  };\n};\n\nexport const createChannelBindingsApi = (ctx: ClientContextIface): ChannelBindingsApiIface => ({\n  places: async ({ bindingId, signal }) =>\n    (\n      await ctx.http.request({\n        method: HttpMethod.Get,\n        path: `/v1/channel-bindings/${encodePath(bindingId)}/places`,\n        response: channelPlacesResponseSchema,\n        signal,\n      })\n    ).places,\n  routes: async ({ conversationId, signal }) =>\n    (\n      await ctx.http.request({\n        method: HttpMethod.Get,\n        path: `/v1/conversations/${encodePath(conversationId)}/channel-routes`,\n        response: channelRoutesResponseSchema,\n        signal,\n      })\n    ).routes,\n  connect: ({ conversationId, signal, ...body }) =>\n    ctx.http.request({\n      method: HttpMethod.Post,\n      path: `/v1/conversations/${encodePath(conversationId)}/channel-routes`,\n      body: { schema: connectChannelPlaceRequestSchema, value: body },\n      response: connectChannelPlaceResponseSchema,\n      signal,\n    }),\n  disconnect: ({ conversationId, routeId, signal }) =>\n    ctx.http.request({\n      method: HttpMethod.Delete,\n      path: `/v1/conversations/${encodePath(conversationId)}/channel-routes/${encodePath(routeId)}`,\n      response: disconnectChannelRouteResponseSchema,\n      signal,\n    }),\n});\n\n/** The default `ChannelSourceOf` when no codec is available. */\nexport const noChannelSource: ChannelSourceOf = () => {\n  throw clientError({\n    message: 'Publish a channel as `source`: this build cannot capture a channel value',\n    status: 0,\n    code: ClientErrorCode.InvalidRequest,\n  });\n};\n"],
+  "mappings": "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",
   "names": []
 }