@finalai/agents 0.11.0 → 0.12.0

package/dist/modules/agent-client/conversation-resources.mjs

@@ -0,0 +1,150 @@
+import {
+  apiDecisionResponseSchema,
+  conversationContextEntryResponseSchema,
+  conversationContextListSchema,
+  conversationLabelsResponseSchema,
+  conversationReadGrantListSchema,
+  conversationReadGrantResponseSchema,
+  createConversationReadGrantRequestSchema,
+  createResourceSubscriptionRequestSchema,
+  endResourceSubscriptionResponseSchema,
+  okResponseSchema,
+  postConversationInputRequestSchema,
+  postConversationInputResponseSchema,
+  putConversationContextEntryRequestSchema,
+  raiseConversationDecisionRequestSchema,
+  resourceSubscriptionListSchema,
+  resourceSubscriptionResponseSchema,
+  setConversationLabelsRequestSchema
+} from "@finalai/agent-protocol/agent-platform";
+import * as z from "zod";
+import {
+  encodePath
+} from "./context.mjs";
+import { HttpMethod } from "./http.mjs";
+const emptyBodySchema = z.strictObject({});
+const createConversationResources = (context, conversationId) => {
+  const { http } = context;
+  const path = (suffix) => `/v1/conversations/${encodePath(conversationId)}${suffix}`;
+  const decisionPath = (decisionId, suffix = "") => path(`/decisions/${encodePath(decisionId)}${suffix}`);
+  return {
+    labels: {
+      set: async (labels, options) => (await http.request({
+        method: HttpMethod.Patch,
+        path: path("/labels"),
+        body: { schema: setConversationLabelsRequestSchema, value: { labels } },
+        response: conversationLabelsResponseSchema,
+        signal: options?.signal
+      })).labels
+    },
+    context: {
+      set: async (key, entry, options) => (await http.request({
+        method: HttpMethod.Put,
+        path: path(`/context/${encodePath(key)}`),
+        body: {
+          schema: putConversationContextEntryRequestSchema,
+          value: { role: entry.role, text: entry.text, participantId: entry.participantId }
+        },
+        response: conversationContextEntryResponseSchema,
+        signal: options?.signal
+      })).entry,
+      delete: async (key, options) => {
+        await http.request({
+          method: HttpMethod.Delete,
+          path: path(`/context/${encodePath(key)}`),
+          query: { participantId: options?.participantId },
+          response: okResponseSchema,
+          signal: options?.signal
+        });
+      },
+      list: async (options) => (await http.request({
+        method: HttpMethod.Get,
+        path: path("/context"),
+        response: conversationContextListSchema,
+        signal: options?.signal
+      })).entries
+    },
+    readGrants: {
+      create: async ({ signal, ...value }) => (await http.request({
+        method: HttpMethod.Post,
+        path: path("/read-grants"),
+        body: { schema: createConversationReadGrantRequestSchema, value },
+        response: conversationReadGrantResponseSchema,
+        signal
+      })).grant,
+      list: async (options) => (await http.request({
+        method: HttpMethod.Get,
+        path: path("/read-grants"),
+        response: conversationReadGrantListSchema,
+        signal: options?.signal
+      })).grants,
+      revoke: async ({ grantId, signal }) => (await http.request({
+        method: HttpMethod.Delete,
+        path: path(`/read-grants/${encodePath(grantId)}`),
+        response: conversationReadGrantResponseSchema,
+        signal
+      })).grant
+    },
+    inputs: {
+      send: async ({ signal, idempotencyKey, ...value }) => (await http.request({
+        method: HttpMethod.Post,
+        path: path("/inputs"),
+        body: {
+          schema: postConversationInputRequestSchema,
+          value: { ...value, idempotencyKey: idempotencyKey ?? context.newKey() }
+        },
+        response: postConversationInputResponseSchema,
+        signal
+      })).input
+    },
+    decisions: {
+      raise: async ({ signal, ...value }) => (await http.request({
+        method: HttpMethod.Post,
+        path: path("/decisions"),
+        body: { schema: raiseConversationDecisionRequestSchema, value },
+        response: apiDecisionResponseSchema,
+        signal
+      })).decision,
+      get: async ({ decisionId, signal }) => (await http.request({
+        method: HttpMethod.Get,
+        path: decisionPath(decisionId),
+        response: apiDecisionResponseSchema,
+        signal,
+        context: { decisionId }
+      })).decision,
+      cancel: async ({ decisionId, signal }) => (await http.request({
+        method: HttpMethod.Post,
+        path: decisionPath(decisionId, "/cancel"),
+        body: { schema: emptyBodySchema, value: {} },
+        response: apiDecisionResponseSchema,
+        signal,
+        context: { decisionId }
+      })).decision
+    },
+    resourceSubscriptions: {
+      list: async (options) => (await http.request({
+        method: HttpMethod.Get,
+        path: path("/resource-subscriptions"),
+        response: resourceSubscriptionListSchema,
+        signal: options?.signal
+      })).subscriptions,
+      create: async ({ signal, ...value }) => (await http.request({
+        method: HttpMethod.Post,
+        path: path("/resource-subscriptions"),
+        body: { schema: createResourceSubscriptionRequestSchema, value },
+        response: resourceSubscriptionResponseSchema,
+        signal
+      })).subscription,
+      delete: async ({ resourceKey, signal }) => (await http.request({
+        method: HttpMethod.Delete,
+        path: path(`/resource-subscriptions/${encodePath(resourceKey)}`),
+        response: endResourceSubscriptionResponseSchema,
+        signal
+      })).ended
+    }
+  };
+};
+export {
+  createConversationResources
+};
+//# sourceMappingURL=conversation-resources.mjs.map

