@qilin-agent/tool-schedule 0.0.0-stage → 3.1.4

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 kkutysllb
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.i18n.yaml

@@ -0,0 +1,70 @@
+# Bilingual-pair consistency record for README.md (docs/i18n/README.md): per heading
+# section, a hash of its English and Chinese blocks outside code blocks and generated regions.
+# After editing either side, bring the other along and re-record with:
+#   pnpm run verify-translation-pairing --write packages/schedule/tool-schedule/README.md
+/:
+  en: 5bcd39034f505033
+  zh: 9bfd85a1ad52bc67
+/qilin-agent-tool-schedule:
+  en: dfe42b83b9653579
+  zh: d8c6ba57ad58aef4
+/qilin-agent-tool-schedule/summary:
+  en: 360650da0a6f1873
+  zh: 722fd650df68beed
+/qilin-agent-tool-schedule/table-of-contents:
+  en: d152484eb41ac6b4
+  zh: 09388d293f9be9cb
+/qilin-agent-tool-schedule/use-this-package:
+  en: a692cac1bda0f1bc
+  zh: 3cc2e4bff8062e4e
+/qilin-agent-tool-schedule/use-this-package/when-to-choose-it:
+  en: 553d58f6946fc4e1
+  zh: f3681e61ec8eb11d
+/qilin-agent-tool-schedule/use-this-package/the-four-tools:
+  en: f8aae686d0531c29
+  zh: 3cccd1ba81aae48d
+/qilin-agent-tool-schedule/use-this-package/minimal-configuration:
+  en: eef3a83c0ffb2931
+  zh: 9b527abfde4c3406
+/qilin-agent-tool-schedule/understand-the-implementation:
+  en: 065702b7a82b8fa1
+  zh: 642037baaa2c0f1d
+/qilin-agent-tool-schedule/understand-the-implementation/source-map:
+  en: 676c4e0595fcc8dd
+  zh: f02ed861f66e7747
+/qilin-agent-tool-schedule/further-exploration:
+  en: 2c34a1d697bc1938
+  zh: 4dcc29a2f8a4b61c
+/qilin-agent-tool-schedule/model-experience:
+  en: 215e7ba838619b7b
+  zh: a311da3843709f90
+/qilin-agent-tool-schedule/model-experience/tool-schemas:
+  en: 3039bc5e7a796b21
+  zh: 6b7a9eaf69c9ea53
+/qilin-agent-tool-schedule/model-experience/tool-schemas/what-the-model-sees:
+  en: d4c220f98fbddede
+  zh: 87c7a231b07cde17
+/qilin-agent-tool-schedule/model-experience/tool-schemas/token-effect:
+  en: 70fb9094859d0804
+  zh: 30726b045484713c
+/qilin-agent-tool-schedule/model-experience/tool-schemas/kv-cache-effect:
+  en: 332231fb9f1b8146
+  zh: eace0b2e789d1c0f
+/qilin-agent-tool-schedule/model-experience/reminder-results:
+  en: ffeb087f9476fddf
+  zh: 94569d39555d5192
+/qilin-agent-tool-schedule/model-experience/reminder-results/what-the-model-sees:
+  en: 68ce690c2d5c2312
+  zh: d3a9fca950518702
+/qilin-agent-tool-schedule/model-experience/reminder-results/token-effect:
+  en: a08931b2c5048399
+  zh: 758ea2131adb23e4
+/qilin-agent-tool-schedule/model-experience/reminder-results/kv-cache-effect:
+  en: 2fbf2175168e8244
+  zh: 9c4c1964ae59e661
+/qilin-agent-tool-schedule/known-limitations-and-deferred-work:
+  en: 502ddc2c0c8f0a24
+  zh: d1354984a6c036d9
+/qilin-agent-tool-schedule/known-limitations-and-deferred-work/dev-note:
+  en: e67f633dc6fe7773
+  zh: b2ee0fbaa165910d

package/README.md

