my-opencode-toolkit 0.0.0-stage → 0.2.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 1cyberlangke1
+
+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.md

@@ -1,3 +1,113 @@
-# Temporary Holding Version
+# my-opencode-toolkit
 
-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.
+OpenCode 插件：系统通知、持久目标、定时任务与循环、TUI 状态面板。
+
+## 功能
+
+### 系统通知
+
+- 会话空闲（任务完成）、权限请求（`permission.asked`）、代理提问（`question` 工具）三种通知
+- 平台：Windows toast（PowerShell）、macOS（osascript）、Linux（notify-send）
+- 标题带会话名，正文按设置语言本地化，长度截断避免 toast 溢出
+
+### 持久目标（Goal）
+
+- 工具：`create_goal`、`get_goal`、`update_goal`
+- 命令：`/goal <objective>`、`/goal pause|resume|clear|edit`、裸 `/goal` 查看
+- 目标 active 时会话空闲自动注入续作提示；同一原因连续 3 次阻塞才标记 `blocked`
+- 记账：每步的输入、输出、缓存读写都计入；达到 token 预算自动转 `budget_limited`
+- 用户打断自动暂停；余额不足暂停并锁死，需显式 `/goal resume`
+
+### 定时任务与循环
+
+- 工具：`cron_create`、`cron_list`、`cron_delete`、`schedule_wakeup`
+- 命令：
+  - `/cron <expr> <prompt>` 创建重复任务
+  - `/cron once <expr> <prompt>` 一次性任务
+  - `/cron list`、`/cron delete <id>`
+  - `/loop [interval] [prompt]` 启动循环，`/loop stop` 停止
+- 5 字段 cron（本地时区），支持 `*`、步进、范围、列表；每会话上限 50；重复任务 7 天过期
+- durable 任务存插件存储，重启恢复并重新武装 timer；非 durable 只留内存
+- 循环：固定间隔或动态（模型用 `schedule_wakeup` 决定下次，60–3600 秒，20 分钟兜底）
+- 裸 `/loop` 使用内置维护提示词；项目根目录有非空 `loop.md` 时优先用它
+
+### TUI 面板
+
+- 侧栏显示目标、缓存命中率、工具使用 Top3、子代理数量、循环与定时任务数量
+- 统计不单独存一份：每个会话第一次打开面板时，从 OpenCode 已存消息（`session.context`）重建一次，
+  之后用事件增量维护；插件重载或进程重启后再重建
+- 设置项可控制显示内容与折叠
+- `/my-opencode-toolkit` 打开设置菜单：启用、语言、通知、Goal、定时任务、侧栏
+
+### 子代理隔离
+
+子代理会话里不会出现 goal / scheduling 工具，也不会收到任何续作或定时注入。
+实现方式是在 `context` 钩子里从工具表删除，并在注入前检查 `session.parentID`。
+
+## 安装
+
+在 `~/.config/opencode/opencode.json` 的 `plugins` 数组里加包名：
+
+```jsonc
+{
+  "plugins": ["my-opencode-toolkit"]
+}
+```
+
+本地开发可以直接指向仓库目录：
+
+```jsonc
+{
+  "plugins": ["D:\\Git_Repository\\my-opencode-toolkit"]
+}
+```
+
+重启 OpenCode 后生效。
+
+要求 Node 20+；Windows 通知走 PowerShell toast，macOS 走 `osascript`，Linux 走 `notify-send`。
+
+## 设置
+
+设置存在插件存储里，首次启动用默认值；通过 `/my-opencode-toolkit` 菜单修改，立即生效。
+
+| 字段 | 默认 | 说明 |
+|---|---|---|
+| `lang` | `auto` | `auto` / `zh` / `en` |
+| `enabled` | `true` | 插件总开关 |
+| `notification.enabled` | `true` | 通知总开关 |
+| `notification.onComplete` | `true` | 任务完成通知 |
+| `notification.onQuestion` | `true` | 提问通知 |
+| `notification.onPermission` | `true` | 权限通知 |
+| `notification.onlyMainSession` | `true` | 跳过子代理会话 |
+| `goal.enabled` | `true` | Goal 功能 |
+| `scheduling.enabled` | `true` | 定时任务与循环 |
+| `sidebar.enabled` | `true` | 侧栏面板 |
+| `sidebar.showCache` | `true` | 显示缓存命中 |
+| `sidebar.showTools` | `true` | 显示工具统计 |
+| `sidebar.showSubagents` | `true` | 显示子代理数量 |
+| `sidebar.collapsed` | `false` | 折叠侧栏 |
+
+## 优先级
+
+会话空闲时：Goal active > 定时任务 / 循环。Goal 进行中，定时任务到点只重排不注入。
+
+## 已知限制
+
+- 侧栏统计是进程内数据：重启后第一次打开面板会从已存消息重建（重建瞬间完成的一步可能漏算）。
+- 通知是尽力而为：系统关闭通知、专注助手拦截或缺少对应命令时静默跳过，不影响会话。
+- 续作与定时注入只在主会话生效；子代理会话既看不到相关工具，也不会被注入。
+- 定时任务按本地时区解析 5 字段 cron，不支持秒级字段。
+
+## 开发
+
+```bash
+pnpm install
+pnpm check        # typecheck + lint + 单测 + TUI 渲染测试
+pnpm test:e2e     # 隔离环境启动真实 opencode，假 provider 驱动工具调用
+```
+
+要求 Node 20+（OpenCode v2 要求），测试用 vitest + bun。
+
+## License
+
+MIT，见 [LICENSE](LICENSE)。

