my-opencode-toolkit 0.0.0-stage → 0.2.2

package/src/scheduling/tools.ts

@@ -0,0 +1,183 @@
+import type { Plugin } from "@opencode/plugin"
+import { Schema } from "effect"
+
+import type { SessionRoles } from "../goal/session-role.ts"
+import { loadSettings } from "../shared/settings-store.ts"
+import { cronToHuman } from "./cron.ts"
+import type { LoopScheduler } from "./loops.ts"
+import type { SchedulingStore } from "./store.ts"
+import { DEFAULT_MAX_AGE_DAYS } from "./types.ts"
+
+const DESCRIPTION_CREATE =
+  'Schedule a recurring or one-shot prompt in this session using a 5-field cron expression ' +
+  '(local time: "M H DoM Mon DoW"). The prompt is auto-injected when the session is idle at the ' +
+  `scheduled time (no catch-up for missed fires). Recurring tasks auto-expire after ${String(DEFAULT_MAX_AGE_DAYS)} ` +
+  "days. Use cron_delete to cancel sooner."
+
+const DESCRIPTION_LIST = "List all scheduled jobs for this session with their ids, schedules, and prompts."
+
+const DESCRIPTION_DELETE = "Cancel a scheduled job by its 8-character id (returned by cron_create)."
+
+const DESCRIPTION_WAKEUP =
+  "Schedule when to resume work in /loop dynamic mode. Only works when there is an active dynamic " +
+  "loop in this session with the exact same prompt. Pass the loop prompt back verbatim to continue; " +
+  "omit this call to end the loop. delaySeconds is clamped to 60-3600. Set stop: true to end the " +
+  "loop immediately."
+
+const CreateInput = Schema.Struct({
+  cron: Schema.String,
+  prompt: Schema.String,
+  recurring: Schema.optional(Schema.Boolean),
+  durable: Schema.optional(Schema.Boolean),
+})
+
+const EmptyInput = Schema.Struct({})
+
+const DeleteInput = Schema.Struct({ id: Schema.String })
+
+const WakeupInput = Schema.Struct({
+  delaySeconds: Schema.Number,
+  prompt: Schema.String,
+  reason: Schema.String,
+  stop: Schema.optional(Schema.Boolean),
+})
+
+const EmptyOutput = Schema.Struct({})
+
+/** 输入：文本 + 上限；输出：超长时截断并加省略号。 */
+function truncate(text: string, max: number): string {
+  return text.length > max ? `${text.slice(0, max - 3)}...` : text
+}
+
+/**
+ * 输入：插件上下文、任务存储、循环调度器、会话角色。
+ * 输出：注册 cron_create / cron_list / cron_delete / schedule_wakeup。
+ * 预期：关闭或子代理会话返回错误文本；不抛异常。
+ */
+export async function registerSchedulingTools(
+  ctx: Plugin.Context,
+  store: SchedulingStore,
+  scheduler: LoopScheduler,
+  roles: SessionRoles,
+): Promise<{ dispose(): Promise<void> }> {
+  /** 输入：会话 ID；输出：不可用原因，可用时为 null。 */
+  const unavailable = async (sessionID: string): Promise<string | null> => {
+    const settings = await loadSettings(ctx.storage)
+    if (!settings.enabled || !settings.scheduling.enabled) {
+      return "Error: the scheduling feature is disabled in settings."
+    }
+    if (await roles.isSubagent(sessionID)) return "Error: scheduling tools are not available to subagents."
+    return null
+  }
+
+  return ctx.tool.transform((tools) => {
+    tools.add({
+      name: "cron_create",
+      options: { codemode: false },
+      description: DESCRIPTION_CREATE,
+      input: CreateInput,
+      output: EmptyOutput,
+      execute: async (input, toolCtx) => {
+        const sessionID = toolCtx.sessionID
+        const blocked = await unavailable(sessionID)
+        if (blocked !== null) return { output: {}, content: blocked }
+
+        const prompt = input.prompt.trim()
+        if (prompt.length === 0) return { output: {}, content: "Error: prompt cannot be empty." }
+
+        const result = await store.addJob({
+          sessionID,
+          cron: input.cron,
+          prompt,
+          recurring: input.recurring ?? true,
+          durable: input.durable ?? false,
+        })
+        if (!result.ok) return { output: {}, content: `Error: ${result.error}` }
+
+        const job = result.job
+        const where =
+          job.durable === true
+            ? "Persisted in plugin storage and survives restarts"
+            : "Session-only (dies when the plugin restarts)"
+        const content =
+          job.recurring === true
+            ? `Scheduled recurring job ${job.id} (${cronToHuman(job.cron)}). ${where}. Auto-expires after ${String(DEFAULT_MAX_AGE_DAYS)} days. Use cron_delete to cancel sooner.`
+            : `Scheduled one-shot task ${job.id} (${cronToHuman(job.cron)}). ${where}. It will fire once then auto-delete.`
+        return { output: {}, content }
+      },
+    })
+
+    tools.add({
+      name: "cron_list",
+      options: { codemode: false },
+      description: DESCRIPTION_LIST,
+      input: EmptyInput,
+      output: EmptyOutput,
+      execute: async (_input, toolCtx) => {
+        const sessionID = toolCtx.sessionID
+        const blocked = await unavailable(sessionID)
+        if (blocked !== null) return { output: {}, content: blocked }
+
+        const jobs = store.listJobs(sessionID)
+        if (jobs.length === 0) return { output: {}, content: "No scheduled jobs." }
+        const lines = jobs.map((job) => {
+          const kind = job.recurring === true ? "recurring" : "one-shot"
+          const scope = job.durable === false ? " [session-only]" : ""
+          return `${job.id} — ${cronToHuman(job.cron)} (${kind})${scope}: ${truncate(job.prompt, 80)}`
+        })
+        return { output: {}, content: lines.join("\n") }
+      },
+    })
+
+    tools.add({
+      name: "cron_delete",
+      options: { codemode: false },
+      description: DESCRIPTION_DELETE,
+      input: DeleteInput,
+      output: EmptyOutput,
+      execute: async (input, toolCtx) => {
+        const sessionID = toolCtx.sessionID
+        const blocked = await unavailable(sessionID)
+        if (blocked !== null) return { output: {}, content: blocked }
+
+        const job = store.getJob(input.id)
+        if (job === undefined) return { output: {}, content: `Error: No scheduled job with id '${input.id}'` }
+        if (job.sessionID !== sessionID) {
+          return { output: {}, content: `Error: Cannot delete cron job '${input.id}': owned by another session` }
+        }
+        await store.removeJobs([input.id])
+        return { output: {}, content: `Cancelled job ${input.id}.` }
+      },
+    })
+
+    tools.add({
+      name: "schedule_wakeup",
+      options: { codemode: false },
+      description: DESCRIPTION_WAKEUP,
+      input: WakeupInput,
+      output: EmptyOutput,
+      execute: async (input, toolCtx) => {
+        const sessionID = toolCtx.sessionID
+        const blocked = await unavailable(sessionID)
+        if (blocked !== null) return { output: {}, content: blocked }
+
+        if (input.stop === true) {
+          const stopped = scheduler.stopLoopByPrompt(sessionID, input.prompt)
+          return {
+            output: {},
+            content: stopped
+              ? `Loop stopped: ${input.prompt}`
+              : `Error: no active dynamic loop for prompt '${input.prompt}'`,
+          }
+        }
+
+        const result = scheduler.scheduleWakeup(sessionID, input.prompt, input.delaySeconds, input.reason)
+        if (!result.ok) return { output: {}, content: `Error: ${result.error}` }
+        return {
+          output: {},
+          content: `Wake-up scheduled for ${new Date(result.fireAt).toLocaleString()} (loop ${result.id}).`,
+        }
+      },
+    })
+  })
+}

