ModApi: Persistence, Model & Account API

Issue không nêu tên tệp mã nguồn, test hoặc entry point nào. Hãy bắt đầu bằng cách xác định API của lệnh mod hiện có và các test của nó, sau đó làm rõ và xác định phạm vi riêng cho bảy khả năng được yêu cầu; trạng thái „done“ phải được xác định bằng các tiêu chí chấp nhận rõ ràng cho từng API, bao gồm persistence, dữ liệu model và account, các platform helper và hành vi của sub-agent.

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