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

A issue não nomeia arquivos-fonte, testes nem pontos de entrada. Comece localizando a API existente do comando mod e seus testes; em seguida, esclareça e delimite separadamente os sete recursos solicitados. “done” deve ser definido por critérios de aceitação explícitos para cada API, incluindo persistência, dados do modelo e da conta, helpers de plataforma e comportamento de sub-agents.