package/src/scheduling/types.ts

@@ -0,0 +1,54 @@
+/** 任务 id 长度（`randomUUID().slice(0, 8)`，8 个 hex 字符）。 */
+export const JOB_ID_LENGTH = 8
+
+/** 每会话定时任务上限。 */
+export const MAX_JOBS = 50
+
+/** recurring 任务自动过期天数。 */
+export const DEFAULT_MAX_AGE_DAYS = 7
+
+/** 定时任务（cron）。 */
+export type ScheduledJob = {
+  readonly id: string
+  readonly sessionID: string
+  /** 5 字段 cron（本地时区）。 */
+  readonly cron: string
+  /** 触发时注入的 prompt。 */
+  readonly prompt: string
+  readonly createdAt: number
+  lastFiredAt?: number
+  /** true = 重复触发；缺省 = one-shot（火一次自删）。 */
+  readonly recurring?: boolean
+  /** 豁免过期（系统内部任务预留）。 */
+  readonly permanent?: boolean
+  /** false = 仅内存；缺省 = 写存储。 */
+  readonly durable?: boolean
+  /** 运行时字段：下一次 fire 时刻，不写存储。 */
+  nextRunAt?: number
+}
+
+/** 固定间隔循环。 */
+export type Loop = {
+  readonly id: string
+  readonly sessionID: string
+  readonly prompt: string
+  readonly mode: "fixed" | "dynamic"
+  /** fixed 模式间隔秒数。 */
+  readonly intervalSeconds?: number
+  readonly createdAt: number
+  readonly expiresAt: number
+  /** 已触发次数（运行时）。 */
+  fires: number
+  /** 下一次 fire 时刻（运行时，供 TUI 倒计时）。 */
+  nextFireAt?: number
+  /** dynamic 模式：`schedule_wakeup` 设定的待唤醒信息。 */
+  pendingWakeup?: Wakeup
+}
+
+/** `schedule_wakeup` 的一次唤醒。 */
+export type Wakeup = {
+  readonly fireAt: number
+  readonly delaySeconds: number
+  readonly prompt: string
+  readonly reason: string
+}

