ModApi: Persistence, Model & Account API

Feature Description

Disclaimer: This message was synthesized by an AI from a long, unstructured Markdown file of notes accumulated while building real mods. Use cases have been kept intentionally simple and generic. If anything seems off or incoherent, feel free to ask for clarification.

1. cmd.globalStore — cross-session key-value store

Problem: There is no way to persist data across sessions without writing a raw JSON file via cmd.exec("bash -c 'cat > ...'"). This works but it's a workaround, not an API.

Use case: Any mod that wants to remember something between sessions (counters, preferences, history) currently has to manage raw files manually.

await cmd.globalStore.set("total-count", 42);
await cmd.globalStore.get("total-count");

---

2. cmd.getAvailableModels() — machine-readable model list

Problem: The /model command shows model display names, but those don't match the IDs the API actually accepts. There's no way for a mod to programmatically get the list of valid model identifiers to use with cmd.setModel().

Use case: Any mod that needs to switch or list available models has no reliable source of truth for valid model IDs.

---

3. Per-model pricing exposed to mods

Problem: No way to get input/output cost per token from within a mod. Mods that track or estimate cost have to hardcode price tables manually and keep them up to date themselves.

Use case: Any mod that tracks or displays cost information needs access to current pricing without maintaining its own hardcoded table.

---

4. cmd.usage — cumulative session usage

Problem: The model_request_end event gives per-turn token usage, but there's no way to access cumulative usage for the current session from a mod.

Use case: Any mod that wants to display total session cost or token count needs to accumulate this manually from individual events rather than reading it from a single source.

---

5. cmd.account.plan — current user plan

Problem: No way for a mod to know what plan the user is on.

Use case: A mod that wants to adapt its behavior based on available resources or limits currently has no way to query this.

---

6. cmd.openBrowser() / cmd.openFile() — cross-platform helpers

Problem: Opening a file or URL from a mod requires cmd.exec({ command: 'open', args: [path] }), which is macOS-only and not part of the official API.

Use case: Any mod that generates output and wants to open it for the user should be able to do so cross-platform.

await cmd.openFile('/path/to/report.html');
await cmd.openBrowser('http://localhost:3000');

---

7. Programmatic sub-agents from a mod

Problem: Only the model can launch sub-agents via the agent tool. A mod has no way to orchestrate parallel workers or delegate work to a dedicated sub-agent.

Use case: A mod that needs to run background analysis or parallel processing on independent sub-tasks currently has no API path to do so.

const result = await cmd.runSubagent({
  model: "haiku",
  prompt: "Analyze this file",
  tools: ["read_file"],
  timeout: 30_000,
});

Use Case

No response

Additional Context

No response

How important is this to you?

None

此 issue 未列出原始檔案、測試或進入點。先找出現有的 mod 指令 API 及其測試，然後分別釐清並界定所要求的七項能力範圍；done 應由每個 API 的明確驗收標準定義，包括持久化、模型與帳戶資料、平台輔助函式，以及子代理行為。