@adecore/agent-contracts 0.23.1 → 0.24.0

package/dist/protocol.d.ts

@@ -175,6 +175,22 @@ export declare const AGENT_REQUEST_SCHEMAS: {
                     async: z.ZodOptional<z.ZodBoolean>;
                 }, z.core.$strip>>;
             }, z.core.$strip>>>;
+            goal: z.ZodOptional<z.ZodObject<{
+                objective: z.ZodString;
+                status: z.ZodEnum<{
+                    active: "active";
+                    blocked: "blocked";
+                    "budget-limited": "budget-limited";
+                    complete: "complete";
+                    paused: "paused";
+                    "usage-limited": "usage-limited";
+                }>;
+                checks: z.ZodOptional<z.ZodNumber>;
+                lastCheck: z.ZodOptional<z.ZodString>;
+                tokensUsed: z.ZodOptional<z.ZodNumber>;
+                tokenBudget: z.ZodOptional<z.ZodNumber>;
+                secondsUsed: z.ZodOptional<z.ZodNumber>;
+            }, z.core.$strip>>;
             createdAt: z.ZodNumber;
         }, z.core.$strip>;
     };
@@ -673,6 +689,22 @@ export declare const AGENT_REQUEST_SCHEMAS: {
                         async: z.ZodOptional<z.ZodBoolean>;
                     }, z.core.$strip>>;
                 }, z.core.$strip>>>;
+                goal: z.ZodOptional<z.ZodObject<{
+                    objective: z.ZodString;
+                    status: z.ZodEnum<{
+                        active: "active";
+                        blocked: "blocked";
+                        "budget-limited": "budget-limited";
+                        complete: "complete";
+                        paused: "paused";
+                        "usage-limited": "usage-limited";
+                    }>;
+                    checks: z.ZodOptional<z.ZodNumber>;
+                    lastCheck: z.ZodOptional<z.ZodString>;
+                    tokensUsed: z.ZodOptional<z.ZodNumber>;
+                    tokenBudget: z.ZodOptional<z.ZodNumber>;
+                    secondsUsed: z.ZodOptional<z.ZodNumber>;
+                }, z.core.$strip>>;
                 createdAt: z.ZodNumber;
             }, z.core.$strip>;
             items: z.ZodArray<z.ZodDiscriminatedUnion<[z.ZodObject<{
@@ -1864,6 +1896,22 @@ export declare const AGENT_REQUEST_SCHEMAS: {
                             async: z.ZodOptional<z.ZodBoolean>;
                         }, z.core.$strip>>;
                     }, z.core.$strip>>>;
+                    goal: z.ZodOptional<z.ZodObject<{
+                        objective: z.ZodString;
+                        status: z.ZodEnum<{
+                            active: "active";
+                            blocked: "blocked";
+                            "budget-limited": "budget-limited";
+                            complete: "complete";
+                            paused: "paused";
+                            "usage-limited": "usage-limited";
+                        }>;
+                        checks: z.ZodOptional<z.ZodNumber>;
+                        lastCheck: z.ZodOptional<z.ZodString>;
+                        tokensUsed: z.ZodOptional<z.ZodNumber>;
+                        tokenBudget: z.ZodOptional<z.ZodNumber>;
+                        secondsUsed: z.ZodOptional<z.ZodNumber>;
+                    }, z.core.$strip>>;
                     createdAt: z.ZodNumber;
                 }, z.core.$strip>;
             }, z.core.$strip>, z.ZodObject<{
@@ -2018,6 +2066,22 @@ export declare const AGENT_REQUEST_SCHEMAS: {
                             async: z.ZodOptional<z.ZodBoolean>;
                         }, z.core.$strip>>;
                     }, z.core.$strip>>>;
