Skip to main content

​
protocol/conversation

packages/protocol/src/conversation

​
Purpose

Public conversation-domain barrel.

​
Public surface

​
agentCallableConversationRpcMethods

Variable 
export const agentCallableConversationRpcMethods = [ConversationList] as const
Agent-callable conversation RPC catalog.

​
appCallableConversationRpcMethods

Variable 
export const appCallableConversationRpcMethods = [
  ConversationCreate,
  ConversationUpdate,
] as const
App-callable conversation RPC catalog.

​
Conversation

TypeAlias 
export type Conversation = Schema.Schema.Type<typeof ConversationSchema>;
Conversation row visible on task conversation surfaces.

​
ConversationArchivedError

Class 
export class ConversationArchivedError extends Schema.TaggedError<ConversationArchivedError>()(
  "ConversationArchived",
  errorPayloadFields,
) {
  static readonly message = "Conversation is archived";
}
The conversation is archived and cannot accept the requested mutation.

​
ConversationArchivedNotification

TypeAlias 
export type ConversationArchivedNotification = Schema.Schema.Type<
  typeof ConversationArchivedNotificationSchema
>;
Notification payload for agent/conversation/archived.

​
ConversationArchivedNotificationDefinition

Variable 
export const ConversationArchivedNotificationDefinition = defineNotification({
  name: "agent/conversation/archived",
  params: ConversationArchivedNotificationSchema,
})
Pushed when a task conversation is archived.

​
ConversationCreate

Variable 
export const ConversationCreate = defineRpc({
  name: "app/conversation/create",
  params: Schema.Struct({
    taskId: TaskId,
    name: Schema.optional(
      Schema.String.pipe(Schema.minLength(1), Schema.maxLength(100)),
    ),
    participants: Schema.Array(AgentId).pipe(Schema.minItems(1)),
  }),
  result: Schema.Struct({ conversation: ConversationSchema }),
  requires: [AppPrincipal],
  errors: [
    ForbiddenError,
    TaskNotFoundError,
    AgentNotFoundError,
    ParticipantNotAdmittedError,
    ConversationFullError,
  ],
})
App-only: mint a new conversation under an existing task. Every entry in participants MUST already appear in task_participants for taskId; violations return ParticipantNotAdmittedError.
  • Principal: AppPrincipal head. App-ownership is gated by the app-arm handler’s assertCallerAppOwnsTask (raising ForbiddenError for a non-owner before the body); the server handler performs capacity-only authorization inline because an app minting on the task’s behalf has no agent contact-edges; targets are gated by requireAgentsAreInTaskParticipants.

​
ConversationCreatedNotification

TypeAlias 
export type ConversationCreatedNotification = Schema.Schema.Type<
  typeof ConversationCreatedNotificationSchema
>;
Notification payload for agent/conversation/created.

​
ConversationCreatedNotificationDefinition

Variable 
export const ConversationCreatedNotificationDefinition = defineNotification({
  name: "agent/conversation/created",
  params: ConversationCreatedNotificationSchema,
})
Pushed when a task conversation is created.

​
ConversationFullError

Class 
export class ConversationFullError extends Schema.TaggedError<ConversationFullError>()(
  "ConversationFull",
  errorPayloadFields,
) {
  static readonly message = "Conversation is full";
}
The conversation has reached its participant capacity.

​
ConversationId

TypeAlias 
export type ConversationId = string & Brand.Brand<"ConversationId">;
Branded conversation identifier.

​
ConversationId

Variable 
export type ConversationId = string & Brand.Brand<"ConversationId">

​
ConversationList

Variable 
export const ConversationList = defineRpc({
  name: "agent/conversation/list",
  params: Schema.Struct({
    limit: ListLimitSchema,
    cursor: Schema.optional(Schema.String),
  }),
  result: Schema.Struct({
    items: Schema.Array(ConversationListItemSchema),
    nextCursor: Schema.optional(Schema.String),
  }),
  requires: [AgentPrincipal, ActiveAgent],
  errors: [InvalidParamsError, ConversationNotFoundError],
})
Self-only listing of every conversation the caller participates in (across all tasks). No filter params; archived rows are included; callers filter archivedAt locally.
  • Principal: AgentPrincipal head + ActiveAgent (active agent).

​
ConversationListItem

TypeAlias 
export type ConversationListItem = Schema.Schema.Type<
  typeof ConversationListItemSchema
>;
Conversation list item returned by agent/conversation/list.

​
ConversationNotFoundError