package/index.ts

@@ -0,0 +1,3 @@
+// 本地插件目录入口：OpenCode 的本地插件解析会找 <dir>/index，
+// 这里只做转发，真正实现放在 src/index.ts。
+export { default } from "./src/index.ts"

package/package.json

@@ -1,6 +1,67 @@
 {
   "name": "my-opencode-toolkit",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.2.1",
+  "description": "OpenCode 插件：系统通知、持久目标、定时任务与 TUI 面板",
+  "type": "module",
+  "license": "MIT",
+  "author": "1cyberlangke1",
+  "homepage": "https://github.com/1cyberlangke1/my-opencode-toolkit#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/1cyberlangke1/my-opencode-toolkit.git"
+  },
+  "bugs": {
+    "url": "https://github.com/1cyberlangke1/my-opencode-toolkit/issues"
+  },
+  "keywords": [
+    "opencode",
+    "plugin",
+    "notification",
+    "goal",
+    "cron",
+    "tui"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "exports": {
+    ".": "./index.ts",
+    "./tui": "./tui.ts"
+  },
+  "files": [
+    "src",
+    "index.ts",
+    "tui.ts"
+  ],
+  "dependencies": {
+    "effect": "4.0.1"
+  },
+  "peerDependencies": {
+    "@opencode/plugin": "^2.0.32",
+    "@opentui/core": ">=0.5.17",
+    "@opentui/solid": ">=0.5.17",
+    "solid-js": ">=1.9.0"
+  },
+  "scripts": {
+    "typecheck": "tsc --noEmit",
+    "lint": "eslint .",
+    "check": "pnpm typecheck && pnpm lint && pnpm test && pnpm test:tui",
+    "test": "vitest run",
+    "test:tui": "cd tui-test && bun test",
+    "test:e2e": "bun scripts/e2e-load.mjs",
+    "test:watch": "vitest"
+  },
+  "devDependencies": {
+    "@eslint/js": "^10.0.1",
+    "@opencode/plugin": "^2.1.2",
+    "@opencode/theme": "2.1.2",
+    "@opentui/core": "0.6.6",
+    "@opentui/solid": "0.6.6",
+    "@types/node": "^26.6.5",
+    "eslint": "^10.13.0",
+    "solid-js": "1.9.15",
+    "typescript": "^6.0.3",
+    "typescript-eslint": "^8.71.2",
+    "vitest": "^5.0.5"
+  }
+}

package/src/goal/command.ts