package/src/shared/events.ts

@@ -0,0 +1,44 @@
+import { asRecord } from "./json.ts"
+
+/** 插件事件的最小形状。 */
+export type PluginEvent = {
+  readonly type: string
+  readonly data: unknown
+}
+
+/**
+ * 输入：插件事件。
+ * 输出：`data.sessionID`，没有则 `undefined`。
+ * 预期：兼容 `sessionID` 字段缺失或类型错误；不抛异常。
+ */
+export function readEventSessionID(event: PluginEvent): string | undefined {
+  const data = asRecord(event.data)
+  const value = data?.["sessionID"]
+  return typeof value === "string" && value.length > 0 ? value : undefined
+}
+
+/**
+ * 输入：插件事件。
+ * 输出：`data` 的对象视图，非对象时为 `undefined`。
+ */
+export function readEventData(event: PluginEvent): Record<string, unknown> | undefined {
+  return asRecord(event.data)
+}
+
+/** 事件处理函数。 */
+export type EventHandler = (event: PluginEvent) => Promise<void>
+
+/**
+ * 输入：处理函数列表 + 事件。
+ * 输出：无。
+ * 预期：按顺序调用；单个 handler 抛错被吞掉，不影响其他 handler 与后续事件。
+ */
+export async function dispatchEvent(handlers: readonly EventHandler[], event: PluginEvent): Promise<void> {
+  for (const handler of handlers) {
+    try {
+      await handler(event)
+    } catch {
+      // 单个 handler 失败不能影响其他 handler 与后续事件
+    }
+  }
+}

package/src/shared/format.ts

@@ -0,0 +1,16 @@
+/**
+ * 输入：token 数。
+ * 输出：紧凑文本（`999` / `12.3k` / `1.2m`）。
+ * 预期：保留一位小数，末尾 `.0` 去掉。
+ */
+export function formatTokens(value: number): string {
+  const abs = Math.abs(value)
+  if (abs < 1000) return String(Math.trunc(value))
+  if (abs < 1_000_000) return trim(`${(value / 1000).toFixed(1)}k`)
+  return trim(`${(value / 1_000_000).toFixed(1)}m`)
+}
+
+/** 输入：`12.0k`；输出：`12k`。预期：只去掉小数部分全零的尾巴。 */
+function trim(text: string): string {
+  return text.replace(/\.0([km])$/, "$1")
+}

package/src/shared/json.ts

