@finalai/agents 0.11.0 → 0.13.0

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 ScheduleRunResultIface, 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[]>;
@@ -281,6 +307,10 @@ export interface ConversationHandleIface {
     deleteSchedule: (args: {
         scheduleId: string;
     }, options?: SignalOptionsIface) => Promise<void>;
+    /** Fires a schedule now (`POST …/schedules/:id/run-now`, needs `agents:execute`). */
+    runSchedule: (args: {
+        scheduleId: string;
+    }, options?: SignalOptionsIface) => Promise<ScheduleRunResultIface>;
     /**
      * The conversations this one handed work to, with what their agents are
      * doing (`GET …/links`). Their replies and waits arrive here as messages.
@@ -314,15 +344,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 +413,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 +473,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 {};