@@ -0,0 +1,84 @@
+import type { Plugin } from "@opencode/plugin"
+
+import { loadSettings } from "../shared/settings-store.ts"
+import type { GoalContinuation } from "./continuation.ts"
+import type { GoalController } from "./controller.ts"
+import { parseGoalCommand } from "./parse-command.ts"
+
+const DESCRIPTION = "Set, inspect, pause, resume or clear the persistent goal for this session"
+
+const USAGE = "Usage: /goal [<objective>|clear|edit|pause|resume]"
+
+/**
+ * 输入：控制器 + 续作控制器 + 会话 ID + 原始参数。
+ * 输出：给模型看的英文反馈。
+ * 预期：set 会清掉旧目标与锁死标志；pause/resume 只对已有目标生效。
+ */
+async function applyGoalCommand(
+  controller: GoalController,
+  continuation: GoalContinuation,
+  sessionID: string,
+  rawArgs: string,
+): Promise<string> {
+  const parsed = parseGoalCommand(rawArgs)
+  switch (parsed.kind) {
+    case "set": {
+      await controller.setGoal(sessionID, parsed.objective)
+      // 新目标 = 全新开始：清掉旧会话残留的打断/超长/余额锁死标志。
+      continuation.resetRunState(sessionID)
+      return `Goal set: ${parsed.objective}`
+    }
+    case "pause": {
+      const goal = await controller.pauseGoal(sessionID)
+      return goal !== null ? `Goal paused. Current goal: ${goal.objective}` : "No active goal"
+    }
+    case "resume": {
+      const goal = await controller.resumeGoal(sessionID)
+      continuation.resetRunState(sessionID)
+      return goal !== null ? `Goal resumed. Current goal: ${goal.objective}` : "No active goal"
+    }
+    case "clear": {
+      const existed = await controller.clearGoal(sessionID)
+      return existed ? "Goal cleared" : "No active goal"
+    }
+    case "edit": {
+      const goal = await controller.getGoal(sessionID)
+      if (goal === null) return USAGE
+      return `Current goal: ${goal.objective}. Edit with /goal <new objective>.\n${USAGE}`
+    }
+    case "show": {
+      const goal = await controller.getGoal(sessionID)
+      if (goal === null) return "No active goal"
+      return `Goal (${goal.status}): ${goal.objective}`
+    }
+  }
+}
+
+/**
+ * 输入：插件上下文 + 控制器 + 续作控制器。
+ * 输出：注册 `/goal` 命令，返回注销句柄。
+ * 预期：命令本身不进对话流；执行后把反馈作为普通 prompt 发给当前会话。
+ */
+export async function registerGoalCommand(
+  ctx: Plugin.Context,
+  controller: GoalController,
+  continuation: GoalContinuation,
+): Promise<{ dispose(): Promise<void> }> {
+  const registration = await ctx.command.transform((editor) => {
+    editor.add({
+      name: "goal",
+      description: DESCRIPTION,
+      execute: async (input) => {
+        const settings = await loadSettings(ctx.storage)
+        const text =
+          settings.enabled && settings.goal.enabled
+            ? await applyGoalCommand(controller, continuation, input.sessionID, input.prompt.text)
+            : "Error: the goal feature is disabled in settings."
+        // /goal 只关心文本参数；附件不回传，避免把命令附件重复塞进会话。
+        await ctx.session.prompt({ sessionID: input.sessionID, text, delivery: input.delivery })
+      },
+    })
+  })
+  await ctx.command.reload()
+  return registration
+}

package/src/goal/continuation.ts