package/dist/modules/agent-client/conversation-resources.mjs.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../../../../../src/agent-client/conversation-resources.ts"],
+  "sourcesContent": ["import {\n  apiDecisionResponseSchema,\n  conversationContextEntryResponseSchema,\n  conversationContextListSchema,\n  conversationLabelsResponseSchema,\n  conversationReadGrantListSchema,\n  conversationReadGrantResponseSchema,\n  createConversationReadGrantRequestSchema,\n  createResourceSubscriptionRequestSchema,\n  endResourceSubscriptionResponseSchema,\n  okResponseSchema,\n  postConversationInputRequestSchema,\n  postConversationInputResponseSchema,\n  putConversationContextEntryRequestSchema,\n  raiseConversationDecisionRequestSchema,\n  resourceSubscriptionListSchema,\n  resourceSubscriptionResponseSchema,\n  setConversationLabelsRequestSchema,\n  type ApiDecisionIface,\n  type ConversationContextEntryIface,\n  type ConversationContextRole,\n  type ConversationReadGrantIface,\n  type CreateConversationReadGrantRequestIface,\n  type CreateResourceSubscriptionRequestIface,\n  type InputReceiptIface,\n  type PostConversationInputRequestIface,\n  type RaiseConversationDecisionRequestIface,\n  type ResourceSubscriptionIface,\n} from '@finalai/agent-protocol/agent-platform';\nimport * as z from 'zod';\nimport {\n  encodePath,\n  type ClientContextIface,\n  type EnumInput,\n  type SignalOptionsIface,\n} from \"./context.mjs\";\nimport { HttpMethod } from \"./http.mjs\";\n\n// What a caller keeps on a conversation besides its messages: labels,\n// standing context, read grants, inputs, the decisions it raises and the\n// outside resources a person follows from it.\n\nexport interface ConversationLabelsApiIface {\n  /**\n   * Sets labels in the caller's namespace (`PATCH \u2026/labels`); `null` removes a\n   * key and keys not named are kept. Needs `labels:write`. Returns every label\n   * the conversation now carries for the caller; `info()` carries them too.\n   */\n  set: (\n    labels: Record<string, string | null>,\n    options?: SignalOptionsIface,\n  ) => Promise<Record<string, string>>;\n}\n\nexport interface ConversationContextEntryInputIface {\n  role: EnumInput<ConversationContextRole>;\n  /** Delivered verbatim; the platform adds no headers. */\n  text: string;\n  /** The one agent participant it is for; omitted or null for every agent in the conversation. */\n  participantId?: string | null;\n}\n\nexport interface ConversationContextApiIface {\n  /**\n   * Creates or replaces the caller's entry `key` (`PUT \u2026/context/:key`). The\n   * agent gets the text at its next turn boundary, and again whenever it\n   * changes or the agent's context was compacted or restored.\n   */\n  set: (\n    key: string,\n    entry: ConversationContextEntryInputIface,\n    options?: SignalOptionsIface,\n  ) => Promise<ConversationContextEntryIface>;\n  /** Stops delivering an entry; the agent is told nothing (write replacement text to tell it). */\n  delete: (key: string, options?: SignalOptionsIface & { participantId?: string }) => Promise<void>;\n  /** The caller's entries. */\n  list: (options?: SignalOptionsIface) => Promise<ConversationContextEntryIface[]>;\n}\n\nexport interface ConversationReadGrantsApiIface {\n  /** Lets this conversation's agents read one message of another conversation (`POST \u2026/read-grants`). */\n  create: (\n    args: CreateConversationReadGrantRequestIface & SignalOptionsIface,\n  ) => Promise<ConversationReadGrantIface>;\n  list: (options?: SignalOptionsIface) => Promise<ConversationReadGrantIface[]>;\n  revoke: (args: { grantId: string } & SignalOptionsIface) => Promise<ConversationReadGrantIface>;\n}\n\nexport type SendInputArgsIface = Omit<PostConversationInputRequestIface, 'idempotencyKey'> & {\n  /** Redelivering the same key from the same caller and `from.id` returns the first receipt; defaults to a new key. */\n  idempotencyKey?: string;\n} & SignalOptionsIface;\n\nexport interface ConversationInputsApiIface {\n  /**\n   * Hands the conversation's agent something to act on that is not a message\n   * from a member (`POST \u2026/inputs`). The reply arrives later as the agent's\n   * message, captioned with `label` (or \"From <from.name>\").\n   */\n  send: (args: SendInputArgsIface) => Promise<InputReceiptIface>;\n}\n\nexport interface ConversationDecisionsApiIface {\n  /**\n   * Asks the audience a question card (`POST \u2026/decisions`). The caller owns\n   * the decision; raising the same `requestKey` again returns it. Its\n   * resolution arrives as a `decision.resolved` event carrying `requestKey`.\n   */\n  raise: (\n    args: RaiseConversationDecisionRequestIface & SignalOptionsIface,\n  ) => Promise<ApiDecisionIface>;\n  /** A decision the caller raised (404 for anyone else's). */\n  get: (args: { decisionId: string } & SignalOptionsIface) => Promise<ApiDecisionIface>;\n  cancel: (args: { decisionId: string } & SignalOptionsIface) => Promise<ApiDecisionIface>;\n}\n\nexport interface ResourceSubscriptionsApiIface {\n  /** The outside resources the caller's person follows from this conversation. */\n  list: (options?: SignalOptionsIface) => Promise<ResourceSubscriptionIface[]>;\n  /** Follows a resource; fails with `no_linked_channel` unless a linked channel handles it. */\n  create: (\n    args: CreateResourceSubscriptionRequestIface & SignalOptionsIface,\n  ) => Promise<ResourceSubscriptionIface>;\n  /** Stops following; resolves whether a follow ended. */\n  delete: (args: { resourceKey: string } & SignalOptionsIface) => Promise<boolean>;\n}\n\nexport interface ConversationResourcesIface {\n  labels: ConversationLabelsApiIface;\n  context: ConversationContextApiIface;\n  readGrants: ConversationReadGrantsApiIface;\n  inputs: ConversationInputsApiIface;\n  decisions: ConversationDecisionsApiIface;\n  resourceSubscriptions: ResourceSubscriptionsApiIface;\n}\n\nconst emptyBodySchema = z.strictObject({});\n\nexport const createConversationResources = (\n  context: ClientContextIface,\n  conversationId: string,\n): ConversationResourcesIface => {\n  const { http } = context;\n  const path = (suffix: string): string =>\n    `/v1/conversations/${encodePath(conversationId)}${suffix}`;\n  const decisionPath = (decisionId: string, suffix = ''): string =>\n    path(`/decisions/${encodePath(decisionId)}${suffix}`);\n  return {\n    labels: {\n      set: async (labels, options) =>\n        (\n          await http.request({\n            method: HttpMethod.Patch,\n            path: path('/labels'),\n            body: { schema: setConversationLabelsRequestSchema, value: { labels } },\n            response: conversationLabelsResponseSchema,\n            signal: options?.signal,\n          })\n        ).labels,\n    },\n    context: {\n      set: async (key, entry, options) =>\n        (\n          await http.request({\n            method: HttpMethod.Put,\n            path: path(`/context/${encodePath(key)}`),\n            body: {\n              schema: putConversationContextEntryRequestSchema,\n              value: { role: entry.role, text: entry.text, participantId: entry.participantId },\n            },\n            response: conversationContextEntryResponseSchema,\n            signal: options?.signal,\n          })\n        ).entry,\n      delete: async (key, options) => {\n        await http.request({\n          method: HttpMethod.Delete,\n          path: path(`/context/${encodePath(key)}`),\n          query: { participantId: options?.participantId },\n          response: okResponseSchema,\n          signal: options?.signal,\n        });\n      },\n      list: async (options) =>\n        (\n          await http.request({\n            method: HttpMethod.Get,\n            path: path('/context'),\n            response: conversationContextListSchema,\n            signal: options?.signal,\n          })\n        ).entries,\n    },\n    readGrants: {\n      create: async ({ signal, ...value }) =>\n        (\n          await http.request({\n            method: HttpMethod.Post,\n            path: path('/read-grants'),\n            body: { schema: createConversationReadGrantRequestSchema, value },\n            response: conversationReadGrantResponseSchema,\n            signal,\n          })\n        ).grant,\n      list: async (options) =>\n        (\n          await http.request({\n            method: HttpMethod.Get,\n            path: path('/read-grants'),\n            response: conversationReadGrantListSchema,\n            signal: options?.signal,\n          })\n        ).grants,\n      revoke: async ({ grantId, signal }) =>\n        (\n          await http.request({\n            method: HttpMethod.Delete,\n            path: path(`/read-grants/${encodePath(grantId)}`),\n            response: conversationReadGrantResponseSchema,\n            signal,\n          })\n        ).grant,\n    },\n    inputs: {\n      send: async ({ signal, idempotencyKey, ...value }) =>\n        (\n          await http.request({\n            method: HttpMethod.Post,\n            path: path('/inputs'),\n            body: {\n              schema: postConversationInputRequestSchema,\n              value: { ...value, idempotencyKey: idempotencyKey ?? context.newKey() },\n            },\n            response: postConversationInputResponseSchema,\n            signal,\n          })\n        ).input,\n    },\n    decisions: {\n      raise: async ({ signal, ...value }) =>\n        (\n          await http.request({\n            method: HttpMethod.Post,\n            path: path('/decisions'),\n            body: { schema: raiseConversationDecisionRequestSchema, value },\n            response: apiDecisionResponseSchema,\n            signal,\n          })\n        ).decision,\n      get: async ({ decisionId, signal }) =>\n        (\n          await http.request({\n            method: HttpMethod.Get,\n            path: decisionPath(decisionId),\n            response: apiDecisionResponseSchema,\n            signal,\n            context: { decisionId },\n          })\n        ).decision,\n      cancel: async ({ decisionId, signal }) =>\n        (\n          await http.request({\n            method: HttpMethod.Post,\n            path: decisionPath(decisionId, '/cancel'),\n            body: { schema: emptyBodySchema, value: {} },\n            response: apiDecisionResponseSchema,\n            signal,\n            context: { decisionId },\n          })\n        ).decision,\n    },\n    resourceSubscriptions: {\n      list: async (options) =>\n        (\n          await http.request({\n            method: HttpMethod.Get,\n            path: path('/resource-subscriptions'),\n            response: resourceSubscriptionListSchema,\n            signal: options?.signal,\n          })\n        ).subscriptions,\n      create: async ({ signal, ...value }) =>\n        (\n          await http.request({\n            method: HttpMethod.Post,\n            path: path('/resource-subscriptions'),\n            body: { schema: createResourceSubscriptionRequestSchema, value },\n            response: resourceSubscriptionResponseSchema,\n            signal,\n          })\n        ).subscription,\n      delete: async ({ resourceKey, signal }) =>\n        (\n          await http.request({\n            method: HttpMethod.Delete,\n            path: path(`/resource-subscriptions/${encodePath(resourceKey)}`),\n            response: endResourceSubscriptionResponseSchema,\n            signal,\n          })\n        ).ended,\n    },\n  };\n};\n"],
+  "mappings": "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",
+  "names": []
+}

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