+                    goal: z.ZodOptional<z.ZodObject<{
+                        objective: z.ZodString;
+                        status: z.ZodEnum<{
+                            active: "active";
+                            blocked: "blocked";
+                            "budget-limited": "budget-limited";
+                            complete: "complete";
+                            paused: "paused";
+                            "usage-limited": "usage-limited";
+                        }>;
+                        checks: z.ZodOptional<z.ZodNumber>;
+                        lastCheck: z.ZodOptional<z.ZodString>;
+                        tokensUsed: z.ZodOptional<z.ZodNumber>;
+                        tokenBudget: z.ZodOptional<z.ZodNumber>;
+                        secondsUsed: z.ZodOptional<z.ZodNumber>;
+                    }, z.core.$strip>>;
                     createdAt: z.ZodNumber;
                 }, z.core.$strip>;
                 items: z.ZodArray<z.ZodDiscriminatedUnion<[z.ZodObject<{
@@ -2723,6 +2787,22 @@ export declare const AGENT_REQUEST_SCHEMAS: {
                     async: z.ZodOptional<z.ZodBoolean>;
                 }, z.core.$strip>>;
             }, z.core.$strip>>>;
+            goal: z.ZodOptional<z.ZodObject<{
+                objective: z.ZodString;
+                status: z.ZodEnum<{
+                    active: "active";
+                    blocked: "blocked";
+                    "budget-limited": "budget-limited";
+                    complete: "complete";
+                    paused: "paused";
+                    "usage-limited": "usage-limited";
+                }>;
+                checks: z.ZodOptional<z.ZodNumber>;
+                lastCheck: z.ZodOptional<z.ZodString>;
+                tokensUsed: z.ZodOptional<z.ZodNumber>;
+                tokenBudget: z.ZodOptional<z.ZodNumber>;
+                secondsUsed: z.ZodOptional<z.ZodNumber>;
+            }, z.core.$strip>>;
             createdAt: z.ZodNumber;
         }, z.core.$strip>;
     };
@@ -2975,6 +3055,22 @@ export declare const AGENT_REQUEST_SCHEMAS: {
                         async: z.ZodOptional<z.ZodBoolean>;
                     }, z.core.$strip>>;
                 }, z.core.$strip>>>;
+                goal: z.ZodOptional<z.ZodObject<{
+                    objective: z.ZodString;
+                    status: z.ZodEnum<{
+                        active: "active";
+                        blocked: "blocked";
+                        "budget-limited": "budget-limited";
+                        complete: "complete";
+                        paused: "paused";
+                        "usage-limited": "usage-limited";
+                    }>;
+                    checks: z.ZodOptional<z.ZodNumber>;
+                    lastCheck: z.ZodOptional<z.ZodString>;
+                    tokensUsed: z.ZodOptional<z.ZodNumber>;
+                    tokenBudget: z.ZodOptional<z.ZodNumber>;
+                    secondsUsed: z.ZodOptional<z.ZodNumber>;
+                }, z.core.$strip>>;
                 createdAt: z.ZodNumber;
             }, z.core.$strip>;
             nodeId: z.ZodString;
@@ -3160,6 +3256,22 @@ export declare const AGENT_REQUEST_SCHEMAS: {
                             async: z.ZodOptional<z.ZodBoolean>;
                         }, z.core.$strip>>;
                     }, z.core.$strip>>>;
+                    goal: z.ZodOptional<z.ZodObject<{
+                        objective: z.ZodString;
+                        status: z.ZodEnum<{
+                            active: "active";
+                            blocked: "blocked";
+                            "budget-limited": "budget-limited";
+                            complete: "complete";
+                            paused: "paused";
+                            "usage-limited": "usage-limited";
+                        }>;
+                        checks: z.ZodOptional<z.ZodNumber>;
+                        lastCheck: z.ZodOptional<z.ZodString>;
+                        tokensUsed: z.ZodOptional<z.ZodNumber>;
+                        tokenBudget: z.ZodOptional<z.ZodNumber>;
+                        secondsUsed: z.ZodOptional<z.ZodNumber>;
+                    }, z.core.$strip>>;
                     createdAt: z.ZodNumber;
                 }, z.core.$strip>;
                 nodeId: z.ZodString;
@@ -3625,6 +3737,17 @@ export declare const AGENT_REQUEST_SCHEMAS: {
         }, z.core.$strip>;
         readonly result: z.ZodObject<{}, z.core.$strip>;
     };