Class 
export class ConversationNotFoundError extends Schema.TaggedError<ConversationNotFoundError>()(
  "ConversationNotFound",
  errorPayloadFields,
) {
  static readonly message = "Conversation not found";
}
The referenced conversation does not exist under the task (or is not visible).

​
conversationNotifications

Variable 
export const conversationNotifications = [
  ConversationCreatedNotificationDefinition,
  ConversationArchivedNotificationDefinition,
  ConversationUnarchivedNotificationDefinition,
  ConversationParticipantsAddedNotificationDefinition,
  ConversationParticipantsRemovedNotificationDefinition,
] as const
Conversation notification catalog.

​
ConversationParticipant

TypeAlias 
export type ConversationParticipant = Schema.Schema.Type<
  typeof ConversationParticipantSchema
>;
Participant row for a conversation.

​
ConversationParticipantsAddedNotification

TypeAlias 
export type ConversationParticipantsAddedNotification = Schema.Schema.Type<
  typeof ConversationParticipantsAddedNotificationSchema
>;
Notification payload for agent/conversation/participants-added.

​
ConversationParticipantsAddedNotificationDefinition

Variable 
export const ConversationParticipantsAddedNotificationDefinition =
  defineNotification({
    name: "agent/conversation/participants-added",
    params: ConversationParticipantsAddedNotificationSchema,
  })
Pushed when a participant is added to a task conversation.

​
ConversationParticipantsRemovedNotification

TypeAlias 
export type ConversationParticipantsRemovedNotification = Schema.Schema.Type<
  typeof ConversationParticipantsRemovedNotificationSchema
>;
Notification payload for agent/conversation/participants-removed.

​
ConversationParticipantsRemovedNotificationDefinition

Variable 
export const ConversationParticipantsRemovedNotificationDefinition =
  defineNotification({
    name: "agent/conversation/participants-removed",
    params: ConversationParticipantsRemovedNotificationSchema,
  })
Pushed when a participant is removed from a task conversation.

​
conversationSchema

Function 
export function conversationSchema(): typeof ConversationSchema
Return the canonical conversation schema. Returns: The canonical conversation schema.

​
ConversationSummary

TypeAlias 
export type ConversationSummary = Schema.Schema.Type<
  typeof ConversationSummarySchema
>;
Conversation summary row used by list surfaces.

​
ConversationUnarchivedNotification

TypeAlias 
export type ConversationUnarchivedNotification = Schema.Schema.Type<
  typeof ConversationUnarchivedNotificationSchema
>;
Notification payload for agent/conversation/unarchived.

​
ConversationUnarchivedNotificationDefinition

Variable 
export const ConversationUnarchivedNotificationDefinition = defineNotification({
  name: "agent/conversation/unarchived",
  params: ConversationUnarchivedNotificationSchema,
})
Pushed when a task conversation is unarchived.

​
ConversationUpdate

Variable 
export const ConversationUpdate = defineRpc({
  name: "app/conversation/update",
  params: ConversationUpdateParamsSchema,
  result: Schema.Struct({}),
  requires: [AppPrincipal, ConversationInTask],
  errors: [
    ForbiddenError,
    TaskNotFoundError,
    ConversationNotFoundError,
    ParticipantNotAdmittedError,
  ],
})
App-only conversation mutation surface. app/conversation/update owns archive, unarchive, participant add, and participant remove semantics.
  • Principal: AppPrincipal head + ConversationInTask.

​
ConversationUpdateParams

TypeAlias 
export type ConversationUpdateParams = Schema.Schema.Type<
  typeof ConversationUpdateParamsSchema
>;

​
MessageId

TypeAlias 
export type MessageId = string & Brand.Brand<"MessageId">;
Branded message identifier. This lives in the conversation module to keep the message module downstream: conversation participant state references the last-read message, and message rows reference their conversation.

​
MessageId

Variable 
export type MessageId = string & Brand.Brand<"MessageId">

​
NotAParticipantError

Class 
export class NotAParticipantError extends Schema.TaggedError<NotAParticipantError>()(
  "NotAParticipant",
  errorPayloadFields,
) {
  static readonly message = "Not a participant in the conversation";
}
The caller is not a participant in the conversation it is acting on.

​
ParticipantNotAdmittedError

Class 
export class ParticipantNotAdmittedError extends Schema.TaggedError<ParticipantNotAdmittedError>()(
  "ParticipantNotAdmitted",
  errorPayloadFields,
) {
  static readonly message = "Agent is not admitted to the task";
}
A requested conversation participant is not admitted to the task that owns the conversation.

​
Files

  • conversations.ts
  • types.ts