@synqa/cli 1.1.1 → 1.2.0

package/README.md

@@ -59,7 +59,61 @@ From a checkout of this repo (for development): `npm link ./cli`.
 2. Paste your `synqa_live_...` key (typing is hidden). It is checked against the Synqa API and
    saved to `~/.config/synqa/config.json` (file mode 0600).
 
-Or skip login and set `SYNQA_API_KEY` in your shell. The variable wins over the saved key.
+Or set `SYNQA_API_KEY` in your shell. A key saved by `synqa login` or `/login` wins over the variable,
+so you never need to unset it; pass `--env-key` to make the variable win for one run.
+
+Starting `synqa` in a terminal with no valid Synqa key shows the welcome screen and asks for the key
+first (typing shows `••••`, the key is checked at `https://api.synqa.ca/v1/account`). Chat and every
+other provider stay locked until you are signed in to Synqa Cloud.
+
+## Providers
+
+After you sign in, `/provider` (or `/login`) opens an arrow-key menu: Synqa Cloud (primary),
+OpenCode Go, OpenCode Zen, OpenRouter (bring your own `sk-or-...` key) and a custom
+OpenAI-compatible endpoint. Keys for the others are typed masked, checked with `GET /v1/models` and
+saved in the same private config file (mode 0600 on macOS and Linux; Windows ignores the mode). The
+active provider and model show in the header and the footer. `/logout` offers to leave the secondary
+provider or to log out fully, which clears the Synqa key (and `SYNQA_API_KEY` in this process) and
+returns to the sign-in prompt. Use `OPENCODE_API_KEY` or the router's key variable as a fallback when
+nothing is saved.
+
+## Keys and modes
+
+- `/` opens the command list under the prompt: Up/Down move, Tab fills, Enter runs, Esc closes.
+- `/model`, `/effort`, `/provider`, `/login`, `/logout` and `/hooks` with no argument open an inline
+  Up/Down list (Enter selects, Esc cancels).
+- Shift+Tab cycles the permission mode: `ask before edits`, `auto-accept edits` (file edits in the
+  workspace apply without a question, like `--yes`; shell commands still ask) and `plan only` (no
+  file is written and no command is run). The mode shows in the footer.
+
+## Hooks
+
+`.synqa/hooks.json` in a project and `hooks.json` in the user config folder can run shell commands at
+`SessionStart`, `PreToolUse`, `PostToolUse` and `Stop`:
+
+```json
+{ "hooks": { "PreToolUse": [ { "matcher": "write_file|edit_file", "command": "python check.py" } ] } }
+```
+
+The hook gets the event as JSON on stdin. A `PreToolUse` hook blocks the tool by exiting with code 2
+or printing `{"decision":"block","reason":"..."}`; other output is ignored. A command that starts
+with `python` runs with `python3` (or `py` on Windows) when `python` is not on PATH. Project hooks
+are repository content, so they start off: `/hooks` lists them and switches them on or off.
+
+### Hooks security
+
+- Project hooks start disabled. An approval is tied to the project path and the exact entry
+  (command, matcher and timeout): a different folder or any edit to the entry needs a new approval.
+- The hook payload includes the tool input and result (up to 4000 characters each), so a hook sees
+  file contents and command output.
+- Never point a hook at a file the agent can write: the agent could rewrite the script that runs next.
+- In plan only mode the `PostToolUse` and `Stop` hooks do not run.
+
+## Updates
+
+On start `synqa` asks the npm registry once, with a 1.5 second limit and no error message, whether a
+newer `@synqa/cli` exists, and shows a quiet hint in the footer. `/update` runs
+`npm install -g @synqa/cli@latest`. Set `SYNQA_NO_UPDATE_CHECK=1` to skip the check.
 
 ## Use
 
