refactor(schedule): simplify request zone authority

2026-08-06 19:33:19 +08:00
parent a667ec55d6
commit cd59acd6f6
25 changed files with 466 additions and 1007 deletions
--- a/packages/schedule/tool-schedule/README.md
+++ b/packages/schedule/tool-schedule/README.md
@@ -8,7 +8,7 @@ English | [中文](README.zh.md)

 Load this function plugin after `ctx.sessions`, `ctx.agents`, `ctx.tools`, `ctx.sessionPersistence`, and the persistence listener that implements Session flushes. Static injection makes a missing persistence service a composition error. The plugin listens only to later `agent/created` events, installs on runtime roots, and registers all tools through the exact `agent.ctx`. Agents that already existed when the plugin loaded and runtime children do not receive Schedule.

-Load `@deepseek-ai/dsh-time-context` before publishing a root that should resolve local `at` values without an explicit zone. The official Schedule Web overlay does so. Explicit-offset and explicit-zone values remain usable without an implicit-zone authority.
+Load `@deepseek-ai/dsh-time-context` before publishing a root that should resolve local `at` values without an explicit zone. The official Schedule Web overlay does so. Explicit-offset and explicit-zone values remain usable without implicit request-zone context.

 Every operation that reads or decides from the Schedule fold first awaits `ctx.sessions.flush(session)`. A missing, rejected, or detached persistence path returns `persistence_uncertain`; it never turns an unconfirmed live suffix into a list or not-found answer. A successful create or actual delete also awaits a post-append barrier before confirming the mutation.

@@ -20,11 +20,11 @@ Replay rejects unknown versions, extra fields, reused ids, and delete or dispatc

 `scheduleReminderPresentation(events, dispatchSeq, seedLength)` is the pure Host-facing receipt projection. It returns `scheduleId`, prompt, and occurrence from the dispatch's nearest preceding same-id create; the client renderer adds the fixed `session-local` label. The current fork's `seedLength` is a hard boundary for child-owned dispatches, while inherited dispatches search their persisted prefix; resumed ancestors therefore remain renderable, nested generations may reuse session-local ids, and presentation never changes live ownership.

-## Absolute-time authority
+## Absolute-time context

-The `at` selector is either a strict `YYYY-MM-DDTHH:mm:ss[.S|.SS|.SSS](Z|±HH:MM)` string or `{ date: "YYYY-MM-DD", time: "HH:mm:ss[.S|.SS|.SSS]", time_zone?: string }`. The offset form already identifies one instant. The local form validates an explicit `UTC` or IANA Area/Location zone, or may omit `time_zone` only when the current step's final time-context authority reports one resolved client zone equal to the immutable Session zone.
+The `at` selector is either a strict `YYYY-MM-DDTHH:mm:ss[.S|.SS|.SSS](Z|±HH:MM)` string or `{ date: "YYYY-MM-DD", time: "HH:mm:ss[.S|.SS|.SSS]", time_zone?: string }`. The offset form already identifies one instant. The local form validates an explicit `UTC` or IANA Area/Location zone, or may omit `time_zone` only when the current open step has a time-context reading and the original user-rpc sources in that turn derive one client zone equal to the immutable Session zone.

-The Web Host validates and canonicalizes the browser zone at Session creation and on every prompt. Session creation fixes `SessionHeader.timeZone`; each prompt instead carries its own `clientTimeZone` in the user-message source, so concurrent tabs do not overwrite shared state. A headerless Session, a missing or mixed client authority, or a client/Session mismatch returns `timezone_confirmation_required` with the known zones and requires an explicit `time_zone`.
+The Web Host validates and canonicalizes the browser zone at Session creation and on every prompt. Session creation fixes `SessionHeader.timeZone`; each prompt instead carries its own `clientTimeZone` in the user-message source, so concurrent tabs do not overwrite shared state. Schedule derives directly from those original owners rather than copying them into the time-context source. A headerless Session, a missing or mixed client-zone result, or a client/Session mismatch returns `timezone_confirmation_required` with the known zones and requires an explicit `time_zone`.

 Local times inside a daylight-saving gap are rejected. An overlap chooses its first, earlier instant. A successful create retains only the canonical UTC target, and no Schedule path reads the process time zone.