@@ -1,11 +1,15 @@
 import { type ProcessInspectionRequestIface, type ProcessInspectionResultIface } from '@finalai/agent-protocol';
-import { AgentSessionState, type PostConversationEventResponseIface, type AgentRealtimeEvent, type AgentTurnPolicy, type AttachmentDownloadIface, type AttachmentUploadIface, type ContentInput, type ConversationIface, type ConversationKind, type ConversationLinkIface, type ConversationListIface, type ConversationMessageIface, type ConversationMessagesPageIface, type ConversationSandboxIface, type ConversationScheduleIface, type CreateConversationScheduleRequestIface, type DecisionsPageIface, type MessageDeliveryIface, type ParticipantIface, type ParticipantInput, type PostConversationEventRequestIface, type ReactionIface, type ReadStateIface, type RespondDecisionResponseIface, type SandboxDirectoryIface, type SandboxEditorSessionIface, type SandboxFileIface, type SandboxPathIface, type SandboxPreviewType, type SandboxSearchIface, type SearchMessagesPageIface, type UpdateConversationRequestIface, type UpdateConversationScheduleRequestIface, type UpdateParticipantRequestIface, type WireFallback } from '@finalai/agent-protocol/agent-platform';
+import { AgentSessionState, type PostConversationEventResponseIface, type AgentRealtimeEvent, type AgentTurnPolicy, type AttachmentDownloadIface, type AttachmentUploadIface, type ContentInput, type ConversationIface, type ConversationKind, type ConversationLinkIface, type ConversationListIface, type ConversationMessageIface, type ConversationMessagesPageIface, type ConversationSandboxIface, type ConversationScheduleIface, type CreateConversationScheduleRequestIface, type DecisionsPageIface, type MessageDeliveryIface, type ParticipantIface, type ActorInputIface, type ParticipantInput, type ParticipantProvideResponseIface, type PostConversationEventRequestIface, type ReactionIface, type ReadStateIface, type RespondDecisionResponseIface, type SandboxDirectoryIface, type SandboxEditorSessionIface, type SandboxFileIface, type SandboxPathIface, type SandboxPreviewType, type SandboxSearchIface, type SearchMessagesPageIface, type UpdateConversationRequestIface, type UpdateConversationScheduleRequestIface, type UpdateParticipantRequestIface, type WireFallback } from '@finalai/agent-protocol/agent-platform';
+import type { AgentInput } from "./agent-input.mjs";
+import { type ConversationResourcesIface } from "./conversation-resources.mjs";
 import { type CollectionEvent, type CollectionEventsOptionsIface } from "./collection-events.mjs";
 import { type ClientContextIface, type EnumInput, type SignalOptionsIface } from "./context.mjs";