@@ -72,14 +126,18 @@ Or skip login and set `SYNQA_API_KEY` in your shell. The variable wins over the
   shell command while an `AGENTS.md` is loaded, and shell commands that name a secrets file or a glob that could.
   Diffs are still shown.
 - `synqa --model sonata` : start on another tier (`blink`, `sonata`, `aeon`).
-- `synqa --effort low` : start with a reasoning effort (`default`, `low`, `medium`).
+- `synqa --effort low` : start with a reasoning effort (`default`, `low`, `medium`, `high`).
 
 ## Slash commands
 
 | Command | What it does |
 |---|---|
-| `/model blink\|sonata\|aeon` | Switch tier. With no argument it shows the current one. |
-| `/effort default\|low\|medium` | Set the reasoning effort. `default` sends no effort setting. |
+| `/model blink\|sonata\|aeon` | Choose the model. With no argument an arrow-key list opens: Blink 5.5, Sonata 6.0, Aeon 6.5 on Synqa Cloud, the provider's own model list otherwise. |
+| `/effort default\|low\|medium\|high` | Set the reasoning effort (arrow-key list with no argument). `default` sends no effort setting. |
+| `/provider`, `/login` | Pick Synqa Cloud, OpenCode Go, OpenCode Zen, OpenRouter or a custom endpoint. |
+| `/logout` | Leave the secondary provider, or log out fully and lock the session. |
+| `/hooks` | List hooks and switch them on or off. |
+| `/update` | Install the latest `@synqa/cli`. |
 | `/status` | Tier, routing, session tokens, context use of the last request, and your live credit and weekly pool balance. |
 | `/init` | Scan the project and write a starter `AGENTS.md`. |
 | `/compact` | Ask the model to summarize the conversation and continue from the summary, to save context. |