+    readonly 'chat.goal': {
+        readonly payload: z.ZodObject<{
+            chatId: z.ZodString;
+            action: z.ZodEnum<{
+                clear: "clear";
+                pause: "pause";
+                resume: "resume";
+            }>;
+        }, z.core.$strip>;
+        readonly result: z.ZodObject<{}, z.core.$strip>;
+    };
     readonly 'chat.addBookmark': {
         readonly payload: z.ZodObject<{
             chatId: z.ZodString;
@@ -3761,6 +3884,7 @@ export declare const AGENT_REQUEST_SCHEMAS: {
                     denyReason: z.ZodBoolean;
                     allowAlways: z.ZodBoolean;
                     asyncQuestions: z.ZodBoolean;
+                    steer: z.ZodOptional<z.ZodBoolean>;
                     compaction: z.ZodEnum<{
                         native: "native";
                         none: "none";
@@ -3770,6 +3894,10 @@ export declare const AGENT_REQUEST_SCHEMAS: {
                     reportsContextWindow: z.ZodBoolean;
                     reportsThinking: z.ZodBoolean;
                     slashCommands: z.ZodBoolean;
+                    goals: z.ZodOptional<z.ZodEnum<{
+                        command: "command";
+                        native: "native";
+                    }>>;
                 }, z.core.$strip>;
                 resumeCommand: z.ZodString;
             }, z.core.$strip>>;
@@ -4240,6 +4368,12 @@ export declare const AGENT_REQUEST_SCHEMAS: {
         }, z.core.$strip>;
         readonly result: z.ZodObject<{}, z.core.$strip>;
     };
+    readonly 'chat.restart': {
+        readonly payload: z.ZodObject<{
+            chatId: z.ZodString;
+        }, z.core.$strip>;
+        readonly result: z.ZodObject<{}, z.core.$strip>;
+    };
     readonly 'chat.list': {
         readonly payload: z.ZodObject<{}, z.core.$strip>;
         readonly result: z.ZodObject<{
@@ -4393,6 +4527,22 @@ export declare const AGENT_REQUEST_SCHEMAS: {
                         async: z.ZodOptional<z.ZodBoolean>;
                     }, z.core.$strip>>;
                 }, z.core.$strip>>>;
+                goal: z.ZodOptional<z.ZodObject<{
+                    objective: z.ZodString;
+                    status: z.ZodEnum<{
+                        active: "active";
+                        blocked: "blocked";
+                        "budget-limited": "budget-limited";
+                        complete: "complete";
+                        paused: "paused";
+                        "usage-limited": "usage-limited";
+                    }>;
+                    checks: z.ZodOptional<z.ZodNumber>;
+                    lastCheck: z.ZodOptional<z.ZodString>;
+                    tokensUsed: z.ZodOptional<z.ZodNumber>;
+                    tokenBudget: z.ZodOptional<z.ZodNumber>;
+                    secondsUsed: z.ZodOptional<z.ZodNumber>;
+                }, z.core.$strip>>;
                 createdAt: z.ZodNumber;
             }, z.core.$strip>>;
         }, z.core.$strip>;
@@ -4935,6 +5085,22 @@ export declare const AGENT_EVENT_SCHEMAS: {
                         async: z.ZodOptional<z.ZodBoolean>;
                     }, z.core.$strip>>;
                 }, z.core.$strip>>>;
+                goal: z.ZodOptional<z.ZodObject<{
+                    objective: z.ZodString;
+                    status: z.ZodEnum<{
+                        active: "active";
+                        blocked: "blocked";
+                        "budget-limited": "budget-limited";
+                        complete: "complete";
+                        paused: "paused";
+                        "usage-limited": "usage-limited";
+                    }>;
+                    checks: z.ZodOptional<z.ZodNumber>;
+                    lastCheck: z.ZodOptional<z.ZodString>;
+                    tokensUsed: z.ZodOptional<z.ZodNumber>;
+                    tokenBudget: z.ZodOptional<z.ZodNumber>;
+                    secondsUsed: z.ZodOptional<z.ZodNumber>;
+                }, z.core.$strip>>;
                 createdAt: z.ZodNumber;
             }, z.core.$strip>;
         }, z.core.$strip>, z.ZodObject<{
@@ -5089,6 +5255,22 @@ export declare const AGENT_EVENT_SCHEMAS: {
                         async: z.ZodOptional<z.ZodBoolean>;
                     }, z.core.$strip>>;
                 }, z.core.$strip>>>;
