@capybara-hq/kernel 0.1.0-rc.21 → 0.1.0-rc.22

package/dist/conversations/events.d.ts

@@ -1,5 +1,9 @@
 import { type ContentBlock, type MediaSource } from "@capybara-hq/plugin-sdk";
 import { z } from "zod";
+/** The most hosts one network ask (and one `network_blocked` event) lists. */
+export declare const NETWORK_ASK_MAX_HOSTS = 20;
+/** The longest host name a network ask or `network_blocked` event carries. */
+export declare const NETWORK_HOST_MAX_CHARS = 255;
 /** The longest deny reason (characters): the decision route's limit and `approval_decided.reason`'s. */
 export declare const APPROVAL_DENY_REASON_MAX_CHARS = 500;
 /** 一条 `media_excluded` 事件最多的附件数。 */
@@ -87,9 +91,12 @@ export type LogContentBlock = Exclude<ContentBlock, MediaBlock> | (MediaBlock ex
 /**
  * Structured view of a builtin tool's result (UI refresh B, spec §5.5 / §5.9): display only, like
  * `display`. `command`: `Bash` (the model's `description`, the exit code, null when the
- * command was stopped, and whether it timed out; the web shows "Failed" for a non-zero exit even
- * though `isError` stays false); `edit`: `Edit` / `Write` (a capped line diff);
- * `read`: `Read` (the line range shown).
+ * command was stopped, and whether it timed out; a non-zero exit is information, not a failure:
+ * the web shows "Failed" only for a timeout or a stopped command, as `isError` does);
+ * `edit`: `Edit` / `Write` (a capped line diff); `read`: `Read` (the line range shown);
+ * `guard`: `Edit` / `Write` refused by the read-before-write check (`not_read`: the file was never
+ * read in the conversation, `modified`: it changed since). The result stays `isError: true` for
+ * the model; the web shows the refusal as a neutral outcome, not a failure.
  */
 export declare const ToolViewSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
     kind: z.ZodLiteral<"command">;
@@ -130,6 +137,12 @@ export declare const ToolViewSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
         size: z.ZodNumber;
         sha256: z.ZodString;
     }, z.core.$strip>>;
