Macro is a unified workspace for teams: email, chat, docs, tasks, agents, calls, and CRM — @-linked together with shared AI memory.
TypeScript agentaiai-agentsall-in-onecrmcrm-systememaillinearmcpmessagingnotesnotionofficerustslackslack-alternativestartupstartup-toolstypescriptworkspace
// This file has been generated by Specta. Do not edit this file manually.
/** What a step put in front of the person. */
export type ActivityCard = ActivityCard_Serialize | ActivityCard_Deserialize;
/** What a step put in front of the person. */
export type ActivityCard_Deserialize =
/**
* A view the agent presented: the `view` of a presented `PresentView`
* call. Its widgets name the items they show, and readers load those
* with their own access.
*/
{ kind: "view";
/** The dynamic-UI view. */
view: View_Deserialize };
/** What a step put in front of the person. */
export type ActivityCard_Serialize =
/**
* A view the agent presented: the `view` of a presented `PresentView`
* call. Its widgets name the items they show, and readers load those
* with their own access.
*/
{ kind: "view";
/** The dynamic-UI view. */
view: View_Serialize };
/** One step of work, worded for a person reading a conversation. */
export type ActivityRow = ActivityRow_Serialize | ActivityRow_Deserialize;
/** One step of work, worded for a person reading a conversation. */
export type ActivityRow_Deserialize = {
/** The tool call's id, stable across updates; `plan` for a plan update. */
id: string,
/** What happened, as a verb phrase: `Ran`, `Reading`, `Search documents`. */
label: string,
/**
* What it happened to - a command, a file, a query - when that is safe
* to show to everyone who can read the conversation.
*/
detail: string | null,
/** Where it got to. */
status: ActivityStatus,
/** What the step put in front of the person, shown where it ran. */
card?: ActivityCard_Deserialize | null,
};
/** One step of work, worded for a person reading a conversation. */
export type ActivityRow_Serialize = {
/** The tool call's id, stable across updates; `plan` for a plan update. */
id: string,
/** What happened, as a verb phrase: `Ran`, `Reading`, `Search documents`. */
label: string,
/**
* What it happened to - a command, a file, a query - when that is safe
* to show to everyone who can read the conversation.
*/
detail: string | null,
/** Where it got to. */
status: ActivityStatus,
/** What the step put in front of the person, shown where it ran. */
card: ActivityCard_Serialize | null,
};
/** Where one step of work got to. */
export type ActivityStatus =
/** Started and not finished, including a call waiting on permission. */
"running" |
/** Finished successfully. */
"completed" |
/** Finished unsuccessfully. */
"failed" |
/** Still running when its turn ended: nobody knows whether it finished. */
"interrupted";
/** A calendar event an agenda lists. */
export type AgendaEvent = AgendaEvent_Serialize | AgendaEvent_Deserialize;
/** A calendar event an agenda lists. */
export type AgendaEvent_Deserialize = {
/** The eventId a calendar tool such as ListCalendarEvents returned. */
eventId: string,
/**
* One instance of a recurring event: that instance's recurrenceId from
* ListCalendarEvents.
*/
occurrenceKey?: string,
};
/** A calendar event an agenda lists. */
export type AgendaEvent_Serialize = {
/** The eventId a calendar tool such as ListCalendarEvents returned. */
eventId: string,
/**
* One instance of a recurring event: that instance's recurrenceId from
* ListCalendarEvents.
*/
occurrenceKey?: string,
};
/**
* The JSON-RPC id of a request the agent made, as the agent wrote it.
*
* Kept in the agent's own shape - a number stays a number - because an
* answer has to echo it exactly; `"7"` does not answer `7`.
*/
export type AgentRequestId =
/**
* A numeric id. Exported as a plain TypeScript number: agents count
* requests from zero, nowhere near where an `i64` stops round-tripping.
*/
number |
/** A string id. */
string;
/** How a container aligns its children across its axis. */
export type Align = "start" | "center" | "end" | "stretch";
/**
* Terminal output with ANSI escape sequences left in place.
*
* Stripping here would be lossy and irreversible, and the escapes carry real
* information - the recordings are full of colorized `ls` and `grep` output.
* Rendering decides whether to interpret, strip, or ignore them.
*/
export type AnsiText = string;
/**
* A chosen option, with the title it was offered under when the schema gave
* one. `title` is `None` for a value no option declared.
*/
export type AnsweredChoice = {
/** The value submitted. */
value: string,
/** The label it was offered under. */
title: string | null,
};
/**
* One property's answer, resolved against the schema that asked for it.
*
* The correlation happens here so that no client repeats it: an option's
* title is looked up where the options live, and the harness "Other" idiom -
* a free-text answer arriving under a *different* key than the property it
* replaces, sometimes alongside the choice it replaces (see the
* `elicitation_claude_single_select` fixture, which carries both) - collapses
* to a single [`AnsweredValue::Custom`].
*/
export type AnsweredField = {
/**
* The property this answers, or the key it arrived under when no
* property claimed it.
*/
name: string,
/** What to show as the label: the property's title, else its name. */
label: string,
/** The answer. */
value: AnsweredValue,
};
/** An answer's value, in the vocabulary the property declared. */
export type AnsweredValue =
/** Free text. */
{ kind: "text";
/** The text as submitted. */
text: string } |
/**
* A number, whole or not, exactly as it was submitted.
*
* Text rather than `f64`: a JSON integer can outrun `f64`'s exact range,
* and `f64` has a `number | null` TypeScript face because a non-finite
* float serializes as null. Nothing computes with an answer - it is
* rendered - so the digits are what matter.
*/
{ kind: "number";
/** The number as written. */
text: string } |
/** A yes/no. */
{ kind: "boolean";
/** Whether it was checked. */
checked: boolean } |
/** One of the offered options. */
{ kind: "choice";
/** The option chosen, with the title it was offered under. */
choice: AnsweredChoice } |
/** Several of the offered options. */
{ kind: "choices";
/** The options chosen, in the order they were submitted. */
choices: AnsweredChoice[] } |
/**
* The free-text escape: the user typed their own answer instead of
* picking, and it arrived under the property's `customField`.
*/
{ kind: "custom";
/** What they typed. */
text: string } |
/**
* A value this fold could not read as any of the above - a nested
* object, or an array of something other than strings.
*/
{ kind: "unrecognized";
/** The value, verbatim. */
raw: unknown };
/** Who produced a [`FoldedMessage`]. */
export type Author =
/**
* A person, via `session/prompt`.
*
* The id comes from the log row rather than the ACP payload, and is
* absent when the prompt was not attributed to a user.
*/
{ kind: "user";
/** The attributed user's id. */
userId: string | null } |
/** The agent. */
{ kind: "agent" };
/**
* One slash command the harness advertises.
*
* Mirrors ACP's `AvailableCommand`, flattened: the only input shape ACP
* defines today is "unstructured text after the name," so the hint is
* carried directly rather than through a nested enum.
*/
export type AvailableCommand = {
/**
* Bare name as advertised (`"qc"`, `"honeycomb:query-patterns"`) - no
* leading slash, which is client syntax rather than part of the name.
*/
name: string,
/** Human-readable description, verbatim from the harness. */
description: string,
/** Placeholder text for the command's input, when it takes any. */
inputHint: string | null,
};
/** Whether a call was attended. */
export type CallStatus = "ATTENDED" | "MISSED" | "UNATTENDED";
/** A workspace item a card shows. */
export type CardItem = {
type: CardItemType,
/**
* The item's id exactly as a tool returned it: a document id (documents
* and spreadsheets), an email thread id, a calendar eventId, or a
* project, channel, routine, form or initiative id.
*/
id: string,
};
/** The kinds of workspace item a card shows. */
export type CardItemType = "document" | "email_thread" | "calendar_event" | "project" | "channel" | "routine" | "form" | "initiative";
/** A session control operation shown in the conversation timeline. */
export type Control =
/** The runtime was asked to switch models. */
{ kind: "set_model";
/** The model slug requested by the caller. */
model: string } |
/** The runtime was asked to change an advertised session setting. */
{ kind: "set_config_option";
/** Opaque config id supplied by the runtime. */
config_id: string;
/** Opaque select value requested by the caller. */
value: string } |
/** The runtime was asked to compact its context. */
{ kind: "compact" } |
/** The runtime was asked to stop its current work. */
{ kind: "stop" };
/**
* How the runtime disposed of a [`Control`], like [`PermissionOutcome`] for
* permission requests. Pending is a legitimate final state: a control the
* session died before answering stays pending.
*/
export type ControlOutcome =
/** No response yet. */
{ kind: "pending" } |
/** Acknowledged - immediately so for a stop, which nothing can answer. */
{ kind: "accepted" } |
/** Answered with a JSON-RPC error. */
{ kind: "rejected";
/** The error's message, verbatim. */
message: string };
/** Bounds on a timestamp, as ISO 8601 strings. */
export type DateRangeFilter = DateRangeFilter_Serialize | DateRangeFilter_Deserialize;
/** Bounds on a timestamp, as ISO 8601 strings. */
export type DateRangeFilter_Deserialize = {
gt?: string,
gte?: string,
lt?: string,
lte?: string,
};
/** Bounds on a timestamp, as ISO 8601 strings. */
export type DateRangeFilter_Serialize = {
gt?: string,
gte?: string,
lt?: string,
lte?: string,
};
/** Overall review decision. */
export type DecisionOutcome =
/** All selected actions were approved. */
"approved" |
/** All selected items were dismissed. */
"dismissed" |
/** The batch contains mixed or unconfirmed results. */
"partial";
/** Surface of a review decision. */
export type DecisionVia =
/** Review card. */
"card" |
/** Owner request in chat. */
"chat" |
/** Inbox action. */
"inbox";
/** The axis a container lays its children along. */
export type Direction = "row" | "col";
/** The filters that apply to documents. */
export type DocumentFieldFilters = DocumentFieldFilters_Serialize | DocumentFieldFilters_Deserialize;
/** The filters that apply to documents. */
export type DocumentFieldFilters_Deserialize = {
documentId?: string[],
fileType?: string[],
fileAssoc?: string[],
subType?: string[],
projectId?: string[],
documentOwnerId?: string[],
documentSeen?: boolean,
documentDone?: boolean,
/** For tasks, whether the current user is an assignee. */
documentImportance?: boolean,
isEmailAttachment?: boolean,
documentCreatedAt?: DateRangeFilter_Deserialize,
documentUpdatedAt?: DateRangeFilter_Deserialize,
};
/** The filters that apply to documents. */
export type DocumentFieldFilters_Serialize = {
documentId?: string[],
fileType?: string[],
fileAssoc?: string[],
subType?: string[],
projectId?: string[],
documentOwnerId?: string[],
documentSeen?: boolean,
documentDone?: boolean,
/** For tasks, whether the current user is an assignee. */
documentImportance?: boolean,
isEmailAttachment?: boolean,
documentCreatedAt?: DateRangeFilter_Serialize,
documentUpdatedAt?: DateRangeFilter_Serialize,
};
/** Documents to include and exclude. */
export type DocumentFilterClause = DocumentFilterClause_Serialize | DocumentFilterClause_Deserialize;
/** Documents to include and exclude. */
export type DocumentFilterClause_Deserialize = {
include?: DocumentFieldFilters_Deserialize,
exclude?: DocumentFieldFilters_Deserialize,
};
/** Documents to include and exclude. */
export type DocumentFilterClause_Serialize = {
include?: DocumentFieldFilters_Serialize,
exclude?: DocumentFieldFilters_Serialize,
};
/** Document filter expressions combined. */
export type DocumentFilterCombination = DocumentFilterCombination_Serialize | DocumentFilterCombination_Deserialize;
/** Document filter expressions combined. */
export type DocumentFilterCombination_Deserialize = ({ op: "and"; clauses: DocumentFilterExpression_Deserialize[] }) & { clause?: never } | ({ op: "or"; clauses: DocumentFilterExpression_Deserialize[] }) & { clause?: never } | ({ op: "not"; clause: DocumentFilterExpression_Deserialize }) & { clauses?: never };
/** Document filter expressions combined. */
export type DocumentFilterCombination_Serialize = ({ op: "and"; clauses: DocumentFilterExpression_Serialize[] }) & { clause?: never } | ({ op: "or"; clauses: DocumentFilterExpression_Serialize[] }) & { clause?: never } | ({ op: "not"; clause: DocumentFilterExpression_Serialize }) & { clauses?: never };
/** A document filter: a clause, or clauses combined with `op`. */
export type DocumentFilterExpression = DocumentFilterExpression_Serialize | DocumentFilterExpression_Deserialize;
/** A document filter: a clause, or clauses combined with `op`. */
export type DocumentFilterExpression_Deserialize = DocumentFilterCombination_Deserialize | DocumentFilterClause_Deserialize;
/** A document filter: a clause, or clauses combined with `op`. */
export type DocumentFilterExpression_Serialize = DocumentFilterCombination_Serialize | DocumentFilterClause_Serialize;
/**
* Several document filter expressions that all apply, or one. Several comes
* first: serde reads a struct from an array too, so a clause would take one.
*/
export type DocumentWhere = DocumentWhere_Serialize | DocumentWhere_Deserialize;
/**
* Several document filter expressions that all apply, or one. Several comes
* first: serde reads a struct from an array too, so a clause would take one.
*/
export type DocumentWhere_Deserialize = DocumentFilterExpression_Deserialize[] | DocumentFilterExpression_Deserialize;
/**
* Several document filter expressions that all apply, or one. Several comes
* first: serde reads a struct from an array too, so a clause would take one.
*/
export type DocumentWhere_Serialize = DocumentFilterExpression_Serialize[] | DocumentFilterExpression_Serialize;
/** One choice in a select. */
export type ElicitationOption = {
/** The value sent back when chosen. */
value: string,
/**
* Label to show; absent for an untitled `enum`, where the value is the
* label.
*/
title: string | null,
/** Help text, when the agent gave one. */
description: string | null,
};
/**
* How an elicitation has resolved so far.
*
* [`Self::Pending`] is a legitimate final state on a dead session, like an
* unanswered permission.
*/
export type ElicitationOutcome =
/** No response has gone out yet. */
{ kind: "pending" } |
/** The user submitted the form, or consented to open the URL. */
{ kind: "accepted";
/**
* What they answered: one entry per property the schema declared and
* the content answered, in declaration order, then any key no
* property claimed. Empty for a URL consent, which carries no
* content.
*/
answers: AnsweredField[] } |
/** The user explicitly said no. */
{ kind: "declined" } |
/** The user dismissed it, or a stop cancelled it. */
{ kind: "cancelled" } |
/** URL only: the agent reported the external interaction finished. */
{ kind: "completed" } |
/**
* The response was a JSON-RPC error - including this client's own
* refusal of a request it could not hold.
*/
{ kind: "errored";
/** The error's message, verbatim. */
message: string } |
/** A result arrived that this fold could not read as an ACP action. */
{ kind: "unrecognized" };
/** One form field. */
export type ElicitationProperty = {
/** The key the answer is sent back under. */
name: string,
/** Label to show, when the agent gave one. */
title: string | null,
/** Help text, when the agent gave one. */
description: string | null,
/** The field's type and constraints. */
schema: ElicitationPropertySchema,
};
/**
* A field's type and constraints, mirroring ACP's restricted property
* schemas.
*/
export type ElicitationPropertySchema =
/** Free text, or a single choice when `options` is non-empty. */
{ type: "string";
/** Minimum length, when constrained. */
minLength: number | null;
/** Maximum length, when constrained. */
maxLength: number | null;
/**
* A regular expression the value must match. Agent-supplied, so a
* renderer must bound its evaluation.
*/
pattern: string | null;
/**
* ACP's format hint as its wire string (`email`, `uri`, `date`,
* `date-time`, or something this fold does not know).
*/
format: string | null;
/** Pre-filled value. */
default: string | null;
/** The choices, when this is a single select. Empty for free text. */
options: ElicitationOption[];
/**
* The key a free-text answer is sent under when one is accepted
* alongside `options` - the user picks a choice *or* types their
* own. A harness idiom (Claude Code's and Codex's "Other" field),
* never ACP's own; `None` for a plain select.
*/
customField: string | null } |
/** A floating-point number. */
{ type: "number";
/** Lower bound, when constrained. */
minimum: number | null;
/** Upper bound, when constrained. */
maximum: number | null;
/** Pre-filled value. */
default: number | null } |
/** A whole number. */
{ type: "integer";
/** Lower bound, when constrained. */
minimum: number | null;
/** Upper bound, when constrained. */
maximum: number | null;
/** Pre-filled value. */
default: number | null } |
/** A yes/no. */
{ type: "boolean";
/** Pre-filled value. */
default: boolean | null } |
/** Several choices from a list. */
{ type: "multi_select";
/** Fewest selections allowed, when constrained. */
minItems: number | null;
/** Most selections allowed, when constrained. */
maxItems: number | null;
/** The choices. */
options: ElicitationOption[];
/** Pre-selected values. */
default: string[];
/**
* The key a free-text answer is sent under when one is accepted
* instead of the choices. Harness idiom, `None` for a plain
* multi-select. See the `String` variant.
*/
customField: string | null } |
/**
* A property type this fold does not know. A renderer shows that it
* cannot display the field; decline and cancel still work.
*/
{ type: "unrecognized";
/** The wire `type`. */
typeName: string;
/** The property schema, verbatim. */
raw: unknown };
/** What the agent asked for. */
export type ElicitationRequest =
/** Structured data through a form the client renders. */
{ kind: "form";
/** The restricted schema describing the form. */
schema: ElicitationSchema } |
/** An out-of-band interaction the user consents to open. */
{ kind: "url";
/**
* The agent's handle for this interaction; `elicitation/complete`
* names it.
*/
elicitationId: string;
/** Where the user is sent. */
url: string } |
/**
* A Macro user tool (`SendEmail`, `CreateCalendarEvent`) paused for the
* user's review: the agent drafted the call and asks before it runs.
*
* Recognized from the call the form is scoped to - a tool this fold
* already knows as a user tool - or from `_meta.macro.userTool`, which
* Macro's own agent stamps. The draft is the call's arguments whole,
* so a client with the tool's own composer renders that and answers
* with the whole edited draft; `schema` is the flat form the agent also
* sent, for a client without one.
*/
{ kind: "user_tool";
/** The tool, by Macro's name. */
tool: string;
/** The call's arguments - the tool's own JSON. */
draft: unknown;
/** The restricted form describing the draft's flat fields. */
schema: ElicitationSchema } |
/**
* A mode this fold does not know. Kept raw so nothing is lost; a
* renderer must not treat it as form or url.
*/
{ kind: "unrecognized";
/** The wire mode. */
mode: string;
/** The request params, verbatim. */
raw: unknown };
/**
* The JSON-RPC id of an agent's `elicitation/create` request, carried whole
* so the answer echoes exactly what the agent sent.
*
* Agents pick these, not us: Claude Code counts from `0`, others use
* strings. `null` is not a legal id for a request that expects a response,
* so it is not representable here.
*/
export type ElicitationRequestId =
/**
* A numeric JSON-RPC id. Specta refuses `i64` (it does not fit a JS
* number); agents count their requests from zero, so `i32` is the
* honest TypeScript face.
*/
number |
/** A string JSON-RPC id. */
string;
/** ACP's restricted form schema: a flat object of primitive properties. */
export type ElicitationSchema = {
/** Schema-level title, when the agent gave one. */
title: string | null,
/** Schema-level description, when the agent gave one. */
description: string | null,
/** The fields, in the order the agent declared them. */
properties: ElicitationProperty[],
/** Property names the agent requires an answer for. */
required: string[],
};
/** Which shared emails to match. */
export type EmailShared = "exclude" | "include" | "only";
/** Which mailbox a query reads. */
export type EmailView = "inbox" | "drafts" | "sent" | "all";
/** A reference to a workspace item. */
export type EntityRef = {
id: string,
type: EntityType,
};
/** The kinds of workspace item a view can show. */
export type EntityType = "user" | "chat" | "channel" | "channel_message" | "document" | "project" | "email_thread" | "calendar_event" | "team" | "call" | "foreign_entity" | "static_file" | "crm_company" | "crm_contact" | "crm_pipeline" | "reminder" | "skill" | "agent_session" | "scheduled_action" | "initiative" | "database" | "database_row" | "form" | "external_chat" | "email" | "routine" | "channel_thread";
/** An external page where the person can act on a [`FailureNotice`]. */
export type FailureLink = {
/** The link's text, e.g. `Manage Cursor usage`. */
label: string,
/** The page, absolute. */
url: string,
};
/**
* A turn failure the person who prompted can act on, in their terms.
*
* A runtime attaches this to the `session/prompt` error as its `data`; the
* fold reads it back onto the failed turn's stop reason. It exists so a
* billing wall or a disconnected integration renders as an instruction with
* somewhere to go, not as the runtime's error text - and so the runtime's
* error text, which for a report includes source locations, never has to
* double as the thing a person reads.
*/
export type FailureNotice = {
/** Which class of failure, for readers that treat one specially. */
kind: FailureNoticeKind,
/** One short line naming what happened. */
title: string,
/** What it means and what to do, in plain language. */
body: string,
/** Where acting on it happens, when that is somewhere else. */
link?: FailureLink | null,
};
/** The classes of actionable failure a runtime can report. */
export type FailureNoticeKind =
/**
* The person's own account with the provider has no budget left for
* this work; the fix is on the provider's billing page.
*/
"provider_usage_limit" |
/** The selected model cannot read image attachments in this conversation. */
"unsupported_image_input" |
/**
* The provider ended the run in failure; its own page for the run is
* where any detail it kept lives.
*/
"provider_run_failed" |
/**
* The runtime accepted the prompt but never handed it to the agent;
* the fix is to send it again.
*/
"prompt_not_delivered";
/**
* Every filter, each over one field of one kind of item. Id lists match any
* of their ids.
*/
export type FieldFilters = FieldFilters_Serialize | FieldFilters_Deserialize;
/**
* Every filter, each over one field of one kind of item. Id lists match any
* of their ids.
*/
export type FieldFilters_Deserialize = {
calendarEventId?: string[],
threadId?: string[],
emailLinkId?: string[],
emailProjectId?: string[],
emailSender?: string[],
channelId?: string[],
channelType?: string[],
/**
* Membership states to match: `[true]` for channels the user is in,
* `[true, false]` to also match team channels they have not joined.
*/
channelIsParticipant?: boolean[],
channelSenderId?: string[],
channelMessageThreadId?: string[],
channelThreadId?: string[],
channelThreadRootSenderId?: string[],
channelThreadParticipantId?: string[],
agentSessionId?: string[],
agentSessionOwnerId?: string[],
chatId?: string[],
chatOwnerId?: string[],
chatProjectId?: string[],
folderId?: string[],
folderOwnerId?: string[],
callId?: string[],
callChannelId?: string[],
callSpeakerId?: string[],
foreignEntityRecordId?: string[],
foreignEntitySource?: string[],
crmCompanyId?: string[],
/** Property values to match; distinct properties all apply. */
properties?: PropertyFilter[],
/** Selected tags, combined by `tagFilterMode`. */
tagFilters?: PropertyFilter[],
tagFilterMode?: TagFilterMode,
emailSeen?: boolean,
emailDone?: boolean,
emailImportance?: boolean,
emailShared?: EmailShared,
emailCalendarOnly?: boolean,
channelSeen?: boolean,
channelDone?: boolean,
channelImportance?: boolean,
channelThreadSeen?: boolean,
channelThreadDone?: boolean,
chatSeen?: boolean,
chatDone?: boolean,
folderSeen?: boolean,
folderDone?: boolean,
initiativeSeen?: boolean,
initiativeDone?: boolean,
foreignEntitySeen?: boolean,
foreignEntityDone?: boolean,
foreignEntityIncludesMe?: boolean,
callStatus?: CallStatus,
callAttended?: boolean,
crmCompanyHidden?: boolean,
crmContactHidden?: boolean,
/** Literal text matched against a CRM contact's name or email. */
crmContactSearch?: string,
calendarEventSeen?: boolean,
calendarEventDone?: boolean,
includeAgentSessions?: boolean,
chatCreatedAt?: DateRangeFilter_Deserialize,
chatUpdatedAt?: DateRangeFilter_Deserialize,
folderCreatedAt?: DateRangeFilter_Deserialize,
folderUpdatedAt?: DateRangeFilter_Deserialize,
emailUpdatedAt?: DateRangeFilter_Deserialize,
} & DocumentFieldFilters_Deserialize;
/**
* Every filter, each over one field of one kind of item. Id lists match any
* of their ids.
*/
export type FieldFilters_Serialize = {
calendarEventId?: string[],
threadId?: string[],
emailLinkId?: string[],
emailProjectId?: string[],
emailSender?: string[],
channelId?: string[],
channelType?: string[],
/**
* Membership states to match: `[true]` for channels the user is in,
* `[true, false]` to also match team channels they have not joined.
*/
channelIsParticipant?: boolean[],
channelSenderId?: string[],
channelMessageThreadId?: string[],
channelThreadId?: string[],
channelThreadRootSenderId?: string[],
channelThreadParticipantId?: string[],
agentSessionId?: string[],
agentSessionOwnerId?: string[],
chatId?: string[],
chatOwnerId?: string[],
chatProjectId?: string[],
folderId?: string[],
folderOwnerId?: string[],
callId?: string[],
callChannelId?: string[],
callSpeakerId?: string[],
foreignEntityRecordId?: string[],
foreignEntitySource?: string[],
crmCompanyId?: string[],
/** Property values to match; distinct properties all apply. */
properties?: PropertyFilter[],
/** Selected tags, combined by `tagFilterMode`. */
tagFilters?: PropertyFilter[],
tagFilterMode?: TagFilterMode,
emailSeen?: boolean,
emailDone?: boolean,
emailImportance?: boolean,
emailShared?: EmailShared,
emailCalendarOnly?: boolean,
channelSeen?: boolean,
channelDone?: boolean,
channelImportance?: boolean,
channelThreadSeen?: boolean,
channelThreadDone?: boolean,
chatSeen?: boolean,
chatDone?: boolean,
folderSeen?: boolean,
folderDone?: boolean,
initiativeSeen?: boolean,
initiativeDone?: boolean,
foreignEntitySeen?: boolean,
foreignEntityDone?: boolean,
foreignEntityIncludesMe?: boolean,
callStatus?: CallStatus,
callAttended?: boolean,
crmCompanyHidden?: boolean,
crmContactHidden?: boolean,
/** Literal text matched against a CRM contact's name or email. */
crmContactSearch?: string,
calendarEventSeen?: boolean,
calendarEventDone?: boolean,
includeAgentSessions?: boolean,
chatCreatedAt?: DateRangeFilter_Serialize,
chatUpdatedAt?: DateRangeFilter_Serialize,
folderCreatedAt?: DateRangeFilter_Serialize,
folderUpdatedAt?: DateRangeFilter_Serialize,
emailUpdatedAt?: DateRangeFilter_Serialize,
} & DocumentFieldFilters_Serialize;
/** A file modification a tool reported. */
export type FileDiff = {
/** The file that changed. */
path: string,
/** Prior contents, absent when the file is new. */
oldText: string | null,
/** New contents. */
newText: string,
};
/** One renderable message, scoped to its agent session for its reader. */
export type FoldedMessage = FoldedMessage_Serialize | FoldedMessage_Deserialize;
/** One renderable message, scoped to its agent session for its reader. */
export type FoldedMessage_Deserialize = {
/** Session that scopes this message id. */
agentSessionId: string,
/**
* The message's identity within its session, `<turn>:<author kind>`
* (`3:agent`): stable across streaming updates, rebases, and pending
* flipping off, so a reader can key and reconcile rows by it.
*/
key: string,
/** The turn within the session, assigned in log order from zero. */
turn: number,
/** Who produced the message. */
author: Author,
/**
* The id the control endpoint returned for the action that derived this
* message, for correlation. Absent on agent messages and on frames the
* control plane did not mint.
*/
requestId: string | null,
/** Ordered renderable content. Never empty. */
parts: MessagePart_Deserialize[],
/** How the turn ended, absent while it remains in flight. */
stop: StopReason | null,
/**
* Derived from an action this client issued that the log has not yet
* confirmed. A reader shows it as sending; it flips off in place when
* the confirmed frame arrives.
*/
pending: boolean,
/**
* How an agent's reply reads as a conversation, the same boundaries the
* server posts channel messages by. Empty on a user's message.
*/
segments: Segment_Deserialize[],
/**
* What an agent's unfinished reply is doing now; absent once its turn
* has ended and on a user's message.
*/
phase: TurnPhase | null,
/**
* When a user's prompt was posted, RFC 3339. Absent on agent and control
* messages, until the log confirms a prompt, and on history a runtime
* replayed on load.
*/
postedAt: string | null,
};
/** One renderable message, scoped to its agent session for its reader. */
export type FoldedMessage_Serialize = {
/** Session that scopes this message id. */
agentSessionId: string,
/**
* The message's identity within its session, `<turn>:<author kind>`
* (`3:agent`): stable across streaming updates, rebases, and pending
* flipping off, so a reader can key and reconcile rows by it.
*/
key: string,
/** The turn within the session, assigned in log order from zero. */
turn: number,
/** Who produced the message. */
author: Author,
/**
* The id the control endpoint returned for the action that derived this
* message, for correlation. Absent on agent messages and on frames the
* control plane did not mint.
*/
requestId: string | null,
/** Ordered renderable content. Never empty. */
parts: MessagePart_Serialize[],
/** How the turn ended, absent while it remains in flight. */
stop: StopReason | null,
/**
* Derived from an action this client issued that the log has not yet
* confirmed. A reader shows it as sending; it flips off in place when
* the confirmed frame arrives.
*/
pending: boolean,
/**
* How an agent's reply reads as a conversation, the same boundaries the
* server posts channel messages by. Empty on a user's message.
*/
segments: Segment_Serialize[],
/**
* What an agent's unfinished reply is doing now; absent once its turn
* has ended and on a user's message.
*/
phase: TurnPhase | null,
/**
* When a user's prompt was posted, RFC 3339. Absent on agent and control
* messages, until the log confirms a prompt, and on history a runtime
* replayed on load.
*/
postedAt: string | null,
};
/**
* One change a pushed frame implied.
*
* Payloads are carried whole rather than as deltas: a reader replaces the
* message under the same session, turn, and author, or replaces its metadata
* outright.
*/
export type FoldedStreamEvent = FoldedStreamEvent_Serialize | FoldedStreamEvent_Deserialize;
/**
* One change a pushed frame implied.
*
* Payloads are carried whole rather than as deltas: a reader replaces the
* message under the same session, turn, and author, or replaces its metadata
* outright.
*/
export type FoldedStreamEvent_Deserialize =
/** A message derived for the first time. */
({ kind: "new";
/** The message as it now stands. */
message: FoldedMessage_Deserialize }) & { messages?: never; metadata?: never } |
/** A previously reported message, changed. */
({ kind: "update";
/** The message as it now stands. */
message: FoldedMessage_Deserialize }) & { messages?: never; metadata?: never } |
/** Replace all messages for this session, including removal of old rows. */
({ kind: "replace";
/** The complete committed conversation. */
messages: FoldedMessage_Deserialize[] }) & { message?: never; metadata?: never } |
/** The session's metadata changed; here it is in full. */
({ kind: "metadata";
/** The metadata as it now stands. */
metadata: SessionMetadata_Deserialize }) & { message?: never; messages?: never };
/**
* One change a pushed frame implied.
*
* Payloads are carried whole rather than as deltas: a reader replaces the
* message under the same session, turn, and author, or replaces its metadata
* outright.
*/
export type FoldedStreamEvent_Serialize =
/** A message derived for the first time. */
({ kind: "new";
/** The message as it now stands. */
message: FoldedMessage_Serialize }) & { messages?: never; metadata?: never } |
/** A previously reported message, changed. */
({ kind: "update";
/** The message as it now stands. */
message: FoldedMessage_Serialize }) & { messages?: never; metadata?: never } |
/** Replace all messages for this session, including removal of old rows. */
({ kind: "replace";
/** The complete committed conversation. */
messages: FoldedMessage_Serialize[] }) & { message?: never; metadata?: never } |
/** The session's metadata changed; here it is in full. */
({ kind: "metadata";
/** The metadata as it now stands. */
metadata: SessionMetadata_Serialize }) & { message?: never; messages?: never };
/** The space between a container's children, as a Tailwind-ish step. */
export type Gap = number;
/** The facet a list groups its rows by. */
export type GroupBy = "date" | "entity_type" | "project";
/**
* Which ACP agent produced a session's log.
*
* ACP names none of a harness's conventions - which `_meta` keys it writes,
* what it calls its tools, how it reports a subagent - so the fold has to
* know who it is reading in order to read those. The agent announces itself
* in the `initialize` response's `agentInfo.name`; a log that starts
* mid-session (a resume) is recognized from the `_meta` namespaces its
* first tool frames carry instead. Carried on the metadata so a reader can
* show it and never has to infer it.
*
* [`Self::Unknown`] is a real state, not a failure: every reader falls back
* to the harness-neutral conventions, and a harness this fold has not met
* still folds to the generic vocabulary.
*/
export type Harness =
/** `@agentclientprotocol/claude-agent-acp`. */
"claude_code" |
/** `OpenCode`, whose ACP server is built in. */
"open_code" |
/** OpenAI Codex, through `codex-acp`. */
"codex" |
/** Cursor cloud agents, through this repository's `cursor_cloud_agents`. */
"cursor" |
/** Macro's own in-process agent, `agent_inmem`. */
"macro" |
/** Nous Research's Hermes agent. */
"hermes" |
/** OpenClaw. */
"open_claw" |
/** Not announced, or an agent this fold does not know. */
"unknown";
/** One object an import report calls out. */
export type ImportItem = ImportItem_Serialize | ImportItem_Deserialize;
/** One object an import report calls out. */
export type ImportItem_Deserialize = {
/** The object's title. */
title: string,
/** Its URL in the source workspace. */
url: string | null,
/** Why it is called out. */
reason: string | null,
};
/** One object an import report calls out. */
export type ImportItem_Serialize = {
/** The object's title. */
title: string,
/** Its URL in the source workspace. */
url?: string | null,
/** Why it is called out. */
reason?: string | null,
};
/** How an approved import's write ended. */
export type ImportOutcome =
/** Every planned object was written or accounted for. */
"completed" |
/** The write stopped on an error. */
"failed" |
/** The owner cancelled it. */
"cancelled";
/** What an import plan proposes, once it is ready to approve. */
export type ImportPlan = {
/** The workspace the import reads. */
source?: ImportWorkspace,
/** Objects to copy as they are; projects for Linear and Jira. */
copy: number,
/** Data sources whose rows become tasks; issues for Linear and Jira. */
taskLists: number,
/** Objects to leave in the source workspace. */
skipped: number,
/** Objects that need handling by hand. */
byHand: number,
};
/** The final report of an approved workspace import, with no page content. */
export type ImportSettlement = ImportSettlement_Serialize | ImportSettlement_Deserialize;
/** The final report of an approved workspace import, with no page content. */
export type ImportSettlement_Deserialize = {
/** The workspace the import read. */
source?: ImportWorkspace,
/** How the write ended. */
outcome: ImportOutcome,
/** Why it failed, or what went wrong in a completed write. */
error: string | null,
/** Objects written into Macro. */
imported: number,
/**
* Objects the plan copies: as they are or as task lists from Notion,
* projects and issues from Linear or Jira.
*/
planned: number,
/** Planned documents. */
documents: number,
/** Planned databases. */
databases: number,
/** Rows those databases hold. */
databaseRows: number,
/** Planned task lists; issues that become tasks for Linear and Jira. */
taskLists: number,
/** Tasks those task lists or issues become. */
taskRows: number,
/** Objects left in the source workspace. */
skipped: number,
/** Planned objects that were not written. */
notWritten: number,
/** Written objects shared with the owner's team. */
sharedWithTeam: number,
/** Objects teammates had already imported, linked instead of copied. */
alreadyInMacro: number,
/** Objects a teammate is writing at the same time, linked once written. */
waitingOnTeammates: number,
/** The Macro folder the import writes into. */
rootFolderId: string | null,
/** Objects that could not be imported, at most [`MAX_IMPORT_ITEMS`]. */
failures: ImportItem_Deserialize[],
/** Objects left for the owner to handle by hand, at most [`MAX_IMPORT_ITEMS`]. */
handItems: ImportItem_Deserialize[],
};
/** The final report of an approved workspace import, with no page content. */
export type ImportSettlement_Serialize = {
/** The workspace the import read. */
source: ImportWorkspace,
/** How the write ended. */
outcome: ImportOutcome,
/** Why it failed, or what went wrong in a completed write. */
error?: string | null,
/** Objects written into Macro. */
imported: number,
/**
* Objects the plan copies: as they are or as task lists from Notion,
* projects and issues from Linear or Jira.
*/
planned: number,
/** Planned documents. */
documents: number,
/** Planned databases. */
databases: number,
/** Rows those databases hold. */
databaseRows: number,
/** Planned task lists; issues that become tasks for Linear and Jira. */
taskLists: number,
/** Tasks those task lists or issues become. */
taskRows: number,
/** Objects left in the source workspace. */
skipped: number,
/** Planned objects that were not written. */
notWritten: number,
/** Written objects shared with the owner's team. */
sharedWithTeam: number,
/** Objects teammates had already imported, linked instead of copied. */
alreadyInMacro: number,
/** Objects a teammate is writing at the same time, linked once written. */
waitingOnTeammates: number,
/** The Macro folder the import writes into. */
rootFolderId?: string | null,
/** Objects that could not be imported, at most [`MAX_IMPORT_ITEMS`]. */
failures: ImportItem_Serialize[],
/** Objects left for the owner to handle by hand, at most [`MAX_IMPORT_ITEMS`]. */
handItems: ImportItem_Serialize[],
};
/**
* The workspace an import reads. Events stored before Linear and Jira
* imports existed are Notion's.
*/
export type ImportWorkspace =
/** Notion pages and databases. */
"notion" |
/** Linear projects and issues. */
"linear" |
/** Jira projects, epics and issues. */
"jira";
/** Review item state, shared with notification consumers. */
export type ItemStatus =
/** Still awaiting a decision. */
"pending" |
/** Claimed for execution. */
"submitting" |
/** Confirmed complete. */
"completed" |
/** Dismissed by the owner. */
"dismissed" |
/** Outcome requires reconciliation. */
"unknown";
/** How a container spaces its children along its axis. */
export type Justify = "start" | "center" | "end" | "between";
/** Where a list's items come from. */
export type ListSource = ListSource_Serialize | ListSource_Deserialize;
/** Where a list's items come from. */
export type ListSource_Deserialize =
/** The items a filter matches, fetched by the list itself. */
({ kind: "query"; query: Query_Deserialize }) & { entities?: never } |
/** A fixed set of items. */
({ kind: "items"; entities: EntityRef[] }) & { query?: never };
/** Where a list's items come from. */
export type ListSource_Serialize =
/** The items a filter matches, fetched by the list itself. */
({ kind: "query"; query: Query_Serialize }) & { entities?: never } |
/** A fixed set of items. */
({ kind: "items"; entities: EntityRef[] }) & { query?: never };
/** A unit of renderable content. */
export type MessagePart = MessagePart_Serialize | MessagePart_Deserialize;
/** A unit of renderable content. */
export type MessagePart_Deserialize =
/** Prose from the user or the agent. */
({ kind: "text";
/** The prose. */
text: string }) & { approvalId?: never; arguments?: never; control?: never; detail?: never; entries?: never; event?: never; id?: never; message?: never; mimeType?: never; name?: never; options?: never; outcome?: never; remembered?: never; reported?: never; request?: never; requestId?: never; requestedBy?: never; resolvedBy?: never; serverName?: never; serverSlug?: never; size?: never; status?: never; summary?: never; toolCall?: never; toolName?: never; toolOutcome?: never; uri?: never } |
/**
* A file the user attached to their prompt, by where it can be fetched.
*
* Read off the prompt's `resource_link` blocks - the only shape this
* side sends files in, since bytes never ride the log. Rendering decides
* from `mime_type` whether that is a thumbnail or a chip.
*/
({ kind: "attachment";
/** Where the file can be fetched - a static file service URL. */
uri: string;
/** Display name, typically the original file name. */
name: string;
/** The file's media type, when the sender knew it. */
mimeType: string | null;
/**
* Size in bytes, when the sender knew it. A double on the wire:
* specta refuses 64-bit integers, and no file this renders is
* anywhere near the precision limit.
*/
size: number | null }) & { approvalId?: never; arguments?: never; control?: never; detail?: never; entries?: never; event?: never; id?: never; message?: never; options?: never; outcome?: never; remembered?: never; reported?: never; request?: never; requestId?: never; requestedBy?: never; resolvedBy?: never; serverName?: never; serverSlug?: never; status?: never; summary?: never; text?: never; toolCall?: never; toolName?: never; toolOutcome?: never } |
/** The agent's reasoning, which a reader may want to hide by default. */
({ kind: "thought";
/** The reasoning. */
text: string }) & { approvalId?: never; arguments?: never; control?: never; detail?: never; entries?: never; event?: never; id?: never; message?: never; mimeType?: never; name?: never; options?: never; outcome?: never; remembered?: never; reported?: never; request?: never; requestId?: never; requestedBy?: never; resolvedBy?: never; serverName?: never; serverSlug?: never; size?: never; status?: never; summary?: never; toolCall?: never; toolName?: never; toolOutcome?: never; uri?: never } |
/** A tool the agent invoked. */
({ kind: "tool_use";
/** The ACP `toolCallId`. */
id: ToolUseId;
/** What the harness called the tool. */
name: ToolName;
/** Where the call got to. */
status: ToolStatus;
/** What the tool did, as far as the log reveals. */
detail: ToolDetail_Deserialize }) & { approvalId?: never; arguments?: never; control?: never; entries?: never; event?: never; message?: never; mimeType?: never; options?: never; outcome?: never; remembered?: never; reported?: never; request?: never; requestId?: never; requestedBy?: never; resolvedBy?: never; serverName?: never; serverSlug?: never; size?: never; summary?: never; text?: never; toolCall?: never; toolName?: never; toolOutcome?: never; uri?: never } |
/** The agent asking to proceed. */
({ kind: "permission";
/** The agent request id an approval must echo. */
requestId: AgentRequestId;
/** The tool call permission was requested for. */
toolCall: ToolUseId;
/** The choices offered, in the order ACP listed them. */
options: PermissionOption[];
/** How the request has resolved so far. */
outcome: PermissionOutcome }) & { approvalId?: never; arguments?: never; control?: never; detail?: never; entries?: never; event?: never; id?: never; message?: never; mimeType?: never; name?: never; remembered?: never; reported?: never; request?: never; requestedBy?: never; resolvedBy?: never; serverName?: never; serverSlug?: never; size?: never; status?: never; summary?: never; text?: never; toolName?: never; toolOutcome?: never; uri?: never } |
/**
* An MCP tool call the egress proxy is holding, or held, until the
* session's owner approved it: made in a turn somebody else prompted.
*/
({ kind: "tool_approval";
/** The approval an answer names. */
approvalId: string;
/** `macro`, or the connected app's slug. */
serverSlug: string;
/** What a person calls the server the tool is on. */
serverName: string;
/** The tool called. */
toolName: string;
/** What it was called with. */
arguments: unknown;
/** Who prompted the turn; absent for a bot on nobody's behalf. */
requestedBy: string | null;
/** Where it stands. */
status: ToolApprovalStatus;
/** Who resolved it, when a person did. */
resolvedBy: string | null;
/**
* Approved for good: the person who asked may make the calls it
* covers without the owner being asked again.
*/
remembered: boolean }) & { control?: never; detail?: never; entries?: never; event?: never; id?: never; message?: never; mimeType?: never; name?: never; options?: never; outcome?: never; reported?: never; request?: never; requestId?: never; size?: never; summary?: never; text?: never; toolCall?: never; toolOutcome?: never; uri?: never } |
/** A user-issued control operation on the session. */
({ kind: "control";
/** The requested operation. */
control: Control;
/** How the runtime disposed of it so far. */
outcome: ControlOutcome }) & { approvalId?: never; arguments?: never; detail?: never; entries?: never; event?: never; id?: never; message?: never; mimeType?: never; name?: never; options?: never; remembered?: never; reported?: never; request?: never; requestId?: never; requestedBy?: never; resolvedBy?: never; serverName?: never; serverSlug?: never; size?: never; status?: never; summary?: never; text?: never; toolCall?: never; toolName?: never; toolOutcome?: never; uri?: never } |
/** The agent's working todo list for the turn. */
({ kind: "plan";
/** The tasks, in the order the agent listed them. */
entries: PlanEntry[] }) & { approvalId?: never; arguments?: never; control?: never; detail?: never; event?: never; id?: never; message?: never; mimeType?: never; name?: never; options?: never; outcome?: never; remembered?: never; reported?: never; request?: never; requestId?: never; requestedBy?: never; resolvedBy?: never; serverName?: never; serverSlug?: never; size?: never; status?: never; summary?: never; text?: never; toolCall?: never; toolName?: never; toolOutcome?: never; uri?: never } |
/**
* A background task the harness reported on: a command, subagent or
* monitor it started earlier finished or emitted an event. The harness
* hands the agent this report as a user turn; it is shown as a system
* fact, never as something a person said.
*/
({ kind: "task_notification";
/** Where the task ended up; absent for a monitor's mid-stream event. */
status: TaskStatus | null;
/**
* The harness's one-line account, such as `Background command
* "Run tests" completed (exit code 0)`.
*/
summary: string;
/** The line a monitor streamed, for a monitor event. */
event: string | null }) & { approvalId?: never; arguments?: never; control?: never; detail?: never; entries?: never; id?: never; message?: never; mimeType?: never; name?: never; options?: never; outcome?: never; remembered?: never; reported?: never; request?: never; requestId?: never; requestedBy?: never; resolvedBy?: never; serverName?: never; serverSlug?: never; size?: never; text?: never; toolCall?: never; toolName?: never; toolOutcome?: never; uri?: never } |
/**
* The agent asking the user a question.
*
* When the question was asked on behalf of a tool call this fold had
* already opened (Claude Code's `AskUserQuestion`), this part *replaces*
* that tool's part in place: the question is the call, and rendering
* both would show one thing twice.
*/
({ kind: "elicitation";
/**
* The agent's `elicitation/create` request id - what an answer must
* echo.
*/
requestId: ElicitationRequestId;
/** The tool call the question belongs to, when the agent said. */
toolCall: ToolUseId | null;
/** What the agent is asking, in prose. */
message: string;
/** The form or URL. */
request: ElicitationRequest;
/** How it has resolved so far. */
outcome: ElicitationOutcome;
/**
* The harness's own reading of the answer, when it reported one
* after the response went back (Claude Code echoes the chosen
* option through its tool result). Absent otherwise.
*
* Shaped like [`ElicitationOutcome::Accepted`]'s answers so a reader
* renders one vocabulary either way, though a harness keys these by
* question prose rather than by property, so each `name` is that
* prose rather than a schema property.
*/
reported: AnsweredField[] | null;
/**
* For a user tool's review ([`ElicitationRequest::UserTool`]): how
* the tool itself ended once the user answered - run with the
* reviewed draft, rejected, or failed - read from the absorbed
* call's later updates. Absent until the tool reports, and for
* every other kind of question.
*/
toolOutcome: UserToolOutcome | null }) & { approvalId?: never; arguments?: never; control?: never; detail?: never; entries?: never; event?: never; id?: never; mimeType?: never; name?: never; options?: never; remembered?: never; requestedBy?: never; resolvedBy?: never; serverName?: never; serverSlug?: never; size?: never; status?: never; summary?: never; text?: never; toolName?: never; uri?: never };
/** A unit of renderable content. */
export type MessagePart_Serialize =
/** Prose from the user or the agent. */
({ kind: "text";
/** The prose. */
text: string }) & { approvalId?: never; arguments?: never; control?: never; detail?: never; entries?: never; event?: never; id?: never; message?: never; mimeType?: never; name?: never; options?: never; outcome?: never; remembered?: never; reported?: never; request?: never; requestId?: never; requestedBy?: never; resolvedBy?: never; serverName?: never; serverSlug?: never; size?: never; status?: never; summary?: never; toolCall?: never; toolName?: never; toolOutcome?: never; uri?: never } |
/**
* A file the user attached to their prompt, by where it can be fetched.
*
* Read off the prompt's `resource_link` blocks - the only shape this
* side sends files in, since bytes never ride the log. Rendering decides
* from `mime_type` whether that is a thumbnail or a chip.
*/
({ kind: "attachment";
/** Where the file can be fetched - a static file service URL. */
uri: string;
/** Display name, typically the original file name. */
name: string;
/** The file's media type, when the sender knew it. */
mimeType: string | null;
/**
* Size in bytes, when the sender knew it. A double on the wire:
* specta refuses 64-bit integers, and no file this renders is
* anywhere near the precision limit.
*/
size: number | null }) & { approvalId?: never; arguments?: never; control?: never; detail?: never; entries?: never; event?: never; id?: never; message?: never; options?: never; outcome?: never; remembered?: never; reported?: never; request?: never; requestId?: never; requestedBy?: never; resolvedBy?: never; serverName?: never; serverSlug?: never; status?: never; summary?: never; text?: never; toolCall?: never; toolName?: never; toolOutcome?: never } |
/** The agent's reasoning, which a reader may want to hide by default. */
({ kind: "thought";
/** The reasoning. */
text: string }) & { approvalId?: never; arguments?: never; control?: never; detail?: never; entries?: never; event?: never; id?: never; message?: never; mimeType?: never; name?: never; options?: never; outcome?: never; remembered?: never; reported?: never; request?: never; requestId?: never; requestedBy?: never; resolvedBy?: never; serverName?: never; serverSlug?: never; size?: never; status?: never; summary?: never; toolCall?: never; toolName?: never; toolOutcome?: never; uri?: never } |
/** A tool the agent invoked. */
({ kind: "tool_use";
/** The ACP `toolCallId`. */
id: ToolUseId;
/** What the harness called the tool. */
name: ToolName;
/** Where the call got to. */
status: ToolStatus;
/** What the tool did, as far as the log reveals. */
detail: ToolDetail_Serialize }) & { approvalId?: never; arguments?: never; control?: never; entries?: never; event?: never; message?: never; mimeType?: never; options?: never; outcome?: never; remembered?: never; reported?: never; request?: never; requestId?: never; requestedBy?: never; resolvedBy?: never; serverName?: never; serverSlug?: never; size?: never; summary?: never; text?: never; toolCall?: never; toolName?: never; toolOutcome?: never; uri?: never } |
/** The agent asking to proceed. */
({ kind: "permission";
/** The agent request id an approval must echo. */
requestId: AgentRequestId;
/** The tool call permission was requested for. */
toolCall: ToolUseId;
/** The choices offered, in the order ACP listed them. */
options: PermissionOption[];
/** How the request has resolved so far. */
outcome: PermissionOutcome }) & { approvalId?: never; arguments?: never; control?: never; detail?: never; entries?: never; event?: never; id?: never; message?: never; mimeType?: never; name?: never; remembered?: never; reported?: never; request?: never; requestedBy?: never; resolvedBy?: never; serverName?: never; serverSlug?: never; size?: never; status?: never; summary?: never; text?: never; toolName?: never; toolOutcome?: never; uri?: never } |
/**
* An MCP tool call the egress proxy is holding, or held, until the
* session's owner approved it: made in a turn somebody else prompted.
*/
({ kind: "tool_approval";
/** The approval an answer names. */
approvalId: string;
/** `macro`, or the connected app's slug. */
serverSlug: string;
/** What a person calls the server the tool is on. */
serverName: string;
/** The tool called. */
toolName: string;
/** What it was called with. */
arguments: unknown;
/** Who prompted the turn; absent for a bot on nobody's behalf. */
requestedBy: string | null;
/** Where it stands. */
status: ToolApprovalStatus;
/** Who resolved it, when a person did. */
resolvedBy: string | null;
/**
* Approved for good: the person who asked may make the calls it
* covers without the owner being asked again.
*/
remembered: boolean }) & { control?: never; detail?: never; entries?: never; event?: never; id?: never; message?: never; mimeType?: never; name?: never; options?: never; outcome?: never; reported?: never; request?: never; requestId?: never; size?: never; summary?: never; text?: never; toolCall?: never; toolOutcome?: never; uri?: never } |
/** A user-issued control operation on the session. */
({ kind: "control";
/** The requested operation. */
control: Control;
/** How the runtime disposed of it so far. */
outcome: ControlOutcome }) & { approvalId?: never; arguments?: never; detail?: never; entries?: never; event?: never; id?: never; message?: never; mimeType?: never; name?: never; options?: never; remembered?: never; reported?: never; request?: never; requestId?: never; requestedBy?: never; resolvedBy?: never; serverName?: never; serverSlug?: never; size?: never; status?: never; summary?: never; text?: never; toolCall?: never; toolName?: never; toolOutcome?: never; uri?: never } |
/** The agent's working todo list for the turn. */
({ kind: "plan";
/** The tasks, in the order the agent listed them. */
entries: PlanEntry[] }) & { approvalId?: never; arguments?: never; control?: never; detail?: never; event?: never; id?: never; message?: never; mimeType?: never; name?: never; options?: never; outcome?: never; remembered?: never; reported?: never; request?: never; requestId?: never; requestedBy?: never; resolvedBy?: never; serverName?: never; serverSlug?: never; size?: never; status?: never; summary?: never; text?: never; toolCall?: never; toolName?: never; toolOutcome?: never; uri?: never } |
/**
* A background task the harness reported on: a command, subagent or
* monitor it started earlier finished or emitted an event. The harness
* hands the agent this report as a user turn; it is shown as a system
* fact, never as something a person said.
*/
({ kind: "task_notification";
/** Where the task ended up; absent for a monitor's mid-stream event. */
status: TaskStatus | null;
/**
* The harness's one-line account, such as `Background command
* "Run tests" completed (exit code 0)`.
*/
summary: string;
/** The line a monitor streamed, for a monitor event. */
event: string | null }) & { approvalId?: never; arguments?: never; control?: never; detail?: never; entries?: never; id?: never; message?: never; mimeType?: never; name?: never; options?: never; outcome?: never; remembered?: never; reported?: never; request?: never; requestId?: never; requestedBy?: never; resolvedBy?: never; serverName?: never; serverSlug?: never; size?: never; text?: never; toolCall?: never; toolName?: never; toolOutcome?: never; uri?: never } |
/**
* The agent asking the user a question.
*
* When the question was asked on behalf of a tool call this fold had
* already opened (Claude Code's `AskUserQuestion`), this part *replaces*
* that tool's part in place: the question is the call, and rendering
* both would show one thing twice.
*/
({ kind: "elicitation";
/**
* The agent's `elicitation/create` request id - what an answer must
* echo.
*/
requestId: ElicitationRequestId;
/** The tool call the question belongs to, when the agent said. */
toolCall: ToolUseId | null;
/** What the agent is asking, in prose. */
message: string;
/** The form or URL. */
request: ElicitationRequest;
/** How it has resolved so far. */
outcome: ElicitationOutcome;
/**
* The harness's own reading of the answer, when it reported one
* after the response went back (Claude Code echoes the chosen
* option through its tool result). Absent otherwise.
*
* Shaped like [`ElicitationOutcome::Accepted`]'s answers so a reader
* renders one vocabulary either way, though a harness keys these by
* question prose rather than by property, so each `name` is that
* prose rather than a schema property.
*/
reported: AnsweredField[] | null;
/**
* For a user tool's review ([`ElicitationRequest::UserTool`]): how
* the tool itself ended once the user answered - run with the
* reviewed draft, rejected, or failed - read from the absorbed
* call's later updates. Absent until the tool reports, and for
* every other kind of question.
*/
toolOutcome: UserToolOutcome | null }) & { approvalId?: never; arguments?: never; control?: never; detail?: never; entries?: never; event?: never; id?: never; mimeType?: never; name?: never; options?: never; remembered?: never; requestedBy?: never; resolvedBy?: never; serverName?: never; serverSlug?: never; size?: never; status?: never; summary?: never; text?: never; toolName?: never; uri?: never };
/** One model the runtime offers. */
export type ModelOption = {
/** The value to send back to select this model. */
id: string,
/** Human-readable label. */
name: string,
/** Descriptive copy - pricing, context size, and the like. */
description: string | null,
/** Image input support, absent when the runtime does not advertise it. */
supportsImages?: boolean | null,
/**
* The heading the runtime listed this model under, when it grouped its
* options (ACP's `SessionConfigSelectGroup.name`). `None` for a runtime
* that offered a flat list; the flattened order still follows the
* runtime's, group by group.
*/
group: string | null,
};
/** Supported event contracts. Add new kinds here rather than inventing prompts. */
export type NotificationEvent = NotificationEvent_Serialize | NotificationEvent_Deserialize;
/** Supported event contracts. Add new kinds here rather than inventing prompts. */
export type NotificationEvent_Deserialize =
/** Owner decision and its confirmed results. */
{ kind: "review.decided"; payload: ReviewOutcome_Deserialize } |
/** Completion of work initiated by a prior review decision. */
{ kind: "review.settled"; payload: ReviewSettlement_Deserialize } |
/** The import plan a presented review shows finished planning. */
{ kind: "import.planned"; payload: ImportPlan } |
/** An app connection became available to the session. */
{ kind: "app.connected"; payload: {
/** Connected application's display name. */
app: string,
} };
/** Supported event contracts. Add new kinds here rather than inventing prompts. */
export type NotificationEvent_Serialize =
/** Owner decision and its confirmed results. */
{ kind: "review.decided"; payload: ReviewOutcome_Serialize } |
/** Completion of work initiated by a prior review decision. */
{ kind: "review.settled"; payload: ReviewSettlement_Serialize } |
/** The import plan a presented review shows finished planning. */
{ kind: "import.planned"; payload: ImportPlan } |
/** An app connection became available to the session. */
{ kind: "app.connected"; payload: {
/** Connected application's display name. */
app: string,
} };
/**
* The one elicitation the user can answer right now, surfaced on
* [`SessionMetadata`](super::SessionMetadata) so a reader need not scan the
* transcript for it.
*/
export type PendingElicitation = {
/** The agent's request id; what an answer must name. */
requestId: ElicitationRequestId,
/** The turn whose agent message holds the matching part. */
turn: number,
/** The tool call it was asked on behalf of, when any. */
toolCall: ToolUseId | null,
/** What the agent is asking, in prose. */
message: string,
/** The form or URL. */
request: ElicitationRequest,
};
/** An answerable request. Each variant retains its own response semantics. */
export type PendingInteraction =
/** A choice among the permission options offered by the agent. */
{
kind: "permission",
} & PendingPermission |
/** A form, URL consent, or user tool review. */
{
kind: "elicitation",
} & PendingElicitation |
/**
* An MCP tool call held until the session's owner approves it. Only
* the owner may approve or decline; anyone with edit access may cancel.
*/
{
kind: "tool_approval",
} & PendingToolApproval;
/** A permission request the current connection can still answer. */
export type PendingPermission = {
/** The agent's request id, preserving numeric and string identities. */
requestId: AgentRequestId,
/** The turn that asked. */
turn: number,
/** The tool whose execution needs permission. */
toolCall: ToolUseId,
/** The options the agent offered. */
options: PermissionOption[],
};
/** A held MCP tool call the owner can still answer. */
export type PendingToolApproval = {
/** The approval an answer names. */
approvalId: string,
/** The turn the call was made in. */
turn: number,
/** `macro`, or the connected app's slug. */
serverSlug: string,
/** What a person calls the server the tool is on. */
serverName: string,
/** The tool called. */
toolName: string,
/** Who prompted the turn; absent for a bot on nobody's behalf. */
requestedBy: string | null,
};
/** One choice offered for a permission request. */
export type PermissionOption = {
/** The id to report back when this option is chosen. */
id: string,
/** Label to show. */
name: string,
/** What kind of choice this is. */
kind: PermissionOptionKind,
};
/**
* What kind of choice a [`PermissionOption`] offers, mirroring ACP's
* `PermissionOptionKind`.
*
* ACP's enum is `#[non_exhaustive]`, but unlike [`StopReason`] there is no
* wire string worth preserving for a variant this fold does not model: the
* fold only ever sees one of these once the whole permission request has
* already deserialized successfully, and a wire value ACP added after this
* was written would have failed that deserialize already - so an unmatched
* kind here cannot happen in practice, not "happens and is rendered
* unlabeled."
*/
export type PermissionOptionKind =
/** Allow this operation only this time. */
"allow_once" |
/** Allow this operation and remember the choice. */
"allow_always" |
/** Reject this operation only this time. */
"reject_once" |
/** Reject this operation and remember the choice. */
"reject_always";
/**
* How a permission request has resolved so far.
*
* Not just "chosen or not": nothing chosen has more than one cause, and a
* reader deciding whether to still show the options needs to tell them
* apart. [`Self::Pending`] may still resolve; [`Self::Errored`] and
* [`Self::Unrecognized`] have already resolved, just not into anything this
* fold can show as a choice.
*/
export type PermissionOutcome =
/** No response has arrived yet - the request is still outstanding. */
{ kind: "pending" } |
/** An option was chosen. */
{ kind: "selected";
/** The chosen option's id. */
optionId: string } |
/** The request was cancelled without a choice. */
{ kind: "cancelled" } |
/**
* The response was a JSON-RPC error rather than a result: the harness
* failed to answer the request rather than resolving it.
*/
{ kind: "errored" } |
/**
* A result arrived, but this fold could not make sense of it - a
* payload that did not match ACP's response shape, or an outcome ACP
* added after this was written.
*/
{ kind: "unrecognized" };
/** One task on an agent plan. */
export type PlanEntry = {
/** What this task aims to accomplish. */
content: string,
/** The task's relative importance. */
priority: PlanEntryPriority,
/** Where the task got to. */
status: PlanEntryStatus,
};
/**
* A [`PlanEntry`]'s relative importance, mirroring ACP's
* `PlanEntryPriority`.
*/
export type PlanEntryPriority =
/** Critical to the overall goal. */
"high" |
/** Important but not critical. */
"medium" |
/** Nice to have but not essential. */
"low";
/** Where a [`PlanEntry`] got to, mirroring ACP's `PlanEntryStatus`. */
export type PlanEntryStatus =
/** Not started yet. */
"pending" |
/** Currently being worked on. */
"in_progress" |
/** Successfully completed. */
"completed";
/** One value of one property. */
export type PropertyFilter = {
propertyId: string,
type: PropertyFilterType,
value: string,
};
/** What a property filter's value is. */
export type PropertyFilterType = "select" | "entity";
/** A Soup filter query: the items to include and exclude. */
export type Query = Query_Serialize | Query_Deserialize;
/** A Soup filter query: the items to include and exclude. */
export type Query_Deserialize = {
include?: FieldFilters_Deserialize,
exclude?: FieldFilters_Deserialize,
documentWhere?: DocumentWhere_Deserialize,
emailView?: EmailView,
};
/** A Soup filter query: the items to include and exclude. */
export type Query_Serialize = {
include?: FieldFilters_Serialize,
exclude?: FieldFilters_Serialize,
documentWhere?: DocumentWhere_Serialize,
emailView?: EmailView,
};
/** One reviewed action's outcome. */
export type ReviewItemOutcome = ReviewItemOutcome_Serialize | ReviewItemOutcome_Deserialize;
/** One reviewed action's outcome. */
export type ReviewItemOutcome_Deserialize = {
/** Stable item identity. */
id: string,
/** Confirmed state. */
status: ItemStatus,
/** Whether the owner changed its draft before deciding. */
edited: boolean,
/** Failure detail when work could not be confirmed. */
error: string | null,
};
/** One reviewed action's outcome. */
export type ReviewItemOutcome_Serialize = {
/** Stable item identity. */
id: string,
/** Confirmed state. */
status: ItemStatus,
/** Whether the owner changed its draft before deciding. */
edited: boolean,
/** Failure detail when work could not be confirmed. */
error?: string | null,
};
/** The result of a review batch, with no draft content. */
export type ReviewOutcome = ReviewOutcome_Serialize | ReviewOutcome_Deserialize;
/** The result of a review batch, with no draft content. */
export type ReviewOutcome_Deserialize = {
/** Overall result. */
outcome: DecisionOutcome,
/** Authenticated owner who made the decision. */
by: string,
/** Surface through which the owner acted. */
via: DecisionVia,
/** Exact affected items and their final states. */
items: ReviewItemOutcome_Deserialize[],
};
/** The result of a review batch, with no draft content. */
export type ReviewOutcome_Serialize = {
/** Overall result. */
outcome: DecisionOutcome,
/** Authenticated owner who made the decision. */
by: string,
/** Surface through which the owner acted. */
via: DecisionVia,
/** Exact affected items and their final states. */
items: ReviewItemOutcome_Serialize[],
};
/**
* How the work a review decision started ended. Untagged so settlements
* stored before imports existed, bare [`ReviewOutcome`]s, still read.
*/
export type ReviewSettlement = ReviewSettlement_Serialize | ReviewSettlement_Deserialize;
/**
* How the work a review decision started ended. Untagged so settlements
* stored before imports existed, bare [`ReviewOutcome`]s, still read.
*/
export type ReviewSettlement_Deserialize =
/** An approved import's background write ended. */
{
/** The import's final report. */
import: ImportSettlement_Deserialize } |
/** The decided actions' confirmed results. */
ReviewOutcome_Deserialize;
/**
* How the work a review decision started ended. Untagged so settlements
* stored before imports existed, bare [`ReviewOutcome`]s, still read.
*/
export type ReviewSettlement_Serialize =
/** An approved import's background write ended. */
{
/** The import's final report. */
import: ImportSettlement_Serialize } |
/** The decided actions' confirmed results. */
ReviewOutcome_Serialize;
/**
* A review's saved record moved to `revision`: presented, edited, decided,
* or an item's action finished.
*/
export type ReviewUpdatedNotification = {
/** The review that changed. */
reviewId: string,
/** Its saved revision after the change. */
revision: number,
};
/** A run of a reply's parts that reads as one unit. */
export type Segment = Segment_Serialize | Segment_Deserialize;
/** What a segment of a reply is. */
export type SegmentKind =
/** A passage the agent wrote. */
"prose" |
/** A run of tool calls and plan updates. */
"activity" |
/** A permission or a question the agent put to the user. */
"interaction";
/** A run of a reply's parts that reads as one unit. */
export type Segment_Deserialize = {
/** Position among the reply's segments, from zero. */
index: number,
/** What the segment is. */
kind: SegmentKind,
/** Index of the segment's first part. */
start: number,
/** Index one past the segment's last part. */
end: number,
/**
* Whether the segment can still change: false only for the last segment
* of a reply that is still being written.
*/
sealed: boolean,
/** The steps, for an activity segment; empty otherwise. */
rows: ActivityRow_Deserialize[],
};
/** A run of a reply's parts that reads as one unit. */
export type Segment_Serialize = {
/** Position among the reply's segments, from zero. */
index: number,
/** What the segment is. */
kind: SegmentKind,
/** Index of the segment's first part. */
start: number,
/** Index one past the segment's last part. */
end: number,
/**
* Whether the segment can still change: false only for the last segment
* of a reply that is still being written.
*/
sealed: boolean,
/** The steps, for an activity segment; empty otherwise. */
rows: ActivityRow_Serialize[],
};
/** The supported ACP session-config shapes. */
export type SessionConfigKind =
/** A single-value selector. */
{ type: "select";
/** The value currently selected by the agent. */
currentValue: string;
/** Choices in the order advertised by the agent. */
options: SessionConfigSelectOption[] } |
/** An on/off setting. */
{ type: "boolean";
/** The value currently selected by the agent. */
currentValue: boolean };
/** One session setting advertised by an ACP agent. */
export type SessionConfigOption = {
/** Opaque id to return in `session/set_config_option`. */
id: string,
/** Human-readable label supplied by the agent. */
name: string,
/** Optional explanatory copy supplied by the agent. */
description: string | null,
/** ACP semantic category, such as `model` or `thought_level`. */
category: string | null,
} & SessionConfigKind;
/** One value in an ACP select option. */
export type SessionConfigSelectOption = {
/** Opaque value to return in `session/set_config_option`. */
value: string,
/** Human-readable label supplied by the agent. */
name: string,
/** Optional explanatory copy supplied by the agent. */
description: string | null,
/** Optional group heading supplied by the agent. */
group: string | null,
};
/**
* Session-level state derived from the log, latest-wins and carried whole.
* Fields start absent and fill in as the log reveals them.
*
* `PartialEq` only: a pending form's numeric bounds are `f64`.
*/
export type SessionMetadata = SessionMetadata_Serialize | SessionMetadata_Deserialize;
/**
* Session-level state derived from the log, latest-wins and carried whole.
* Fields start absent and fill in as the log reveals them.
*
* `PartialEq` only: a pending form's numeric bounds are `f64`.
*/
export type SessionMetadata_Deserialize = {
/** System events, projected independently of the conversation messages. */
notifications: SessionNotification_Deserialize[],
/**
* The newest saved revision of each review the log announced, in the
* order they were first announced.
*/
reviewRevisions: ReviewUpdatedNotification[],
/** The last notification turn whose entire answer was suppressed. */
noopTurn: number | null,
/** The agent that produced the log. See [`Harness`]. */
harness: Harness,
/**
* Current model per the runtime's own `configOptions` responses, so a
* rejected model change never moves it.
*/
model: string | null,
/** The models the runtime offers, in the order it listed them. */
supportedModels: ModelOption[],
/**
* Every setting the ACP agent currently advertises. The list is replaced
* whole whenever ACP returns a new `configOptions` snapshot.
*/
configOptions: SessionConfigOption[],
/** Session title, when the harness reports one. */
title: string | null,
/**
* The slash commands the harness most recently advertised, in the order
* it listed them. Empty until the first `available_commands_update`,
* which arrives right after session setup, before any turn.
*/
availableCommands: AvailableCommand[],
/**
* The last system event's wire name (`"acp_ready"`, `"disconnected"`),
* `None` until the runtime reports one.
*/
status: string | null,
/**
* Requests the user can answer on the current turn and connection.
* Multiple permissions may coexist with the one allowed elicitation.
* History remains in the transcript after these live requests clear.
*/
pendingInteractions: PendingInteraction[],
/**
* Where the newest turn stands, as one value. Readers used to derive it
* from the transcript's tail, the status, and their own record of what
* they had posted; this is that derivation done once, in the fold.
*/
turn: TurnState,
};
/**
* Session-level state derived from the log, latest-wins and carried whole.
* Fields start absent and fill in as the log reveals them.
*
* `PartialEq` only: a pending form's numeric bounds are `f64`.
*/
export type SessionMetadata_Serialize = {
/** System events, projected independently of the conversation messages. */
notifications: SessionNotification_Serialize[],
/**
* The newest saved revision of each review the log announced, in the
* order they were first announced.
*/
reviewRevisions: ReviewUpdatedNotification[],
/** The last notification turn whose entire answer was suppressed. */
noopTurn: number | null,
/** The agent that produced the log. See [`Harness`]. */
harness: Harness,
/**
* Current model per the runtime's own `configOptions` responses, so a
* rejected model change never moves it.
*/
model: string | null,
/** The models the runtime offers, in the order it listed them. */
supportedModels: ModelOption[],
/**
* Every setting the ACP agent currently advertises. The list is replaced
* whole whenever ACP returns a new `configOptions` snapshot.
*/
configOptions: SessionConfigOption[],
/** Session title, when the harness reports one. */
title: string | null,
/**
* The slash commands the harness most recently advertised, in the order
* it listed them. Empty until the first `available_commands_update`,
* which arrives right after session setup, before any turn.
*/
availableCommands: AvailableCommand[],
/**
* The last system event's wire name (`"acp_ready"`, `"disconnected"`),
* `None` until the runtime reports one.
*/
status: string | null,
/**
* Requests the user can answer on the current turn and connection.
* Multiple permissions may coexist with the one allowed elicitation.
* History remains in the transcript after these live requests clear.
*/
pendingInteractions: PendingInteraction[],
/**
* Where the newest turn stands, as one value. Readers used to derive it
* from the transcript's tail, the status, and their own record of what
* they had posted; this is that derivation done once, in the fold.
*/
turn: TurnState,
};
/** A timeline event or a card state change. Never a conversation message. */
export type SessionNotification = SessionNotification_Serialize | SessionNotification_Deserialize;
/** A timeline event or a card state change. Never a conversation message. */
export type SessionNotification_Deserialize = {
/** Outbox identity. */
id: string,
/** Subject identity used to find an existing card. */
subjectId: string,
/** Event creation time, RFC3339. */
createdAt: string,
/** Turn that received it. */
turn: number,
/** Stable delivery action identity. */
actionId: string,
/** Whether this turn had no user prompt. */
systemTurn: boolean,
} & NotificationEvent_Deserialize;
/** A timeline event or a card state change. Never a conversation message. */
export type SessionNotification_Serialize = {
/** Outbox identity. */
id: string,
/** Subject identity used to find an existing card. */
subjectId: string,
/** Event creation time, RFC3339. */
createdAt: string,
/** Turn that received it. */
turn: number,
/** Stable delivery action identity. */
actionId: string,
/** Whether this turn had no user prompt. */
systemTurn: boolean,
} & NotificationEvent_Serialize;
/**
* Why a turn stopped.
*
* All but one variant is parsed straight off ACP's `stopReason` wire string
* by [`FromStr`]: the `snake_case` variant names are the wire names, and
* anything unmodelled falls through to [`Self::Other`], so parsing never
* fails. [`Self::Failed`] is the exception - no wire string produces it,
* because it is what a turn that got no `stopReason` at all stopped for.
*/
export type StopReason =
/** The agent finished its turn. */
{ kind: "end_turn" } |
/** The model hit its token limit. */
{ kind: "max_tokens" } |
/** The agent hit its turn-request limit. */
{ kind: "max_turn_requests" } |
/** The agent declined. */
{ kind: "refusal" } |
/** The turn was cancelled. */
{ kind: "cancelled" } |
/** A stop reason this fold does not model, as its wire string. */
{ kind: "other";
/** The unrecognized wire value. */
reason: string } |
/**
* The runtime answered the prompt with a JSON-RPC error, so the turn
* produced no reply and never will.
*
* Constructed by the fold, never parsed: an error response carries no
* `stopReason` to read. Modelled as a stop reason rather than as
* something alongside one because that is what it is - a turn that
* ended - and because every reader already asks `stop` whether a turn
* is still running. A turn left with no stop reason reads as forever in
* flight, which is how a failed prompt used to wedge a session.
*/
{ kind: "failed";
/** The runtime's error message, verbatim. */
message: string;
/**
* The failure in the person's terms, when the runtime classified it
* as one they can act on. Absent for an opaque failure, which a
* reader shows as `message` alone.
*/
notice?: FailureNotice | null };
/**
* What a subagent reported back, as far as its harness told us.
*
* Every field is optional because every harness tells us a different
* subset: Claude Code reports timings, token counts and a per-tool
* breakdown; OpenCode names the child session and its model; Cursor and
* Hermes give back little more than the text. A reader shows what is
* there.
*/
export type SubagentResult = {
/** The subagent's answer, as text. */
text: string | null,
/** Why the subagent failed, when it did. */
error: string | null,
/**
* The harness's id for the subagent or its session, for anyone who
* wants to find it again.
*/
agentId: string | null,
/** The model the subagent ran on. */
model: string | null,
/**
* Wall-clock time the subagent took. `u32` because the browser
* contract forbids 64-bit integers; 49 days of milliseconds is plenty.
*/
durationMs: number | null,
/** Tokens the subagent consumed. `u32` for the same reason. */
tokens: number | null,
/** How many tools the subagent called. */
toolUses: number | null,
/** What kinds of tools the subagent called. */
stats: ToolStats | null,
};
/** How selected tags combine: items with any of them, or with all of them. */
export type TagFilterMode = "any" | "all";
/**
* One tag of an ontology and the narrower tags under it. A tag may exist
* already, or be one the answer proposes.
*/
export type TagNode = TagNode_Serialize | TagNode_Deserialize;
/**
* One tag of an ontology and the narrower tags under it. A tag may exist
* already, or be one the answer proposes.
*/
export type TagNode_Deserialize = {
/**
* The tag's name. Name a narrower tag on its own: "bug" under "Type",
* not "Type/bug".
*/
label: string,
/**
* One of the tag colours: red, tomato, orange, amber, yellow, green,
* teal, blue, indigo, purple, pink, gray. Gray when omitted.
*/
color?: string,
/** What the tag is for, in a few words. */
description?: string,
/**
* For a tag that exists, the id ListTags or CreateTag returned: the tag
* then shows its current name and colour, and opens what is tagged with
* it.
*/
tagId?: string,
/** The narrower tags under this one. */
children?: TagNode_Deserialize[],
};
/**
* One tag of an ontology and the narrower tags under it. A tag may exist
* already, or be one the answer proposes.
*/
export type TagNode_Serialize = {
/**
* The tag's name. Name a narrower tag on its own: "bug" under "Type",
* not "Type/bug".
*/
label: string,
/**
* One of the tag colours: red, tomato, orange, amber, yellow, green,
* teal, blue, indigo, purple, pink, gray. Gray when omitted.
*/
color?: string,
/** What the tag is for, in a few words. */
description?: string,
/**
* For a tag that exists, the id ListTags or CreateTag returned: the tag
* then shows its current name and colour, and opens what is tagged with
* it.
*/
tagId?: string,
/** The narrower tags under this one. */
children?: TagNode_Serialize[],
};
/** How a background task ended, per [`MessagePart::TaskNotification`]. */
export type TaskStatus =
/** It ran to the end. */
"completed" |
/** It ended with an error or a nonzero exit. */
"failed" |
/** It was stopped, or did not survive the previous session. */
"stopped";
/** One event of a timeline. */
export type TimelineEvent = TimelineEvent_Serialize | TimelineEvent_Deserialize;
/** One event of a timeline. */
export type TimelineEvent_Deserialize = {
/** Human-readable timestamp, e.g. "9:32am" or "Yesterday". */
time: string,
title: string,
description?: string,
/** Links the event to a workspace entity. */
entity?: EntityRef,
/**
* true = upcoming/future event, rendered gray; omitted/false = past,
* rendered accent.
*/
future?: boolean,
};
/** One event of a timeline. */
export type TimelineEvent_Serialize = {
/** Human-readable timestamp, e.g. "9:32am" or "Yesterday". */
time: string,
title: string,
description?: string,
/** Links the event to a workspace entity. */
entity?: EntityRef,
/**
* true = upcoming/future event, rendered gray; omitted/false = past,
* rendered accent.
*/
future?: boolean,
};
/** Where a held call stands. */
export type ToolApprovalStatus =
/** Held until the owner answers. */
"pending" |
/** The owner approved it; the call went through. */
"approved" |
/** The owner refused it; the call did not run. */
"denied" |
/** Someone with edit access, the agent, or the session gave up on it. */
"cancelled" |
/** Nobody answered in time. */
"expired";
/**
* What a tool call actually did.
*
* Discriminated by what a reader needs in order to render it, not by ACP's
* [`ToolKind`](agent_client_protocol::ToolKind). A terminal wants command and
* output; an edit wants a diff; a handful of others want the paths they
* touched or whatever text they reported; everything else wants its raw
* input shown as JSON. Every named [`ToolKind`](agent_client_protocol::ToolKind)
* has a variant here, so the fold never falls back to [`Self::Other`] for a
* kind ACP defines - only for `switch_mode` (nothing a reader would want
* rendered) and a kind this fold does not yet know about.
*
* Four variants are chosen by *name* rather than kind: Macro's own tools
* ([`Self::Macro`], [`Self::View`], [`Self::UserTool`]) arrive as ACP `other`, and what a
* reader wants for them is the tool's own JSON, not a generic card; a
* delegation ([`Self::Subagent`]) is a tool call by whatever name its
* harness gives it. The harness layer decides which names are which.
*/
export type ToolDetail = ToolDetail_Serialize | ToolDetail_Deserialize;
/**
* What a tool call actually did.
*
* Discriminated by what a reader needs in order to render it, not by ACP's
* [`ToolKind`](agent_client_protocol::ToolKind). A terminal wants command and
* output; an edit wants a diff; a handful of others want the paths they
* touched or whatever text they reported; everything else wants its raw
* input shown as JSON. Every named [`ToolKind`](agent_client_protocol::ToolKind)
* has a variant here, so the fold never falls back to [`Self::Other`] for a
* kind ACP defines - only for `switch_mode` (nothing a reader would want
* rendered) and a kind this fold does not yet know about.
*
* Four variants are chosen by *name* rather than kind: Macro's own tools
* ([`Self::Macro`], [`Self::View`], [`Self::UserTool`]) arrive as ACP `other`, and what a
* reader wants for them is the tool's own JSON, not a generic card; a
* delegation ([`Self::Subagent`]) is a tool call by whatever name its
* harness gives it. The harness layer decides which names are which.
*/
export type ToolDetail_Deserialize =
/** A shell command. ACP's `execute`. */
({ kind: "terminal";
/** The command line, when the harness reported one. */
command: string | null;
/** Captured output, ANSI escapes intact. See [`AnsiText`]. */
output: AnsiText | null;
/** Process exit code, when the harness reported one. */
exitCode: number | null }) & { acpKind?: never; agentType?: never; background?: never; children?: never; description?: never; diffs?: never; error?: never; input?: never; outcome?: never; paths?: never; prompt?: never; result?: never; title?: never; view?: never } |
/** One or more file modifications. ACP's `edit`. */
({ kind: "edit";
/** The diffs ACP reported for this call. */
diffs: FileDiff[] }) & { acpKind?: never; agentType?: never; background?: never; children?: never; command?: never; description?: never; error?: never; exitCode?: never; input?: never; outcome?: never; output?: never; paths?: never; prompt?: never; result?: never; title?: never; view?: never } |
/** A file read. ACP's `read`. */
({ kind: "read";
/** Paths this call touched. */
paths: string[] }) & { acpKind?: never; agentType?: never; background?: never; children?: never; command?: never; description?: never; diffs?: never; error?: never; exitCode?: never; input?: never; outcome?: never; output?: never; prompt?: never; result?: never; title?: never; view?: never } |
/** One or more files removed. ACP's `delete`. */
({ kind: "delete";
/** Paths this call touched. */
paths: string[] }) & { acpKind?: never; agentType?: never; background?: never; children?: never; command?: never; description?: never; diffs?: never; error?: never; exitCode?: never; input?: never; outcome?: never; output?: never; prompt?: never; result?: never; title?: never; view?: never } |
/**
* One or more files moved or renamed. ACP's `move`.
*
* Only the paths a reader can be sure of. ACP has no standard field for
* "from" versus "to" - a call's `locations` is just the set of paths it
* touched - so this does not guess at a direction.
*/
({ kind: "move";
/** Paths this call touched. */
paths: string[] }) & { acpKind?: never; agentType?: never; background?: never; children?: never; command?: never; description?: never; diffs?: never; error?: never; exitCode?: never; input?: never; outcome?: never; output?: never; prompt?: never; result?: never; title?: never; view?: never } |
/** A search. ACP's `search`. */
({ kind: "search";
/** Paths this call touched. */
paths: string[];
/** Text the call reported - e.g. matched lines - when any. */
output: string | null }) & { acpKind?: never; agentType?: never; background?: never; children?: never; command?: never; description?: never; diffs?: never; error?: never; exitCode?: never; input?: never; outcome?: never; prompt?: never; result?: never; title?: never; view?: never } |
/** Retrieving external data. ACP's `fetch`. */
({ kind: "fetch";
/** Text the call reported, when any. */
output: string | null }) & { acpKind?: never; agentType?: never; background?: never; children?: never; command?: never; description?: never; diffs?: never; error?: never; exitCode?: never; input?: never; outcome?: never; paths?: never; prompt?: never; result?: never; title?: never; view?: never } |
/**
* Explicit reasoning surfaced as its own tool call, as distinct from
* [`MessagePart::Thought`], which is reasoning streamed inline. ACP's
* `think`.
*/
({ kind: "think";
/** Text the call reported, when any. */
output: string | null }) & { acpKind?: never; agentType?: never; background?: never; children?: never; command?: never; description?: never; diffs?: never; error?: never; exitCode?: never; input?: never; outcome?: never; paths?: never; prompt?: never; result?: never; title?: never; view?: never } |
/**
* Anything else: ACP's `switch_mode`, a tool from an MCP server the fold
* knows nothing about, and any kind - including `other` itself,
* [`ToolKind`](agent_client_protocol::ToolKind)'s default for a call
* that names no kind at all - this fold has no special rendering for.
* What a reader wants is the exchange itself: the request the agent
* made and the response it got, as JSON.
*/
({ kind: "other";
/** ACP's tool kind, as its wire string. */
acpKind: string;
/** Text the call reported in its content blocks, when any. */
output: string | null;
/**
* The tool's own arguments, when reported - out of any wrapper the
* harness put around them.
*/
input: unknown;
/**
* The tool's own result, when the harness reported one in
* `rawOutput` - out of the harness's wrapper and MCP's envelope, so
* an MCP tool's `structuredContent` (or its text, parsed when it is
* JSON) arrives as the JSON the tool returned.
*/
result: unknown;
/** The error text, when the harness's wrapper reported failure. */
error: string | null }) & { agentType?: never; background?: never; children?: never; command?: never; description?: never; diffs?: never; exitCode?: never; outcome?: never; paths?: never; prompt?: never; title?: never; view?: never } |
/**
* A Macro tool the fold knows by name - reached over Macro's MCP
* server, or called in-process by Macro's own agent. Input and output
* are the tool's own JSON, any MCP envelope already removed, so a
* reader that knows the tool renders it without parsing the wire.
*/
({ kind: "macro";
/** The tool's arguments, as it defines them. */
input: unknown;
/**
* The tool's result, as it defines it; absent until the call
* completes.
*/
output: unknown;
/** The error text, when the call failed. */
error: string | null }) & { acpKind?: never; agentType?: never; background?: never; children?: never; command?: never; description?: never; diffs?: never; exitCode?: never; outcome?: never; paths?: never; prompt?: never; result?: never; title?: never; view?: never } |
/**
* A view shown to the person: Macro's `DisplayResults`, or the call the
* harness presents for `execution.views.present`. The server decodes
* the view into its result, so this is the view a reader renders.
*/
({ kind: "view";
/** The view, once the call has returned one that decodes. */
view: View_Deserialize | null;
/** The error text, when the call failed. */
error: string | null }) & { acpKind?: never; agentType?: never; background?: never; children?: never; command?: never; description?: never; diffs?: never; exitCode?: never; input?: never; outcome?: never; output?: never; paths?: never; prompt?: never; result?: never; title?: never } |
/**
* A Macro user tool: the agent drafted it, the user finishes it after
* the turn. See [`UserToolOutcome`].
*/
({ kind: "user_tool";
/**
* The draft, as the tool defines its arguments; patched as the
* user edits.
*/
input: unknown;
/** Where the user got to with it. */
outcome: UserToolOutcome }) & { acpKind?: never; agentType?: never; background?: never; children?: never; command?: never; description?: never; diffs?: never; error?: never; exitCode?: never; output?: never; paths?: never; prompt?: never; result?: never; title?: never; view?: never } |
/**
* Work the agent delegated to another agent.
*
* ACP has no notion of this; every harness spells it as a tool call by
* its own conventions (Claude Code's `Agent`, OpenCode's and Cursor's
* `task`, Codex's `spawnAgent`, Hermes's `delegate_task`), and the
* harness reader recognizes it. What the subagent itself did nests in
* `children` when the harness attributes its calls to the parent -
* only Claude Code does today - and is otherwise summarized in
* `result`.
*/
({ kind: "subagent";
/**
* What to call the delegation: the harness's description when it
* gave one, else the first line of the brief, else the tool's own
* name. Always present, so a reader never has to pick a fallback
* itself; `description` and `prompt` stay exactly what the harness
* said.
*/
title: string;
/**
* Which kind of agent was delegated to (`general-purpose`,
* `explore`), when the harness names one.
*/
agentType: string | null;
/** A short description of the task, when given. */
description: string | null;
/** The brief the subagent was given. */
prompt: string | null;
/**
* Whether the subagent was started in the background: its call
* completes at once and its answer, if any, arrives some other way.
*/
background: boolean;
/**
* The subagent's own parts, in arrival order, for a harness that
* attributes them to the parent call.
*/
children: MessagePart_Deserialize[];
/**
* What the subagent reported back, once it has.
*
* Boxed: this is by far the widest thing a part can hold, and every
* part pays for the widest variant.
*/
result: SubagentResult | null }) & { acpKind?: never; command?: never; diffs?: never; error?: never; exitCode?: never; input?: never; outcome?: never; output?: never; paths?: never; view?: never };
/**
* What a tool call actually did.
*
* Discriminated by what a reader needs in order to render it, not by ACP's
* [`ToolKind`](agent_client_protocol::ToolKind). A terminal wants command and
* output; an edit wants a diff; a handful of others want the paths they
* touched or whatever text they reported; everything else wants its raw
* input shown as JSON. Every named [`ToolKind`](agent_client_protocol::ToolKind)
* has a variant here, so the fold never falls back to [`Self::Other`] for a
* kind ACP defines - only for `switch_mode` (nothing a reader would want
* rendered) and a kind this fold does not yet know about.
*
* Four variants are chosen by *name* rather than kind: Macro's own tools
* ([`Self::Macro`], [`Self::View`], [`Self::UserTool`]) arrive as ACP `other`, and what a
* reader wants for them is the tool's own JSON, not a generic card; a
* delegation ([`Self::Subagent`]) is a tool call by whatever name its
* harness gives it. The harness layer decides which names are which.
*/
export type ToolDetail_Serialize =
/** A shell command. ACP's `execute`. */
({ kind: "terminal";
/** The command line, when the harness reported one. */
command: string | null;
/** Captured output, ANSI escapes intact. See [`AnsiText`]. */
output: AnsiText | null;
/** Process exit code, when the harness reported one. */
exitCode: number | null }) & { acpKind?: never; agentType?: never; background?: never; children?: never; description?: never; diffs?: never; error?: never; input?: never; outcome?: never; paths?: never; prompt?: never; result?: never; title?: never; view?: never } |
/** One or more file modifications. ACP's `edit`. */
({ kind: "edit";
/** The diffs ACP reported for this call. */
diffs: FileDiff[] }) & { acpKind?: never; agentType?: never; background?: never; children?: never; command?: never; description?: never; error?: never; exitCode?: never; input?: never; outcome?: never; output?: never; paths?: never; prompt?: never; result?: never; title?: never; view?: never } |
/** A file read. ACP's `read`. */
({ kind: "read";
/** Paths this call touched. */
paths: string[] }) & { acpKind?: never; agentType?: never; background?: never; children?: never; command?: never; description?: never; diffs?: never; error?: never; exitCode?: never; input?: never; outcome?: never; output?: never; prompt?: never; result?: never; title?: never; view?: never } |
/** One or more files removed. ACP's `delete`. */
({ kind: "delete";
/** Paths this call touched. */
paths: string[] }) & { acpKind?: never; agentType?: never; background?: never; children?: never; command?: never; description?: never; diffs?: never; error?: never; exitCode?: never; input?: never; outcome?: never; output?: never; prompt?: never; result?: never; title?: never; view?: never } |
/**
* One or more files moved or renamed. ACP's `move`.
*
* Only the paths a reader can be sure of. ACP has no standard field for
* "from" versus "to" - a call's `locations` is just the set of paths it
* touched - so this does not guess at a direction.
*/
({ kind: "move";
/** Paths this call touched. */
paths: string[] }) & { acpKind?: never; agentType?: never; background?: never; children?: never; command?: never; description?: never; diffs?: never; error?: never; exitCode?: never; input?: never; outcome?: never; output?: never; prompt?: never; result?: never; title?: never; view?: never } |
/** A search. ACP's `search`. */
({ kind: "search";
/** Paths this call touched. */
paths: string[];
/** Text the call reported - e.g. matched lines - when any. */
output: string | null }) & { acpKind?: never; agentType?: never; background?: never; children?: never; command?: never; description?: never; diffs?: never; error?: never; exitCode?: never; input?: never; outcome?: never; prompt?: never; result?: never; title?: never; view?: never } |
/** Retrieving external data. ACP's `fetch`. */
({ kind: "fetch";
/** Text the call reported, when any. */
output: string | null }) & { acpKind?: never; agentType?: never; background?: never; children?: never; command?: never; description?: never; diffs?: never; error?: never; exitCode?: never; input?: never; outcome?: never; paths?: never; prompt?: never; result?: never; title?: never; view?: never } |
/**
* Explicit reasoning surfaced as its own tool call, as distinct from
* [`MessagePart::Thought`], which is reasoning streamed inline. ACP's
* `think`.
*/
({ kind: "think";
/** Text the call reported, when any. */
output: string | null }) & { acpKind?: never; agentType?: never; background?: never; children?: never; command?: never; description?: never; diffs?: never; error?: never; exitCode?: never; input?: never; outcome?: never; paths?: never; prompt?: never; result?: never; title?: never; view?: never } |
/**
* Anything else: ACP's `switch_mode`, a tool from an MCP server the fold
* knows nothing about, and any kind - including `other` itself,
* [`ToolKind`](agent_client_protocol::ToolKind)'s default for a call
* that names no kind at all - this fold has no special rendering for.
* What a reader wants is the exchange itself: the request the agent
* made and the response it got, as JSON.
*/
({ kind: "other";
/** ACP's tool kind, as its wire string. */
acpKind: string;
/** Text the call reported in its content blocks, when any. */
output: string | null;
/**
* The tool's own arguments, when reported - out of any wrapper the
* harness put around them.
*/
input: unknown;
/**
* The tool's own result, when the harness reported one in
* `rawOutput` - out of the harness's wrapper and MCP's envelope, so
* an MCP tool's `structuredContent` (or its text, parsed when it is
* JSON) arrives as the JSON the tool returned.
*/
result: unknown;
/** The error text, when the harness's wrapper reported failure. */
error: string | null }) & { agentType?: never; background?: never; children?: never; command?: never; description?: never; diffs?: never; exitCode?: never; outcome?: never; paths?: never; prompt?: never; title?: never; view?: never } |
/**
* A Macro tool the fold knows by name - reached over Macro's MCP
* server, or called in-process by Macro's own agent. Input and output
* are the tool's own JSON, any MCP envelope already removed, so a
* reader that knows the tool renders it without parsing the wire.
*/
({ kind: "macro";
/** The tool's arguments, as it defines them. */
input: unknown;
/**
* The tool's result, as it defines it; absent until the call
* completes.
*/
output: unknown;
/** The error text, when the call failed. */
error: string | null }) & { acpKind?: never; agentType?: never; background?: never; children?: never; command?: never; description?: never; diffs?: never; exitCode?: never; outcome?: never; paths?: never; prompt?: never; result?: never; title?: never; view?: never } |
/**
* A view shown to the person: Macro's `DisplayResults`, or the call the
* harness presents for `execution.views.present`. The server decodes
* the view into its result, so this is the view a reader renders.
*/
({ kind: "view";
/** The view, once the call has returned one that decodes. */
view: View_Serialize | null;
/** The error text, when the call failed. */
error: string | null }) & { acpKind?: never; agentType?: never; background?: never; children?: never; command?: never; description?: never; diffs?: never; exitCode?: never; input?: never; outcome?: never; output?: never; paths?: never; prompt?: never; result?: never; title?: never } |
/**
* A Macro user tool: the agent drafted it, the user finishes it after
* the turn. See [`UserToolOutcome`].
*/
({ kind: "user_tool";
/**
* The draft, as the tool defines its arguments; patched as the
* user edits.
*/
input: unknown;
/** Where the user got to with it. */
outcome: UserToolOutcome }) & { acpKind?: never; agentType?: never; background?: never; children?: never; command?: never; description?: never; diffs?: never; error?: never; exitCode?: never; output?: never; paths?: never; prompt?: never; result?: never; title?: never; view?: never } |
/**
* Work the agent delegated to another agent.
*
* ACP has no notion of this; every harness spells it as a tool call by
* its own conventions (Claude Code's `Agent`, OpenCode's and Cursor's
* `task`, Codex's `spawnAgent`, Hermes's `delegate_task`), and the
* harness reader recognizes it. What the subagent itself did nests in
* `children` when the harness attributes its calls to the parent -
* only Claude Code does today - and is otherwise summarized in
* `result`.
*/
({ kind: "subagent";
/**
* What to call the delegation: the harness's description when it
* gave one, else the first line of the brief, else the tool's own
* name. Always present, so a reader never has to pick a fallback
* itself; `description` and `prompt` stay exactly what the harness
* said.
*/
title: string;
/**
* Which kind of agent was delegated to (`general-purpose`,
* `explore`), when the harness names one.
*/
agentType: string | null;
/** A short description of the task, when given. */
description: string | null;
/** The brief the subagent was given. */
prompt: string | null;
/**
* Whether the subagent was started in the background: its call
* completes at once and its answer, if any, arrives some other way.
*/
background: boolean;
/**
* The subagent's own parts, in arrival order, for a harness that
* attributes them to the parent call.
*/
children: MessagePart_Serialize[];
/**
* What the subagent reported back, once it has.
*
* Boxed: this is by far the widest thing a part can hold, and every
* part pays for the widest variant.
*/
result: SubagentResult | null }) & { acpKind?: never; command?: never; diffs?: never; error?: never; exitCode?: never; input?: never; outcome?: never; output?: never; paths?: never; view?: never };
/**
* What a harness called a tool.
*
* ACP has no tool-name field - a call carries a human-readable `title` and a
* coarse `kind`, nothing more. The name a reader wants (`Bash`, `ReadContent`)
* is a harness convention: Claude Code writes it to `_meta`, others put it
* in the title, and tools reached over MCP arrive namespaced as
* `mcp__<server>__<tool>`. This type is the one place that namespacing is
* understood, so no reader downstream ever splits a string.
*
* Parsing is infallible: a string that is not an MCP name is a native one,
* however odd it looks. Nothing is dropped for being unrecognized.
*/
export type ToolName =
/**
* A tool the harness owns: `Bash`, `Read`, `Write`, or a Macro tool
* called in-process by Macro's own agent.
*/
{ kind: "native";
/** The name as the harness reported it. */
name: string } |
/**
* A tool reached over MCP, from the server the harness registered it
* under.
*/
{ kind: "mcp";
/** The MCP server's name, as the harness registered it. */
server: string;
/** The tool's name on that server. */
tool: string };
/**
* A subagent's tool use, by kind. Claude Code's `toolStats`, in the fold's
* vocabulary.
*/
export type ToolStats = {
/** Files read. */
reads: number,
/** Searches run. */
searches: number,
/** Shell commands run. */
commands: number,
/** Files edited. */
edits: number,
/** Lines added across those edits. */
linesAdded: number,
/** Lines removed across those edits. */
linesRemoved: number,
/** Anything else. */
other: number,
};
/**
* How far a tool call progressed.
*
* [`ToolStatus::Pending`] and [`ToolStatus::Running`] are legitimate final
* states, not errors: a live session's newest calls have not finished, and a
* session that dies mid-call leaves one behind permanently.
*/
export type ToolStatus =
/** Not started - either still streaming input or awaiting permission. */
"pending" |
/** Currently running. */
"running" |
/** Finished successfully. */
"completed" |
/** Finished unsuccessfully. */
"failed";
/** A tool call within a turn, identified by its ACP `toolCallId`. */
export type ToolUseId = string;
/** What the agent is doing right now, as a typing indicator says it. */
export type TurnPhase =
/** Nothing to show yet, or between steps. */
"thinking" |
/** Writing prose. */
"writing" |
/** Running a tool. */
"working" |
/** Waiting on the user to answer a permission or a question. */
"waiting";
/** Where the newest turn stands. */
export type TurnState =
/** No turn is open. */
"idle" |
/** No turn is open, and the newest agent reply failed. */
"failed" |
/**
* A prompt this client issued is on the wire, unconfirmed, and the agent
* has produced nothing. Only a speculative fold reports this.
*/
"starting" |
/** A turn is open and the agent is working. */
"running" |
/** A stop was issued against the open turn and no stop reason has arrived. */
"stopping" |
/**
* The open turn is waiting on a permission, elicitation, or tool
* approval response.
*/
"blocked" |
/** The runtime reported `disconnected`; whatever was open is not moving. */
"disconnected";
/**
* How far a user tool has got - the fold's reading of the backend's
* `UserToolResponse`, restated each time the call is patched.
*
* A user tool's call completes, from ACP's point of view, the moment the
* agent invokes it: the backend answers `"PendingUserExecution"` and does
* nothing. What happens next - the user editing, sending, or rejecting the
* draft - reaches the log as later patches to the same call, so
* [`Self::Pending`] is where every user tool starts and where one the user
* never touched stays.
*/
export type UserToolOutcome =
/** Awaiting the user. The draft is whatever the input currently holds. */
{ kind: "pending" } |
/**
* The user edited the draft without finishing it; the input holds
* their edits.
*/
{ kind: "edited" } |
/** `SendEmail`: the email went out. */
{ kind: "sent";
/** The sent message's id. */
messageId: string;
/** The thread the message landed in. */
threadId: string } |
/** `SendEmail`: the user saved the draft instead of sending it. */
{ kind: "draft";
/** The saved draft's id. */
draftId: string;
/** The thread the draft belongs to, when it is a reply. */
threadId: string | null } |
/**
* The user executed the tool; this is what the tool returned. The shape
* is the tool's own - a calendar event for `CreateCalendarEvent`.
*/
{ kind: "completed";
/** The tool's result, verbatim. */
result: unknown } |
/** The user declined. */
{ kind: "rejected" } |
/** The call itself failed before the user could act. */
{ kind: "failed";
/** The error, as reported. */
message: string } |
/**
* A result arrived that this fold could not read as a user tool
* response - a shape the backend added after this was written.
*/
{ kind: "unrecognized" };
/** A top-level composed view: a flex column of widgets. */
export type View = View_Serialize | View_Deserialize;
/** A top-level composed view: a flex column of widgets. */
export type View_Deserialize = {
title?: string,
widgets: Widget_Deserialize[],
};
/** A top-level composed view: a flex column of widgets. */
export type View_Serialize = {
title?: string,
widgets: Widget_Serialize[],
};
/**
* One block of a view. Layout is order-driven; nesting is achieved with the
* `container` widget.
*/
export type Widget = Widget_Serialize | Widget_Deserialize;
/**
* One block of a view. Layout is order-driven; nesting is achieved with the
* `container` widget.
*/
export type Widget_Deserialize =
/**
* Markdown text: the narrative between the other widgets. Its type is
* "md", never "markdown".
*/
({ type: "md"; markdown: string }) & { align?: never; channelId?: never; children?: never; direction?: never; events?: never; gap?: never; groupBy?: never; items?: never; justify?: never; limit?: never; messageId?: never; source?: never; tags?: never; title?: never; wrap?: never } |
/** A chronological sequence of events. Great for "what happened" answers. */
({ type: "timeline"; title?: string; events: TimelineEvent_Deserialize[] }) & { align?: never; channelId?: never; children?: never; direction?: never; gap?: never; groupBy?: never; items?: never; justify?: never; limit?: never; markdown?: never; messageId?: never; source?: never; tags?: never; wrap?: never } |
/**
* A list of workspace items, fetched by a filter query or given as a
* fixed set of entity references.
*/
({ type: "list"; title?: string; source: ListSource_Deserialize;
/** Group rows by a facet. */
groupBy?: GroupBy;
/** Cap the number of rows shown. */
limit?: number }) & { align?: never; channelId?: never; children?: never; direction?: never; events?: never; gap?: never; items?: never; justify?: never; markdown?: never; messageId?: never; tags?: never; wrap?: never } |
/** A single channel message with surrounding context. */
({ type: "channelMessage";
/** The channel the message belongs to. */
channelId: string;
/** The message to render. */
messageId: string }) & { align?: never; children?: never; direction?: never; events?: never; gap?: never; groupBy?: never; items?: never; justify?: never; limit?: never; markdown?: never; source?: never; tags?: never; title?: never; wrap?: never } |
/**
* A calendar agenda: the events grouped by day with their times, places
* and attendees, loaded live from the user's calendars. Use it whenever
* an answer is about calendar events instead of listing them in text.
*/
({ type: "events"; title?: string; events: AgendaEvent_Deserialize[] }) & { align?: never; channelId?: never; children?: never; direction?: never; gap?: never; groupBy?: never; items?: never; justify?: never; limit?: never; markdown?: never; messageId?: never; source?: never; tags?: never; wrap?: never } |
/**
* Rich cards for the one to four specific items the answer is about: a
* document or spreadsheet, an email thread, a calendar event, a project,
* a channel, a routine, a form or an initiative. Each card opens its
* item, and a routine's card can pause it or run it now. Use a list
* widget for longer sets.
*/
({ type: "cards"; title?: string; items: CardItem[] }) & { align?: never; channelId?: never; children?: never; direction?: never; events?: never; gap?: never; groupBy?: never; justify?: never; limit?: never; markdown?: never; messageId?: never; source?: never; tags?: never; wrap?: never } |
/**
* Tags as coloured pills, nested to any depth: the user's tags, a
* taxonomy the answer proposes, or any other ontology of tags, each with
* what it is for. Use it whenever an answer is about tags, instead of a
* table or a list in markdown.
*/
({ type: "tags"; title?: string; tags: TagNode_Deserialize[] }) & { align?: never; channelId?: never; children?: never; direction?: never; events?: never; gap?: never; groupBy?: never; items?: never; justify?: never; limit?: never; markdown?: never; messageId?: never; source?: never; wrap?: never } |
/** A nestable flex container of widgets. */
({ type: "container"; direction?: Direction;
/** Tailwind-ish gap step, 0-8. Defaults to 3. */
gap?: Gap; wrap?: boolean; align?: Align; justify?: Justify; title?: string; children: Widget_Deserialize[] }) & { channelId?: never; events?: never; groupBy?: never; items?: never; limit?: never; markdown?: never; messageId?: never; source?: never; tags?: never };
/**
* One block of a view. Layout is order-driven; nesting is achieved with the
* `container` widget.
*/
export type Widget_Serialize =
/**
* Markdown text: the narrative between the other widgets. Its type is
* "md", never "markdown".
*/
({ type: "md"; markdown: string }) & { align?: never; channelId?: never; children?: never; direction?: never; events?: never; gap?: never; groupBy?: never; items?: never; justify?: never; limit?: never; messageId?: never; source?: never; tags?: never; title?: never; wrap?: never } |
/** A chronological sequence of events. Great for "what happened" answers. */
({ type: "timeline"; title?: string; events: TimelineEvent_Serialize[] }) & { align?: never; channelId?: never; children?: never; direction?: never; gap?: never; groupBy?: never; items?: never; justify?: never; limit?: never; markdown?: never; messageId?: never; source?: never; tags?: never; wrap?: never } |
/**
* A list of workspace items, fetched by a filter query or given as a
* fixed set of entity references.
*/
({ type: "list"; title?: string; source: ListSource_Serialize;
/** Group rows by a facet. */
groupBy?: GroupBy;
/** Cap the number of rows shown. */
limit?: number }) & { align?: never; channelId?: never; children?: never; direction?: never; events?: never; gap?: never; items?: never; justify?: never; markdown?: never; messageId?: never; tags?: never; wrap?: never } |
/** A single channel message with surrounding context. */
({ type: "channelMessage";
/** The channel the message belongs to. */
channelId: string;
/** The message to render. */
messageId: string }) & { align?: never; children?: never; direction?: never; events?: never; gap?: never; groupBy?: never; items?: never; justify?: never; limit?: never; markdown?: never; source?: never; tags?: never; title?: never; wrap?: never } |
/**
* A calendar agenda: the events grouped by day with their times, places
* and attendees, loaded live from the user's calendars. Use it whenever
* an answer is about calendar events instead of listing them in text.
*/
({ type: "events"; title?: string; events: AgendaEvent_Serialize[] }) & { align?: never; channelId?: never; children?: never; direction?: never; gap?: never; groupBy?: never; items?: never; justify?: never; limit?: never; markdown?: never; messageId?: never; source?: never; tags?: never; wrap?: never } |
/**
* Rich cards for the one to four specific items the answer is about: a
* document or spreadsheet, an email thread, a calendar event, a project,
* a channel, a routine, a form or an initiative. Each card opens its
* item, and a routine's card can pause it or run it now. Use a list
* widget for longer sets.
*/
({ type: "cards"; title?: string; items: CardItem[] }) & { align?: never; channelId?: never; children?: never; direction?: never; events?: never; gap?: never; groupBy?: never; justify?: never; limit?: never; markdown?: never; messageId?: never; source?: never; tags?: never; wrap?: never } |
/**
* Tags as coloured pills, nested to any depth: the user's tags, a
* taxonomy the answer proposes, or any other ontology of tags, each with
* what it is for. Use it whenever an answer is about tags, instead of a
* table or a list in markdown.
*/
({ type: "tags"; title?: string; tags: TagNode_Serialize[] }) & { align?: never; channelId?: never; children?: never; direction?: never; events?: never; gap?: never; groupBy?: never; items?: never; justify?: never; limit?: never; markdown?: never; messageId?: never; source?: never; wrap?: never } |
/** A nestable flex container of widgets. */
({ type: "container"; direction?: Direction;
/** Tailwind-ish gap step, 0-8. Defaults to 3. */
gap?: Gap; wrap?: boolean; align?: Align; justify?: Justify; title?: string; children: Widget_Serialize[] }) & { channelId?: never; events?: never; groupBy?: never; items?: never; limit?: never; markdown?: never; messageId?: never; source?: never; tags?: never };