@synqa/cli 1.1.1 → 1.2.1

package/README.md

@@ -59,7 +59,66 @@ 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.
+- While an answer streams, the keyboard is locked: what you type is not echoed or kept. A tool call
+  that is still arriving (for example a large `write_file`) shows a live line such as
+  `⠋ write_file index.html · streaming 18.4 KB…`. Esc or Ctrl+C stops the request and returns to the
+  prompt; if a shell command is still running, press it a second time to leave. A tool call cut off
+  by the output limit is never run: the model is told to split the work into smaller files.
+
+## 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 +131,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 +170,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 +284,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 +322,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.
@@ -270,7 +333,9 @@ it. Use git for that.
 ## Develop
 
 From the repo root: `node --test 'cli/test/*.test.ts'` (or `npm test` inside `cli/`). Tests use fake
-`fetch`, fake terminals and temporary folders and never call the live API.
+`fetch`, fake terminals and temporary folders and never call the live API. `test/pty.test.ts` also
+runs the real CLI in a pseudo-terminal through a small Python driver (standard library only) with a
+throwaway home folder and no network; it skips with a message where Python or a PTY is missing.
 
 Sources are TypeScript run directly by Node (type stripping); only erasable syntax is allowed. Node
 will not strip types inside `node_modules`, so the published package ships plain JS: `npm run build`

package/dist/agent.js

@@ -1,6 +1,6 @@
 import { fenceText } from "./sanitize.js";
-import { chat, parseToolArguments } from "./api.js";
-                                                               
+import { AbortedError, chat } from "./api.js";
+                                                                             
 import { runTool, TOOL_DEFS } from "./tools.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,