@@ -0,0 +1,44 @@
+/**
+ * 插件存储能接受的 JSON 值。
+ *
+ * 预期：只包含 JSON 原生类型，保证 `ctx.storage.set` 能直接落盘。
+ */
+export type JsonValue =
+  | string
+  | number
+  | boolean
+  | null
+  | JsonValue[]
+  | { [key: string]: JsonValue }
+
+/**
+ * 插件存储的最小接口。
+ *
+ * 输入：key 与 JSON 值。
+ * 输出：读取返回 `unknown`（调用方负责校验），写入无返回。
+ * 预期：与 `ctx.storage` 结构兼容，测试里可用内存实现替换。
+ */
+export type JsonStore = {
+  get(key: string): Promise<unknown>
+  set(key: string, value: JsonValue): Promise<void>
+  remove(key: string): Promise<void>
+}
+
+/** 带分页扫描能力的存储（`ctx.storage` 满足）。 */
+export type ScannableStore = JsonStore & {
+  scan(options: {
+    prefix: string
+    limit?: number
+    after?: string
+  }): Promise<{ entries: readonly { key: string; value: unknown }[]; next?: string }>
+}
+
+/**
+ * 输入：任意值。
+ * 输出：普通对象则返回自身，否则 `undefined`。
+ * 预期：用于把存储里读出的 `unknown` 收窄成可按 key 访问的记录；数组不算记录。
+ */
+export function asRecord(value: unknown): Record<string, unknown> | undefined {
+  if (typeof value !== "object" || value === null || Array.isArray(value)) return undefined
+  return value as Record<string, unknown>
+}

package/src/shared/keys.ts

@@ -0,0 +1,26 @@
+/** 全局设置的存储 key。 */
+export const SETTINGS_KEY = "settings"
+
+/** Goal 状态的 key 前缀，后面拼会话 ID。 */
+export const GOAL_PREFIX = "goal:"
+
+/** 定时任务的 key 前缀，后面拼会话 ID。 */
+export const SCHEDULE_PREFIX = "schedule:"
+
+/**
+ * 输入：会话 ID。
+ * 输出：该会话的 goal 存储 key。
+ * 预期：不同会话互不覆盖。
+ */
+export function goalKey(sessionID: string): string {
+  return `${GOAL_PREFIX}${sessionID}`
+}
+
+/**
+ * 输入：会话 ID。
+ * 输出：该会话的定时任务存储 key。
+ * 预期：不同会话互不覆盖。
+ */
+export function scheduleKey(sessionID: string): string {
+  return `${SCHEDULE_PREFIX}${sessionID}`
+}

package/src/shared/messages.ts

@@ -0,0 +1,17 @@
+import type { Plugin } from "@opencode/plugin"
+
+/**
+ * 输入：插件上下文 + 会话 ID + 注入标记。
+ * 输出：末条消息是否是真实用户输入（不是本插件注入的）。
+ * 预期：读不到消息时返回 false——宁可尝试注入，也不因为读取失败而永久死锁。
+ */
+export async function lastMessageIsUserInput(
+  ctx: Plugin.Context,
+  sessionID: string,
+  marker: string,
+): Promise<boolean> {
+  const messages = await ctx.session.context({ sessionID }).catch(() => undefined)
+  const last = messages?.at(-1)
+  if (last?.type !== "user") return false
+  return last.metadata?.[marker] !== true
+}

package/src/shared/rpc.ts

