@adecore/agent-contracts 0.23.0 → 0.24.0

package/src/index.ts

@@ -1,13 +1,413 @@
-export * from './agent.ts';
-export * from './chat.ts';
-export * from './envelope.ts';
-export * from './ids.ts';
-export * from './model.ts';
-export * from './protocol.ts';
-export * from './provider-accounts.ts';
-export * from './task.ts';
-export * from './text.ts';
-export * from './usage.ts';
-export * from './visual.ts';
-export * from './worktree.ts';
-export type * from './port.ts';
+// Public API: exports.test.ts snapshots this list, so a name added or dropped here is an API change.
+export {
+    AgentKindSchema,
+    type AgentKind,
+    AgentStatusSchema,
+    type AgentStatus,
+    SUGGESTED_TITLE_LIMIT,
+    SuggestedTitleSchema,
+    AgentRequestSchema,
+    type AgentRequest,
+    AgentInfoSchema,
+    type AgentInfo,
+    SessionStatusEventSchema,
+    type SessionStatusEvent,
+    AgentResumePayloadSchema,
+    type AgentResumePayload,
+    ApprovalChoiceSchema,
+    type ApprovalChoice,
+    ApprovalRequestSchema,
+    type ApprovalRequest,
+    SessionApprovalsEventSchema,
+    type SessionApprovalsEvent,
+    ApprovalAnswerPayloadSchema,
+    type ApprovalAnswerPayload,
+    ApprovalAnswerResultSchema,
+    type ApprovalAnswerResult,
+    ApprovalPreferencePayloadSchema,
+    type ApprovalPreferencePayload
+} from './agent.ts';
+export {
+    ChatIdSchema,
+    type ChatId,
+    ChatContextBreakdownSchema,
+    type ChatContextBreakdown,
+    ChatUsageSchema,
+    type ChatUsage,
+    CHAT_ATTACHMENTS_MAX_BYTES,
+    CHAT_ATTACHMENT_MAX_BYTES,
+    CHAT_ATTACHMENTS_MAX_COUNT,
+    attachmentBytes,
+    attachmentImageMime,
+    ChatAttachmentUploadSchema,
+    type ChatAttachmentUpload,
+    ChatAttachmentUploadsSchema,
+    ChatAttachmentSchema,
+    type ChatAttachment,
+    ChatUiChoiceOriginSchema,
+    type ChatUiChoiceOrigin,
+    ChatUiAnswerSchema,
+    type ChatUiAnswer,
+    ChatQuoteSourceSchema,
+    type ChatQuoteSource,
+    ChatQueuedMessageSchema,
+    type ChatQueuedMessage,
+    ChatBackgroundTaskSchema,
+    type ChatBackgroundTask,
+    ChatTurnLimitSchema,
+    type ChatTurnLimit,
+    ChatGoalStatusSchema,
+    type ChatGoalStatus,
+    ChatGoalSchema,
+    type ChatGoal,
+    ChatQuestionSchema,
+    type ChatQuestion,
+    ChatRequestKindSchema,
+    type ChatRequestKind,
+    CHAT_REQUEST_LIMITS,
+    ChatRequestApprovalSchema,
+    type ChatRequestApproval,
+    ChatRequestSummarySchema,
+    type ChatRequestSummary,
+    ChatInfoSchema,
+    type ChatInfo,
+    ChatSkillSourceSchema,
+    type ChatSkillSource,
+    ChatSkillSchema,
+    type ChatSkill,
+    SkillsListPayloadSchema,
+    type SkillsListPayload,
+    SkillsListResultSchema,
+    type SkillsListResult,
+    ChatUserItemSchema,
+    ChatUiQueryReadingSchema,
+    type ChatUiQueryReading,
+    ChatUiLinkReadingSchema,
+    type ChatUiLinkReading,
+    ChatUiQueryStateSchema,
+    type ChatUiQueryState,
+    ChatAssistantItemSchema,
+    ChatThinkingItemSchema,
+    ChatToolStateSchema,
+    type ChatToolState,
+    ChatToolProgressSchema,
+    type ChatToolProgress,
+    ChatFileChangeSchema,
+    type ChatFileChange,
+    ChatSubagentStatusSchema,
+    type ChatSubagentStatus,
+    ChatWorkflowPhaseSchema,
+    type ChatWorkflowPhase,
+    ChatWorkflowAgentSchema,
+    type ChatWorkflowAgent,
+    ChatWorkflowSchema,
+    type ChatWorkflow,
+    workflowAgentRef,
+    workflowAgentIdOf,
+    ChatToolItemSchema,
+    ChatSubagentUsageSchema,
+    type ChatSubagentUsage,
+    HOST_TASK_ORIGIN,
+    ChatSubagentItemSchema,
+    ChatApprovalDecisionSchema,
+    type ChatApprovalDecision,
+    ChatApprovalItemSchema,
+    ChatQuestionItemSchema,
+    ChatCheckpointFileSchema,
+    type ChatCheckpointFile,
+    ChatCheckpointDiffSchema,
+    type ChatCheckpointDiff,
+    ChatTurnItemSchema,
+    notResumedNote,
+    abortedByMachine,
+    WAITING_NOTE_PREFIX,
+    ChatNoteItemSchema,
+    ChatCompactionItemSchema,
+    ChatItemSchema,
+    type ChatItem,
+    type ChatUserItem,
+    type ChatAssistantItem,
+    type ChatThinkingItem,
+    type ChatToolItem,
+    type ChatSubagentItem,
+    type ChatApprovalItem,
+    type ChatQuestionItem,
+    type ChatTurnItem,
+    type ChatNoteItem,
+    type ChatCompactionItem,
+    ChatEventSchema,
+    type ChatEvent,
+    ChatEventEnvelopeSchema,
+    type ChatEventEnvelope,
+    ChatCreatePayloadSchema,
+    type ChatCreatePayload,
+    ChatConfigurePayloadSchema,
+    type ChatConfigurePayload,
+    ChatPreferencesPayloadSchema,
+    type ChatPreferencesPayload,
+    ChatTargetPayloadSchema,
+    type ChatTargetPayload,
+    ChatClearPayloadSchema,
+    type ChatClearPayload,
+    ChatCancelPayloadSchema,
+    type ChatCancelPayload,
+    ChatAttachPayloadSchema,
+    ChatHistoryPayloadSchema,
+    ChatHistoryPageSchema,
+    ChatHistoryResultSchema,
+    type ChatHistoryResult,
+    ChatSubagentPayloadSchema,
+    type ChatSubagentPayload,
+    ChatStopSubagentPayloadSchema,
+    type ChatStopSubagentPayload,
+    ChatGoalActionSchema,
+    type ChatGoalAction,
+    ChatGoalPayloadSchema,
+    type ChatGoalPayload,
+    ChatStopTaskPayloadSchema,
+    type ChatStopTaskPayload,
+    ChatSubagentPageSchema,
+    ChatSubagentSourceSchema,
+    type ChatSubagentSource,
+    ChatSubagentResultSchema,
+    type ChatSubagentResult,
+    ChatStatusEventSchema,
+    type ChatStatusEvent,
+    ChatSubagentChangedEventSchema,
+    type ChatSubagentChangedEvent,
+    CHAT_BOOKMARK_LIMITS,
+    ChatBookmarkSchema,
+    type ChatBookmark,
+    ChatBookmarksSchema,
+    ChatAddBookmarkPayloadSchema,
+    type ChatAddBookmarkPayload,
+    ChatRenameBookmarkPayloadSchema,
+    type ChatRenameBookmarkPayload,
+    ChatRemoveBookmarkPayloadSchema,
+    type ChatRemoveBookmarkPayload,
+    ChatBookmarksResultSchema,
+    type ChatBookmarksResult,
+    ChatBookmarksEventSchema,
+    type ChatBookmarksEvent,
+    ChatRemoveVisualPayloadSchema,
+    type ChatRemoveVisualPayload,
+    ChatVisualsResultSchema,
+    type ChatVisualsResult,
+    ChatVisualsEventSchema,
+    type ChatVisualsEvent,
+    ChatAttachResultSchema,
+    type ChatAttachResult,
+    ChatDeliverySchema,
+    type ChatDelivery,
+    ChatSendPayloadSchema,
+    type ChatSendPayload,
+    ChatSendResultSchema,
+    type ChatSendResult,
+    ChatUiChoicePayloadSchema,
+    type ChatUiChoicePayload,
+    ChatUiQueryPayloadSchema,
+    type ChatUiQueryPayload,
+    ChatUiLinkPayloadSchema,
+    type ChatUiLinkPayload,
+    ChatQueuePayloadSchema,
+    type ChatQueuePayload,
+    ChatUnqueueResultSchema,
+    type ChatUnqueueResult,
+    ChatApprovePayloadSchema,
+    type ChatApprovePayload,
+    ChatDismissPayloadSchema,
+    type ChatDismissPayload,
+    ChatAnswerPayloadSchema,
+    type ChatAnswerPayload,
+    ChatTurnDiffPayloadSchema,
+    type ChatTurnDiffPayload,
+    ChatTurnDiffResultSchema,
+    type ChatTurnDiffResult,
+    CHAT_FORK_TITLE_MAX,
+    ChatForkPayloadSchema,
+    type ChatForkPayload,
+    ChatForkResultSchema,
+    type ChatForkResult,
+    ChatContinueOnPayloadSchema,
+    type ChatContinueOnPayload,
+    ChatContinueOnResultSchema,
+    type ChatContinueOnResult,
+    ChatSummarizePayloadSchema,
+    type ChatSummarizePayload,
+    ChatSummarizeResultSchema,
+    type ChatSummarizeResult,
+    ChatForkInfoPayloadSchema,
+    type ChatForkInfoPayload,
+    ChatForkInfoResultSchema,
+    type ChatForkInfoResult,
+    ChatListResultSchema,
+    type ChatListResult,
+    GeneratedImageInputSchema,
+    type GeneratedImageInput,
+    generatedImageAttachment
+} from './chat.ts';
+export {
+    ErrorSchema,
+    type WireError,
+    RequestSchema,
+    type Request,
+    ReplyOkSchema,
+    type ReplyOk,
+    ReplyErrorSchema,
+    type ReplyError,
+    ReplySchema,
+    type Reply,
+    EventSchema,
+    type Event,
+    ServerFrameSchema,
+    type ServerFrame,
+    type ParseResult,
+    parseRequest,
+    parseServerFrame
+} from './envelope.ts';
+export { SessionIdSchema, type SessionId } from './ids.ts';
+export {
+    ModelOptionChoiceSchema,
+    type ModelOptionChoice,
+    ModelOptionDescriptorSchema,
+    type ModelOptionDescriptor,
+    ModelInfoSchema,
+    type ModelInfo,
+    ModelSelectionSchema,
+    type ModelSelection,
+    ModelCatalogProfileSchema,
+    type ModelCatalogProfile,
+    ModelCatalogEntrySchema,
+    type ModelCatalogEntry,
+    ModelCatalogDataSchema,
+    type ModelCatalogData,
+    RuntimeModeSchema,
+    type RuntimeMode,
+    ProviderCapabilitiesSchema,
+    type ProviderCapabilities,
+    ProviderInfoSchema,
+    type ProviderInfo,
+    ProviderListResultSchema,
+    type ProviderListResult,
+    resumeCommandFor
+} from './model.ts';
+export type { FramePort } from './port.ts';
+export { EmptySchema, AGENT_REQUEST_SCHEMAS, AGENT_EVENT_SCHEMAS, type AgentRequestType, type AgentEventType } from './protocol.ts';
+export {
+    ProviderAccountIdSchema,
+    type ProviderAccountId,
+    ProviderAccountVariableSchema,
+    type ProviderAccountVariable,
+    ProviderAccountSchema,
+    type ProviderAccount,
+    ProviderAccountStateSchema,
+    type ProviderAccountState,
+    ProviderAccountStatusSchema,
+    type ProviderAccountStatus,
+    ProviderAccountMapSchema,
+    type ProviderAccountMap,
+    ProviderAccountsSchema,
+    type ProviderAccounts,
+    ProviderAccountsSavePayloadSchema,
+    type ProviderAccountsSavePayload,
+    ProviderAccountCreatePayloadSchema,
+    type ProviderAccountCreatePayload,
+    ProviderAccountCreateResultSchema,
+    type ProviderAccountCreateResult,
+    ProviderAccountWatchLoginPayloadSchema,
+    type ProviderAccountWatchLoginPayload
+} from './provider-accounts.ts';
+export { isRecord } from './record.ts';
+export {
+    TaskStatusSchema,
+    type TaskStatus,
+    TaskResultSchema,
+    type TaskResult,
+    TaskSchema,
+    type Task,
+    TaskChangedEventSchema,
+    type TaskChangedEvent
+} from './task.ts';
+export { clipText, TOOL_OUTPUT_TAIL, appendToolOutput } from './text.ts';
+export {
+    UsageProviderSchema,
+    type UsageProvider,
+    USAGE_PROVIDERS,
+    UsageResolutionSchema,
+    type UsageResolution,
+    UsageTotalsSchema,
+    type UsageTotals,
+    EMPTY_TOTALS,
+    totalTokensOf,
+    addTotals,
+    UsageAccountSchema,
+    type UsageAccount,
+    UsageBucketSchema,
+    type UsageBucket,
+    UsagePriceBasisSchema,
+    type UsagePriceBasis,
+    UsageModelSchema,
+    type UsageModel,
+    UsageProjectSchema,
+    type UsageProject,
+    UsageSummaryPayloadSchema,
+    type UsageSummaryPayload,
+    UsageScanSchema,
+    type UsageScan,
+    UsagePricingSchema,
+    type UsagePricing,
+    UsageRootSchema,
+    type UsageRoot,
+    UsageRateSchema,
+    type UsageRate,
+    UsageSummaryResultSchema,
+    type UsageSummaryResult,
+    UsageChangedEventSchema,
+    type UsageChangedEvent,
+    UsageWindowSchema,
+    type UsageWindow,
+    UsageLimitsProviderSchema,
+    type UsageLimitsProvider,
+    UsageLimitsSnapshotSchema,
+    type UsageLimitsSnapshot
+} from './usage.ts';
+export {
+    VISUAL_LIMITS,
+    VISUAL_MEASURE_WIDTHS,
+    VisualHeightSchema,
+    type VisualHeight,
+    VisualLayoutSchema,
+    type VisualLayout,
+    ChatVisualSchema,
+    type ChatVisual,
+    ChatVisualsSchema,
+    visualFrameHeight,
+    VISUAL_BRIDGE_METHODS,
+    type VisualAppearance,
+    type VisualTheme,
+    type VisualRequestId,
+    type VisualViewport,
+    type VisualScrollRequest,
+    visualViewportMessage,
+    visualScrollMessage,
+    type VisualMessage,
+    visualProxyReadyMessage,
+    visualResourceReadyMessage,
+    visualHostContextMessage,
+    visualSizeChangedMessage,
+    visualOpenLinkRequest,
+    visualOpenLinkResult,
+    parseVisualMessage,
+    VISUAL_THEME_VARIABLES,
+    type VisualThemeVariable,
+    VISUAL_LIGHT_THEME,
+    VISUAL_DARK_THEME,
+    cleanVisualVariables,
+    visualThemeFragment,
+    VISUAL_PAGE_RULES,
+    VISUAL_LAYOUT_GUIDE,
+    VISUAL_THEME_GUIDE,
+    injectVisualBootstrap,
+    VISUAL_HOST_PAGE
+} from './visual.ts';
+export { WorktreeWorkSchema, type WorktreeWork, WorktreeSchema, type Worktree } from './worktree.ts';

