@finalai/agents 0.11.0 → 0.13.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,23 +1,135 @@
-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 ActorInputIface, type ChannelAppIface, type ChannelBindingIface, type ChannelIdentityLinkIface, type ChannelIdentityLinkProgressIface, type ChannelIface, type ChannelSeenPlaceIface, type ChannelTenantTicketIface, type ChannelTicketIface, type CompleteChannelIdentityLinkRequestIface, type CompleteChannelPlaceConnectionRequestIface, type CreateChannelAppRequestIface, type DefinitionVisibility, type InstallChannelRequestIface, type InstalledChannelIface, type PublishChannelResponseIface, type UpdateChannelAppRequestIface, type UpdateChannelBindingRequestIface } 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>;
+    /** A channel app of this project that installs of the publication use unless they bring their own. */
+    app?: string;
+} & SignalOptionsIface & ({
+    channel: object;
+} | {
+    source: string;
+    export?: string;
+});
+export type InstallChannelArgsIface = Omit<InstallChannelRequestIface, 'agents'> & {
+    /** What the agent gets in every chat this install creates. */
+    agents: {
+        provide: ProvideIface;
+    };
+} & SignalOptionsIface;
+export type UpdateChannelBindingArgsIface = Omit<UpdateChannelBindingRequestIface, 'agents'> & {
+    bindingId: string;
+    agents?: {
+        provide: ProvideIface;
+    };
+} & SignalOptionsIface;
+export interface ProjectChannelsApiIface {
+    publish: (args: PublishChannelArgsIface) => Promise<PublishChannelResponseIface>;
+    get: (selector: ({
+        name: string;
+    } | {
+        hash: string;
+    }) & SignalOptionsIface) => Promise<ChannelIface>;
+    /**
+     * Installs a channel in the project. Fails with `requirements_unmet`, and
+     * installs nothing, unless `agents.provide` meets the agent's requirements
+     * and the channel's app requirement is met.
+     */
+    install: (args: InstallChannelArgsIface) => Promise<InstalledChannelIface>;
+    /** The project's installs, newest first. */
+    installs: (options?: SignalOptionsIface & {
+        includeArchived?: boolean;
+    }) => Promise<ChannelBindingIface[]>;
+}
 export interface ChannelBindingsApiIface {
-    create(args: CreateChannelBindingRequestIface & SignalOptionsIface): Promise<CreateChannelBindingResponseIface>;
-    places(args: {
+    /** One install, with whether its agent's requirements are met now. */
+    get: (args: {
         bindingId: string;
-    } & SignalOptionsIface): Promise<ChannelSeenPlaceIface[]>;
-    routes(args: {
-        conversationId: string;
-    } & SignalOptionsIface): Promise<ChannelRouteIface[]>;
-    connect(args: ConnectChannelPlaceRequestIface & {
-        conversationId: string;
-    } & SignalOptionsIface): Promise<{
-        id: string;
+    } & SignalOptionsIface) => Promise<ChannelBindingIface>;
+    /** Fails with `revision_conflict` unless `revision` is the one last read, and with `requirements_unmet` when the change would leave them unmet. */
+    update: (args: UpdateChannelBindingArgsIface) => Promise<InstalledChannelIface>;
+    /** Ends the install: its connected places, tenants, listeners and the links made through it. */
+    uninstall: (args: {
+        bindingId: string;
+    } & SignalOptionsIface) => Promise<{
+        archivedAt: string | null;
     }>;
-    disconnect(args: {
-        conversationId: string;
+    /** A single-use link that installs the provider app for one tenant (a workspace, a server). */
+    tenantTicket: (args: {
+        bindingId: string;
+    } & SignalOptionsIface) => Promise<ChannelTenantTicketIface>;
+    /** The provider places the install has seen. */
+    places: (args: {
+        bindingId: string;
+    } & SignalOptionsIface) => Promise<ChannelSeenPlaceIface[]>;
+}
+export interface ChannelAppsApiIface {
+    /** Registers the provider application's credentials; secret values stay project secrets. */
+    create: (args: CreateChannelAppRequestIface & SignalOptionsIface) => Promise<ChannelAppIface>;
+    /** The apps of the project and its ancestors. */
+    list: (options?: SignalOptionsIface) => Promise<ChannelAppIface[]>;
+    update: (args: UpdateChannelAppRequestIface & {
+        id: string;
+    } & SignalOptionsIface) => Promise<ChannelAppIface>;
+    /** Refused while a live install or publication uses the app. */
+    delete: (args: {
+        id: string;
+    } & SignalOptionsIface) => Promise<void>;
+}
+/** The actor an API key or app acts for, by its external id. */
+export interface ActorOptionIface {
+    actor?: string;
+}
+export interface ChannelTicketsApiIface {
+    /** What a ticket from an installer's link or connect page is for. */
+    get: (args: {
+        ticket: string;
+    } & ActorOptionIface & SignalOptionsIface) => Promise<ChannelTicketIface>;
+    /** Links the ticket's channel account to the caller's person, or to `actor`. */
+    link: (args: {
+        ticket: string;
+    } & CompleteChannelIdentityLinkRequestIface & SignalOptionsIface) => Promise<ChannelIdentityLinkProgressIface>;
+    /** Connects the ticket's place to a conversation the caller manages. */
+    connect: (args: {
+        ticket: string;
+    } & CompleteChannelPlaceConnectionRequestIface & SignalOptionsIface) => Promise<{
         routeId: string;
-    } & SignalOptionsIface): Promise<{
-        ok: boolean;
     }>;
 }
+export interface IdentityLinksApiIface {
+    /** The channel accounts linked to the caller's person, or to `actor`. */
+    list: (options?: ActorOptionIface & SignalOptionsIface) => Promise<ChannelIdentityLinkIface[]>;
+    /** Chooses where the person's direct messages to the channel land. */
+    update: (args: {
+        id: string;
+        directConversationId: string | null;
+        actor?: ActorInputIface;
+    } & SignalOptionsIface) => Promise<void>;
+    /** Unlinks the account. */
+    delete: (args: {
+        id: string;
+    } & ActorOptionIface & SignalOptionsIface) => Promise<void>;
+}
+export declare const createProjectChannelsApi: (args: {
+    context: ClientContextIface;
+    projectId: string;
+    sourceOf: ChannelSourceOf;
+}) => ProjectChannelsApiIface;
 export declare const createChannelBindingsApi: (ctx: ClientContextIface) => ChannelBindingsApiIface;
+export declare const createChannelAppsApi: (args: {
+    context: ClientContextIface;
+    projectId: string;
+}) => ChannelAppsApiIface;
+export declare const createChannelTicketsApi: (ctx: ClientContextIface) => ChannelTicketsApiIface;
+export declare const createIdentityLinksApi: (ctx: ClientContextIface) => IdentityLinksApiIface;
+/** The default `ChannelSourceOf` when no codec is available. */
+export declare const noChannelSource: ChannelSourceOf;