@@ -0,0 +1,214 @@
+import { Rpc } from "@opencode/plugin/rpc"
+
+import type { Settings } from "./settings.ts"
+
+/** 设置读取的输入：当前不需要参数，保留空对象以便后续扩展。 */
+const EmptyInputJson = {
+  type: "object",
+  properties: {},
+  additionalProperties: false,
+} as const
+
+/** 面板查询输入。 */
+const PanelInputJson = {
+  type: "object",
+  properties: { sessionID: { type: "string" } },
+  required: ["sessionID"],
+  additionalProperties: false,
+} as const
+
+/** 设置对象的 JSON Schema，服务端与 TUI 共用。 */
+const SettingsJson = {
+  type: "object",
+  properties: {
+    lang: { type: "string", enum: ["auto", "zh", "en"] },
+    enabled: { type: "boolean" },
+    notification: {
+      type: "object",
+      properties: {
+        enabled: { type: "boolean" },
+        onComplete: { type: "boolean" },
+        onQuestion: { type: "boolean" },
+        onPermission: { type: "boolean" },
+        onlyMainSession: { type: "boolean" },
+      },
+      required: ["enabled", "onComplete", "onQuestion", "onPermission", "onlyMainSession"],
+      additionalProperties: false,
+    },
+    goal: {
+      type: "object",
+      properties: { enabled: { type: "boolean" } },
+      required: ["enabled"],
+      additionalProperties: false,
+    },
+    scheduling: {
+      type: "object",
+      properties: { enabled: { type: "boolean" } },
+      required: ["enabled"],
+      additionalProperties: false,
+    },
+    sidebar: {
+      type: "object",
+      properties: {
+        enabled: { type: "boolean" },
+        showCache: { type: "boolean" },
+        showTools: { type: "boolean" },
+        showSubagents: { type: "boolean" },
+        collapsed: { type: "boolean" },
+      },
+      required: ["enabled", "showCache", "showTools", "showSubagents", "collapsed"],
+      additionalProperties: false,
+    },
+  },
+  required: ["lang", "enabled", "notification", "goal", "scheduling", "sidebar"],
+  additionalProperties: false,
+} as const
+
+/** 面板里的目标摘要。 */
+const PanelGoalJson = {
+  type: "object",
+  properties: {
+    objective: { type: "string" },
+    status: { type: "string", enum: ["active", "paused", "blocked", "budget_limited", "complete"] },
+    tokensUsed: { type: "number" },
+    tokenBudget: { type: "number" },
+    timeUsedSeconds: { type: "number" },
+  },
+  required: ["objective", "status", "tokensUsed", "timeUsedSeconds"],
+  additionalProperties: false,
+} as const
+
+/** 面板里的循环摘要。 */
+const PanelLoopJson = {
+  type: "object",
+  properties: {
+    id: { type: "string" },
+    mode: { type: "string", enum: ["fixed", "dynamic"] },
+    prompt: { type: "string" },
+    nextFireAt: { type: "number" },
+  },
+  required: ["id", "mode", "prompt"],
+  additionalProperties: false,
+} as const
+
+/** 面板里的定时任务摘要。 */
+const PanelJobJson = {
+  type: "object",
+  properties: {
+    id: { type: "string" },
+    cron: { type: "string" },
+    prompt: { type: "string" },
+    nextRunAt: { type: "number" },
+  },
+  required: ["id", "cron", "prompt"],
+  additionalProperties: false,
+} as const
+
+/** 面板里的统计。 */
+const PanelStatsJson = {
+  type: "object",
+  properties: {
+    steps: { type: "number" },
+    input: { type: "number" },
+    output: { type: "number" },
+    cached: { type: "number" },
+    hitRate: { type: "number" },
+    subagents: { type: "number" },
+    tools: {
+      type: "array",
+      items: {
+        type: "object",
+        properties: { name: { type: "string" }, count: { type: "number" } },
+        required: ["name", "count"],
+        additionalProperties: false,
+      },
+    },
+  },
+  required: ["steps", "input", "output", "cached", "hitRate", "subagents", "tools"],
+  additionalProperties: false,
+} as const
+
+const PanelOutputJson = {
+  type: "object",
+  properties: {
+    goal: { anyOf: [PanelGoalJson, { type: "null" }] },
+    loops: { type: "array", items: PanelLoopJson },
+    jobs: { type: "array", items: PanelJobJson },
+    stats: PanelStatsJson,
+  },
+  required: ["goal", "loops", "jobs", "stats"],
+  additionalProperties: false,
+} as const
+
+/** 服务端与 TUI 共用的 RPC 定义。 */
+export const ToolkitRpc: Rpc.PortableDefinition = Rpc.define({
+  id: "my-opencode-toolkit",
+  methods: {
+    settingsGet: { input: EmptyInputJson, output: SettingsJson },
+    settingsSet: { input: SettingsJson, output: SettingsJson },
+    panelGet: { input: PanelInputJson, output: PanelOutputJson },
+  },
+  events: {},
+})
+
+/** 面板目标摘要。 */
+export type PanelGoal = {
+  readonly objective: string
+  readonly status: string
+  readonly tokensUsed: number
+  readonly tokenBudget?: number
+  readonly timeUsedSeconds: number
+}
+
+/** 面板循环摘要。 */
+export type PanelLoop = {
+  readonly id: string
+  readonly mode: "fixed" | "dynamic"
+  readonly prompt: string
+  readonly nextFireAt?: number
+}
+
+/** 面板任务摘要。 */
+export type PanelJob = {
+  readonly id: string
+  readonly cron: string
+  readonly prompt: string
+  readonly nextRunAt?: number
+}
+
+/** 面板统计。 */
+export type PanelStats = {
+  readonly steps: number
+  readonly input: number
+  readonly output: number
+  readonly cached: number
+  readonly hitRate: number
+  readonly subagents: number
+  readonly tools: readonly { readonly name: string; readonly count: number }[]
+}
+
+/** 面板数据。 */
+export type PanelData = {
+  readonly goal: PanelGoal | null
+  readonly loops: readonly PanelLoop[]
+  readonly jobs: readonly PanelJob[]
+  readonly stats: PanelStats
+}
+
+/** TUI 侧对 ToolkitRpc 的类型化视图。 */
+export type ToolkitRpcClient = {
+  settingsGet(input: Record<string, never>): Promise<Settings>
+  settingsSet(input: Settings): Promise<Settings>
+  panelGet(input: { readonly sessionID: string }): Promise<PanelData>
+}
+
+/**
+ * 输入：带 `rpc` 方法的 TUI client。
+ * 输出：类型化 RPC 客户端。
+ * 预期：只做类型断言，不改变运行时行为。
+ */
+export function toolkitRpc(client: {
+  rpc(definition: Rpc.PortableDefinition): unknown
+}): ToolkitRpcClient {
+  return client.rpc(ToolkitRpc) as ToolkitRpcClient
+}

