zames_pro 2.77.0 → 2.78.0

package/CHANGELOG.md

@@ -7,6 +7,26 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [2.78.0] - 2026-10-18
+
+### Added
+
+- **skills:** ship the methodology skills inside the package
+
+### Fixed
+
+- **fsutil:** remove the temp file when an atomic write fails
+
+## [2.77.1] - 2026-10-17
+
+### Fixed
+
+- **backlog:** only collapse real archive blocks, not notes that mention details
+- **qwen:** do not read a retry phrase in the answer as a rate limit
+- **web:** block IPv4-compatible IPv6 addresses in the SSRF guard
+- **sessions:** cap the input history when loading it
+- **sessions:** keep chat ids with unsafe characters in separate files
+
 ## [2.77.0] - 2026-10-17
 
 ### Added

package/dist/backlog.js

@@ -62,6 +62,20 @@ function isRealBoundary(line) {
 function isDetailsOpen(line) {
     return line.trim().startsWith('<details');
 }
+// An ARCHIVE block is a <details> that actually wraps the struck-through copy
+// of an item heading (`### X. ~~original~~`). A note that merely MENTIONS
+// `Use <details> in README:` must not be treated as an archive: collapsing it
+// deleted the note's own body (everything up to the next heading).
+function isArchiveBlock(lines, from) {
+    for (let j = from; j < lines.length; j++) {
+        const t = lines[j].trim();
+        if (isArchivedHeading(t))
+            return true;
+        if (t.startsWith('</details>') || isRealBoundary(t))
+            return false;
+    }
+    return false;
+}
 function isArchivedHeading(line) {
     return /^###\s+[A-Z]\d+[.]\s+~~/.test(line.trim());
 }
@@ -85,7 +99,8 @@ export function collapseBacklog(text) {
     let collapsed = 0;
     let i = 0;
     while (i < lines.length) {
-        if (isDetailsOpen(lines[i]) || isArchivedHeading(lines[i])) {
+        const archiveOpen = isDetailsOpen(lines[i]) && isArchiveBlock(lines, i + 1);
+        if (archiveOpen || isArchivedHeading(lines[i])) {
             // Skip to the end of the archive: the first `</details>` OR the first
             // real heading, whichever comes first (see the note above).
             let j = i + 1;

package/dist/context.js

@@ -2,6 +2,7 @@ import fs from 'fs/promises';
 import { statSync } from 'fs';
 import path from 'path';
 import os from 'os';
+import { fileURLToPath } from 'url';
 // Built-in skills, always available unless a project/global skill with the
 // same name overrides them (real files win). They give the agent proven,
 // reusable workflows in the spirit of Claude Code / Codex. English only (the
@@ -362,6 +363,20 @@ export async function loadSkills(workdir) {
         dir: path.join(os.homedir(), '.claude', 'skills'),
         source: 'global',
     });
+    // The skills SHIPPED with the package. In the installed layout they sit next
+    // to `dist/`; in a development checkout that path resolves INSIDE the repo
+    // (`src/../skills`), where the same skills also exist as files. The built-in
+    // copies (BUILTIN_SKILLS, appended below with an inline body) are the
+    // canonical ones — adding the files here would override them and break
+    // `/skill-name` expansion and the offline docs. So only add the directory when
+    // the module runs from the built `dist/` layout.
+    const moduleDir = path.dirname(fileURLToPath(import.meta.url));
+    if (!moduleDir.endsWith(path.sep + 'src')) {
+        roots.push({
+            dir: path.join(moduleDir, '..', 'skills'),
+            source: 'global',
+        });
+    }
     for (const root of roots) {
         const files = await findSkillFiles(root.dir);
         for (const f of files) {

package/dist/fsutil.js

@@ -20,15 +20,27 @@ export function writeFileAtomic(file, data) {
     // fsync the file BEFORE rename: without it a power loss can leave the
     // renamed name pointing at an empty/partial inode (rename itself is atomic,
     // but the data blocks may not have reached the disk yet).
-    const fd = fs.openSync(tmp, 'w', 0o600);
     try {
-        fs.writeFileSync(fd, data);
-        fs.fsyncSync(fd);
+        const fd = fs.openSync(tmp, 'w', 0o600);
+        try {
+            fs.writeFileSync(fd, data);
+            fs.fsyncSync(fd);
+        }
+        finally {
+            fs.closeSync(fd);
+        }
+        fs.renameSync(tmp, file);
     }
-    finally {
-        fs.closeSync(fd);
+    catch (e) {
+        // A failed write/fsync/rename (full disk, EIO, a directory in the way)
+        // must not leave the temp file behind: every failure used to accumulate a
+        // stray `<file>.tmp-<pid>` next to the real file.
+        try {
+            fs.unlinkSync(tmp);
+        }
+        catch { }
+        throw e;
     }
-    fs.renameSync(tmp, file);
     // fsync the DIRECTORY so the rename entry itself is durable.
     try {
         const dirFd = fs.openSync(path.dirname(file), 'r');

package/dist/qwen-net-capture.js

@@ -195,6 +195,12 @@ export function isFinishedWithoutAnswer(body) {
 }
 // True when the body carries Qwen's rate-limit / busy notice, so ask() can
 // back off instead of waiting out the deadline. Matched against the RAW body.
+// The classifier runs against the RAW body, so a phrase like `please try again
+// later` would also match a NORMAL answer (the model writing about retry
+// logic) and make ask() back off on a good turn. A real notice arrives in an
+// ERROR payload (`event: error` / `"type":"error"`) or as a code; answer text
+// lives in `choices[].delta.content`. We therefore only inspect the body when
+// it is NOT a plain answer stream, or when it carries no answer content.
 export function isRateLimitText(body) {
     const b = String(body || '');
     if (!b)
@@ -203,7 +209,42 @@ export function isRateLimitText(body) {
     // ("The service is currently experiencing high demand. Please try again
     // later.") — a TRANSIENT capacity limit, so it belongs with the rate-limit
     // family (back off and retry), not with the guest DAILY limit.
-    return /too many requests|rate limit|too frequent|please try again later|quota_limit|high demand|слишком часто/i.test(b);
+    if (/quota_limit/i.test(b))
+        return true;
+    if (/event:\s*error|"type"\s*:\s*"error"|"error"\s*:/i.test(b)) {
+        return /too many requests|rate limit|too frequent|please try again later|high demand|слишком часто/i.test(b);
+    }
+    // No structured error marker: only treat the body as a notice when it has
+    // NO answer content (a bare notice page/JSON).
+    if (hasAnswerContent(b))
+        return false;
+    return /too many requests|rate limit|too frequent|please try again later|high demand|слишком часто/i.test(b);
+}
+// True when the body carries actual answer text in an SSE/JSON chunk.
+function hasAnswerContent(body) {
+    for (const obj of parseDataLines(body)) {
+        const choices = obj.choices;
+        if (!Array.isArray(choices))
+            continue;
+        for (const ch of choices) {
+            if (!ch || typeof ch !== 'object')
+                continue;
+            const c = ch;
+            const delta = c.delta && typeof c.delta === 'object'
+                ? c.delta
+                : c.message && typeof c.message === 'object'
+                    ? c.message
+                    : null;
+            if (!delta)
+                continue;
+            if (isThinkingPhase(delta))
+                continue;
+            if (typeof delta.content === 'string' && delta.content.trim()) {
+                return true;
+            }
+        }
+    }
+    return false;
 }
 // The GUEST daily limit is a DIFFERENT failure from a transient rate limit:
 // Qwen answers `RateLimited` with "You've reached the guest chat limit for
@@ -221,5 +262,11 @@ export function isServerBusyText(body) {
     const b = String(body || '');
     if (!b)
         return false;
+    // Same rule as isRateLimitText: a normal ANSWER may mention "try again
+    // later"; only a structured error payload or a body with NO answer content
+    // can be a server-busy notice.
+    const errNotice = /event:\s*error|"type"\s*:\s*"error"|"error"\s*:/i.test(b);
+    if (!errNotice && hasAnswerContent(b))
+        return false;
     return /server is busy|service unavailable|try again later/i.test(b);
 }

package/dist/sessions.js

@@ -46,8 +46,21 @@ export function isInternalChat(id) {
 function ensureDir() {
     fs.mkdirSync(SESSIONS_DIR, { recursive: true });
 }
+// A chat id is used as a FILE NAME. Replacing every unsafe character with `_`
+// made two DIFFERENT ids collide on one file ('a/b' and 'a_b'), so the second
+// session overwrote the first and the other chat could not be resumed. Encode
+// the unsafe characters instead: `_` becomes `_5f` and every other unsafe byte
+// `_XX` (hex), which is injective and still path-safe.
 function safeName(id) {
-    return String(id).replace(/[^a-zA-Z0-9_.-]/g, '_');
+    const s = String(id);
+    let out = '';
+    for (const ch of s) {
+        if (/[a-zA-Z0-9.-]/.test(ch))
+            out += ch;
+        else
+            out += '_' + ch.codePointAt(0).toString(16).padStart(2, '0');
+    }
+    return out;
 }
 // Save/update a session. workdir is needed so that when launched from the same
 // project we restore exactly its last chat.
@@ -194,7 +207,11 @@ export function loadHistory() {
         const raw = JSON.parse(fs.readFileSync(HISTORY_FILE, 'utf-8'));
         if (!Array.isArray(raw))
             return [];
-        return raw.filter((x) => typeof x === 'string');
+        const list = raw.filter((x) => typeof x === 'string');
+        // Cap on LOAD as well: an old/hand-edited/merged file could exceed the
+        // limit, and the next save would write the whole array back out. Keep the
+        // most recent (tail) entries, matching saveHistory().
+        return list.length > HISTORY_LIMIT ? list.slice(-HISTORY_LIMIT) : list;
     }
     catch {
         return [];

package/dist/web.js

@@ -188,6 +188,26 @@ export function isPrivateIp(ip) {
     }
     if (low.startsWith('64:ff9b:'))
         return true;
+    // IPv4-COMPATIBLE form `::a.b.c.d` (deprecated, but the OS/HTTP stack still
+    // resolves it, so `http://[::127.0.0.1]/` reached localhost). `::` itself and
+    // `::1` are already handled above; `::ffff:…` was handled as MAPPED. Any
+    // other `::`-prefixed address whose tail is an embedded IPv4 belongs to the
+    // same family and must be judged by the embedded address.
+    const compat = low.match(/^::(?:ffff:)?(\d{1,3}\.\d{1,3}\.\d{1,3}\.\d{1,3})$/);
+    if (compat)
+        return isPrivateIp(compat[1]);
+    const compatHex = low.match(/^::([0-9a-f]{1,4}):([0-9a-f]{1,4})$/);
+    if (compatHex) {
+        const hi = parseInt(compatHex[1], 16);
+        const lo = parseInt(compatHex[2], 16);
+        return isPrivateIp(((hi >> 8) & 0xff) +
+            '.' +
+            (hi & 0xff) +
+            '.' +
+            ((lo >> 8) & 0xff) +
+            '.' +
+            (lo & 0xff));
+    }
     return false;
 }
 export function isPrivateHostname(host) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "zames_pro",
-  "version": "2.77.0",
+  "version": "2.78.0",
   "description": "Terminal coding agent that drives a real browser to chat with DeepSeek, Qwen and other web LLMs — no API key required. Reads and edits files, runs commands, commits to git, like Claude Code / Codex CLI.",
   "type": "module",
   "bin": {
@@ -8,6 +8,7 @@
   },
   "files": [
     "dist",
+    "skills",
     "scripts/postinstall.mjs",
     "README.md",
     "CHANGELOG.md",

package/skills/brainstorming/SKILL.md

@@ -0,0 +1,37 @@
+---
+name: brainstorming
+description: Use when the operator's request is a GOAL, not a spec — "add X", "make it better", "integrate Y" — and it is unclear what "done" means. Draws out the intent and plays it back before building.
+---
+
+# Brainstorming
+
+When a request is a goal ("add superpowers", "make scrolling feel right"),
+building immediately produces the wrong thing fast. First make the intent
+concrete.
+
+## What to pin down
+
+- **The real outcome.** What should be TRUE after this that is not true now?
+  Not the feature name — the result the operator wants to see.
+- **The acceptance check.** How will the operator know it works? "I open X
+  and Y happens." If neither of you can state this, the task is not ready.
+- **Scope edges.** What is explicitly NOT part of this (the operator often
+  has an opinion, e.g. "no button", "don't touch the existing code").
+- **The alternatives you considered** and why you chose one — a decision is
+  cheaper to correct before it is built.
+
+## The zames constraint (IMPORTANT)
+
+zames has NO conversational turn: the operator sees only your final `respond`
+and your tool calls, and a task is expected to make PROGRESS, not to ask
+questions and wait. So do the brainstorming yourself and return it as a
+SHORT, concrete proposal in ONE `respond`, instead of an interview:
+
+- state the goal as you understood it;
+- state your assumptions and the choices you made by default;
+- state what you will NOT do;
+- then either (a) proceed if the request was clearly actionable, or (b) stop
+  and ask the ONE decision you genuinely cannot make alone.
+
+For a request that is already precise ("read file X", "rename Y"), skip this
+entirely — brainstorming a one-line task wastes the operator's time.

package/skills/systematic-debugging/SKILL.md

@@ -0,0 +1,56 @@
+---
+name: systematic-debugging
+description: Use when something is broken and the cause is not obvious — a failing test, a wrong result, a hang, a crash. Four phases: reproduce, isolate, hypothesize, fix. Prevents guessing.
+---
+
+# Systematic debugging
+
+Do NOT start by editing code. Work through the four phases in order; each
+phase must produce an artifact you can point at.
+
+## Phase 1 — Reproduce (no fix yet)
+
+Get a command that FAILS the same way the operator describes it.
+
+- Run it. Copy the exact error/output into your reasoning.
+- If it passes, you do not have the bug yet: narrow the input until it fails,
+  or ask which steps differ.
+- A bug you cannot reproduce is a bug you cannot verify you fixed.
+
+## Phase 2 — Isolate (bisect, do not read blindly)
+
+Shrink the failure to the smallest unit that still fails.
+
+- Comment out / stub / binary-search the input space; each step doubles the
+  information you have.
+- Read the code that the failing path ACTUALLY executes — not the code you
+  remember writing.
+- Check the obvious causes FIRST: wrong file, stale build, cached state,
+  different config, an earlier error swallowed by a catch.
+
+## Phase 3 — Hypothesize (one at a time)
+
+State the hypothesis in one sentence and predict what you should see if it is
+right. Then test exactly that.
+
+- One change at a time; two changes at once prove nothing.
+- Prefer an observation (a log, a probe, a test assertion) over an edit.
+- If the prediction is wrong, the hypothesis is wrong — discard it, do not
+  "adjust" it to fit.
+
+## Phase 4 — Fix and verify
+
+- Fix the CAUSE, not the symptom. A guard added to hide a wrong value leaves
+  the wrong value in place.
+- Add a regression test that fails WITHOUT the fix and passes WITH it.
+- Re-run the Phase 1 reproduction verbatim.
+- Look for the same bug elsewhere (the same wrong assumption is usually not
+  in one place only).
+
+## Anti-patterns
+
+- Editing before reproducing.
+- "It works now" without knowing what changed.
+- Adding a try/catch or a null-check to silence an error you do not understand.
+- Trusting a green test you wrote against the FIXED code without ever seeing
+  it red.

package/skills/test-driven-development/SKILL.md

@@ -0,0 +1,34 @@
+---
+name: test-driven-development
+description: Use when writing or changing behaviour that can be tested — a bug fix, a new function, a parser, a formatter. Write the failing test first, watch it fail, then make it pass. Prevents tests that only pass because they were written against the finished code.
+---
+
+# Test-driven development
+
+RED → GREEN → REFACTOR. The order is the point, not a formality.
+
+## The cycle
+
+1. **RED** — write the smallest test that expresses the new behaviour and
+   RUN it. It must FAIL, and fail for the RIGHT reason ("not implemented",
+   not a typo or a missing import). A test you never saw fail proves nothing.
+2. **GREEN** — write the MINIMUM code that makes it pass. Do not add the
+   next feature "while you are there"; that code is untested.
+3. **REFACTOR** — clean up with the test green, and re-run it.
+
+## What makes a test good
+
+- It asserts BEHAVIOUR (input → output), not implementation detail.
+- It fails when the behaviour is wrong — verify this by breaking the code
+  on purpose once, if you are unsure.
+- It is deterministic: no sleeps, no network, no dependence on wall-clock
+  time or on the order other tests ran in.
+- One reason to fail, with a message that says what broke.
+
+## Rules in this project
+
+- A bug fix ALWAYS gets a regression test that reproduces the original bug.
+- When you fix a test to make it pass, ask whether the TEST was wrong or the
+  CODE was wrong; do not just move the assertion.
+- If the code was written before its test, delete and rewrite it driven by
+  the test — otherwise the test is shaped around the implementation.

package/skills/verification-before-completion/SKILL.md

@@ -0,0 +1,40 @@
+---
+name: verification-before-completion
+description: Use BEFORE declaring a task done or reporting success — a feature, a bug fix, a file you generated. Forces you to run the verification you promised instead of trusting that the code looks right.
+---
+
+# Verification before completion
+
+"It should work" is not done. Before you report success, produce EVIDENCE
+from the real artifact — not from your intent.
+
+## The checklist
+
+1. **Re-read the original request.** Every requirement, including the small
+   ones in a parenthetical. List them; tick each one against something you
+   can show.
+2. **Run the thing.** For code: build/typecheck/tests. For a script: run it.
+   For a generated file: open/parse it and confirm it is complete, not
+   truncated. For a UI: the real screen, not the diff.
+3. **Check the WHOLE file.** A generated file (HTML/JSON/config) is a common
+   silent failure: the head is there, the body/tail is missing or a
+   placeholder. Confirm the closing structure exists and the file runs.
+4. **Re-read your own diff** as a reviewer: leftover debug output, dead code,
+   a commented-out block, a wrong path, a test that asserts nothing.
+5. **State the evidence** in the final report — the exact command and its
+   result — so the operator can reproduce it. "Tests pass" without the
+   command is not evidence.
+
+## The two failure modes this prevents
+
+- **Partial delivery**: a game file with a scene but no game loop; a handler
+  that handles one case; a migration that covers one table. The operator runs
+  it, it is broken, and trust drops.
+- **Phantom fix**: the code changed, but the original reproduction was never
+  re-run, so nothing proves the bug is gone.
+
+## Rule
+
+If you cannot run the verification (no test, no runnable entry point), SAY SO
+explicitly and describe exactly what you did instead. Never report "done"
+while implying a verification you did not perform.

package/skills/writing-plans/SKILL.md

@@ -0,0 +1,40 @@
+---
+name: writing-plans
+description: Use when a task is large enough to need more than one or two tool calls — a multi-file change, a new feature, a refactor. Breaks the work into small ordered steps with exact paths and a verification for each.
+---
+
+# Writing plans
+
+A plan is a sequence of steps a careful engineer with NO project context
+could follow. If a step needs knowledge you have but did not write down, the
+plan is incomplete.
+
+## Shape of a good plan
+
+Each step is 2–5 minutes of work and names:
+
+- the EXACT file path(s) it touches;
+- what changes (the concrete edit, not "update the parser");
+- how to verify it (the command, the test name, the expected output).
+
+Order matters: put the step that DE-RISKS the task first (a spike, a failing
+test, a proof that the API works). Do not build three layers on an unverified
+assumption.
+
+## Rules
+
+- One concern per step. "Add the flag AND refactor the caller" is two steps.
+- Prefer a step that FAILS LOUDLY over a step that silently half-works.
+- Every behavioural change gets a test step (see test-driven-development);
+  write the failing test BEFORE the implementation step that satisfies it.
+- If you discover mid-plan that a step was wrong, STOP and revise the plan —
+  do not improvise the rest of it.
+- Keep the plan short enough to hold in your head; a 30-step plan is a sign
+  the task should be split.
+
+## In zames
+
+Because there is no separate plan file unless the operator asks for one, the
+plan lives in your reasoning and, for a long task, in a TodoWrite list — one
+entry per step, status updated as you go. Do not narrate the plan to the
+operator between tool calls; the todo list IS the visible plan.