+import { type ProvideIface, type ProvidePatchIface } from "./provide.mjs";
 import { type RespondArgs } from "./sessions.mjs";
+import { type AgentStartDepsIface } from "./start.mjs";
 export interface SandboxFileContentArgsIface {
     snapshotId?: string;
-    bindingId: string;
+    sandboxId: string;
     path: string;
     download?: boolean;
     /** One HTTP byte range, for example `bytes=1024-2047`. */
@@ -70,15 +74,37 @@ export interface SendMessageOptionsIface extends SignalOptionsIface {
     attachmentIds?: string[];
     /** When the person submitted, for the prompt-to-inference trace; defaults to now. */
     clientSubmittedAtMs?: number;
+    /** The caller's own end user posting it; API keys and app tokens only. */
+    actor?: ActorInputIface;
 }
+type RoutingModeInput = EnumInput<NonNullable<Extract<ParticipantInput, {
+    routingMode?: unknown;
+}>['routingMode']>>;
+/**
+ * A person by id, the caller's own end user (API keys and app tokens only), or
+ * an agent with what it is provided in this conversation.
+ */
 export type ParticipantCreateInput = {
     user: string;
 } | {
-    agent: string;
-    routingMode?: EnumInput<NonNullable<Extract<ParticipantInput, {
-        agent: string;
-    }>['routingMode']>>;
+    actor: ActorInputIface;
+} | {
+    /** The agent you defined, or one fetched with `project.agents.get`; never a string. */
+    agent: AgentInput;
+    routingMode?: RoutingModeInput;
+    provide: ProvideIface;
 };
+export interface ParticipantsApiIface {
+    (options?: SignalOptionsIface): Promise<ParticipantIface[]>;
+    /** An agent participant's settings: its provide document and per-chat overrides. */
+    settings: (participantId: string, options?: SignalOptionsIface) => Promise<ParticipantProvideResponseIface>;
+    /**
+     * Changes an agent participant's settings. Fails with `requirements_unmet` if
+     * the result no longer meets the agent's requirements, or
+     * `harness_unsuitable` for harness settings it cannot run on.
+     */
+    provide: (participantId: string, patch: ProvidePatchIface, options?: SignalOptionsIface) => Promise<ParticipantProvideResponseIface>;
+}
 export interface SentMessageIface {
     message: ConversationMessageIface;
     messageId: string;
@@ -102,7 +128,7 @@ export interface UploadAttachmentArgsIface extends SignalOptionsIface {
     contentType: string;
     data: Blob | ArrayBuffer;
 }
-export interface ConversationHandleIface {
+export interface ConversationHandleIface extends ConversationResourcesIface {
     /** Durable accepted prompt receipts for a message, including queued deliveries once admitted. */
     deliveries: (args: {
         messageId: string;
@@ -162,7 +188,7 @@ export interface ConversationHandleIface {
         reason?: string;
         throughMessageSeq?: number;
     }) => Promise<void>;
-    participants: (options?: SignalOptionsIface) => Promise<ParticipantIface[]>;
+    participants: ParticipantsApiIface;
     /**
      * Each agent participant's session state, read now: whether a turn is
      * running in it. What a client re-reads when it may have missed a
@@ -202,48 +228,48 @@ export interface ConversationHandleIface {
      * Never starts a parked sandbox.
      */
     sandboxes: (options?: SignalOptionsIface) => Promise<ConversationSandboxIface[]>;
-    /** One directory of a running sandbox, confined to its workspace (`…/sandboxes/:bindingId/files`). */
+    /** One directory of a running sandbox, confined to its workspace (`…/sandboxes/:sandboxId/files`). */
     sandboxFiles: (args: {
-        bindingId: string;
+        sandboxId: string;
         path?: string;
         snapshotId?: string;
     }, options?: SignalOptionsIface) => Promise<SandboxDirectoryIface>;
     /** Resolves a file or directory without waking its sandbox. */
     sandboxPath: (args: {
-        bindingId: string;
+        sandboxId: string;
         path?: string;
         snapshotId?: string;
     }, options?: SignalOptionsIface) => Promise<SandboxPathIface>;
     /** Bounded recursive path search; truncated signals incomplete traversal. */
     searchSandboxFiles: (args: {
-        bindingId: string;
+        sandboxId: string;
         path?: string;
         query: string;
         limit?: number;
     }, options?: SignalOptionsIface) => Promise<SandboxSearchIface>;
-    /** A byte range of a file in a running sandbox, at most 1 MiB (`…/sandboxes/:bindingId/file`). */
+    /** A byte range of a file in a running sandbox, at most 1 MiB (`…/sandboxes/:sandboxId/file`). */
     sandboxFile: (args: {
-        bindingId: string;
+        sandboxId: string;
         path: string;
         offset?: number;
         length?: number;
         snapshotId?: string;
     }, options?: SignalOptionsIface) => Promise<SandboxFileIface>;
     inspectSandboxProcesses(args: {
-        bindingId: string;
+        sandboxId: string;
         request: ProcessInspectionRequestIface;
     }, options?: SignalOptionsIface): Promise<ProcessInspectionResultIface>;
     /** Opens a provider editor for an existing workspace, with write authorization. */
     openSandboxEditor(args: {
-        bindingId: string;
+        sandboxId: string;
     }, options?: SignalOptionsIface): Promise<SandboxEditorSessionIface>;
     refreshSandboxEditor(args: {
-        bindingId: string;
+        sandboxId: string;
         editorId: string;
         authorizationId: string;
     }, options?: SignalOptionsIface): Promise<SandboxEditorSessionIface>;
     closeSandboxEditor(args: {
-        bindingId: string;
+        sandboxId: string;
         editorId: string;
         authorizationId: string;
     }, options?: SignalOptionsIface & {
@@ -259,12 +285,12 @@ export interface ConversationHandleIface {
     sandboxFileContentRequest: (args: SandboxFileContentArgsIface) => Promise<SandboxFileContentRequestIface>;
     /** A short-lived screen preview of a running sandbox; 404 when it serves none (`…/preview`). */
     sandboxPreview: (args: {
-        bindingId: string;
+        sandboxId: string;
         viewOnly?: boolean;
     }, options?: SignalOptionsIface) => Promise<SandboxPreviewType>;
     /** Starts a parked sandbox (conversation owners and admins; `POST …/wake`). */
     wakeSandbox: (args: {
-        bindingId: string;
+        sandboxId: string;
     }, options?: SignalOptionsIface) => Promise<ConversationSandboxIface>;
     /** The conversation's runtime schedules: reminders and recurring checks (`GET …/schedules`). */
     schedules: (options?: SignalOptionsIface) => Promise<ConversationScheduleIface[]>;
@@ -314,15 +340,63 @@ export interface OpenedConversationIface extends ConversationHandleIface {
 }
 export interface CreateConversationArgsIface extends SignalOptionsIface {
     /**
-     * The project (`prj_...`) a signed-in person creates a group chat in (editors only).
-     * Omitted: their personal project. Project API keys cannot create person-owned chats.
-     * A direct chat is the caller's own and lives in their personal project.
+     * A conversation id you chose, so whatever you create for it first (a sandbox
+     * it owns) can name it. Creating with an id that exists returns that conversation.
      */
-    projectId?: string;
+    id?: string;
     kind: EnumInput<ConversationKind>;
     title?: string;
     participants: ParticipantCreateInput[];
     turnPolicy?: EnumInput<AgentTurnPolicy>;
+    /** Shared by the conversation's agents; each participant's own `provide` wins per key. */
+    provide?: ProvideIface;
+    /**
+     * Direct only. True (the default): the person's one direct conversation with
+     * the agent in this project, found or created. False: another private 1:1
+     * thread, created on every call (a retry with the same `id` returns it).
+     */
+    primary?: boolean;
+    /** Written with the conversation in the caller's namespace; needs `labels:write`. */
+    labels?: Record<string, string>;
+    /** The caller's own end user creating it; API keys and app tokens only. */
+    actor?: ActorInputIface;
+}
+export interface ProjectConversationsApiIface extends ConversationsApiIface {
+    /**
+     * Creates a conversation in this project. Fails with `requirements_unmet`,
+     * creating nothing, unless each agent's requirements are met.
+     */
+    create: (args: CreateConversationArgsIface) => Promise<OpenedConversationIface>;
+    /**
+     * The caller's own Home thread with the project's agent, found or created.
+     * `provide` is stored only when the agent has no settings there yet.
+     */
+    home: (args: {
+        id?: string;
+        provide: ProvideIface;
+    } & SignalOptionsIface) => Promise<OpenedConversationIface>;
+    /** The caller's Home thread, if there is one. Creates nothing. */
+    findHome: (options?: SignalOptionsIface) => Promise<ConversationIface | null>;
+    /**
+     * The caller's direct conversation with an agent, found or created.
+     * `provide` is stored only when the agent has no settings there yet.
+     */
+    direct: (args: {
+        id?: string;
+        agent: AgentInput;
+        provide: ProvideIface;
+        /** The caller's own end user whose direct conversation it is; API keys and app tokens only. */
+        actor?: ActorInputIface;
+    } & SignalOptionsIface) => Promise<OpenedConversationIface>;
+    /**
+     * The caller's primary direct conversation with an agent (by its id), if
+     * there is one. Creates nothing. `actorExternalId` names the caller's own end
+     * user (API keys and app tokens only).
+     */
+    findDirect: (args: {
+        agent: string;
+        actorExternalId?: string;
+    } & SignalOptionsIface) => Promise<ConversationIface | null>;
 }
 export interface ConversationsApiIface {
     /**
@@ -335,19 +409,11 @@ export interface ConversationsApiIface {
         limit?: number;
         includeArchived?: boolean;
         projectId?: string;
+        /** With `projectId`: false leaves out the projects below it. */
+        includeSubprojects?: boolean;
+        /** Only conversations carrying every one of these labels in the caller's namespace. */
+        labels?: Record<string, string>;
     }) => Promise<ConversationListIface>;
-    /** Finds or creates the caller's direct conversation with an agent. */
-    direct: (args: {
-        agent: string;
-    } & SignalOptionsIface) => Promise<OpenedConversationIface>;
-    /**
-     * Finds or creates the caller's own Project Agent thread in `projectId`, which
-     * omitted, is the signed-in person's personal project. Requires person authority.
-     */
-    home: (options?: SignalOptionsIface & {
-        projectId?: string;
-    }) => Promise<OpenedConversationIface>;
-    create: (args: CreateConversationArgsIface) => Promise<OpenedConversationIface>;
     /** I/O-free handle. */
     get: (conversationId: string) => ConversationHandleIface;
     /** Full-text search over the caller's conversations (or one), newest first. */
@@ -403,5 +469,17 @@ export declare const messageVersionOf: (message: ConversationMessageIface) => Me
  * time, and equal times fall back to content.
  */
 export declare const isNewerMessageVersion: (incoming: MessageVersionIface, current: MessageVersionIface | undefined) => boolean;
-export declare const createConversationHandle: (context: ClientContextIface, conversationId: string) => ConversationHandleIface;
-export declare const createConversationsApi: (context: ClientContextIface) => ConversationsApiIface;
+/** How a conversation handle starts the agents added to it. */
+export interface ConversationStarterIface {
+    deps: AgentStartDepsIface;
+    /** Null for handles made outside a project, which cannot serve local compute. */
+    projectId: string | null;
+}
+export declare const createConversationHandle: (context: ClientContextIface, conversationId: string, starter: ConversationStarterIface) => ConversationHandleIface;
+export declare const createConversationsApi: (context: ClientContextIface, starter: ConversationStarterIface) => ConversationsApiIface;
+export declare const createProjectConversationsApi: (args: {
+    context: ClientContextIface;
+    projectId: string;
+    start: AgentStartDepsIface;
+}) => ProjectConversationsApiIface;
+export {};