+                goal: z.ZodOptional<z.ZodObject<{
+                    objective: z.ZodString;
+                    status: z.ZodEnum<{
+                        active: "active";
+                        blocked: "blocked";
+                        "budget-limited": "budget-limited";
+                        complete: "complete";
+                        paused: "paused";
+                        "usage-limited": "usage-limited";
+                    }>;
+                    checks: z.ZodOptional<z.ZodNumber>;
+                    lastCheck: z.ZodOptional<z.ZodString>;
+                    tokensUsed: z.ZodOptional<z.ZodNumber>;
+                    tokenBudget: z.ZodOptional<z.ZodNumber>;
+                    secondsUsed: z.ZodOptional<z.ZodNumber>;
+                }, z.core.$strip>>;
                 createdAt: z.ZodNumber;
             }, z.core.$strip>;
             items: z.ZodArray<z.ZodDiscriminatedUnion<[z.ZodObject<{
@@ -5571,6 +5753,22 @@ export declare const AGENT_EVENT_SCHEMAS: {
                     async: z.ZodOptional<z.ZodBoolean>;
                 }, z.core.$strip>>;
             }, z.core.$strip>>>;
+            goal: z.ZodOptional<z.ZodObject<{
+                objective: z.ZodString;
+                status: z.ZodEnum<{
+                    active: "active";
+                    blocked: "blocked";
+                    "budget-limited": "budget-limited";
+                    complete: "complete";
+                    paused: "paused";
+                    "usage-limited": "usage-limited";
+                }>;
+                checks: z.ZodOptional<z.ZodNumber>;
+                lastCheck: z.ZodOptional<z.ZodString>;
+                tokensUsed: z.ZodOptional<z.ZodNumber>;
+                tokenBudget: z.ZodOptional<z.ZodNumber>;
+                secondsUsed: z.ZodOptional<z.ZodNumber>;
+            }, z.core.$strip>>;
             createdAt: z.ZodNumber;
         }, z.core.$strip>;
     }, z.core.$strip>;

package/dist/protocol.js

@@ -1,5 +1,5 @@
 import { z } from 'zod';
-import { ChatAddBookmarkPayloadSchema, ChatAnswerPayloadSchema, ChatApprovePayloadSchema, ChatAttachPayloadSchema, ChatAttachResultSchema, ChatBookmarksEventSchema, ChatBookmarksResultSchema, ChatCancelPayloadSchema, ChatClearPayloadSchema, ChatConfigurePayloadSchema, ChatContinueOnPayloadSchema, ChatContinueOnResultSchema, ChatCreatePayloadSchema, ChatDismissPayloadSchema, ChatEventEnvelopeSchema, ChatForkInfoPayloadSchema, ChatForkInfoResultSchema, ChatForkPayloadSchema, ChatForkResultSchema, ChatHistoryPayloadSchema, ChatHistoryResultSchema, ChatInfoSchema, ChatListResultSchema, ChatPreferencesPayloadSchema, ChatQueuePayloadSchema, ChatRemoveBookmarkPayloadSchema, ChatRemoveVisualPayloadSchema, ChatRenameBookmarkPayloadSchema, ChatSendPayloadSchema, ChatSendResultSchema, ChatUiChoicePayloadSchema, ChatUiLinkPayloadSchema, ChatUiLinkReadingSchema, ChatUiQueryPayloadSchema, ChatUiQueryReadingSchema, ChatStatusEventSchema, ChatStopSubagentPayloadSchema, ChatStopTaskPayloadSchema, ChatSubagentChangedEventSchema, ChatSubagentPayloadSchema, ChatSubagentResultSchema, ChatSummarizePayloadSchema, ChatSummarizeResultSchema, ChatTargetPayloadSchema, ChatTurnDiffPayloadSchema, ChatTurnDiffResultSchema, ChatUnqueueResultSchema, ChatVisualsEventSchema, ChatVisualsResultSchema, SkillsListPayloadSchema, SkillsListResultSchema } from './chat.js';
+import { ChatAddBookmarkPayloadSchema, ChatAnswerPayloadSchema, ChatApprovePayloadSchema, ChatAttachPayloadSchema, ChatAttachResultSchema, ChatBookmarksEventSchema, ChatBookmarksResultSchema, ChatCancelPayloadSchema, ChatClearPayloadSchema, ChatConfigurePayloadSchema, ChatContinueOnPayloadSchema, ChatContinueOnResultSchema, ChatCreatePayloadSchema, ChatDismissPayloadSchema, ChatEventEnvelopeSchema, ChatForkInfoPayloadSchema, ChatForkInfoResultSchema, ChatForkPayloadSchema, ChatForkResultSchema, ChatGoalPayloadSchema, ChatHistoryPayloadSchema, ChatHistoryResultSchema, ChatInfoSchema, ChatListResultSchema, ChatPreferencesPayloadSchema, ChatQueuePayloadSchema, ChatRemoveBookmarkPayloadSchema, ChatRemoveVisualPayloadSchema, ChatRenameBookmarkPayloadSchema, ChatSendPayloadSchema, ChatSendResultSchema, ChatUiChoicePayloadSchema, ChatUiLinkPayloadSchema, ChatUiLinkReadingSchema, ChatUiQueryPayloadSchema, ChatUiQueryReadingSchema, ChatStatusEventSchema, ChatStopSubagentPayloadSchema, ChatStopTaskPayloadSchema, ChatSubagentChangedEventSchema, ChatSubagentPayloadSchema, ChatSubagentResultSchema, ChatSummarizePayloadSchema, ChatSummarizeResultSchema, ChatTargetPayloadSchema, ChatTurnDiffPayloadSchema, ChatTurnDiffResultSchema, ChatUnqueueResultSchema, ChatVisualsEventSchema, ChatVisualsResultSchema, SkillsListPayloadSchema, SkillsListResultSchema } from './chat.js';
 import { ProviderListResultSchema } from './model.js';
 import { ProviderAccountCreatePayloadSchema, ProviderAccountCreateResultSchema, ProviderAccountWatchLoginPayloadSchema, ProviderAccountsSavePayloadSchema, ProviderAccountsSchema } from './provider-accounts.js';
 import { UsageChangedEventSchema, UsageLimitsSnapshotSchema, UsageSummaryPayloadSchema, UsageSummaryResultSchema } from './usage.js';