@@ -40,6 +42,8 @@ export function systemPrompt(tier      , cwd        , notes         )         {
                                   
                                                           
                                                                       
+                                                                                  
+                                                                                       
   
 
                           
@@ -52,6 +56,16 @@ export function systemPrompt(tier      , cwd        , notes         )         {
                       
                      
                      
+                                                                              
+                                                                                         
+                    
+                                                                                 
+  
+
+// PreToolUse and PostToolUse hooks. pre returns a reason to block the tool, or undefined to run it.
+                         
+                                                                   
+                                                                      
   
 
                          
@@ -62,6 +76,44 @@ export function systemPrompt(tier      , cwd        , notes         )         {
                                                                                     
   
 
+// What the model is told when a tool call was cut off by the output limit. No provider or model
+// name, and no file content: only what to do next.
+export const CUT_OFF_RESULT =
+  "error: this tool call was cut off before its arguments were complete (the output limit was reached), so nothing was run and nothing was written. Split the work into smaller modular files (for example styles.css, app.js and index.html), one short tool call each, and do not repeat the large call.";
+
+// A different failure, a different message: the stream ended early (a dropped connection), not the
+// output limit. The call may be fine to try again as it was.
+export const CONNECTION_LOST_RESULT =
+  "error: the connection ended before this tool call was complete, so nothing was run and nothing was written. This is not a size problem: try the same call again.";
+
+export const CONNECTION_LOST_NOTICE = "connection lost before the response finished; no tool was run";
+
+                                                                                                                                  
+
+// Decides whether a streamed tool call can run. Its arguments must be complete JSON (an object).
+// Policy for finish_reason "length": the cap can only cut the last call, and a call whose JSON
+// parsed is complete (a string closed with its quote cannot hold a truncated file), so it runs
+// as usual; a call with no arguments at all is treated as cut off, because a tool that needs
+// arguments was begun and never filled. Anything that does not parse is never run, and its
+// arguments are stored as "{}" so the next request stays valid.
+// complete: false when the stream ended without [DONE] and without a finish_reason (a dropped
+// connection): then no call is trusted, whatever its arguments look like. Whatever the outcome,
+// `stored` is always a valid JSON object text, so the next request cannot be refused for it.
+export function checkCall(raw        , finishReason         , complete = true)            {
+  if (!complete) return { ok: false, stored: "{}", result: CONNECTION_LOST_RESULT };
+  if (raw.trim() === "") {
+    return finishReason === "length" ? { ok: false, stored: "{}", result: CUT_OFF_RESULT } : { ok: true, args: {}, stored: "{}" };
+  }
+  let v         ;
+  try {
+    v = JSON.parse(raw);
+  } catch {
+    return { ok: false, stored: "{}", result: CUT_OFF_RESULT };
+  }
+  if (!v || typeof v !== "object" || Array.isArray(v)) return { ok: false, stored: "{}", result: "error: tool arguments must be a JSON object" };
+  return { ok: true, args: v                           , stored: raw };
+}
+
 // Runs model -> tools -> model until the model answers without tool calls. Mutates history.
 export async function runAgent(o            )                     {
   const total        = { prompt: 0, completion: 0 };
@@ -75,14 +127,18 @@ export async function runAgent(o            )                     {
   let routing                = null;
   let lastUsage        = { prompt: 0, completion: 0 };
   for (let step = 0; step < MAX_STEPS; step++) {
+    if (o.signal?.aborted) throw new AbortedError();
     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,
       onText: o.events.onText,
+      onToolProgress: o.events.onToolProgress,
+      signal: o.signal,
       timeoutMs: o.timeoutMs,
       reasoningEffort: o.effort && o.effort !== "default" ? o.effort : undefined,
       now: o.now,
@@ -99,23 +155,37 @@ export async function runAgent(o            )                     {
       lastUsage = r.usage;
     }
     o.events.onTurn(r);
+    if (r.complete === false && r.toolCalls.length) o.events.onNotice?.(CONNECTION_LOST_NOTICE);
+    const checks = r.toolCalls.map((c) => checkCall(c.arguments, r.finishReason, r.complete !== false));
     const assistant          = { role: "assistant", content: r.content || null };
     if (r.toolCalls.length) {
-      assistant.tool_calls = r.toolCalls.map((c) => ({ id: c.id, type: "function", function: { name: c.name, arguments: c.arguments } }));
+      assistant.tool_calls = r.toolCalls.map((c, i) => ({ id: c.id, type: "function", function: { name: c.name, arguments: (checks[i]             ).stored } }));
     }
     o.history.push(assistant);
     if (!r.toolCalls.length) return result();
-    for (const c of r.toolCalls) {
-      o.events.onTool(c.name, c.arguments);
+    // Every call gets exactly one result, also when the person stops the run between calls.
+    for (const [i, c] of r.toolCalls.entries()) {
+      const check = checks[i]             ;
+      const shownArgs = check.stored;
+      o.events.onTool(c.name, shownArgs);
       let result        ;
-      try {
-        result = await runTool(o.ctx, c.name, parseToolArguments(c.arguments));
-      } catch (err) {
-        result = `error: ${err instanceof Error ? err.message : String(err)}`;
+      if (o.signal?.aborted) {
+        result = "error: stopped by the user before this tool ran";
+      } else if (!check.ok) {
+        result = check.result;
+      } else {
+        try {
+          const blocked = await o.hooks?.pre(c.name, c.arguments);
+          result = blocked !== undefined ? `blocked by a hook: ${blocked}` : await runTool(o.ctx, c.name, check.args);
+          if (blocked === undefined) await o.hooks?.post(c.name, c.arguments, result);
+        } catch (err) {
+          result = `error: ${err instanceof Error ? err.message : String(err)}`;
+        }
       }
-      o.events.onToolResult?.(c.name, c.arguments, result);
+      o.events.onToolResult?.(c.name, shownArgs, result);
       o.history.push({ role: "tool", tool_call_id: c.id, content: result });
     }
+    if (o.signal?.aborted) throw new AbortedError();
   }
   o.events.onText("\n[stopped: step limit reached]\n");
   return result();

package/dist/api.js

@@ -14,14 +14,42 @@ import { REQUEST_TIMEOUT_MS, MAX_OUTPUT_TOKENS, usageFrom } from "./tiers.js";
                          
                                                                
                                                                   
+                                                                                                    
+                                                                                                                
   
 
-                                                                   
+                                                                                                                    
+
+// What the terminal shows while a tool call is still streaming in.
+                            
+                                                        
+               
+                                                  
+                                                                          
+  
+
+const PATH_SCAN_CHARS = 4096;
+
+// The "path" argument out of a possibly cut-off JSON object. Only a string whose closing quote has
+// arrived counts, so a half-received path is never shown. A "path" key inside another string value
+// is escaped there (\"path\"), so it cannot match.
+export function partialPath(raw        )                     {
+  const m = /"path"\s*:\s*"((?:[^"\\]|\\.)*)"/.exec(raw);
+  if (!m) return undefined;
+  try {
+    const v = JSON.parse(`"${m[1]}"`);
+    return typeof v === "string" && v !== "" ? v : undefined;
+  } catch {
+    return undefined;
+  }
+}
 
 // Folds streamed chunks into text and complete tool calls.
 export class StreamAccumulator {
   content = "";
   usage                   ;
+  finishReason                    ;
+  onToolProgress                                         ;
           calls = new Map                     ();
 
   push(chunk     )         {
@@ -32,14 +60,27 @@ export class StreamAccumulator {
       text = delta.content;
       this.content += text;
     }
+    if (typeof choice?.finish_reason === "string") this.finishReason = choice.finish_reason;
     if (delta && Array.isArray(delta.tool_calls)) {
       for (const tc of delta.tool_calls) {
         const idx = typeof tc.index === "number" ? tc.index : 0;
-        const cur = this.calls.get(idx) ?? { id: "", name: "", arguments: "" };
+        const cur = this.calls.get(idx) ?? { id: "", name: "", arguments: "", bytes: 0 };
         if (tc.id) cur.id = tc.id;
         if (tc.function?.name) cur.name += tc.function.name;
-        if (typeof tc.function?.arguments === "string") cur.arguments += tc.function.arguments;
+        if (typeof tc.function?.arguments === "string") {
+          cur.arguments += tc.function.arguments;
+          cur.bytes += Buffer.byteLength(tc.function.arguments);
+        }
         this.calls.set(idx, cur);
+        if (this.onToolProgress && cur.name) {
+          // The path is looked for only near the start and only until it is found, so a 60 KB
+          // argument string is not rescanned on every chunk.
+          if (cur.path === undefined && !cur.scanned) {
+            cur.path = partialPath(cur.arguments.slice(0, PATH_SCAN_CHARS));
+            if (cur.arguments.length >= PATH_SCAN_CHARS) cur.scanned = true;
+          }
+          this.onToolProgress({ index: idx, name: cur.name, bytes: cur.bytes, path: cur.path });
+        }
       }
     }
     const u = usageFrom(chunk?.usage);
@@ -66,7 +107,7 @@ export function parseToolArguments(raw        )                          {
 }
 
 // Parses an SSE byte stream into JSON events; "[DONE]" ends it.
-export async function* sseEvents(body                           )                      {
+export async function* sseEvents(body                           , state                    )                      {
   const dec = new TextDecoder();
   let buf = "";
   for await (const part of body) {
@@ -77,7 +118,7 @@ export async function* sseEvents(body                           )
       buf = buf.slice(nl + 1);
       if (!line.startsWith("data:")) continue;
       const data = line.slice(5).trim();
-      if (data === "[DONE]") return;
+      if (data === "[DONE]") { if (state) state.done = true; return; }
       if (data) yield JSON.parse(data);
     }
   }
@@ -141,20 +182,34 @@ export async function checkKey(apiKey        , fetchFn            = fetch)
                       
                    
                       
+                                                                            
                                
+                                                                                                           
+                                                           
                      
                                                                     
                                                           
   
 
+// Thrown when the person aborts a request; not a failure to report as an error.
+export class AbortedError extends Error {
+  constructor() {
+    super("interrupted");
+    this.name = "AbortedError";
+  }
+}
+
 export async function chat(o             )                      {
   const fetchFn = o.fetchFn ?? fetch;
   const now = o.now ?? (() => performance.now());
   const t0 = now();
   const ac = new AbortController();
   const timer = setTimeout(() => ac.abort(), o.timeoutMs ?? REQUEST_TIMEOUT_MS);
+  const onUserAbort = () => ac.abort();
+  if (o.signal?.aborted) { clearTimeout(timer); throw new AbortedError(); }
+  o.signal?.addEventListener("abort", onUserAbort, { once: true });
   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({
@@ -171,8 +226,10 @@ export async function chat(o             )                      {
     if (!res.ok) throw new ApiError(res.status, friendlyStatus(res.status, res.status === 401 ? "" : await detailOf(res)));
     if (!res.body) throw new ApiError(res.status, "the service sent an empty answer");
     const acc = new StreamAccumulator();
+    acc.onToolProgress = o.onToolProgress;
     let firstAt                    ;
-    for await (const ev of sseEvents(res.body                                        )) {
+    const sseState = { done: false };
+    for await (const ev of sseEvents(res.body                                        , sseState)) {
       const t = acc.push(ev);
       if (firstAt === undefined && acc.hasOutput()) firstAt = now();
       if (t && o.onText) o.onText(t);
@@ -183,14 +240,18 @@ export async function chat(o             )                      {
       toolCalls: acc.toolCalls(),
       usage: acc.usage,
       routing: res.headers.get("x-synqa-routing"),
+      finishReason: acc.finishReason,
+      complete: sseState.done || acc.finishReason !== undefined,
       ttftMs: firstAt === undefined ? undefined : firstAt - t0,
       genMs: firstAt === undefined ? undefined : end - firstAt,
     };
   } catch (err) {
+    if (o.signal?.aborted) throw new AbortedError();
     if (ac.signal.aborted) throw new Error("request timed out");
     throw err;
   } finally {
     clearTimeout(timer);
+    o.signal?.removeEventListener("abort", onUserAbort);
   }
 }