+}, z.core.$strip>, z.ZodObject<{
+    kind: z.ZodLiteral<"guard">;
+    reason: z.ZodEnum<{
+        modified: "modified";
+        not_read: "not_read";
+    }>;
 }, z.core.$strip>], "kind">;
 export type ToolView = z.infer<typeof ToolViewSchema>;
 /**
@@ -158,6 +171,15 @@ export declare const MessageSenderSchema: z.ZodObject<{
     }>>;
     anonymous: z.ZodOptional<z.ZodLiteral<true>>;
 }, z.core.$strip>;
+/** `user_message.schedule` (scheduled tasks spec §6): the `ScheduleMarker` shape. */
+export declare const ScheduleMarkerSchema: z.ZodObject<{
+    taskId: z.ZodString;
+    taskRunId: z.ZodString;
+    scheduledFor: z.ZodString;
+    trial: z.ZodBoolean;
+    taskName: z.ZodString;
+    localTime: z.ZodString;
+}, z.core.$strip>;
 /** `run_context` (run context spec §3.1): every field optional, a later event holds changes only. */
 export declare const RunContextSchema: z.ZodObject<{
     agent: z.ZodOptional<z.ZodObject<{
@@ -280,6 +302,14 @@ export declare const ConversationEventSchema: z.ZodDiscriminatedUnion<[z.ZodObje
             }>;
             agentType: z.ZodOptional<z.ZodString>;
         }, z.core.$strip>>;
+        schedule: z.ZodOptional<z.ZodObject<{
+            taskId: z.ZodString;
+            taskRunId: z.ZodString;
+            scheduledFor: z.ZodString;
+            trial: z.ZodBoolean;
+            taskName: z.ZodString;
+            localTime: z.ZodString;
+        }, z.core.$strip>>;
         dispatch: z.ZodOptional<z.ZodObject<{
             parentConversationId: z.ZodString;
             parentRunId: z.ZodString;
@@ -301,6 +331,14 @@ export declare const ConversationEventSchema: z.ZodDiscriminatedUnion<[z.ZodObje
                     connectorId: z.ZodString;
                     tools: z.ZodUnion<readonly [z.ZodLiteral<"all">, z.ZodArray<z.ZodString>]>;
                 }, z.core.$strict>], "kind">>>;
+                disabledSkills: z.ZodOptional<z.ZodArray<z.ZodDiscriminatedUnion<[z.ZodObject<{
+                    kind: z.ZodLiteral<"plugin">;
+                    plugin: z.ZodString;
+                    skills: z.ZodUnion<readonly [z.ZodLiteral<"all">, z.ZodArray<z.ZodString>]>;
+                }, z.core.$strict>, z.ZodObject<{
+                    kind: z.ZodLiteral<"skill">;
+                    skillId: z.ZodString;
+                }, z.core.$strict>], "kind">>>;
                 skills: z.ZodOptional<z.ZodObject<{
                     orgSkills: z.ZodArray<z.ZodString>;
                     pinned: z.ZodOptional<z.ZodArray<z.ZodString>>;
@@ -340,6 +378,7 @@ export declare const ConversationEventSchema: z.ZodDiscriminatedUnion<[z.ZodObje
         trigger: z.ZodOptional<z.ZodEnum<{
             background_task: "background_task";
             message: "message";
+            schedule: "schedule";
             subagent: "subagent";
         }>>;
         triggerSeq: z.ZodOptional<z.ZodNumber>;
@@ -523,6 +562,27 @@ export declare const ConversationEventSchema: z.ZodDiscriminatedUnion<[z.ZodObje
             skills: z.ZodString;
             tmp: z.ZodString;
         }, z.core.$strip>;
+        tier: z.ZodOptional<z.ZodEnum<{
+            dev: "dev";
+            open: "open";
+            strict: "strict";
+        }>>;
+        isolation: z.ZodOptional<z.ZodEnum<{
+            none: "none";
+            sandbox: "sandbox";
+        }>>;
+        network: z.ZodOptional<z.ZodLiteral<"none">>;
+        localhost: z.ZodOptional<z.ZodEnum<{
+            off: "off";
+            "off-proxy-detected": "off-proxy-detected";
+            on: "on";
+        }>>;
+        unixSockets: z.ZodOptional<z.ZodEnum<{
+            "all-masked": "all-masked";
+            off: "off";
+            roots: "roots";
+        }>>;
+        unattended: z.ZodOptional<z.ZodLiteral<true>>;
     }, z.core.$strip>;
 }, z.core.$strip>, z.ZodObject<{
     type: z.ZodLiteral<"tool_call_started">;
@@ -588,6 +648,12 @@ export declare const ConversationEventSchema: z.ZodDiscriminatedUnion<[z.ZodObje
                 size: z.ZodNumber;
                 sha256: z.ZodString;
             }, z.core.$strip>>;
+        }, z.core.$strip>, z.ZodObject<{
+            kind: z.ZodLiteral<"guard">;
+            reason: z.ZodEnum<{
+                modified: "modified";
+                not_read: "not_read";
+            }>;
         }, z.core.$strip>], "kind">>;
         card: z.ZodOptional<z.ZodObject<{
             plugin: z.ZodString;
@@ -626,6 +692,9 @@ export declare const ConversationEventSchema: z.ZodDiscriminatedUnion<[z.ZodObje
             org: "org";
             role: "role";
         }>>;
+        network: z.ZodOptional<z.ZodObject<{
+            hosts: z.ZodArray<z.ZodString>;
+        }, z.core.$strip>>;
     }, z.core.$strip>;
 }, z.core.$strip>, z.ZodObject<{
     type: z.ZodLiteral<"approval_decided">;
@@ -637,6 +706,7 @@ export declare const ConversationEventSchema: z.ZodDiscriminatedUnion<[z.ZodObje
             cancelled: "cancelled";
             denied: "denied";
             expired: "expired";
+            skipped: "skipped";
         }>;
         scope: z.ZodOptional<z.ZodEnum<{
             always: "always";
@@ -720,6 +790,7 @@ export declare const ConversationEventSchema: z.ZodDiscriminatedUnion<[z.ZodObje
             version: z.ZodNumber;
             source: z.ZodString;
             plugin: z.ZodOptional<z.ZodString>;
+            nameOnly: z.ZodOptional<z.ZodLiteral<true>>;
         }, z.core.$strip>>;
         pinned: z.ZodOptional<z.ZodArray<z.ZodObject<{
             id: z.ZodString;
@@ -748,6 +819,22 @@ export declare const ConversationEventSchema: z.ZodDiscriminatedUnion<[z.ZodObje
         attempt: z.ZodOptional<z.ZodNumber>;
         callId: z.ZodOptional<z.ZodString>;
     }, z.core.$strip>;
+}, z.core.$strip>, z.ZodObject<{
+    type: z.ZodLiteral<"network_blocked">;
+    payload: z.ZodObject<{
+        step: z.ZodNumber;
+        callId: z.ZodString;
+        hosts: z.ZodArray<z.ZodObject<{
+            host: z.ZodString;
+            port: z.ZodNumber;
+            layer: z.ZodEnum<{
+                address: "address";
+                device: "device";
+                org: "org";
+                unknown: "unknown";
+            }>;
+        }, z.core.$strip>>;
+    }, z.core.$strip>;
 }, z.core.$strip>, z.ZodObject<{
     type: z.ZodLiteral<"subagent_started">;
     payload: z.ZodObject<{
@@ -776,6 +863,14 @@ export declare const ConversationEventSchema: z.ZodDiscriminatedUnion<[z.ZodObje
             }, z.core.$strip>>;
         }, z.core.$strip>;
         definition: z.ZodObject<{
+            skills: z.ZodOptional<z.ZodObject<{
+                writePolicy: z.ZodOptional<z.ZodEnum<{
+                    allow: "allow";
+                    ask: "ask";
+                }>>;
+                orgSkills: z.ZodOptional<z.ZodArray<z.ZodString>>;
+                pinned: z.ZodOptional<z.ZodArray<z.ZodString>>;
+            }, z.core.$strict>>;
             name: z.ZodString;
             description: z.ZodOptional<z.ZodString>;
             avatarUrl: z.ZodDefault<z.ZodNullable<z.ZodURL>>;
@@ -815,14 +910,14 @@ export declare const ConversationEventSchema: z.ZodDiscriminatedUnion<[z.ZodObje
                 ask: "ask";
                 deny: "deny";
             }>>>;
-            skills: z.ZodOptional<z.ZodObject<{
-                orgSkills: z.ZodDefault<z.ZodArray<z.ZodString>>;
-                writePolicy: z.ZodOptional<z.ZodEnum<{
-                    allow: "allow";
-                    ask: "ask";
-                }>>;
-                pinned: z.ZodOptional<z.ZodArray<z.ZodString>>;
-            }, z.core.$strict>>;
+            disabledSkills: z.ZodDefault<z.ZodArray<z.ZodDiscriminatedUnion<[z.ZodObject<{
+                kind: z.ZodLiteral<"plugin">;
+                plugin: z.ZodString;
+                skills: z.ZodUnion<readonly [z.ZodLiteral<"all">, z.ZodArray<z.ZodString>]>;
+            }, z.core.$strict>, z.ZodObject<{
+                kind: z.ZodLiteral<"skill">;
+                skillId: z.ZodString;
+            }, z.core.$strict>], "kind">>>;
             subagents: z.ZodOptional<z.ZodObject<{
                 general: z.ZodOptional<z.ZodBoolean>;
                 templates: z.ZodOptional<z.ZodArray<z.ZodString>>;

package/dist/conversations/events.js

@@ -1,6 +1,6 @@
 import { DOCUMENT_MEDIA_TYPES, hasControlChars, IMAGE_MEDIA_TYPES, isAttachmentId, isSkillName, MEDIA_NAME_MAX_CHARS, } from "@capybara-hq/plugin-sdk";
 import { z } from "zod";
-import { AgentDefinitionSchema, DisabledToolRef, ModelRef } from "../agents/definition.js";
+import { AgentDefinitionSchema, DisabledSkillRef, DisabledToolRef, ModelRef, } from "../agents/definition.js";
 import { ORG_ROLES } from "../orgs/roles.js";
 import { TOOL_VIEW_DIFF_MAX_LINES, TOOL_VIEW_LINE_MAX_CHARS, TOOL_VIEW_PATH_MAX_CHARS, } from "../tools/view.js";
 /** 供应商私有数据（`ProviderOpaque`）：原样保存、只回放给同一供应商。 */
@@ -27,6 +27,10 @@ const ApproverFields = {
     requestedFor: z.string().nullable().optional(),
     approverRole: z.enum(ORG_ROLES).nullable().optional(),
 };
+/** The most hosts one network ask (and one `network_blocked` event) lists. */
+export const NETWORK_ASK_MAX_HOSTS = 20;
+/** The longest host name a network ask or `network_blocked` event carries. */
+export const NETWORK_HOST_MAX_CHARS = 255;
 /** The longest deny reason (characters): the decision route's limit and `approval_decided.reason`'s. */
 export const APPROVAL_DENY_REASON_MAX_CHARS = 500;
 /** 一条 `media_excluded` 事件最多的附件数。 */
@@ -98,9 +102,12 @@ const FileStateViewSchema = z.object({
 /**
  * Structured view of a builtin tool's result (UI refresh B, spec §5.5 / §5.9): display only, like
  * `display`. `command`: `Bash` (the model's `description`, the exit code, null when the
- * command was stopped, and whether it timed out; the web shows "Failed" for a non-zero exit even
- * though `isError` stays false); `edit`: `Edit` / `Write` (a capped line diff);
- * `read`: `Read` (the line range shown).
+ * command was stopped, and whether it timed out; a non-zero exit is information, not a failure:
+ * the web shows "Failed" only for a timeout or a stopped command, as `isError` does);
+ * `edit`: `Edit` / `Write` (a capped line diff); `read`: `Read` (the line range shown);
+ * `guard`: `Edit` / `Write` refused by the read-before-write check (`not_read`: the file was never
+ * read in the conversation, `modified`: it changed since). The result stays `isError: true` for
+ * the model; the web shows the refusal as a neutral outcome, not a failure.
  */
 export const ToolViewSchema = z.discriminatedUnion("kind", [
     z.object({
@@ -137,6 +144,10 @@ export const ToolViewSchema = z.discriminatedUnion("kind", [
         toLine: count.optional(),
         file: FileStateViewSchema.optional(),
     }),
+    z.object({
+        kind: z.literal("guard"),
+        reason: z.enum(["not_read", "modified"]),
+    }),
 ]);
 const ModelUsageShape = {
     inputTokens: count,
@@ -186,6 +197,15 @@ export const MessageSenderSchema = z.object({
     /** An IM sender served as the org's anonymous guest; `name` is the IM profile name. */
     anonymous: z.literal(true).optional(),
 });
+/** `user_message.schedule` (scheduled tasks spec §6): the `ScheduleMarker` shape. */
+export const ScheduleMarkerSchema = z.object({
+    taskId: z.string(),
+    taskRunId: z.string(),
+    scheduledFor: z.string(),
+    trial: z.boolean(),
+    taskName: z.string(),
+    localTime: z.string(),
+});
 /** `run_context` (run context spec §3.1): every field optional, a later event holds changes only. */
 export const RunContextSchema = z.object({
     /** The agent itself: its name and its versioned description collapsed to one line. */
@@ -208,6 +228,21 @@ export const RunContextSchema = z.object({
         .optional(),
 });
 const ev = (type, payload) => z.object({ type: z.literal(type), payload });
+/**
+ * An agent definition frozen into a log (`subagent_started`): the current schema, with the
+ * selected and pinned skills of older logs still accepted (skills default-on spec §4: history
+ * keeps the old fields; new definitions never carry them).
+ */
+const LoggedAgentDefinition = AgentDefinitionSchema.extend({
+    skills: z
+        .object({
+        writePolicy: z.enum(["allow", "ask"]).optional(),
+        orgSkills: z.array(z.string()).optional(),
+        pinned: z.array(z.string()).optional(),
+    })
+        .strict()
+        .optional(),
+});
 /**
  * 会话事件（`type` + `payload`）的判别联合。事件日志只追加，写入前用它校验 payload；
  * 读出时按写入时的形状原样返回。
@@ -263,6 +298,14 @@ export const ConversationEventSchema = z.discriminatedUnion("type", [
             agentType: z.string().optional(),
         })
             .optional(),
+        /**
+         * A scheduled task's message (scheduled tasks spec §6, §12): which task and tick posted it.
+         * Not model-visible as such: request building renders only `taskName` and `localTime`, fixed
+         * here at write time, as the header `[Scheduled task "<name>", run for <local time>]`
+         * (`scheduleHeader`). The run this message triggers is unattended
+         * (`runs.scheduled_task_run_id`).
+         */
+        schedule: ScheduleMarkerSchema.optional(),
         /**
          * Set on a sub-agent's task message (phase C, spec §6.3): which parent call dispatched it.
          * Not model-visible; the web renders the message as the task block.
@@ -279,8 +322,9 @@ export const ConversationEventSchema = z.discriminatedUnion("type", [
             kind: z.enum(["task", "message"]).optional(),
             /**
              * A follow-up (`resume`, final review I1): the frozen and the current version's
-             * turned-off tools together, and the frozen org skills intersected with the current
-             * ones (`narrowFollowUp`); the child's run uses these instead of the frozen ones.
+             * turned-off tools and skills together (`narrowFollowUp`; older logs: the frozen org
+             * skills intersected with the current ones); the child's run uses these instead of the
+             * frozen ones.
              * Absent on a first dispatch and in older logs; logs from before tools were on by
              * default carry an enabled `tools` list instead of `disabledTools` (read as no tool
              * narrowing).
@@ -288,6 +332,11 @@ export const ConversationEventSchema = z.discriminatedUnion("type", [
             narrowed: z
                 .object({
                 disabledTools: z.array(DisabledToolRef).optional(),
+                /**
+                 * Skills default-on (spec §6.1): the frozen and the current version's turned-off
+                 * skills together. Logs from before carry `skills` (`orgSkills` / `pinned`) instead.
+                 */
+                disabledSkills: z.array(DisabledSkillRef).optional(),
                 skills: z
                     .object({ orgSkills: z.array(z.string()), pinned: z.array(z.string()).optional() })
                     .optional(),
@@ -320,9 +369,9 @@ export const ConversationEventSchema = z.discriminatedUnion("type", [
          * What started the run (display only): absent or `message` = a person's message (or a
          * sub-agent's task), `background_task` = a finished background task woke the conversation
          * (spec 2026-11-05-background-bash-design §3), `subagent` = a sub-agent's delivery woke it
-         * (agent map spec §5.3).
+         * (agent map spec §5.3), `schedule` = a scheduled task's message (scheduled tasks spec §6).
          */
-        trigger: z.enum(["message", "background_task", "subagent"]).optional(),
+        trigger: z.enum(["message", "background_task", "subagent", "schedule"]).optional(),
         /**
          * A wake run's boundary: the seq of the finish or delivery that woke it (full-run replay
          * seeds from it).
@@ -444,11 +493,12 @@ export const ConversationEventSchema = z.discriminatedUnion("type", [
      */
     ev("tools_changed", z.object({ step: count, added: z.array(z.string()), removed: z.array(z.string()) })),
     /**
-     * The directories of the instance a sandbox tool call entered, when they differ from the
-     * defaults (environments spec §13.1: a connected machine's real paths). Written once per
-     * conversation and roots, before that call's result. **Model-visible**: rendered at its position
-     * as a system message (`devicePathsText`); a summary covering it is followed by the latest
-     * one again.
+     * The directories of the instance a sandbox tool call entered and the device's sandbox level
+     * (environments spec §13.1; sandbox dev tiers spec §11.5: `tier`, `isolation`, and when they
+     * apply `network: "none"`, a local device's `localhost` / `unixSockets` and `unattended`; all
+     * absent on events recorded before tiers). Written on a conversation's first sandbox call and whenever
+     * they change, before that call's result. **Model-visible**: rendered at its position as a
+     * system message (`devicePathsText`); a summary covering it is followed by the latest one again.
      */
     ev("device_paths", z.object({
         roots: z.object({
@@ -456,6 +506,12 @@ export const ConversationEventSchema = z.discriminatedUnion("type", [
             skills: z.string().min(1).max(4096),
             tmp: z.string().min(1).max(4096),
         }),
+        tier: z.enum(["strict", "dev", "open"]).optional(),
+        isolation: z.enum(["sandbox", "none"]).optional(),
+        network: z.literal("none").optional(),
+        localhost: z.enum(["on", "off-proxy-detected", "off"]).optional(),
+        unixSockets: z.enum(["roots", "all-masked", "off"]).optional(),
+        unattended: z.literal(true).optional(),
     })),
     /** 工具调用开始执行之前写入（续跑时「有开始无结果」的调用记为结果未知，不再执行）。 */
     ev("tool_call_started", z.object({ step: count, callId: z.string(), toolKey: z.string(), specHash: z.string() })),
@@ -513,13 +569,28 @@ export const ConversationEventSchema = z.discriminatedUnion("type", [
         expiresAt: z.string(),
         /** Which rule asked (UI refresh B; display only, absent in older logs). */
         policy: z.enum(["agent", "connector", "default", "role", "org", "fixed"]).optional(),
+        /**
+         * A network ask (network ask-to-allow spec §6.1): the hosts the device owner is asked to
+         * allow. Display only, never model-visible: the model sees the call's `tool_result` only.
+         */
+        network: z
+            .object({
+            hosts: z
+                .array(z.string().min(1).max(NETWORK_HOST_MAX_CHARS))
+                .min(1)
+                .max(NETWORK_ASK_MAX_HOSTS),
+        })
+            .optional(),
         ...ApproverFields,
     })),
-    /** 审批已处理（批准 / 拒绝 / 超时 / 取消）；`scope` 只在批准时出现，`byAccountId` 为处理人（超时 / 取消为 null）。 */
+    /**
+     * 审批已处理（批准 / 拒绝 / 超时 / 取消，或 `skipped`：网络询问被运行发起人的消息跳过，`byAccountId`
+     * 为消息作者）；`scope` 只在批准时出现，`byAccountId` 为处理人（超时 / 取消为 null）。
+     */
     ev("approval_decided", z.object({
         approvalId: z.string(),
         callId: z.string(),
-        decision: z.enum(["approved", "denied", "expired", "cancelled"]),
+        decision: z.enum(["approved", "denied", "expired", "cancelled", "skipped"]),
         scope: z.enum(["once", "session", "always"]).optional(),
         byAccountId: z.string().nullable(),
         /**
@@ -599,6 +670,12 @@ export const ConversationEventSchema = z.discriminatedUnion("type", [
              * resolves `<plugin>:<name>` with it; it is not model-visible otherwise.
              */
             plugin: z.string().min(1).max(64).optional(),
+            /**
+             * Listed by name only, past the catalog budget (`skills.catalogBudgetChars`, skills
+             * default-on spec §7): decided when the snapshot is written, so a later budget never
+             * changes an old request. Absent in every snapshot before phase 2 (= described).
+             */
+            nameOnly: z.literal(true).optional(),
         }))
             .max(SKILLS_CATALOG_MAX),
         /**
@@ -638,6 +715,24 @@ export const ConversationEventSchema = z.discriminatedUnion("type", [
         attempt: count.optional(),
         callId: z.string().optional(),
     })),
+    /**
+     * The network refusals a command reported (network ask-to-allow spec §6.5), whether or not they
+     * raised an ask: the web draws the facts and the org-layer request under the command's row. Not
+     * model-visible: request building skips it; the model sees only the call's `tool_result` (the
+     * device's trailer and the kernel's note).
+     */
+    ev("network_blocked", z.object({
+        step: count,
+        callId: z.string(),
+        hosts: z
+            .array(z.object({
+            host: z.string().min(1).max(NETWORK_HOST_MAX_CHARS),
+            port: z.number().int().min(1).max(65535),
+            layer: z.enum(["device", "org", "address", "unknown"]),
+        }))
+            .min(1)
+            .max(NETWORK_ASK_MAX_HOSTS),
+    })),
     /**
      * The first event of a sub-agent's (child) conversation (phase C, spec §6.3), written once in the
      * dispatch transaction. Request building for a `subagent` conversation takes the definition and
@@ -671,9 +766,15 @@ export const ConversationEventSchema = z.discriminatedUnion("type", [
                 .object({ id: z.string(), version: z.number().int(), name: z.string() })
                 .optional(),
         }),
-        /** The effective (narrowed) definition, frozen at dispatch. */
-        definition: AgentDefinitionSchema,
-        /** `SUBAGENT_PREAMBLE` at dispatch time. */
+        /**
+         * The effective (narrowed) definition, frozen at dispatch. Logs from before skills were on
+         * by default also carry `skills.orgSkills` / `skills.pinned` (skills default-on spec §4).
+         */
+        definition: LoggedAgentDefinition,
+        /**
+         * `SUBAGENT_PREAMBLE` at dispatch time; since skills were on by default, followed by the line
+         * naming a template's skills the child loads first (skills default-on spec §6.1).
+         */
         preamble: z.string(),
         maxSteps: z.number().int().positive(),
         warnings: z.array(z.string()).optional(),
@@ -849,6 +950,8 @@ void _effort;
 const _usage = true;
 const _toolResult = true;
 void _toolResult;
+const _schedule = true;
+void _schedule;
 void _blocks;
 void _logIsBlock;
 void _stop;

package/dist/conversations/message-context.d.ts

@@ -59,9 +59,10 @@ export type MessageContext = Pick<EventPayload<"user_message">, "sender" | "time
  * - `sender`: the account's display name and org role at send time; the org's anonymous guest
  *   account (`org_anonymous_accounts`) is `{ name: <senderName, else "Anonymous guest">, role:
  *   "guest", anonymous: true }`. Names are sanitised; an empty one leaves `sender` out.
- * - `timeZone`: what the IM platform gave for the sender (`im`, when valid), else the account's
- *   setting, else the browser's (when valid), else the org default, else UTC. The anonymous guest
- *   account has no setting of its own, so it gets the IM value or the org default.
+ * - `timeZone`: the override (`timeZoneOverride`, when valid: a scheduled task's zone, scheduled
+ *   tasks spec §6), else what the IM platform gave for the sender (`im`, when valid), else the
+ *   account's setting, else the browser's (when valid), else the org default, else UTC. The
+ *   anonymous guest account has no setting of its own, so it gets the IM value or the org default.
  * - `locale`: the IM platform's value, else the browser's UI language, else the UI language of the
  *   person's most recent web message in the org ({@link latestWebLocale}; not for the shared
  *   anonymous guest account), else the org's `locale`.
@@ -76,4 +77,6 @@ export declare function readMessageContext(t: KernelSchemaDb, input: {
     browser?: BrowserContext | undefined;
     /** An IM message: what the platform gave for the sender (maintainer decision 2026-11-08). */
     im?: ImSenderContext | undefined;
+    /** A zone that beats every other source (a scheduled task's zone); internal callers only. */
+    timeZoneOverride?: string | undefined;
 }): Promise<MessageContext>;

package/dist/conversations/message-context.js

@@ -84,9 +84,10 @@ export async function recipientLocale(t, input) {
  * - `sender`: the account's display name and org role at send time; the org's anonymous guest
  *   account (`org_anonymous_accounts`) is `{ name: <senderName, else "Anonymous guest">, role:
  *   "guest", anonymous: true }`. Names are sanitised; an empty one leaves `sender` out.
- * - `timeZone`: what the IM platform gave for the sender (`im`, when valid), else the account's
- *   setting, else the browser's (when valid), else the org default, else UTC. The anonymous guest
- *   account has no setting of its own, so it gets the IM value or the org default.
+ * - `timeZone`: the override (`timeZoneOverride`, when valid: a scheduled task's zone, scheduled
+ *   tasks spec §6), else what the IM platform gave for the sender (`im`, when valid), else the
+ *   account's setting, else the browser's (when valid), else the org default, else UTC. The
+ *   anonymous guest account has no setting of its own, so it gets the IM value or the org default.
  * - `locale`: the IM platform's value, else the browser's UI language, else the UI language of the
  *   person's most recent web message in the org ({@link latestWebLocale}; not for the shared
  *   anonymous guest account), else the org's `locale`.
@@ -124,13 +125,16 @@ export async function readMessageContext(t, input) {
     const im = input.im?.timeZone;
     const own = row?.time_zone ?? null;
     const browser = input.browser?.timeZone;
-    const timeZone = im !== undefined && isTimeZone(im)
-        ? im
-        : own !== null && isTimeZone(own)
-            ? own
-            : browser !== undefined && isTimeZone(browser)
-                ? browser
-                : (org.timeZone ?? "UTC");
+    const override = input.timeZoneOverride;
+    const timeZone = override !== undefined && isTimeZone(override)
+        ? override
+        : im !== undefined && isTimeZone(im)
+            ? im
+            : own !== null && isTimeZone(own)
+                ? own
+                : browser !== undefined && isTimeZone(browser)
+                    ? browser
+                    : (org.timeZone ?? "UTC");
     const locale = input.im?.locale ??
         input.browser?.locale ??
         (row !== undefined && !anonymous

package/dist/conversations/queue.d.ts

@@ -1,6 +1,7 @@
 import { type ModelRef } from "../agents/definition.js";
 import type { KernelSchemaDb } from "../db/kernel-schema.js";
 import { ApiError } from "../errors.js";
+import type { ScheduleMarker } from "../schedules/types.js";
 import { type InvocationRecord, type RenderedInvocation } from "../skills/invoke.js";
 import type { AttachmentRef } from "./conversations.service.js";
 import { type AppendEvent, type EventLog } from "./event-log.js";
@@ -28,6 +29,14 @@ export interface QueuedSkill {
     invokedAs: string;
     record: InvocationRecord;
 }
+/**
+ * A scheduled task's queued message (scheduled tasks spec §6), stored in
+ * `conversation_queue.schedule`: the marker the `user_message` carries and the task's zone, which
+ * becomes the message's `timeZone` (the top-priority override of `readMessageContext`).
+ */
+export type QueuedSchedule = ScheduleMarker & {
+    timeZone?: string;
+};
 /** The caller's transaction handle (the module helpers below run inside it). */
 type KernelTrx = KernelSchemaDb;
 /** A queued message as the API returns it. */
@@ -92,9 +101,10 @@ export interface QueueRow {
     model: unknown;
     effort: string | null;
     skill: unknown;
+    schedule: unknown;
     created_at: Date;
 }
-export declare const COLUMNS: readonly ["id", "conversation_id", "account_id", "position", "text", "content", "attachments", "files", "client_message_id", "model", "effort", "skill", "created_at"];
+export declare const COLUMNS: readonly ["id", "conversation_id", "account_id", "position", "text", "content", "attachments", "files", "client_message_id", "model", "effort", "skill", "schedule", "created_at"];
 /**
  * Queued text as the event log will store it: NUL becomes U+FFFD (PG rejects NUL in text and
  * jsonb), the mapping `payloadJson` applies to a direct send (final review m1).
@@ -113,7 +123,10 @@ export declare function storedSkill(invokedAs: string, invoked: RenderedInvocati
     skill: string;
     first: LogContentBlock;
 };
-/** The `user_message` a queued item becomes, as `postUserMessage` would have written it. */
+/**
+ * The `user_message` a queued item becomes, as `postUserMessage` would have written it; a scheduled
+ * task's item carries its marker (without the stored zone, which is in `context`).
+ */
 export declare function queuedUserMessage(r: QueueRow, context?: MessageContext): AppendEvent;
 /**
  * Appends a queued item inside `t` (the caller holds the conversation row lock): its pick, re-planned

package/dist/conversations/queue.js

@@ -28,6 +28,7 @@ export const COLUMNS = [
     "model",
     "effort",
     "skill",
+    "schedule",
     "created_at",
 ];
 /**
@@ -77,10 +78,14 @@ export function storedSkill(invokedAs, invoked) {
     const skill = { invokedAs, record: invoked.skill };
     return { skill: payloadJson(skill), first: { type: "text", text: invoked.text } };
 }
-/** The `user_message` a queued item becomes, as `postUserMessage` would have written it. */
+/**
+ * The `user_message` a queued item becomes, as `postUserMessage` would have written it; a scheduled
+ * task's item carries its marker (without the stored zone, which is in `context`).
+ */
 export function queuedUserMessage(r, context = {}) {
     const attachments = r.attachments;
     const skill = r.skill;
+    const marker = queuedMarker(r);
     return {
         type: "user_message",
         idemKey: userMessageIdemKey(r.client_message_id),
@@ -95,9 +100,18 @@ export function queuedUserMessage(r, context = {}) {
             ...context,
             clientMessageId: r.client_message_id,
             ...(skill !== null && { skill: skill.record }),
+            ...(marker !== undefined && { schedule: marker }),
         },
     };
 }
+/** A queued item's schedule marker as the log stores it (the six marker fields), or undefined. */
+function queuedMarker(r) {
+    const s = r.schedule;
+    if (s === null || s === undefined)
+        return undefined;
+    const { taskId, taskRunId, scheduledFor, trial, taskName, localTime } = s;
+    return { taskId, taskRunId, scheduledFor, trial, taskName, localTime };
+}
 /**
  * Appends a queued item inside `t` (the caller holds the conversation row lock): its pick, re-planned
  * against the selection in effect now, becomes a `model_switched` before the `user_message`, as a
@@ -122,13 +136,18 @@ export async function appendQueuedIn(t, eventLog, conversationId, r) {
             payload: { ...next, byAccountId: r.account_id, reason: "user" },
         });
     }
-    // run context spec §3.4: no browser values were stored with a leftover row
+    // run context spec §3.4: no browser values were stored with a leftover row; a scheduled task's
+    // item stored its task's zone, which wins (scheduled tasks spec §6)
     const org = await t
         .selectFrom("conversations")
         .select("org_id")
         .where("id", "=", conversationId)
         .executeTakeFirstOrThrow();
-    const context = await readMessageContext(t, { orgId: org.org_id, accountId: r.account_id });
+    const context = await readMessageContext(t, {
+        orgId: org.org_id,
+        accountId: r.account_id,
+        timeZoneOverride: r.schedule?.timeZone,
+    });
     events.push(queuedUserMessage(r, context));
     const written = await eventLog.appendIn(conversationId, events);
     if (next !== null) {