@@ -0,0 +1,211 @@
+import type { Plugin } from "@opencode/plugin"
+
+import { readEventData } from "../shared/events.ts"
+import type { PluginEvent } from "../shared/events.ts"
+import { asRecord, type JsonStore } from "../shared/json.ts"
+import { lastMessageIsUserInput } from "../shared/messages.ts"
+import { loadSettings } from "../shared/settings-store.ts"
+import type { GoalController } from "./controller.ts"
+import { classifyGoalFailure } from "./error.ts"
+import { buildContinuationPrompt } from "./prompts.ts"
+import type { SessionRoles } from "./session-role.ts"
+
+/** 注入消息的 metadata 标记，用于识别“这条 user 消息是我们发的”。 */
+const CONTINUATION_MARKER = "goalContinuation"
+
+/** 会话运行期锁死标志。 */
+type RunState = {
+  /** 用户打断过，暂停后需显式 resume。 */
+  wasCancelled: boolean
+  /** 上下文超长，等下一次模型活动自动解除。 */
+  tokenLimitDetected: boolean
+  /** 余额不足，只有显式 resume 才解除。 */
+  insufficientFundsDetected: boolean
+}
+
+/** 续作控制器。 */
+export type GoalContinuation = {
+  /** 输入：会话事件；输出：无。预期：按事件类型记账、续作或暂停。 */
+  handle(event: PluginEvent): Promise<void>
+  /** 输入：会话 ID；输出：无。预期：清除打断/超长/余额锁死与待确认注入。 */
+  resetRunState(sessionID: string): void
+}
+
+/**
+ * 输入：插件上下文、存储、目标控制器、可选时钟。
+ * 输出：续作控制器。
+ * 预期：只在 goal 处于 active 且未被锁死时注入续作；一次 idle 最多注入一条。
+ */
+export function createGoalContinuation(args: {
+  readonly ctx: Plugin.Context
+  readonly store: JsonStore
+  readonly controller: GoalController
+  readonly roles: SessionRoles
+  readonly now?: () => number
+}): GoalContinuation {
+  const { ctx, store, controller, roles } = args
+  const now = args.now ?? Date.now
+  const runStates = new Map<string, RunState>()
+  const pending = new Set<string>()
+  const inFlight = new Set<string>()
+  const lastAccountAt = new Map<string, number>()
+
+  /** 输入：会话 ID；输出：可变的运行状态。预期：不存在时创建默认值。 */
+  const stateOf = (sessionID: string): RunState => {
+    const existing = runStates.get(sessionID)
+    if (existing !== undefined) return existing
+    const created: RunState = { wasCancelled: false, tokenLimitDetected: false, insufficientFundsDetected: false }
+    runStates.set(sessionID, created)
+    return created
+  }
+
+  /** 输入：会话 ID；输出：设置是否允许续作。预期：总开关或 goal 开关关闭时不续作。 */
+  const enabled = async (): Promise<boolean> => {
+    const settings = await loadSettings(store)
+    return settings.enabled && settings.goal.enabled
+  }
+
+  /** 输入：会话 ID + token 增量；输出：无。预期：只对 active 目标记账。 */
+  const account = async (sessionID: string, tokens: number): Promise<void> => {
+    const at = now()
+    const last = lastAccountAt.get(sessionID)
+    const elapsedSeconds = last === undefined ? 0 : Math.max(0, Math.floor((at - last) / 1000))
+    lastAccountAt.set(sessionID, at)
+    if (tokens === 0 && elapsedSeconds === 0) return
+    await controller.accountUsage(sessionID, { tokens, elapsedSeconds })
+  }
+
+  /** 输入：会话 ID + 文本；输出：无。预期：注入一条带标记的续作提示；并发或失败时静默跳过。 */
+  const inject = async (sessionID: string, text: string): Promise<void> => {
+    if (inFlight.has(sessionID)) return
+    inFlight.add(sessionID)
+    try {
+      await ctx.session.prompt({ sessionID, text, delivery: "steer", metadata: { [CONTINUATION_MARKER]: true } })
+      pending.add(sessionID)
+    } catch {
+      // 注入失败：下一轮 idle 再试，不阻塞其他会话
+    } finally {
+      inFlight.delete(sessionID)
+    }
+  }
+
+  /**
+   * 输入：会话 ID。
+   * 输出：末条消息是否是真实用户输入。
+   * 预期：委托共享 helper，读不到消息时返回 false。
+   */
+  const userInputPending = (sessionID: string): Promise<boolean> =>
+    lastMessageIsUserInput(ctx, sessionID, CONTINUATION_MARKER)
+
+  /** 输入：会话 ID；输出：无。预期：active 且未锁死、且不是子代理时注入续作。 */
+  const handleIdle = async (sessionID: string): Promise<void> => {
+    if (!(await enabled())) return
+    // 子代理不续作：子代理的生命周期由主会话的工具调用驱动。
+    if (await roles.isSubagent(sessionID)) return
+
+    const state = stateOf(sessionID)
+    if (state.wasCancelled || state.tokenLimitDetected || state.insufficientFundsDetected) return
+
+    // 上一条续作注入后没有产生任何 step：说明模型没有接手，先跳过一次避免死循环。
+    if (pending.has(sessionID)) {
+      pending.delete(sessionID)
+      return
+    }
+
+    const goal = await controller.getGoal(sessionID)
+    if (goal?.status !== "active") return
+
+    // 末条是真实用户输入（上一条续作还没被回复）时跳过，避免叠加。
+    if (await userInputPending(sessionID)) return
+
+    await inject(sessionID, buildContinuationPrompt(goal))
+  }
+
+  /** 输入：会话 ID + 错误载荷；输出：无。预期：余额不足/超长锁死，其余只记录。 */
+  const handleFailure = async (sessionID: string, error: unknown): Promise<void> => {
+    if (!(await enabled())) return
+
+    const state = stateOf(sessionID)
+    const kind = classifyGoalFailure(error)
+    if (kind === "insufficient_funds") {
+      state.insufficientFundsDetected = true
+      await controller.pauseGoal(sessionID)
+      return
+    }
+    if (kind === "token_limit") {
+      state.tokenLimitDetected = true
+    }
+  }
+
+  /** 输入：会话 ID + 打断原因；输出：无。预期：用户打断时暂停目标。 */
+  const handleInterrupted = async (sessionID: string, reason: string): Promise<void> => {
+    if (reason !== "user") return
+    if (!(await enabled())) return
+    const state = stateOf(sessionID)
+    state.wasCancelled = true
+    await controller.pauseGoal(sessionID)
+  }
+
+  /** 输入：任意值；输出：本步消耗的 token 总数。预期：输入、输出、缓存读写都计入。 */
+  const readTokens = (raw: unknown): number => {
+    const record = asRecord(raw)
+    if (record === undefined) return 0
+    const cache = asRecord(record["cache"]) ?? {}
+    const parts = [record["input"], record["output"], cache["read"], cache["write"]]
+    let total = 0
+    for (const part of parts) {
+      if (typeof part === "number" && Number.isFinite(part) && part > 0) total += part
+    }
+    return total
+  }
+
+  return {
+    async handle(event) {
+      const data = readEventData(event)
+      if (data === undefined) return
+      const sessionID = data["sessionID"]
+      if (typeof sessionID !== "string" || sessionID.length === 0) return
+
+      switch (event.type) {
+        case "session.step.ended": {
+          // 模型活动：解除打断/超长锁死，并记账。
+          const state = stateOf(sessionID)
+          state.wasCancelled = false
+          state.tokenLimitDetected = false
+          pending.delete(sessionID)
+          if (!(await enabled())) return
+          await account(sessionID, readTokens(data["tokens"]))
+          return
+        }
+        case "session.idle":
+          await handleIdle(sessionID)
+          return
+        case "session.execution.failed":
+          await handleFailure(sessionID, data["error"])
+          return
+        case "session.execution.interrupted":
+          await handleInterrupted(sessionID, typeof data["reason"] === "string" ? data["reason"] : "")
+          return
+        case "session.deleted":
+          runStates.delete(sessionID)
+          pending.delete(sessionID)
+          inFlight.delete(sessionID)
+          lastAccountAt.delete(sessionID)
+          roles.forget(sessionID)
+          // 会话删了就把目标一起清掉，避免插件存储里留下永远读不到的 key。
+          await controller.clearGoal(sessionID)
+          return
+        default:
+          return
+      }
+    },
+
+    resetRunState(sessionID) {
+      const state = stateOf(sessionID)
+      state.wasCancelled = false
+      state.tokenLimitDetected = false
+      state.insufficientFundsDetected = false
+      pending.delete(sessionID)
+    },
+  }
+}