--- a/packages/schedule/tool-schedule/README.zh.md
+++ b/packages/schedule/tool-schedule/README.zh.md
@@ -8,7 +8,7 @@

 请在 `ctx.sessions`、`ctx.agents`、`ctx.tools`、`ctx.sessionPersistence`，以及实现 Session flush 的持久化监听器之后加载此函数插件。静态注入会使缺少持久化服务的组合直接失败。此插件只监听后续的 `agent/created` 事件，在运行时根 agent 上安装，并通过完全相同的 `agent.ctx` 注册所有工具。插件加载时已经存在的 agent 与运行时子 agent 不会获得 Schedule。

-若根 agent 需要在未显式指定时区时解析本地 `at` 值，请在发布该 agent 前加载 `@deepseek-ai/dsh-time-context`。官方 Schedule Web overlay 会按此顺序加载。带显式偏移量的值和带显式时区的值即使没有隐式时区 authority 仍可使用。
+若根 agent 需要在未显式指定时区时解析本地 `at` 值，请在发布该 agent 前加载 `@deepseek-ai/dsh-time-context`。官方 Schedule Web overlay 会按此顺序加载。带显式偏移量的值和带显式时区的值即使没有隐式请求时区上下文仍可使用。

 每项从 Schedule 折叠结果读取或作出判断的操作，都会先等待 `ctx.sessions.flush(session)`。持久化路径缺失、拒绝或已分离时，操作返回 `persistence_uncertain`；它绝不会把未经确认的 live 后缀当成列表或未找到结果。成功创建或实际删除后，还会等待追加后的持久化 barrier（屏障）再确认变更。

@@ -20,11 +20,11 @@

 `scheduleReminderPresentation(events, dispatchSeq, seedLength)` 是供 Host 使用的纯回执投影。它从 dispatch 之前最近的同 id create 返回 `scheduleId`、prompt 和 occurrence；client renderer 添加固定的 `session-local` 标签。当前 fork 的 `seedLength` 是 child 自有 dispatch 的硬边界，而继承的 dispatch 则会搜索其已持久前缀；因此恢复后的祖先仍可渲染，嵌套 generation 可以复用会话本地 id，presentation 绝不会改变 live ownership。

-## 绝对时间 authority
+## 绝对时间上下文

-`at` selector 可以是严格的 `YYYY-MM-DDTHH:mm:ss[.S|.SS|.SSS](Z|±HH:MM)` 字符串，也可以是 `{ date: "YYYY-MM-DD", time: "HH:mm:ss[.S|.SS|.SSS]", time_zone?: string }`。偏移量形式本身即可确定一个时刻。本地形式会校验显式指定的 `UTC` 或 IANA Area/Location 时区；仅当当前步骤最终的 time-context authority 给出唯一一个已解析的客户端时区，且该时区与不可变的 Session 时区相同时，才可以省略 `time_zone`。
+`at` selector 可以是严格的 `YYYY-MM-DDTHH:mm:ss[.S|.SS|.SSS](Z|±HH:MM)` 字符串，也可以是 `{ date: "YYYY-MM-DD", time: "HH:mm:ss[.S|.SS|.SSS]", time_zone?: string }`。偏移量形式本身即可确定一个时刻。本地形式会校验显式指定的 `UTC` 或 IANA Area/Location 时区；仅当当前 open step 含有 time-context 读数，并且该 turn 的原始 user-rpc 来源派生出唯一一个与不可变 Session 时区相等的客户端时区时，才可以省略 `time_zone`。

-Web Host 会在创建 Session 时以及每次提交提示词时校验并规范化浏览器时区。Session 创建会固定 `SessionHeader.timeZone`；每条提示词则会在用户消息来源中携带自己的 `clientTimeZone`，因此并发标签页不会覆盖共享状态。如果 Session 没有 header、客户端 authority 缺失或混杂，或客户端与 Session 不匹配，系统会返回 `timezone_confirmation_required` 并附上已知时区，同时要求显式指定 `time_zone`。
+Web Host 会在创建 Session 时以及每次提交提示词时校验并规范化浏览器时区。Session 创建会固定 `SessionHeader.timeZone`；每条提示词则会在用户消息来源中携带自己的 `clientTimeZone`，因此并发标签页不会覆盖共享状态。Schedule 会直接从这些原始拥有方派生，而不会把它们复制进 time-context source。如果 Session 没有 header、客户端时区结果缺失或混杂，或客户端与 Session 不匹配，系统会返回 `timezone_confirmation_required` 并附上已知时区，同时要求显式指定 `time_zone`。

 落在夏令时空档内的本地时间会被拒绝。遇到重叠时会选择第一次出现的较早时刻。创建成功后只保留规范化后的 UTC 目标，Schedule 的任何路径都不会读取进程时区。