@@ -107,7 +165,7 @@ The balance lookup waits at most 2 seconds; if it fails the note says `balance u
   ▄▄▄▀ ▀▄▄█ █  █ ▀▄▄█ ▀▄▄█ ▄
        ▄▄▄▀         █
 
-  v1.1.1 · Blink 5.5 · default effort
+  v1.2.0 · Blink 5.5 · default effort
   ~/synqa-test
   ⎿ no AGENTS.md yet: /init writes one
   ⎿ $9.98 credit · weekly pool $4.00 of $10.00
@@ -221,7 +279,7 @@ it. Use git for that.
 
 | Name | Meaning |
 |---|---|
-| `SYNQA_API_KEY` | Your key; wins over the saved one (the start screen says so, and `synqa login` warns when it differs from the key you just saved). Never passed to commands the agent runs. |
+| `SYNQA_API_KEY` | Your key. A key saved by `synqa login` or `/login` wins over it unless you pass `--env-key`. Never passed to commands the agent runs. |
 | `NO_COLOR` | Any non-empty value turns colour off. |
 | `~/.config/synqa/config.json` | Saved key and default tier (mode 0600). |
 
@@ -259,8 +317,8 @@ it. Use git for that.
 
 - `No API key`: run `synqa login` or set `SYNQA_API_KEY`.
 - `Your API key was rejected`: run `synqa login` again, or check on the dashboard that the key is
-  active. If `SYNQA_API_KEY` is set in your shell, that key is used instead of the saved one: remove it
-  (`unset SYNQA_API_KEY`, and the line in `~/.zshrc`).
+  active. A key saved with `/login` is used before `SYNQA_API_KEY`; `/logout` then `Full logout` clears
+  both in the running session.
 - `synqa login` checks the key against the same key check the chat uses, and refuses a key with no
   chat access.
 - `request timed out`: a request is cut off after 10 minutes.

package/dist/agent.js

@@ -13,7 +13,7 @@ export const MAX_NOTES_CHARS = 8000;
 // from a third party (a cloned repo), so it goes in a delimited block as data: conventions only,
 // never an instruction source. fenceText removes invisible characters and neutralizes every "<", so
 // nothing inside can open or close the block.
-export function systemPrompt(tier      , cwd        , notes         )         {
+export function systemPrompt(tier      , cwd        , notes         , external = false)         {
   const body = fenceText(notes ?? "", MAX_NOTES_CHARS);
   const extra = body
     ? [
@@ -26,8 +26,10 @@ export function systemPrompt(tier      , cwd        , notes         )         {
     ]
     : [];
   return [
-    `You are Synqa-${tier.display}, a terminal coding agent made by Synqa.`,
-    "If asked what model you are or who created you, say you are Synqa and name your tier; say nothing else about what runs inside.",
+    external
+      ? "You are the Synqa terminal coding agent, running on a model provider the user chose. If asked who created this tool, say Synqa."
+      : `You are Synqa-${tier.display}, a terminal coding agent made by Synqa.`,
+    ...(external ? [] : ["If asked what model you are or who created you, say you are Synqa and name your tier; say nothing else about what runs inside."]),
     `Working directory: ${cwd}. File tools cannot leave it.`,
     "Use the tools to read, search and change files and to run commands. Make small, correct changes and say briefly what you did.",
     ...extra,
@@ -52,6 +54,15 @@ export function systemPrompt(tier      , cwd        , notes         )         {
                       
                      
                      
+                                                                              
+                                                                                         
+                    
+  
+
+// PreToolUse and PostToolUse hooks. pre returns a reason to block the tool, or undefined to run it.
+                         
+                                                                   
+                                                                      
   
 
                          
@@ -78,7 +89,8 @@ export async function runAgent(o            )                     {
     o.events.onRequest?.();
     const r = await chat({
       apiKey: o.apiKey,
-      model: o.tier.id,
+      model: o.modelId ?? o.tier.id,
+      baseUrl: o.baseUrl,
       messages: o.history,
       tools: TOOL_DEFS,
       fetchFn: o.fetchFn,
@@ -109,7 +121,9 @@ export async function runAgent(o            )                     {
       o.events.onTool(c.name, c.arguments);
       let result        ;
       try {
-        result = await runTool(o.ctx, c.name, parseToolArguments(c.arguments));
+        const blocked = await o.hooks?.pre(c.name, c.arguments);
+        result = blocked !== undefined ? `blocked by a hook: ${blocked}` : await runTool(o.ctx, c.name, parseToolArguments(c.arguments));
+        if (blocked === undefined) await o.hooks?.post(c.name, c.arguments, result);
       } catch (err) {
         result = `error: ${err instanceof Error ? err.message : String(err)}`;
       }

package/dist/api.js

@@ -141,6 +141,7 @@ export async function checkKey(apiKey        , fetchFn            = fetch)
                       
                    
                       
+                                                                            
                                
                      
                                                                     
@@ -154,7 +155,7 @@ export async function chat(o             )                      {
   const ac = new AbortController();
   const timer = setTimeout(() => ac.abort(), o.timeoutMs ?? REQUEST_TIMEOUT_MS);
   try {
-    const res = await fetchFn(`${API_BASE}/chat/completions`, {
+    const res = await fetchFn(`${(o.baseUrl ?? API_BASE).replace(/\/+$/, "")}/chat/completions`, {
       method: "POST",
       headers: { authorization: `Bearer ${o.apiKey}`, "content-type": "application/json" },
       body: JSON.stringify({

package/dist/commands.js

@@ -13,6 +13,15 @@ import { sanitize } from "./sanitize.js";
 import { groupDigits } from "./statusbar.js";
                                                   
 import { CONTEXT_TOKENS, EFFORTS, findEffort, findTier, TIERS } from "./tiers.js";
+import { MODE_LABEL } from "./modes.js";
+                                                 
+import { describeHook } from "./hooks.js";
+                                       
+import { fetchModelIds, logout, modelItems, providerDef, providerMenu } from "./providers.js";
+                                                                              
+import { API_BASE, saveProvider } from "./config.js";
+import { sanitizeModelId } from "./sanitize.js";
+                                            
                                                       
                                         
 import { renderHelp, SLASH_HELP, unknownCommandHint } from "./prompt.js";
@@ -32,6 +41,10 @@ import { renderHelp, SLASH_HELP, unknownCommandHint } from "./prompt.js";
                      
                                                                               
                                                             
+                                                                         
+                                   
+                                                                                          
+                                                                       
   
 
                          
@@ -41,12 +54,23 @@ import { renderHelp, SLASH_HELP, unknownCommandHint } from "./prompt.js";
                                                                         
                       
                      
+                                                                                                  
+                                                                                      
+                                                                           
+                                                                        
+                                                                                                 
+                                
+                                                                      
+                                                                        
   
 
-                                                                 
+// relogin: a full logout locked the session; the caller shows the sign-in prompt again.
+                                                                                    
 
 export { SLASH_HELP };
 
+export const isExternal = (st              )          => (st.providerId ?? "synqa") !== "synqa";
+
 export function statusParts(st              )              {
   return {
     tier: st.tier,
@@ -62,7 +86,7 @@ export function statusParts(st              )              {
 export function systemMessage(st              , tier       = st.tier)          {
   const notes = loadNotes(st.cwd);
   st.notesChars = notes.length;
-  return { role: "system", content: systemPrompt(tier, st.cwd, notes) };
+  return { role: "system", content: systemPrompt(tier, st.cwd, notes, isExternal(st)) };
 }
 
 export function freshHistory(st              )            {
@@ -81,12 +105,15 @@ const errText = (err         ) => sanitize(err instanceof Error ? err.message :
 async function cmdStatus(st              , io           )                {
   const u = st.total;
   io.print([
-    `Tier      ${st.tier.display} (${st.tier.id})`,
+    isExternal(st) ? `Provider  ${providerDef(st.providerId          )?.name ?? "custom"}, model ${sanitize(st.modelId ?? "?")}` : `Tier      ${st.tier.display} (${st.tier.id})`,
+    `Mode      ${MODE_LABEL[st.mode ?? "ask"]}`,
     `Routing   ${st.routing}`,
     `Effort    ${st.effort}`,
     `Session   ${groupDigits(u.prompt + u.completion)} tokens (${groupDigits(u.prompt)} in, ${groupDigits(u.completion)} out)`,
     st.last.prompt > 0 ? `Context   ${groupDigits(st.last.prompt)} of ${groupDigits(CONTEXT_TOKENS)} used by the last request` : "Context   no request yet",
   ].join("\n"));
+  // The balance belongs to Synqa Cloud: a secondary provider's key is never sent there.
+  if (isExternal(st)) return;
   const r = await fetchAccount(st.apiKey, io.fetchFn);
   io.print(r.ok ? formatAccount(r.account).join("\n") : `Balance   unavailable: ${sanitize(r.message)}`);
 }
@@ -113,7 +140,7 @@ async function cmdCompact(st              , io           )                {
   if (st.history.length <= 1) { io.print("Nothing to compact yet."); return; }
   io.print("Compacting the conversation...");
   try {
-    const r = await compactHistory({ apiKey: st.apiKey, tier: st.tier, history: st.history, effort: st.effort, fetchFn: io.fetchFn, now: io.now });
+    const r = await compactHistory({ apiKey: st.apiKey, tier: st.tier, baseUrl: st.baseUrl, modelId: st.modelId, history: st.history, effort: st.effort, fetchFn: io.fetchFn, now: io.now });
     st.history = r.history;
     if (r.usage) {
       st.total = { prompt: st.total.prompt + r.usage.prompt, completion: st.total.completion + r.usage.completion };
@@ -124,6 +151,93 @@ async function cmdCompact(st              , io           )                {
   }
 }
 
+// The provider helpers need the arrow-key controls; without a terminal they are unavailable.
+function providerIO(st              , io           )                         {
+  const { pick, secret, ask } = io;
+  if (!pick || !secret || !ask) return undefined;
+  return { print: io.print, pick, secret, ask, fetchFn: io.fetchFn, env: io.env, envKey: io.envKey };
+}
+
+const session = (st              )                  => {
+  st.providerId ??= "synqa";
+  st.baseUrl ??= API_BASE;
+  return st                                  ;
+};
+
+async function cmdModel(st              , io           , arg        )                {
+  if (!isExternal(st)) {
+    const t = arg ? findTier(arg) : undefined;
+    if (arg && !t) { io.print(`Choose one of: ${TIERS.map((x) => x.key).join(", ")}`); return; }
+    let chosen = t;
+    if (!arg) {
+      if (!io.pick) { io.print(`Tier is ${st.tier.display}. Choose one of: ${TIERS.map((x) => x.key).join(", ")}`); return; }
+      const key = await io.pick(modelItems("synqa"), "Choose a model");
+      if (key === undefined) { io.print("Cancelled."); return; }
+      chosen = findTier(key);
+    }
+    if (!chosen) return;
+    st.tier = chosen;
+    st.history[0] = systemMessage(st, chosen);
+    io.print(`Switched to ${chosen.display}.`);
+    return;
+  }
+  const id = st.providerId              ;
+  let model = arg ? sanitizeModelId(arg) : undefined;
+  if (!arg) {
+    if (!io.pick) { io.print(`Model is ${sanitize(st.modelId ?? "?")}. Pass a model id: /model <id>`); return; }
+    let fetched                      ;
+    try {
+      fetched = await fetchModelIds(st.baseUrl          , st.apiKey, io.fetchFn);
+    } catch {
+      fetched = undefined; // the curated defaults are offered instead
+    }
+    const items = modelItems(id, fetched);
+    if (items.length === 0) { io.print("No models to choose from. Pass a model id: /model <id>"); return; }
+    const initial = Math.max(0, items.findIndex((i) => i.value === st.modelId));
+    model = await io.pick(items.map((i, n) => ({ ...i, hint: n === initial ? "(current)" : undefined })), "Choose a model");
+    if (model === undefined) { io.print("Cancelled."); return; }
+  }
+  if (!model) { io.print("That is not a usable model id."); return; }
+  st.modelId = model;
+  try { saveProvider(id, { model }, io.env); } catch { /* the choice still applies to this session */ }
+  io.print(`Model set to ${model}.`);
+}
+
+async function cmdEffort(st              , io           , arg        )                {
+  if (!arg) {
+    if (!io.pick) { io.print(`Effort is ${st.effort}. Choose one of: ${EFFORTS.join(", ")}`); return; }
+    const e = await io.pick(EFFORTS.map((x) => ({ label: x, value: x, hint: x === st.effort ? "(current)" : undefined })), "Reasoning effort");
+    if (e === undefined) { io.print("Cancelled."); return; }
+    st.effort = e;
+    io.print(`Reasoning effort set to ${e}.`);
+    return;
+  }
+  const e = findEffort(arg);
+  if (!e) { io.print(`Choose one of: ${EFFORTS.join(", ")}`); return; }
+  st.effort = e;
+  io.print(`Reasoning effort set to ${e}.`);
+}
+
+async function cmdHooks(io           )                {
+  const hooks = io.hooks?.list() ?? [];
+  if (hooks.length === 0) {
+    io.print("No hooks. Add .synqa/hooks.json in the project (off until you switch it on here) or hooks.json in your Synqa config folder. Events: SessionStart, PreToolUse, PostToolUse, Stop.");
+    return;
+  }
+  if (!io.pick) { io.print(hooks.map(describeHook).join("\n")); return; }
+  const id = await io.pick(hooks.map((h) => ({ label: describeHook(h), value: h.id })), "Hooks: Enter toggles one");
+  if (id === undefined) return;
+  const now = io.hooks?.toggle(id);
+  io.print(now === undefined ? "No such hook." : `Hook is now ${now ? "on" : "off"}.`);
+}
+
+async function cmdUpdate(io           )                {
+  if (!io.update) { io.print("Update from a terminal: npm install -g @synqa/cli@latest"); return; }
+  io.print(io.update.latest ? `Updating ${io.update.current} to ${sanitize(io.update.latest)} ...` : "Running npm install -g @synqa/cli@latest ...");
+  const code = await io.update.run();
+  io.print(code === 0 ? "Updated. Restart synqa to use the new version." : `The update failed (exit ${code}). Run it yourself: npm install -g @synqa/cli@latest`);
+}
+
 export async function runCommand(line        , st              , io           )                         {
   const [first = "", ...args] = line.trim().split(/\s+/);
   // A first word like /usr/bin/foo is a path in a question, not a command.
@@ -141,23 +255,36 @@ export async function runCommand(line        , st              , io           )
       io.print("Conversation cleared.");
       announceNotes(st, io.print);
       break;
-    case "/model": {
-      if (!arg) { io.print(`Tier is ${st.tier.display}. Choose one of: ${TIERS.map((x) => x.key).join(", ")}`); break; }
-      const t = findTier(arg);
-      if (!t) { io.print(`Choose one of: ${TIERS.map((x) => x.key).join(", ")}`); break; }
-      st.tier = t;
-      st.history[0] = systemMessage(st, t);
-      io.print(`Switched to ${t.display}.`);
+    case "/model":
+      await cmdModel(st, io, arg);
+      break;
+    case "/effort":
+      await cmdEffort(st, io, arg);
+      break;
+    case "/provider":
+    case "/login": {
+      const pio = providerIO(st, io);
+      if (!pio) { io.print("This needs an interactive terminal."); break; }
+      if (await providerMenu(session(st), pio, arg)) {
+        st.history[0] = systemMessage(st);
+        io.print(isExternal(st) ? `Active: ${providerDef(st.providerId          )?.name} ${st.modelId ?? ""}`.trim() : `Active: Synqa Cloud ${st.tier.display}`);
+      }
       break;
     }
-    case "/effort": {
-      if (!arg) { io.print(`Effort is ${st.effort}. Choose one of: ${EFFORTS.join(", ")}`); break; }
-      const e = findEffort(arg);
-      if (!e) { io.print(`Choose one of: ${EFFORTS.join(", ")}`); break; }
-      st.effort = e;
-      io.print(`Reasoning effort set to ${e}.`);
+    case "/logout": {
+      const pio = providerIO(st, io);
+      if (!pio) { io.print("This needs an interactive terminal."); break; }
+      const out = await logout(session(st), pio);
+      if (out) st.history[0] = systemMessage(st);
+      if (out === "locked") return { handled: true, relogin: true };
       break;
     }
+    case "/hooks":
+      await cmdHooks(io);
+      break;
+    case "/update":
+      await cmdUpdate(io);
+      break;
     case "/status":
       await cmdStatus(st, io);
       break;

package/dist/compact.js

@@ -51,6 +51,8 @@ export const approxTokens = (history           )         => Math.ceil(JSON.strin
                               
                  
              
+                                                      
+                                       
                      
                   
                       
@@ -64,7 +66,8 @@ export async function compactHistory(o                )
   if (!text.trim()) throw new Error("nothing to compact");
   const r = await chat({
     apiKey: o.apiKey,
-    model: o.tier.id,
+    model: o.modelId ?? o.tier.id,
+    baseUrl: o.baseUrl,
     messages: [
       { role: "system", content: COMPACT_PROMPT },
       { role: "user", content: text },

package/dist/config.js

@@ -7,7 +7,17 @@ export const API_BASE = "https://api.synqa.ca/v1";
 export const ACCOUNT_URL = `${API_BASE}/account`;
 export const DASHBOARD_URL = "https://synqa.ca/client-dashboard";
 
-                                                        
+// A secondary provider the user chose themselves (OpenCode, a bring-your-own router key, a custom
+// endpoint). Keys live in the same private file as the Synqa key and never leave this machine
+// except to that provider's own base URL.
+                                                                                  
+                      
+                  
+                
+                                                                          
+                                            
+                                                                                                                      
+  
 
 export function configDir(env                                     = process.env)         {
   // SYNQA_CONFIG_DIR is honoured only under the node test runner (NODE_TEST_CONTEXT is set);
@@ -29,11 +39,21 @@ export function readConfig(env                                     = process.env
   }
 }
 
-// Directory 0700, file 0600, enforced even when they already existed with looser modes.
+// chmod does nothing useful on Windows file systems and may fail there: the mode is best effort
+// on win32 and enforced everywhere else.
+function tryChmod(path        , mode        , platform         = process.platform)       {
+  try {
+    chmodSync(path, mode);
+  } catch (err) {
+    if (platform !== "win32") throw err;
+  }
+}
+
+// Directory 0700, file 0600, enforced even when they already existed with looser modes (POSIX).
 export function writeConfig(config        , env                                     = process.env)         {
   const dir = configDir(env);
   mkdirSync(dir, { recursive: true, mode: 0o700 });
-  chmodSync(dir, 0o700);
+  tryChmod(dir, 0o700);
   const file = configPath(env);
   // The key is never written into a pre-existing file: create a fresh 0600 temp file ("wx"
   // fails if it exists) in the 0700 directory, then rename it over the target.
@@ -46,7 +66,7 @@ export function writeConfig(config        , env
     } finally {
       closeSync(fd);
     }
-    chmodSync(tmp, 0o600);
+    tryChmod(tmp, 0o600);
     renameSync(tmp, file);
     renamed = true;
   } finally {
@@ -56,11 +76,34 @@ export function writeConfig(config        , env
   return file;
 }
 
-// The env var wins over the saved key.
-export function resolveApiKey(env                                     = process.env)                     {
-  const fromEnv = env.SYNQA_API_KEY?.trim();
-  if (fromEnv) return fromEnv;
-  return readConfig(env).apiKey;
+// Since 1.2.0 a key saved by /login or synqa login wins over SYNQA_API_KEY, so nobody has to
+// unset a shell variable to use the key they just saved. The environment is the fallback when
+// nothing is saved, and wins only when the caller passes the explicit --env-key flag.
+export function resolveApiKey(env                                     = process.env, opts                       = {})                     {
+  const fromEnv = env.SYNQA_API_KEY?.trim() || undefined;
+  const saved = readConfig(env).apiKey?.trim() || undefined;
+  return opts.envKey ? fromEnv ?? saved : saved ?? fromEnv;
+}
+
+// The environment variable a secondary provider's key may come from.
+export const PROVIDER_ENV                         = {
+  "opencode-go": "OPENCODE_API_KEY",
+  "opencode-zen": "OPENCODE_API_KEY",
+  openrouter: "OPENROUTER_API_KEY",
+};
+
+// The same priority for a secondary provider.
+export function resolveProviderKey(id        , env                                     = process.env, opts                       = {})                     {
+  const name = PROVIDER_ENV[id];
+  const fromEnv = name ? env[name]?.trim() || undefined : undefined;
+  const saved = readConfig(env).providers?.[id]?.apiKey?.trim() || undefined;
+  return opts.envKey ? fromEnv ?? saved : saved ?? fromEnv;
+}
+
+// Merge-writes one secondary provider into the file.
+export function saveProvider(id        , entry               , env                                     = process.env)         {
+  const cfg = readConfig(env);
+  return writeConfig({ ...cfg, providers: { ...cfg.providers, [id]: { ...cfg.providers?.[id], ...entry } } }, env);
 }
 
 export function looksLikeKey(key        )          {