package/src/goal/controller.ts

@@ -0,0 +1,107 @@
+import type { JsonStore } from "../shared/json.ts"
+import { clearGoal, createGoal, nowSeconds, readGoal, setGoalStatus, writeGoal } from "./store.ts"
+import type { Goal } from "./types.ts"
+
+/** 同一阻塞原因连续出现多少次才判定为 blocked。 */
+export const BLOCKED_STREAK_REQUIRED = 3
+
+/** 一次记账的增量。 */
+export type GoalUsage = {
+  readonly tokens: number
+  readonly elapsedSeconds: number
+}
+
+/** 目标控制器：所有方法异步，读写都经过插件存储。 */
+export type GoalController = {
+  setGoal(sessionID: string, objective: string, tokenBudget?: number): Promise<Goal>
+  getGoal(sessionID: string): Promise<Goal | null>
+  pauseGoal(sessionID: string): Promise<Goal | null>
+  resumeGoal(sessionID: string): Promise<Goal | null>
+  clearGoal(sessionID: string): Promise<boolean>
+  markComplete(sessionID: string): Promise<Goal | null>
+  markBlocked(sessionID: string, reason: string): Promise<Goal | null>
+  accountUsage(sessionID: string, usage: GoalUsage): Promise<Goal | null>
+}
+
+/**
+ * 输入：插件存储。
+ * 输出：目标控制器。
+ * 预期：所有状态转换都落盘；不合法转换返回 `null` 或原目标，不抛异常。
+ */
+export function createGoalController(store: JsonStore): GoalController {
+  return {
+    async setGoal(sessionID, objective, tokenBudget) {
+      await clearGoal(store, sessionID)
+      const goal = await createGoal(store, sessionID, objective)
+      if (tokenBudget === undefined) return goal
+      const withBudget: Goal = { ...goal, tokenBudget }
+      await writeGoal(store, withBudget)
+      return withBudget
+    },
+
+    getGoal(sessionID) {
+      return readGoal(store, sessionID)
+    },
+
+    async pauseGoal(sessionID) {
+      // 只允许 active → paused：已 complete/blocked/budget_limited 的目标不覆写。
+      const existing = await readGoal(store, sessionID)
+      if (existing?.status !== "active") return null
+      return setGoalStatus(store, sessionID, "paused")
+    },
+
+    async resumeGoal(sessionID) {
+      const existing = await readGoal(store, sessionID)
+      if (existing === null) return null
+      if (existing.status === "active") return existing
+      return setGoalStatus(store, sessionID, "active")
+    },
+
+    clearGoal(sessionID) {
+      return clearGoal(store, sessionID)
+    },
+
+    markComplete(sessionID) {
+      return setGoalStatus(store, sessionID, "complete")
+    },
+
+    async markBlocked(sessionID, reason) {
+      const existing = await readGoal(store, sessionID)
+      if (existing === null) return null
+
+      const sameReason = existing.lastBlockedReason === reason
+      const streak = sameReason ? (existing.blockedStreak ?? 1) + 1 : 1
+      const status = streak >= BLOCKED_STREAK_REQUIRED ? "blocked" : existing.status
+      const updated: Goal = {
+        ...existing,
+        status,
+        lastBlockedReason: reason,
+        blockedStreak: streak,
+        updatedAt: nowSeconds(),
+      }
+      await writeGoal(store, updated)
+      return updated
+    },
+
+    async accountUsage(sessionID, usage) {
+      const goal = await readGoal(store, sessionID)
+      if (goal?.status !== "active") return goal
+
+      const tokenDelta = Math.max(0, usage.tokens)
+      const timeDelta = Math.max(0, usage.elapsedSeconds)
+      if (tokenDelta === 0 && timeDelta === 0) return goal
+
+      const nextTokens = goal.tokensUsed + tokenDelta
+      const budgetReached = goal.tokenBudget !== undefined && nextTokens >= goal.tokenBudget
+      const updated: Goal = {
+        ...goal,
+        tokensUsed: nextTokens,
+        timeUsedSeconds: goal.timeUsedSeconds + timeDelta,
+        updatedAt: nowSeconds(),
+        ...(budgetReached ? { status: "budget_limited" as const } : {}),
+      }
+      await writeGoal(store, updated)
+      return updated
+    },
+  }
+}