--- a/packages/schedule/tool-schedule/src/tools.ts
+++ b/packages/schedule/tool-schedule/src/tools.ts
@@ -6,8 +6,7 @@
 import type { Context } from 'cordis'
 import type { Agent } from '@deepseek-ai/dsh-agent'
 import type { ContentBlock } from '@deepseek-ai/dsh-llm'
-import { decodeTimeContextSource } from '@deepseek-ai/dsh-time-context'
-import type { TimeContextAuthority } from '@deepseek-ai/dsh-time-context'
+import { deriveClientTimeZoneContext } from '@deepseek-ai/dsh-time-context'
 import { defineTool } from '@deepseek-ai/dsh-tools'
 import type { GenericCallView } from '@deepseek-ai/dsh-tools'
 import {
@@ -218,58 +217,47 @@ interface AtTimeZoneContext {
  readonly clientTimeZones: string[]
 }

-/** Find the last time-context authority belonging to the currently open step. */
-function currentTimeContextAuthority(agent: Agent): TimeContextAuthority | undefined {
+/** Derive request zones only while the current open step contains a time-context reading. */
+function currentClientTimeZoneContext(agent: Agent): ReturnType<typeof deriveClientTimeZoneContext> | undefined {
  const events = agent.session.events
-  let start = -1
+  let stepStart = -1
  let turn = 0
-  let step = 0
  for (let index = events.length - 1; index >= 0; index--) {
    const event = events[index]
    /* v8 ignore next -- the loop bounds index to the dense Session event array. */
    if (event === undefined) continue
-    if (event.type === 'step/end') return undefined
+    if (event.type === 'step/end' || event.type === 'turn/end') return undefined
    if (event.type === 'step/start') {
-      start = index
+      stepStart = index
      turn = event.data.turn
-      step = event.data.step
      break
    }
  }
-  if (start < 0) return undefined
-  for (let index = events.length - 1; index > start; index--) {
-    const event = events[index]
-    /* v8 ignore next -- the loop bounds index to the dense Session event array. */
-    if (event === undefined || event.type !== 'user/message') continue
-    const source = event.data.source
-    if (source.kind !== 'plugin' || source.plugin !== 'time-context') continue
-    let decoded: ReturnType<typeof decodeTimeContextSource>
-    try {
-      decoded = decodeTimeContextSource(source)
-    } catch {
-      return undefined
-    }
-    if (decoded.authority.turn === turn && decoded.authority.step === step) {
-      return decoded.authority
-    }
-  }
-  return undefined
+  if (stepStart < 0) return undefined
+  const hasReading = events.slice(stepStart + 1).some(event => event.type === 'user/message'
+    && event.data.source.kind === 'plugin'
+    && event.data.source.plugin === 'time-context'
+    && Object.keys(event.data.source).length === 2)
+  if (!hasReading) return undefined
+  const turnStart = events.findLastIndex(event => event.type === 'turn/start' && event.data.turn === turn)
+  if (turnStart < 0) return undefined
+  const messages = events.slice(turnStart + 1)
+    .flatMap(event => event.type === 'user/message' ? [event.data] : [])
+  return deriveClientTimeZoneContext(messages)
 }

-/** Resolve the only authority state that may supply an omitted local time zone. */
+/** Resolve the only request state that may supply an omitted local time zone. */
 function atTimeZoneContext(agent: Agent): AtTimeZoneContext {
  const sessionTimeZone = agent.session.header.timeZone ?? 'unavailable'
-  const authority = currentTimeContextAuthority(agent)
-  const clientTimeZones = authority === undefined || authority.client.kind === 'missing'
+  const client = currentClientTimeZoneContext(agent)
+  const clientTimeZones = client === undefined || client.kind === 'missing'
    ? []
-    : authority.client.kind === 'resolved'
-      ? [authority.client.timeZone]
-      : [...authority.client.timeZones]
+    : client.kind === 'resolved'
+      ? [client.timeZone]
+      : [...client.timeZones]
  const implicitTimeZone = sessionTimeZone !== 'unavailable'
-    && authority?.session.kind === 'resolved'
-    && authority.session.timeZone === sessionTimeZone
-    && authority.client.kind === 'resolved'
-    && authority.client.timeZone === sessionTimeZone
+    && client?.kind === 'resolved'
+    && client.timeZone === sessionTimeZone
    ? sessionTimeZone
    : undefined
  return {
@@ -279,14 +267,17 @@ function atTimeZoneContext(agent: Agent): AtTimeZoneContext {
  }
 }

-/** Translate a contained input failure to the closed tool union. */
+/** Translate one contained input failure to the closed tool union. */
 function inputError(error: ScheduleInputError, timeZone?: AtTimeZoneContext): ScheduleToolError {
  if (error.code === 'timezone_confirmation_required') {
+    // The domain emits this code only for the omitted-zone local-at arm,
+    // whose request context is computed immediately before decoding.
+    const requestTimeZone = timeZone as AtTimeZoneContext
    return {
      code: error.code,
      message: error.message,
-      sessionTimeZone: timeZone?.sessionTimeZone ?? 'unavailable',
-      clientTimeZones: timeZone?.clientTimeZones ?? [],
+      sessionTimeZone: requestTimeZone.sessionTimeZone,
+      clientTimeZones: requestTimeZone.clientTimeZones,
    }
  }
  return { code: error.code, message: error.message }
--- a/packages/schedule/tool-schedule/tests/tools.spec.ts
+++ b/packages/schedule/tool-schedule/tests/tools.spec.ts
@@ -91,21 +91,16 @@ function value(result: ToolExecutionResult): unknown {
  return result.value
 }

-function appendTimeAuthority(
-  agent: Agent,
-  authority: {
-    turn: number
-    step: number
-    session: { kind: 'resolved'; timeZone: string } | { kind: 'unavailable' }
-    client:
-      | { kind: 'resolved'; timeZone: string }
-      | { kind: 'mixed'; timeZones: string[] }
-      | { kind: 'missing' }
-  },
-): void {
+function appendRequestContext(agent: Agent, clientTimeZones: readonly string[]): void {
+  for (const [index, clientTimeZone] of clientTimeZones.entries()) {
+    agent.session.append('user/message', createUserMessage({
+      content: [{ type: 'text', text: `request ${index + 1}` }],
+      source: { kind: 'user', clientTimeZone } as never,
+    }), { surfaceOp: 'append' })
+  }
  agent.session.append('user/message', createUserMessage({
-    content: [{ type: 'text', text: 'time authority' }],
-    source: { kind: 'plugin', plugin: 'time-context', authority },
+    content: [{ type: 'text', text: 'time context' }],
+    source: { kind: 'plugin', plugin: 'time-context' },
  }), { surfaceOp: 'append' })
 }

@@ -254,7 +249,7 @@ describe('Schedule tool protocol', () => {
    expect(changes[0]?.data).not.toHaveProperty('time_zone')
  })

-  it('fails closed when local at lacks confirmed request-zone authority', async () => {
+  it('fails closed when local at lacks confirmed request-zone context', async () => {
    const test = await harness()
    expect(value(await execute(test, 'schedule_create', {
      prompt: 'ambiguous', at: { date: '2026-08-06', time: '09:00:00' },
@@ -268,16 +263,11 @@ describe('Schedule tool protocol', () => {
    expect(test.agent.session.events.filter(event => event.type === 'schedule/change')).toEqual([])
  })

-  it('uses only the current-step matching zone authority for implicit local at', async () => {
+  it('uses the current turn request zones behind a current-step time-context marker', async () => {
    const test = await harness(true, 'Asia/Shanghai')
    test.agent.session.append('turn/start', { turn: 1 })
    test.agent.session.append('step/start', { turn: 1, step: 1 })
-    appendTimeAuthority(test.agent, {
-      turn: 1,
-      step: 1,
-      session: { kind: 'resolved', timeZone: 'Asia/Shanghai' },
-      client: { kind: 'resolved', timeZone: 'Asia/Shanghai' },
-    })
+    appendRequestContext(test.agent, ['Asia/Shanghai'])

    expect(value(await execute(test, 'schedule_create', {
      prompt: 'implicit local', at: { date: '2026-08-06', time: '09:00:00' },
@@ -291,12 +281,7 @@ describe('Schedule tool protocol', () => {
    const mismatch = await harness(true, 'Asia/Shanghai')
    mismatch.agent.session.append('turn/start', { turn: 1 })
    mismatch.agent.session.append('step/start', { turn: 1, step: 1 })
-    appendTimeAuthority(mismatch.agent, {
-      turn: 1,
-      step: 1,
-      session: { kind: 'resolved', timeZone: 'Asia/Shanghai' },
-      client: { kind: 'resolved', timeZone: 'America/New_York' },
-    })
+    appendRequestContext(mismatch.agent, ['America/New_York'])
    expect(value(await execute(mismatch, 'schedule_create', {
      prompt: 'mismatch', at: { date: '2026-08-06', time: '09:00:00' },
    }))).toEqual({
@@ -309,18 +294,7 @@ describe('Schedule tool protocol', () => {
    const mixed = await harness(true, 'Asia/Shanghai')
    mixed.agent.session.append('turn/start', { turn: 1 })
    mixed.agent.session.append('step/start', { turn: 1, step: 1 })
-    appendTimeAuthority(mixed.agent, {
-      turn: 1,
-      step: 1,
-      session: { kind: 'resolved', timeZone: 'Asia/Shanghai' },
-      client: { kind: 'resolved', timeZone: 'Asia/Shanghai' },
-    })
-    appendTimeAuthority(mixed.agent, {
-      turn: 1,
-      step: 1,
-      session: { kind: 'resolved', timeZone: 'Asia/Shanghai' },
-      client: { kind: 'mixed', timeZones: ['America/New_York', 'Asia/Shanghai'] },
-    })
+    appendRequestContext(mixed.agent, ['Asia/Shanghai', 'America/New_York'])
    expect(value(await execute(mixed, 'schedule_create', {
      prompt: 'mixed', at: { date: '2026-08-06', time: '09:00:00' },
    }))).toMatchObject({
@@ -331,12 +305,7 @@ describe('Schedule tool protocol', () => {
    const unavailable = await harness()
    unavailable.agent.session.append('turn/start', { turn: 1 })
    unavailable.agent.session.append('step/start', { turn: 1, step: 1 })
-    appendTimeAuthority(unavailable.agent, {
-      turn: 1,
-      step: 1,
-      session: { kind: 'unavailable' },
-      client: { kind: 'resolved', timeZone: 'America/New_York' },
-    })
+    appendRequestContext(unavailable.agent, ['America/New_York'])
    expect(value(await execute(unavailable, 'schedule_create', {
      prompt: 'legacy', at: { date: '2026-08-06', time: '09:00:00' },
    }))).toMatchObject({
@@ -345,16 +314,11 @@ describe('Schedule tool protocol', () => {
    })
  })

-  it('ignores prior-step authority and fails closed on a malformed current authority', async () => {
+  it('requires a simple current-step marker and fails closed on a malformed source', async () => {
    const test = await harness(true, 'Asia/Shanghai')
    test.agent.session.append('turn/start', { turn: 1 })
    test.agent.session.append('step/start', { turn: 1, step: 1 })
-    appendTimeAuthority(test.agent, {
-      turn: 1,
-      step: 1,
-      session: { kind: 'resolved', timeZone: 'Asia/Shanghai' },
-      client: { kind: 'resolved', timeZone: 'Asia/Shanghai' },
-    })
+    appendRequestContext(test.agent, ['Asia/Shanghai'])
    test.agent.session.append('step/end', { turn: 1, step: 1 })
    test.agent.session.append('step/start', { turn: 1, step: 2 })
    test.agent.session.append('user/message', createUserMessage({
@@ -374,6 +338,41 @@ describe('Schedule tool protocol', () => {
    })
  })

+  it.each(['step/end', 'turn/end'] as const)(
+    'fails closed after the current %s boundary',
+    async (boundary) => {
+      const test = await harness(true, 'Asia/Shanghai')
+      test.agent.session.append('turn/start', { turn: 1 })
+      test.agent.session.append('step/start', { turn: 1, step: 1 })
+      appendRequestContext(test.agent, ['Asia/Shanghai'])
+      test.agent.session.append('step/end', { turn: 1, step: 1 })
+      if (boundary === 'turn/end') {
+        test.agent.session.append('turn/end', { turn: 1, reason: { kind: 'completed' } })
+      }
+
+      expect(value(await execute(test, 'schedule_create', {
+        prompt: `closed ${boundary}`,
+        at: { date: '2026-08-06', time: '09:00:00' },
+      }))).toMatchObject({
+        sessionTimeZone: 'Asia/Shanghai',
+        clientTimeZones: [],
+      })
+    },
+  )
+
+  it('fails closed when an open step has no owning turn boundary', async () => {
+    const test = await harness(true, 'Asia/Shanghai')
+    test.agent.session.append('step/start', { turn: 1, step: 1 })
+    appendRequestContext(test.agent, ['Asia/Shanghai'])
+
+    expect(value(await execute(test, 'schedule_create', {
+      prompt: 'missing turn', at: { date: '2026-08-06', time: '09:00:00' },
+    }))).toMatchObject({
+      sessionTimeZone: 'Asia/Shanghai',
+      clientTimeZones: [],
+    })
+  })
+
  it('returns stable at validation errors after persistence preflight', async () => {
    const test = await harness()
    expect(value(await execute(test, 'schedule_create', {