@@ -1,3 +1,131 @@
-# Temporary Holding Version
+---
+description: "Preset-scoped reminder management tools (schedule_create, schedule_list, schedule_update, schedule_delete) over the Host ctx.schedule service, for deployments choosing which agents may keep durable reminders."
+kind: "package-reference"
+---
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+# @qilin-agent/tool-schedule
+
+English | [中文](README.zh.md)
+
+## Summary
+
+Use `dsh-tool-schedule` to let an agent create, list, edit, and delete durable Host reminders through `schedule_create`, `schedule_list`, `schedule_update`, and `schedule_delete`. The package registers the four tools in the preset or Agent scope that mounts it, so the composition decides which agents receive them; `minimal` keeps none. Each call acts on the calling Agent's Session and only manages stored reminders — the Host `@qilin-agent/schedule` service owns storage, scheduling, and delivery. Failures return one structured error code instead of storage details.
+
+## Table of Contents
+
+- [Use this package](#use-this-package)
+- [Understand the implementation](#understand-the-implementation)
+- [Further Exploration](#further-exploration)
+- [Model Experience](#model-experience)
+- [Known Limitations and Deferred Work](#known-limitations-and-deferred-work)
+- [Dev Note](#dev-note)
+
+-----
+
+<a id="use-this-package"></a>
+## Use this package
+
+Add the row below to a preset's plugin list when that preset's agents should manage durable reminders. The shipped Web `standard`, `cordis`, and `ptc` presets mount it; `minimal` does not.
+
+### When to choose it
+
+Choose it for any preset whose agents need to schedule future work in their own Session, and load `@qilin-agent/schedule` in the same process: this package is only the model-facing consumer of that service. A preset that should stay capability-poor — `minimal` is the shipped example — omits the row, and its agents see no reminder tool at all.
+
+### The four tools
+
+- `schedule_create(prompt, title, <one selector>)` — Create one reminder. Supply a non-empty prompt, a title of at most 120 characters, and exactly one of `after_seconds`, `at`, `every_seconds`, `daily`, `weekly`, or `cron`. Returns the canonical reminder view.
+- `schedule_list()` — List every active reminder of the calling Session with its id, title, UTC target, state, and delivery mode.
+- `schedule_update(id, <title|prompt|one selector>)` — Replace the name, instruction, or timing in place, or a combination of them. An unknown or ended reminder returns `updated: false` with the reason code; `after_seconds` is create-only.
+- `schedule_delete(id)` — Remove one retained reminder, active or ended. Unknown or already-deleted ids return `deleted: false`.
+
+### Minimal configuration
+
+```yaml
+- name: '@qilin-agent/tool-schedule'
+```
+
+The package declares no `Config` fields. It injects `ctx.tools` and registers the four tools once the scope resolves the Host `ctx.schedule` service, so a composition that keeps that service off mounts no reminder tool. Each call acts on the Session of the Agent that dispatched it.
+
+-----
+
+<a id="understand-the-implementation"></a>
+## Understand the implementation
+
+<details>
+<summary>Implementation internals — click to expand</summary>
+
+The plugin registers four `defineTool` definitions through the context that loads it, so a preset mount decides visibility and Cordis effect ownership disposes them with the mount. Execution reads `exec.agent` for the Session binding and the injected `ctx.schedule` service for storage; the delegation-depth guard runs before selector and identity checks, all before the service call, and any failure the service raises that is not a `ScheduleInputError` collapses to `internal_error` so storage details never reach the model. Model content is the canonical JSON of the returned value, and the Host service owns persistence, scheduling, Session restoration, and delivery.
+
+### Source map
+
+| File | Role |
+|---|---|
+| [`src/index.ts`](src/index.ts) | Plugin entry: the four registrations, selector validation, and the render/present helpers |
+
+</details>
+
+-----
+
+<a id="further-exploration"></a>
+## Further Exploration
+
+- [Schedule service](../schedule/README.md) — the Host task store, runtime, and delivery behavior these tools manage.
+- [Schedule group map](../README.md) — the sibling packages in this group.
+- [Generated tool catalog](../../../docs/tool-catalog.md#qilin-agenttool-schedule) — the exact four schemas the model receives.
+- [Schedule subsystem](../../../docs/subsystems/schedule.md) — the `ctx.schedule` Cordis surface and stored types.
+- [Schedule user guide](../../../docs/user/guide/schedule.md) — the user-facing reminder workflow.
+
+-----
+
+<a id="model-experience"></a>
+## Model Experience
+
+### Tool schemas
+
+#### What the model sees
+
+The generated [`schedule_create`, `schedule_list`, `schedule_update`, and `schedule_delete` schemas](../../../docs/tool-catalog.md#qilin-agenttool-schedule) whenever this package is visible in the calling Agent's scope.
+
+#### Token effect
+
+A fixed schema cost on every request from an Agent whose preset mounts the package. Agents under a preset that omits the row pay nothing.
+
+#### KV Cache effect
+
+Prefix-stable while tool definitions and visibility are unchanged. Mounting, disposal, or a scope change may invalidate reuse from the first changed schema token.
+
+### Reminder results
+
+#### What the model sees
+
+One lossless JSON text block per call: a reminder view for `schedule_create`, an array of views for `schedule_list`, `{ id, deleted }` for `schedule_delete`, and a reminder view or `{ id, updated: false, code }` for `schedule_update`. A rejected call returns `{ code, message }` carrying one published error code.
+
+#### Token effect
+
+Results remain in the calling Session's history until compaction and repeat the stored reminder fields; a long reminder list costs its full rendered length on every later request.
+
+#### KV Cache effect
+
+Append-only; newly visible content follows the reusable request prefix and does not invalidate existing KV Cache entries.
+
+## Known Limitations and Deferred Work
+
+<a id="known-limitations-and-deferred-work"></a>
+
+- **No tools without the Host service** — a composition that mounts this package without `ctx.schedule` leaves the plugin pending, so none of the four tools register.
+- **Every call needs a calling Agent** — a call dispatched without one returns `internal_error` rather than guessing a Session.
+- **Deletion does not retract a queued message** — a reminder the Host already delivered stays in the Session inbox after `schedule_delete`.
+- **Reminder timing belongs to the Host** — the tools expose no target-time correction, clock source, or delivery retry; those limits are the service's.
+- **Every tool refuses a delegated caller** — each of `schedule_create`, `schedule_list`, `schedule_update`, and `schedule_delete` reads the calling Agent's delegation depth before dispatch and returns `{ code: 'subagent_session', message: 'A delegated subagent cannot use reminders.' }` when that depth is above zero. The guard lives in this package and reads `delegationDepthOf` from `@qilin-agent/subagent`, the same accounting the delegation cap enforces, so it holds under any preset that mounts the tools.
+- **A preset's delegation rows remove the four tools from a child's prompt** — the `standard`, `cordis`, and `ptc` presets declare `toolFilter.deny` for `schedule_create`, `schedule_delete`, `schedule_list`, and `schedule_update` on both the `tool-subagent` and `tool-subagent-fork` rows. The provider applies that filter through `ctx.tools.restrict()` in the child scope, so the four tools leave a delegated child's prompt; delegating further on that chain intersects the same restriction.
+- **A Session a delegated child owns cannot arm a reminder** — `ScheduleService.create` throws `ScheduleInputError` with code `subagent_session`, and `ScheduleService.update` returns the non-mutating `subagent_session` result, when the Session's Agent has a delegation depth above zero. The delegation depth is the accounting the delegation cap itself reads, and the persisted session header carries it across a cold resume. The rule sits in the service, not in these tools, so other in-process consumers reach it too: the Automation surface included. `schedule_list` and `schedule_delete` still serve that Session, so a reminder stored before this rule stays removable.
+
+<a id="dev-note"></a>
+### Dev Note
+
+<details>
+<summary>Working context for maintainers — click to expand</summary>
+
+None.
+
+</details>

package/README.zh.md

@@ -0,0 +1,131 @@
+---
+description: "预设作用域的提醒管理工具（schedule_create、schedule_list、schedule_update、schedule_delete），基于宿主 ctx.schedule 服务，供选择哪些 agent 可以维护持久提醒的部署使用。"
+kind: "package-reference"
+---
+
+# @qilin-agent/tool-schedule
+
+[English](README.md) | 中文
+
+## 概述
+
+使用 `dsh-tool-schedule`，可通过 `schedule_create`、`schedule_list`、`schedule_update` 与 `schedule_delete` 让 agent（智能体）创建、列出、编辑和删除宿主持久提醒。本包把四个工具注册进挂载它的 preset 或 Agent 作用域，因此由组合决定哪些 agent 获得这些工具；`minimal` 不获得。每次调用都作用于调用方 Agent 的 Session，并且只管理已存储的提醒——存储、调度与投递由宿主 `@qilin-agent/schedule` 服务负责。失败时返回一个结构化错误码，而不是存储细节。
+
+## 目录
+
+- [使用本包](#use-this-package)
+- [理解实现](#understand-the-implementation)
+- [进一步探索](#further-exploration)
+- [模型体验](#model-experience)
+- [已知限制与延期工作](#known-limitations-and-deferred-work)
+- [开发备注](#dev-note)
+
+-----
+
+<a id="use-this-package"></a>
+## 使用本包
+
+当某个 preset 的 agent 需要管理持久提醒时，把下面这一行加入该 preset 的插件列表。随产品发布的 Web `standard`、`cordis` 与 `ptc` preset 会挂载它；`minimal` 不会。
+
+### 何时选用
+
+当 preset 的 agent 需要在自己的 Session 中安排未来工作时选用它，并在同一进程内加载 `@qilin-agent/schedule`：本包只是该服务面向模型的消费方。需要保持能力精简的 preset——随产品发布的例子是 `minimal`——会省略该行，其 agent 完全看不到提醒工具。
+
+### 四个工具
+
+- `schedule_create(prompt, title, <一个选择器>)` —— 创建一条提醒。需提供非空提示文本、不超过 120 个字符的标题，以及 `after_seconds`、`at`、`every_seconds`、`daily`、`weekly`、`cron` 中的恰好一个。返回规范提醒视图。
+- `schedule_list()` —— 列出调用方 Session 的全部活动提醒及其 id、标题、UTC 目标、状态与投递模式。
+- `schedule_update(id, <title|prompt|一个选择器>)` —— 原地替换名称、指令或时间，或它们的组合。未知或已结束的提醒返回 `updated: false` 及原因码；`after_seconds` 仅限创建时使用。
+- `schedule_delete(id)` —— 删除一条保留的提醒，无论活动还是已结束。未知或已删除的 id 返回 `deleted: false`。
+
+### 最小配置
+
+```yaml
+- name: '@qilin-agent/tool-schedule'
+```
+
+本包不声明任何 `Config` 字段。它注入 `ctx.tools`，并在作用域解析到宿主 `ctx.schedule` 服务后注册这四个工具，因此保持该服务关闭的组合不会挂载任何提醒工具。每次调用都作用于派发该调用的 Agent 的 Session。
+
+-----
+
+<a id="understand-the-implementation"></a>
+## 理解实现
+
+<details>
+<summary>实现内部细节——点击展开</summary>
+
+插件通过加载它的上下文注册四个 `defineTool` 定义，因此由 preset 挂载决定可见性，并由 Cordis effect 的所有权随挂载一并释放。执行时读取 `exec.agent` 作为 Session 绑定，并读取注入的 `ctx.schedule` 服务进行存储；委派深度守卫先于选择器与身份校验运行，二者均在服务调用之前完成，服务抛出的任何非 `ScheduleInputError` 失败都收敛为 `internal_error`，因此存储细节不会到达模型。模型内容为返回值的规范 JSON，而持久化、调度、Session 恢复与投递都由宿主服务负责。
+
+### 源码映射
+
+| 文件 | 作用 |
+|---|---|
+| [`src/index.ts`](src/index.ts) | 插件入口：四个注册、选择器校验，以及 render/present 辅助函数 |
+
+</details>
+
+-----
+
+<a id="further-exploration"></a>
+## 进一步探索
+
+- [Schedule 服务](../schedule/README.zh.md) —— 这些工具所管理的宿主任务存储、运行时与投递行为。
+- [Schedule 分组映射](../README.zh.md) —— 本组内的同级包。
+- [生成的工具目录](../../../docs/tool-catalog.zh.md#qilin-agenttool-schedule) —— 模型接收的确切四个 schema。
+- [Schedule 子系统](../../../docs/subsystems/schedule.zh.md) —— `ctx.schedule` 的 Cordis 接线区域与存储类型。
+- [Schedule 用户指南](../../../docs/user/guide/schedule.zh.md) —— 面向用户的提醒工作流。
+
+-----
+
+<a id="model-experience"></a>
+## 模型体验
+
+### 工具 schema
+
+#### What the model sees
+
+只要本包在调用方 Agent 的作用域内可见，模型就会收到生成的 [`schedule_create`、`schedule_list`、`schedule_update` 与 `schedule_delete` schema](../../../docs/tool-catalog.zh.md#qilin-agenttool-schedule)。
+
+#### Token effect
+
+凡是 preset 挂载了本包的 Agent，其每次请求都有固定的 schema 开销。省略该行的 preset 下的 Agent 不付出任何开销。
+
+#### KV Cache effect
+
+只要工具定义与可见性不变，前缀保持稳定。挂载、释放或作用域变化都可能使从首个变化 schema token 起的复用失效。
+
+### 提醒结果
+
+#### What the model sees
+
+每次调用返回一个无损 JSON 文本块：`schedule_create` 返回提醒视图，`schedule_list` 返回视图数组，`schedule_delete` 返回 `{ id, deleted }`，`schedule_update` 返回提醒视图或 `{ id, updated: false, code }`。被拒绝的调用返回带有某个已发布错误码的 `{ code, message }`。
+
+#### Token effect
+
+结果会留在调用方 Session 的历史中直到压缩，并重复存储的提醒字段；较长的提醒列表在之后每次请求中都付出其全部渲染长度。
+
+#### KV Cache effect
+
+只追加；新可见内容跟在可复用的请求前缀之后，不会使既有 KV Cache 条目失效。
+
+## Known Limitations and Deferred Work
+
+<a id="known-limitations-and-deferred-work"></a>
+
+- **没有宿主服务就没有工具** —— 在缺少 `ctx.schedule` 的组合中挂载本包会让插件保持挂起，四个工具都不会注册。
+- **每次调用都需要调用方 Agent** —— 未携带 Agent 的派发返回 `internal_error`，而不会猜测某个 Session。
+- **删除不会撤回已排队的消息** —— 宿主已经投递的提醒在 `schedule_delete` 之后仍留在 Session 收件箱中。
+- **提醒时间由宿主负责** —— 这些工具不提供目标时间校正、时钟来源或投递重试；这些限制属于该服务。
+- **每个工具都拒绝被委派的调用方** —— `schedule_create`、`schedule_list`、`schedule_update` 与 `schedule_delete` 都会在派发前读取调用方 Agent 的委派深度，当该深度大于零时返回 `{ code: 'subagent_session', message: 'A delegated subagent cannot use reminders.' }`。该守卫位于本包内，读取来自 `@qilin-agent/subagent` 的 `delegationDepthOf`，即委派封顶本身执行的同一份记账，因此在任何挂载这些工具的 preset 下都成立。
+- **preset 的委派行让这四个工具从子 agent 的 prompt 中消失** —— `standard`、`cordis` 与 `ptc` preset 在 `tool-subagent` 与 `tool-subagent-fork` 两行上都声明 `toolFilter.deny`，拒绝 `schedule_create`、`schedule_delete`、`schedule_list` 和 `schedule_update`。provider 会在子作用域内通过 `ctx.tools.restrict()` 应用该过滤，因此这四个工具会从被委派子 agent 的 prompt 中消失；在子链上继续委派会沿链求交同一限制。
+- **被委派子 agent 拥有的 Session 不能设置提醒** —— 当 Session 的 Agent 委派深度大于零时，`ScheduleService.create` 会抛出 `ScheduleInputError`（code 为 `subagent_session`），`ScheduleService.update` 则返回非变更的 `subagent_session` 结果。委派深度正是委派封顶本身读取的同一份记账，持久化 session header 让它在冷恢复后仍然成立。这条规则在服务层而非这些工具里，因此其它进程内消费方（包括自动化任务页面）也会命中。`schedule_list` 与 `schedule_delete` 仍可服务该 Session，所以在这条规则之前存储的提醒仍可删除。
+
+<a id="dev-note"></a>
+### 开发备注
+
+<details>
+<summary>维护者工作上下文——点击展开</summary>
+
+None.
+
+</details>

package/lib/index.js

@@ -0,0 +1,660 @@
+import { delegationDepthOf } from "@qilin-agent/subagent";
+import { defineTool } from "@qilin-agent/tools";
+import { MAX_TITLE_LENGTH, MIN_EVERY_INTERVAL_SECONDS, REQUIRED_TITLE_MESSAGE, ScheduleId, ScheduleInputError, scheduleView } from "@qilin-agent/schedule";
+//#region lib/types/index.js
+/**
+* Model-facing `schedule_create`, `schedule_list`, `schedule_update`, and
+* `schedule_delete` tools over the Host `ctx.schedule` service. Mounting the
+* plugin registers them in the mounting scope, so a preset decides which
+* agents receive them; every call acts on the calling Agent's Session.
+* @module @qilin-agent/tool-schedule
+*/
+/** Plugin name registered with the Loader. */
+const name = "tool-schedule";
+/** Host services this plugin consumes. The Schedule service is resolved per
+* scope, so a preset that declares this plugin stays inert while the shipped
+* composition keeps that service off. */
+const inject = ["tools"];
+const SHARED_VIEW_PROPERTIES = {
+	id: {
+		type: "string",
+		required: true
+	},
+	title: {
+		type: "string",
+		required: true
+	},
+	prompt: {
+		type: "string",
+		required: true
+	},
+	scheduledAt: {
+		type: "string",
+		required: true
+	},
+	state: {
+		type: "string",
+		required: true,
+		enum: ["scheduled", "overdue"]
+	},
+	deliveryMode: {
+		type: "string",
+		required: true,
+		const: "host"
+	}
+};
+const VIEW_SCHEMA = { oneOf: [
+	{
+		type: "object",
+		additionalProperties: false,
+		properties: {
+			...SHARED_VIEW_PROPERTIES,
+			kind: {
+				type: "string",
+				required: true,
+				const: "after"
+			},
+			afterSeconds: {
+				type: "integer",
+				required: true
+			}
+		}
+	},
+	{
+		type: "object",
+		additionalProperties: false,
+		properties: {
+			...SHARED_VIEW_PROPERTIES,
+			kind: {
+				type: "string",
+				required: true,
+				const: "at"
+			}
+		}
+	},
+	{
+		type: "object",
+		additionalProperties: false,
+		properties: {
+			...SHARED_VIEW_PROPERTIES,
+			kind: {
+				type: "string",
+				required: true,
+				const: "every"
+			},
+			everySeconds: {
+				type: "integer",
+				required: true
+			}
+		}
+	},
+	{
+		type: "object",
+		additionalProperties: false,
+		properties: {
+			...SHARED_VIEW_PROPERTIES,
+			kind: {
+				type: "string",
+				required: true,
+				const: "daily"
+			},
+			time: {
+				type: "string",
+				required: true
+			},
+			timeZone: {
+				type: "string",
+				required: true
+			}
+		}
+	},
+	{
+		type: "object",
+		additionalProperties: false,
+		properties: {
+			...SHARED_VIEW_PROPERTIES,
+			kind: {
+				type: "string",
+				required: true,
+				const: "weekly"
+			},
+			time: {
+				type: "string",
+				required: true
+			},
+			timeZone: {
+				type: "string",
+				required: true
+			},
+			weekdays: {
+				type: "array",
+				required: true,
+				items: { type: "integer" }
+			}
+		}
+	},
+	{
+		type: "object",
+		additionalProperties: false,
+		properties: {
+			...SHARED_VIEW_PROPERTIES,
+			kind: {
+				type: "string",
+				required: true,
+				const: "cron"
+			},
+			expression: {
+				type: "string",
+				required: true
+			},
+			timeZone: {
+				type: "string",
+				required: true
+			}
+		}
+	}
+] };
+/** Build one exact two-field error schema while preserving its literal code. */
+function basicErrorSchema(code) {
+	return {
+		type: "object",
+		additionalProperties: false,
+		properties: {
+			code: {
+				type: "string",
+				required: true,
+				const: code
+			},
+			message: {
+				type: "string",
+				required: true
+			}
+		}
+	};
+}
+const ERROR_SCHEMAS = [
+	basicErrorSchema("invalid_prompt"),
+	basicErrorSchema("invalid_selector"),
+	basicErrorSchema("invalid_rule"),
+	basicErrorSchema("invalid_time_zone"),
+	basicErrorSchema("not_future"),
+	basicErrorSchema("time_out_of_range"),
+	basicErrorSchema("frequency_too_high"),
+	basicErrorSchema("subagent_session"),
+	basicErrorSchema("internal_error")
+];
+const CREATE_OUTPUT_SCHEMA = { oneOf: [VIEW_SCHEMA, ...ERROR_SCHEMAS] };
+const LIST_OUTPUT_SCHEMA = { oneOf: [{
+	type: "array",
+	items: VIEW_SCHEMA
+}, ...ERROR_SCHEMAS] };
+const DELETE_OUTPUT_SCHEMA = { oneOf: [
+	{
+		type: "object",
+		additionalProperties: false,
+		properties: {
+			id: {
+				type: "string",
+				required: true
+			},
+			deleted: {
+				type: "boolean",
+				required: true,
+				const: true
+			}
+		}
+	},
+	{
+		type: "object",
+		additionalProperties: false,
+		properties: {
+			id: {
+				type: "string",
+				required: true
+			},
+			deleted: {
+				type: "boolean",
+				required: true,
+				const: false
+			},
+			code: {
+				type: "string",
+				required: true,
+				const: "schedule_not_found"
+			}
+		}
+	},
+	...ERROR_SCHEMAS
+] };
+const UPDATE_OUTPUT_SCHEMA = { oneOf: [
+	VIEW_SCHEMA,
+	{
+		type: "object",
+		additionalProperties: false,
+		properties: {
+			id: {
+				type: "string",
+				required: true
+			},
+			updated: {
+				type: "boolean",
+				required: true,
+				const: false
+			},
+			code: {
+				type: "string",
+				required: true,
+				enum: [
+					"schedule_not_found",
+					"schedule_ended",
+					"schedule_conflict"
+				]
+			}
+		}
+	},
+	...ERROR_SCHEMAS
+] };
+const CREATE_DESCRIPTION = "Create a reminder in the current session that delivers prompt when it becomes due. Supply exactly one timing parameter: after_seconds, at, every_seconds, daily, weekly, or cron. Local times that do not exist in the zone are skipped; repeated local times fire once, at the earlier instant. After downtime, a recurring reminder delivers only its latest missed occurrence. Delivery can repeat after a crash.";
+const LIST_DESCRIPTION = "List the active reminders in the current session.";
+const DELETE_DESCRIPTION = "Delete a reminder in the current session, active or inactive. Deletion does not retract a reminder message that is already queued.";
+const UPDATE_DESCRIPTION = "Change a reminder in place, keeping its id. Supply a new title, prompt, or at most one timing parameter; omitted fields keep their stored values. To change a relative delay, create a new reminder.";
+/** Deterministic model content for every canonical Schedule value. */
+function renderValue(_args, value) {
+	return [{
+		type: "text",
+		text: JSON.stringify(value)
+	}];
+}
+/** Pure generic pending card. */
+function present(title, kind, rawInput) {
+	return {
+		card: "generic",
+		title,
+		kind,
+		...rawInput === void 0 ? {} : { rawInput }
+	};
+}
+/** Stable error for failures not safe to expose. */
+function internalError() {
+	return {
+		code: "internal_error",
+		message: "The schedule operation failed."
+	};
+}
+/** Translate invalid input while withholding internal storage failures. */
+function operationError(error) {
+	return error instanceof ScheduleInputError ? {
+		code: error.code,
+		message: error.message
+	} : internalError();
+}
+/**
+* Refuse a caller that is a delegated child. A subagent cannot use reminders at
+* all, so every tool rejects before dispatch instead of relying on the mounting
+* preset's tool filter alone.
+* @param agent - the calling agent, when the outer call has one.
+* @returns the stable refusal, or undefined for a top-level caller.
+*/
+function subagentCallerRefusal(agent) {
+	if (agent === void 0 || delegationDepthOf(agent) === 0) return void 0;
+	return {
+		code: "subagent_session",
+		message: "A delegated subagent cannot use reminders."
+	};
+}
+/** One supplied fixed-rate interval: a safe integer at or above the Host floor, or undefined. */
+function invalidInterval(everySeconds) {
+	if (everySeconds === void 0) return void 0;
+	if (!Number.isSafeInteger(everySeconds)) return {
+		code: "invalid_rule",
+		message: "every_seconds must be a safe integer."
+	};
+	if (everySeconds < MIN_EVERY_INTERVAL_SECONDS) return {
+		code: "frequency_too_high",
+		message: `every_seconds must be at least ${MIN_EVERY_INTERVAL_SECONDS}.`
+	};
+}
+/** Validate selector constraints that the open parameter root cannot express. */
+function validateCreateArgs(args) {
+	if (Object.keys(args).some((key) => key !== "prompt" && key !== "title" && key !== "after_seconds" && key !== "at" && key !== "every_seconds" && key !== "daily" && key !== "weekly" && key !== "cron") || Number(args.after_seconds !== void 0) + Number(args.at !== void 0) + Number(args.every_seconds !== void 0) + Number(args.daily !== void 0) + Number(args.weekly !== void 0) + Number(args.cron !== void 0) !== 1) return {
+		code: "invalid_selector",
+		message: "schedule_create accepts exactly one of after_seconds, at, every_seconds, daily, weekly, or cron."
+	};
+	if (args.prompt.trim().length === 0) return {
+		code: "invalid_prompt",
+		message: "prompt must be non-empty after trimming."
+	};
+	if (args.title.trim().length === 0) return {
+		code: "invalid_prompt",
+		message: REQUIRED_TITLE_MESSAGE
+	};
+	if (args.title.trim().length > MAX_TITLE_LENGTH) return {
+		code: "invalid_prompt",
+		message: `title must be at most ${MAX_TITLE_LENGTH} characters.`
+	};
+	if (args.after_seconds !== void 0 && (!Number.isSafeInteger(args.after_seconds) || args.after_seconds <= 0)) return {
+		code: "invalid_rule",
+		message: "after_seconds must be a positive safe integer."
+	};
+	return invalidInterval(args.every_seconds);
+}
+/** Validate the in-place update's selector count, id, and any supplied name, instruction, or interval. */
+function validateUpdateArgs(args) {
+	const selectors = [
+		args.at !== void 0,
+		args.every_seconds !== void 0,
+		args.daily !== void 0,
+		args.weekly !== void 0,
+		args.cron !== void 0
+	].filter(Boolean).length;
+	if (Object.keys(args).some((key) => key !== "id" && key !== "title" && key !== "prompt" && key !== "at" && key !== "every_seconds" && key !== "daily" && key !== "weekly" && key !== "cron") || selectors > 1) return {
+		code: "invalid_selector",
+		message: "schedule_update accepts at most one of at, every_seconds, daily, weekly, or cron."
+	};
+	if (args.id.length === 0 || args.id.trim() !== args.id) return {
+		code: "invalid_rule",
+		message: "schedule_update id must be non-empty without surrounding whitespace."
+	};
+	if (selectors === 0 && args.title === void 0 && args.prompt === void 0) return {
+		code: "invalid_selector",
+		message: "schedule_update needs a new title, prompt, or one of at, every_seconds, daily, weekly, or cron."
+	};
+	if (args.title !== void 0 && args.title.trim().length === 0) return {
+		code: "invalid_prompt",
+		message: REQUIRED_TITLE_MESSAGE
+	};
+	if (args.title !== void 0 && args.title.trim().length > MAX_TITLE_LENGTH) return {
+		code: "invalid_prompt",
+		message: `title must be at most ${MAX_TITLE_LENGTH} characters.`
+	};
+	if (args.prompt !== void 0 && args.prompt.trim().length === 0) return {
+		code: "invalid_prompt",
+		message: "prompt must be non-empty after trimming."
+	};
+	return invalidInterval(args.every_seconds);
+}
+/** The one timing replacement the update carries, or undefined when the request keeps the committed target. */
+function timingChangeFrom(args) {
+	if (args.at !== void 0) return {
+		kind: "at",
+		at: args.at
+	};
+	if (args.every_seconds !== void 0) return {
+		kind: "every",
+		every_seconds: args.every_seconds
+	};
+	if (args.daily !== void 0) return {
+		kind: "daily",
+		daily: args.daily
+	};
+	if (args.weekly !== void 0) return {
+		kind: "weekly",
+		weekly: args.weekly
+	};
+	if (args.cron !== void 0) return {
+		kind: "cron",
+		cron: args.cron
+	};
+}
+/**
+* Selector parameters shared by `schedule_create` and `schedule_update`, in the order the
+* generated tool catalog states them.
+*/
+const SELECTOR_PARAMETERS = {
+	every_seconds: {
+		type: "number",
+		description: `Fixed-rate interval in whole seconds, at least ${MIN_EVERY_INTERVAL_SECONDS}, aligned to the creation time; changing it with schedule_update re-aligns it to the save time.`
+	},
+	daily: {
+		type: "object",
+		additionalProperties: false,
+		description: "Every day at a local time.",
+		properties: {
+			time: {
+				type: "string",
+				required: true,
+				description: "HH:mm:ss with optional 1-3 fractional digits, for example 23:00:00."
+			},
+			time_zone: {
+				type: "string",
+				required: true,
+				description: "UTC or IANA Area/Location, for example Asia/Shanghai."
+			}
+		}
+	},
+	weekly: {
+		type: "object",
+		additionalProperties: false,
+		description: "On the given weekdays at a local time.",
+		properties: {
+			time: {
+				type: "string",
+				required: true,
+				description: "HH:mm:ss with optional 1-3 fractional digits, for example 09:00:00."
+			},
+			time_zone: {
+				type: "string",
+				required: true,
+				description: "UTC or IANA Area/Location, for example Asia/Shanghai."
+			},
+			weekdays: {
+				type: "array",
+				required: true,
+				description: "ISO weekdays, Monday 1 through Sunday 7, without repetitions.",
+				items: { type: "integer" }
+			}
+		}
+	},
+	cron: {
+		type: "object",
+		additionalProperties: false,
+		description: "Five-field Vixie cron expression in a time zone.",
+		properties: {
+			expression: {
+				type: "string",
+				required: true,
+				description: "minute hour day-of-month month day-of-week, for example \"*/15 9-17 * * 1-5\". When both day fields are restricted, a date matches if either one matches."
+			},
+			time_zone: {
+				type: "string",
+				required: true,
+				description: "UTC or IANA Area/Location, for example Asia/Shanghai."
+			}
+		}
+	},
+	at: {
+		description: "Absolute target: an RFC 3339 date-time with offset, or a local date, time, and IANA time_zone.",
+		oneOf: [{ type: "string" }, {
+			type: "object",
+			additionalProperties: false,
+			properties: {
+				date: {
+					type: "string",
+					required: true
+				},
+				time: {
+					type: "string",
+					required: true
+				},
+				time_zone: {
+					type: "string",
+					required: true
+				}
+			}
+		}]
+	}
+};
+/**
+* Register the four Schedule tools in the mounting scope.
+*
+* Each call mutates the Session of the Agent that dispatched it, so a mount
+* outside an agent scope still registers the tools but every call without a
+* caller Agent is refused as an internal failure.
+* @param ctx - Context owning the `tools` registry and the Host `schedule` service.
+*/
+function apply(ctx) {
+	ctx.inject(["schedule"], (scheduleCtx) => {
+		registerScheduleTools(scheduleCtx);
+	});
+}
+/**
+* Register the four reminder tools in the scope that resolved the Schedule
+* service.
+* @param ctx - Scope whose `schedule` service the tools act through.
+*/
+function registerScheduleTools(ctx) {
+	ctx.tools.register(defineTool({
+		name: "schedule_create",
+		description: CREATE_DESCRIPTION,
+		parameters: {
+			prompt: {
+				type: "string",
+				required: true,
+				description: "Reminder content to present when the target becomes due."
+			},
+			title: {
+				type: "string",
+				required: true,
+				description: `Task name of at most ${MAX_TITLE_LENGTH} characters, shown on the task card and in task lists.`
+			},
+			after_seconds: {
+				type: "number",
+				description: "Delay in whole seconds."
+			},
+			...SELECTOR_PARAMETERS
+		},
+		output: {
+			schema: CREATE_OUTPUT_SCHEMA,
+			render: renderValue
+		},
+		async execute(args, exec) {
+			const agent = exec.agent;
+			if (agent === void 0) return internalError();
+			const refusal = subagentCallerRefusal(agent);
+			if (refusal !== void 0) return refusal;
+			const invalid = validateCreateArgs(args);
+			if (invalid !== void 0) return invalid;
+			if (exec.signal.aborted) return internalError();
+			try {
+				return scheduleView(await ctx.schedule.create(agent.session.id, args, exec.signal), Date.now());
+			} catch (error) {
+				return operationError(error);
+			}
+		},
+		presentCall: (args) => present("Create reminder", "other", args.prompt)
+	}));
+	ctx.tools.register(defineTool({
+		name: "schedule_list",
+		description: LIST_DESCRIPTION,
+		parameters: {},
+		output: {
+			schema: LIST_OUTPUT_SCHEMA,
+			render: renderValue
+		},
+		async execute(_args, exec) {
+			const agent = exec.agent;
+			if (agent === void 0) return internalError();
+			const refusal = subagentCallerRefusal(agent);
+			if (refusal !== void 0) return refusal;
+			if (exec.signal.aborted) return internalError();
+			try {
+				return (await ctx.schedule.list({ sessionId: agent.session.id })).map((record) => scheduleView(record, Date.now()));
+			} catch (error) {
+				return operationError(error);
+			}
+		},
+		presentCall: () => present("List reminders", "read")
+	}));
+	ctx.tools.register(defineTool({
+		name: "schedule_delete",
+		description: DELETE_DESCRIPTION,
+		parameters: { id: {
+			type: "string",
+			required: true,
+			description: "Exact schedule id."
+		} },
+		output: {
+			schema: DELETE_OUTPUT_SCHEMA,
+			render: renderValue
+		},
+		async execute(args, exec) {
+			if (args.id.length === 0 || args.id.trim() !== args.id) return {
+				code: "invalid_rule",
+				message: "schedule_delete id must be non-empty without surrounding whitespace."
+			};
+			const id = ScheduleId(args.id);
+			const agent = exec.agent;
+			if (agent === void 0) return internalError();
+			const refusal = subagentCallerRefusal(agent);
+			if (refusal !== void 0) return refusal;
+			if (exec.signal.aborted) return internalError();
+			try {
+				return await ctx.schedule.delete({
+					sessionId: agent.session.id,
+					id
+				}, exec.signal);
+			} catch (error) {
+				return operationError(error);
+			}
+		},
+		presentCall: (args) => present("Delete reminder", "other", args.id)
+	}));
+	ctx.tools.register(defineTool({
+		name: "schedule_update",
+		description: UPDATE_DESCRIPTION,
+		parameters: {
+			id: {
+				type: "string",
+				required: true,
+				description: "Schedule id returned by schedule_list."
+			},
+			title: {
+				type: "string",
+				description: `New task name of at most ${MAX_TITLE_LENGTH} characters.`
+			},
+			prompt: {
+				type: "string",
+				description: "New reminder content."
+			},
+			...SELECTOR_PARAMETERS
+		},
+		output: {
+			schema: UPDATE_OUTPUT_SCHEMA,
+			render: renderValue
+		},
+		async execute(args, exec) {
+			const agent = exec.agent;
+			if (agent === void 0) return internalError();
+			const refusal = subagentCallerRefusal(agent);
+			if (refusal !== void 0) return refusal;
+			const invalid = validateUpdateArgs(args);
+			if (invalid !== void 0) return invalid;
+			if (exec.signal.aborted) return internalError();
+			const id = ScheduleId(args.id);
+			try {
+				const sessionId = agent.session.id;
+				const expected = (await ctx.schedule.list({ sessionId })).find((record) => record.id === id);
+				if (expected === void 0) return {
+					id,
+					updated: false,
+					code: (await ctx.schedule.catalog()).some((entry) => entry.sessionId === sessionId && entry.id === id) ? "schedule_ended" : "schedule_not_found"
+				};
+				const change = timingChangeFrom(args);
+				const result = await ctx.schedule.update({
+					sessionId,
+					id,
+					expected,
+					...change === void 0 ? {} : { change },
+					...args.title === void 0 ? {} : { title: args.title },
+					...args.prompt === void 0 ? {} : { prompt: args.prompt }
+				}, exec.signal);
+				return "record" in result ? scheduleView(result.record, Date.now()) : result;
+			} catch (error) {
+				return operationError(error);
+			}
+		},
+		presentCall: (args) => present("Update reminder", "other", args.id)
+	}));
+}
+//#endregion
+export { apply, inject, name };

package/lib/types/index.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Model-facing `schedule_create`, `schedule_list`, `schedule_update`, and
+ * `schedule_delete` tools over the Host `ctx.schedule` service. Mounting the
+ * plugin registers them in the mounting scope, so a preset decides which
+ * agents receive them; every call acts on the calling Agent's Session.
+ * @module @qilin-agent/tool-schedule
+ */
+import type { Context } from '@qilin-agent/kylin';
+/** Plugin name registered with the Loader. */
+export declare const name = "tool-schedule";
+/** Host services this plugin consumes. The Schedule service is resolved per
+ * scope, so a preset that declares this plugin stays inert while the shipped
+ * composition keeps that service off. */
+export declare const inject: string[];
+/**
+ * Register the four Schedule tools in the mounting scope.
+ *
+ * Each call mutates the Session of the Agent that dispatched it, so a mount
+ * outside an agent scope still registers the tools but every call without a
+ * caller Agent is refused as an internal failure.
+ * @param ctx - Context owning the `tools` registry and the Host `schedule` service.
+ */
+export declare function apply(ctx: Context): void;
+//# sourceMappingURL=index.d.ts.map

package/package.json

@@ -1,6 +1,49 @@
 {
   "name": "@qilin-agent/tool-schedule",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "description": "Model-facing reminder management tools (schedule_create, schedule_list, schedule_update, schedule_delete) over the Host ctx.schedule service",
+  "version": "3.1.4",
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/kkutysllb/QiLin.git",
+    "directory": "packages/schedule/tool-schedule"
+  },
+  "engines": {
+    "node": "^22.19.0 || >=24.0.0"
+  },
+  "type": "module",
+  "main": "lib/index.js",
+  "types": "lib/types/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./lib/types/index.d.ts",
+      "default": "./lib/index.js"
+    },
+    "./src/*": "./src/*",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "lib/index.js",
+    "lib/types/**/*.d.ts"
+  ],
+  "license": "MIT",
+  "peerDependencies": {
+    "@qilin-agent/kylin": "~4.0.3",
+    "@qilin-agent/schedule": "3.1.4",
+    "@qilin-agent/llm": "3.1.4",
+    "@qilin-agent/subagent": "3.1.4",
+    "@qilin-agent/tools": "3.1.4"
+  },
+  "devDependencies": {
+    "@qilin-agent/llm": "3.1.4",
+    "@qilin-agent/schedule": "3.1.4",
+    "@qilin-agent/agent": "3.1.4",
+    "@qilin-agent/kylin": "~4.0.3",
+    "@qilin-agent/scope": "3.1.4",
+    "@qilin-agent/session": "3.1.4",
+    "@qilin-agent/subagent": "3.1.4",
+    "@qilin-agent/tools": "3.1.4"
+  }
 }