package/src/shared/scan.ts

@@ -0,0 +1,21 @@
+import type { ScannableStore } from "./json.ts"
+
+/**
+ * 输入：具备 scan 能力的存储 + 前缀 + 每条目处理函数 + 每页条数。
+ * 输出：无。
+ * 预期：按 next 游标分页遍历全部匹配条目，逐条串行处理，避免一次读进内存。
+ */
+export async function forEachScannedEntry(
+  store: ScannableStore,
+  prefix: string,
+  visit: (entry: { key: string; value: unknown }) => Promise<void>,
+  limit = 100,
+): Promise<void> {
+  let after: string | undefined
+  for (;;) {
+    const page = await store.scan({ prefix, limit, ...(after === undefined ? {} : { after }) })
+    for (const entry of page.entries) await visit(entry)
+    if (page.next === undefined) return
+    after = page.next
+  }
+}

package/src/shared/settings-store.ts

@@ -0,0 +1,28 @@
+import type { JsonStore } from "./json.ts"
+import { SETTINGS_KEY } from "./keys.ts"
+import { normalizeSettings, type Settings } from "./settings.ts"
+
+/**
+ * 输入：存储 + 插件 options（可缺省）。
+ * 输出：当前设置。
+ * 预期：首次运行时把 options 归一化成默认值写盘；之后以存储里的值为准，
+ *       存储损坏或字段缺失时按默认值补齐。
+ */
+export async function loadSettings(store: JsonStore, options?: unknown): Promise<Settings> {
+  const stored = await store.get(SETTINGS_KEY)
+  if (stored === undefined) {
+    const initial = normalizeSettings(options)
+    await store.set(SETTINGS_KEY, initial)
+    return initial
+  }
+  return normalizeSettings(stored)
+}
+
+/**
+ * 输入：存储 + 完整设置。
+ * 输出：无。
+ * 预期：先归一化再写盘，保证存储里不会出现未知字段或错误类型。
+ */
+export async function saveSettings(store: JsonStore, settings: Settings): Promise<void> {
+  await store.set(SETTINGS_KEY, normalizeSettings(settings))
+}