package/src/model.ts

@@ -109,13 +109,19 @@ export const ProviderCapabilitiesSchema = z.object({
     allowAlways: z.boolean(),
     // A question the person may leave alone while the turn goes on.
     asyncQuestions: z.boolean(),
+    // Whether a message sent while a turn runs can join that turn rather than wait for the next;
+    // absent where it cannot, which is also what a host from before this field reports.
+    steer: z.boolean().optional(),
     // Folding the context: a call of its own, a slash command sent as a turn, or nothing.
     compaction: z.enum(['native', 'prompt', 'none']),
     reportsCost: z.boolean(),
     reportsContextWindow: z.boolean(),
     // Whether the CLI hands over what the model thought before it answered.
     reportsThinking: z.boolean(),
-    slashCommands: z.boolean()
+    slashCommands: z.boolean(),
+    // How `/goal` reaches the CLI: through a protocol of its own that pauses, resumes and clears (`native`),
+    // or as the slash command alone (`command`); absent where the CLI has no goals.
+    goals: z.enum(['native', 'command']).optional()
 });
 export type ProviderCapabilities = z.infer<typeof ProviderCapabilitiesSchema>;
 

package/src/protocol.ts

@@ -19,6 +19,7 @@ import {
     ChatForkInfoResultSchema,
     ChatForkPayloadSchema,
     ChatForkResultSchema,
+    ChatGoalPayloadSchema,
     ChatHistoryPayloadSchema,
     ChatHistoryResultSchema,
     ChatInfoSchema,
@@ -96,6 +97,7 @@ export const AGENT_REQUEST_SCHEMAS = {
     'chat.subagent': { payload: ChatSubagentPayloadSchema, result: ChatSubagentResultSchema },
     'chat.stopSubagent': { payload: ChatStopSubagentPayloadSchema, result: EmptySchema },
     'chat.stopTask': { payload: ChatStopTaskPayloadSchema, result: EmptySchema },
+    'chat.goal': { payload: ChatGoalPayloadSchema, result: EmptySchema },
     'chat.addBookmark': { payload: ChatAddBookmarkPayloadSchema, result: ChatBookmarksResultSchema },
     'chat.renameBookmark': { payload: ChatRenameBookmarkPayloadSchema, result: ChatBookmarksResultSchema },
     'chat.removeBookmark': { payload: ChatRemoveBookmarkPayloadSchema, result: ChatBookmarksResultSchema },
@@ -115,6 +117,8 @@ export const AGENT_REQUEST_SCHEMAS = {
     'usage.limits': { payload: EmptySchema, result: UsageLimitsSnapshotSchema },
     'usage.refreshLimits': { payload: EmptySchema, result: UsageLimitsSnapshotSchema },
     'chat.kill': { payload: ChatTargetPayloadSchema, result: EmptySchema },
+    // Ends the chat's CLI and keeps the conversation, which the next message resumes in a fresh process.
+    'chat.restart': { payload: ChatTargetPayloadSchema, result: EmptySchema },
     'chat.list': { payload: EmptySchema, result: ChatListResultSchema }
 } as const;
 

package/src/record.ts

@@ -0,0 +1,4 @@
+/* A plain object read off the wire or a file, whose fields are still unchecked; an array is not one. */
+export function isRecord(value: unknown): value is Record<string, unknown> {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}

package/src/text.ts

@@ -18,3 +18,20 @@ export function clipText(text: string, max: number): string {
     }
     return text.slice(0, end);
 }
+
+// What a running tool call keeps of the output it streams; the host and every client cut it alike, so a delta grows both the same way.
+export const TOOL_OUTPUT_TAIL = 64 * 1024;
+
+/* `output` with `text` after it, cut to its last `TOOL_OUTPUT_TAIL` UTF-16 units, never between the halves of a surrogate pair. */
+export function appendToolOutput(output: string | null, text: string): string {
+    const whole = (output ?? '') + text;
+    let start = whole.length - TOOL_OUTPUT_TAIL;
+    if (start <= 0) {
+        return whole;
+    }
+    const unit = whole.charCodeAt(start);
+    if (unit >= 0xdc00 && unit <= 0xdfff) {
+        start += 1;
+    }
+    return whole.slice(start);
+}

package/src/visual.ts

@@ -1,4 +1,5 @@
 import { z } from 'zod';
+import { isRecord } from './record.ts';
 import { visualViewportScript } from './visual-viewport.ts';
 
 /*
@@ -162,10 +163,6 @@ export function visualOpenLinkResult(id: VisualRequestId) {
     return { jsonrpc: '2.0', id, result: {} } as const;
 }
 
-function isRecord(value: unknown): value is Record<string, unknown> {
-    return typeof value === 'object' && value !== null && !Array.isArray(value);
-}
-
 function sizeOf(value: unknown): number | undefined {
     return typeof value === 'number' && Number.isFinite(value) && value >= 0 ? value : undefined;
 }