@@ -36,6 +36,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 },
@@ -55,6 +56,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 }
 };
 export const AGENT_EVENT_SCHEMAS = {

package/dist/record.d.ts

@@ -0,0 +1 @@
+export declare function isRecord(value: unknown): value is Record<string, unknown>;

package/dist/record.js

@@ -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) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}

package/dist/text.d.ts

@@ -1 +1,3 @@
 export declare function clipText(text: string, max: number): string;
+export declare const TOOL_OUTPUT_TAIL: number;
+export declare function appendToolOutput(output: string | null, text: string): string;

package/dist/text.js

@@ -17,3 +17,18 @@ export function clipText(text, max) {
     }
     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, text) {
+    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/dist/visual.js

@@ -1,4 +1,5 @@
 import { z } from 'zod';
+import { isRecord } from './record.js';
 import { visualViewportScript } from './visual-viewport.js';
 /*
  * What a host accepts when an agent publishes a visual. The schemas below check shapes only, so a
@@ -113,9 +114,6 @@ export function visualOpenLinkRequest(id, url) {
 export function visualOpenLinkResult(id) {
     return { jsonrpc: '2.0', id, result: {} };
 }
-function isRecord(value) {
-    return typeof value === 'object' && value !== null && !Array.isArray(value);
-}
 function sizeOf(value) {
     return typeof value === 'number' && Number.isFinite(value) && value >= 0 ? value : undefined;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@adecore/agent-contracts",
-  "version": "0.23.1",
+  "version": "0.24.0",
   "description": "Schemas and port contracts for agent chats, provider accounts, models and usage.",
   "type": "module",
   "exports": {
@@ -49,6 +49,11 @@
       "types": "./dist/provider-accounts.d.ts",
       "default": "./dist/provider-accounts.js"
     },
+    "./record": {
+      "source": "./src/record.ts",
+      "types": "./dist/record.d.ts",
+      "default": "./dist/record.js"
+    },
     "./task": {
       "source": "./src/task.ts",
       "types": "./dist/task.d.ts",
@@ -81,7 +86,7 @@
     "test": "bun --conditions=source test"
   },
   "dependencies": {
-    "@adecore/intelligent-ui": "0.23.1",
+    "@adecore/intelligent-ui": "0.24.0",
     "zod": "^4.6.5"
   },
   "devDependencies": {

package/src/chat.ts

@@ -167,6 +167,28 @@ export const ChatTurnLimitSchema = z.object({
 });
 export type ChatTurnLimit = z.infer<typeof ChatTurnLimitSchema>;
 
+/*
+ * A goal the chat's CLI works toward on its own, turn after turn, until it is met: Claude Code's and Codex's
+ * `/goal`. The statuses are this schema's own, so a client that validates a chat payload whole never meets
+ * a new value inside one it already knew. `usage-limited` and `budget-limited` are Codex's: the plan's limit,
+ * or the token budget the goal was given.
+ */
+export const ChatGoalStatusSchema = z.enum(['active', 'paused', 'blocked', 'usage-limited', 'budget-limited', 'complete']);
+export type ChatGoalStatus = z.infer<typeof ChatGoalStatusSchema>;
+
+export const ChatGoalSchema = z.object({
+    objective: z.string(),
+    status: ChatGoalStatusSchema,
+    // How often the CLI's own check found the goal not met yet and sent the agent on; absent from a CLI that counts tokens instead.
+    checks: z.number().int().nonnegative().optional(),
+    // What that check last said was still missing.
+    lastCheck: z.string().optional(),
+    tokensUsed: z.number().int().nonnegative().optional(),
+    tokenBudget: z.number().int().positive().optional(),
+    secondsUsed: z.number().int().nonnegative().optional()
+});
+export type ChatGoal = z.infer<typeof ChatGoalSchema>;
+
 export const ChatQuestionSchema = z.object({
     id: z.string(),
     header: z.string(),
@@ -274,6 +296,8 @@ export const ChatInfoSchema = z.object({
     resumeAt: z.number().optional(),
     // What the chat waits on a person for, oldest first and at most `CHAT_REQUEST_LIMITS.perChat`; absent while nothing waits.
     requests: z.array(ChatRequestSummarySchema).optional(),
+    // The goal the CLI works toward, from the moment one is set until it is cleared; absent while there is none.
+    goal: ChatGoalSchema.optional(),
     createdAt: z.number()
 });
 export type ChatInfo = z.infer<typeof ChatInfoSchema>;
@@ -469,6 +493,9 @@ export type ChatSubagentUsage = z.infer<typeof ChatSubagentUsageSchema>;
  * ordinary items that carry `parentToolUseId`, so streaming keeps working; the timeline gathers
  * them under this row. `result` is the report it ended with, as markdown.
  */
+// The `origin` of a subagent row a host opened with a task of its own rather than the CLI with its tool; a legacy spelling that stored threads carry.
+export const HOST_TASK_ORIGIN = 'ruimte';
+
 export const ChatSubagentItemSchema = z.object({
     ...base,
     kind: z.literal('subagent'),
@@ -497,8 +524,7 @@ export const ChatSubagentItemSchema = z.object({
     // Where the CLI keeps this subagent's own conversation; set once the daemon found it.
     native: z.object({ agentId: z.string().optional(), threadId: z.string().optional() }).optional(),
     // Who opened it: the CLI with its own tool, or a verb with `--task` that made a node; absent is `native`.
-    // The second value keeps its legacy spelling, since stored threads carry it.
-    origin: z.enum(['native', 'ruimte']).optional(),
+    origin: z.enum(['native', HOST_TASK_ORIGIN]).optional(),
     // The node a `--task` opened, whose own conversation this row stands for.
     childId: z.string().optional(),
     // Set for an agent a subagent opened, with the id of that subagent's own Agent call; its row hangs under that one.
@@ -765,6 +791,13 @@ export const ChatStopSubagentPayloadSchema = ChatTargetPayloadSchema.extend({
 });
 export type ChatStopSubagentPayload = z.infer<typeof ChatStopSubagentPayloadSchema>;
 
+// What a person does to a chat's goal without a turn of its own; `pause` and `resume` only where the CLI's protocol has them.
+export const ChatGoalActionSchema = z.enum(['pause', 'resume', 'clear']);
+export type ChatGoalAction = z.infer<typeof ChatGoalActionSchema>;
+
+export const ChatGoalPayloadSchema = ChatTargetPayloadSchema.extend({ action: ChatGoalActionSchema });
+export type ChatGoalPayload = z.infer<typeof ChatGoalPayloadSchema>;
+
 export const ChatStopTaskPayloadSchema = ChatTargetPayloadSchema.extend({ taskId: z.string().min(1).max(256) });
 export type ChatStopTaskPayload = z.infer<typeof ChatStopTaskPayloadSchema>;