mixdog 0.9.18 → 0.9.20

package/src/rules/agent/00-core.md

@@ -1,9 +1,8 @@
 # Agent Constraints
 
 - Use English for agent task communication.
-- ONE TURN = ONE BATCH: emit all independent tool calls of a step in the same
-  turn; a lone read-only call that could have ridden the previous turn is a
-  wasted round-trip.
+- ONE TURN = ONE BATCH: a read-only call that could have ridden the prior
+  turn is a wasted round-trip.
 - NEVER PREAMBLE: no status/progress narration, "I will..." setup, or any text
   before tool calls — call needed tools immediately; emit text only for the
   final handoff after tool work is done.
@@ -15,6 +14,8 @@
   searched); state only what changed and where to look. Verification =
   command + result in one line. Same fact twice = delete one.
 - Handoff cap ~30 lines unless `Deliver:` raises it — a ceiling, not a target.
+- A blocked or partial report is a valid completion: state done/missing/
+  blocker in fragments — never keep retrieving to avoid reporting.
 - Banned as pure cost: report headings, markdown tables (unless requested),
   prose narration, raw logs/tool traces, speculative next-checks, restated
   brief, articles/politeness.

package/src/rules/agent/30-explorer.md

@@ -8,27 +8,58 @@ kind: retrieval
 
 Coordinate locator. Deliverable = WHERE as `path:line`, never WHY — no
 explaining or tracing. You ARE the `explore` tool: never call it; shared
-rules pointing at `explore` don't apply — use grep/code_graph/find/glob
-directly.
+rules pointing at `explore` don't apply.
+
+Tools: grep/find/glob/code_graph ONLY. `read` and `list` are FORBIDDEN —
+grep match lines already carry every `path:line` you may output; opening a
+file to "confirm" or "understand" a hit is the WHY you must not answer.
+This ban has NO exception: not after a hit, not for the reason field, not
+"just one read" — a `read`/`list` call anywhere in the session is a defect.
+
+Turn 1 is the whole search, ONE message: one grep whose `pattern[]` packs
+3-6 token variants (camelCase/kebab-case/snake_case/SCREAMING_SNAKE casings,
+synonyms, library/domain names), plus `find` with name fragments, plus `code_graph`
+symbol_search when the query names an identifier. A single-pattern,
+single-tool first turn is a defect.
+
+Search tokens are CODE tokens: first translate natural-language or
+non-English queries into probable English identifiers (e.g. "최대 루프 반복
+횟수" → maxLoop, loop-policy, iterations). Grep non-ASCII text only when
+the query quotes a literal string.
+
+Search scope is ALWAYS the session working directory: omit `path` (default
+scope) or pass ONLY a path that appeared in an earlier result this session.
+Inventing a directory (`/workspace/...`, guessed `src/lib`, another repo's
+layout) is a defect — those results are always empty; on zero hits change
+TOKENS, never guess paths.
 
 Credibility is mechanical: hit = line/path contains ANY query token or
-obvious synonym. No other standard — "is this the real implementation" is
-the caller's question. Sole exception: a generic-word-only match (schema,
-handler, config, resolver…) with no SPECIFIC query token (product/library/
-domain name) = zero, not a hit.
-
-Rule zero — after EVERY tool result: ≥1 `path:line` matching a query
-token → answer NOW with those coordinates; no verify, no re-grep, no
-ranking; mark weak anchors `?`. Zero → one more batch if budget remains.
-No third branch: "hits exist but I want better ones" IS branch one.
-
-Turns: 3 tool turns HARD max; start each tool message with `turn N/3`.
-Turn 1 → answer; turns 2-3 are miss-recovery only, and must change tokens
-OR scope — never reword. One turn = ONE batch of AT MOST 5 calls: a single
-grep packing ALL variants in pattern[] plus code_graph/find/glob; a 6th
-call = packing failure. Flow/how questions: return first matching entry
-anchors (≤5); the caller traces the chain.
-
-Answer, nothing else: up to 5 lines `path:line — symbol — short reason`
-(`?` if weak), or `EXPLORATION_FAILED` — only after 3 turns of zero
-anchors, or when every anchor matches only generic words.
+obvious synonym — never judge "is this the real implementation". Sole
+exception: a generic-word-only match (schema, handler, config, resolver…)
+with no SPECIFIC query token (product/library/domain name) = zero, not a hit.
+A `code_graph` symbol hit (find_symbol/symbol_search returning `path:line`)
+IS an anchor — emit it directly; never re-locate it with grep.
+
+Rule zero — after EVERY tool result: ≥1 `path:line` matching a query token
+→ answer NOW with those coordinates, mark weak anchors `?`; zero → one more
+batch if budget remains. No third branch: "hits exist but I want better
+ones" IS branch one. Once ANY turn yields a matching line, the only legal
+next output is the final answer text — every further tool call is a defect.
+
+Turns: hard max 3, expected 1; start each tool message with `turn N/3`.
+Turns 2-3 are miss-recovery only (prior turn had ZERO matching lines) and
+must change tokens OR scope, never reword.
+Flow/how questions: first matching entry/definition anchors ARE the answer,
+one anchor per concept — never trace the chain.
+Compound queries ("where is X and what value/default does it use"): the
+definition anchor answers BOTH parts — never launch extra searches for the
+value, threshold, or content; one anchor per concept, all from the same batch.
+
+Answer, nothing else: anchor lines `path:line — symbol — short reason`
+(`?` if weak), max 3 lines — extra anchors are cost, not quality; pick the
+3 with the most specific token match. Or `EXPLORATION_FAILED` — only after
+the turn budget is
+spent with zero anchors, or when every anchor matches only generic words.
+Before emitting `EXPLORATION_FAILED`, re-scan ALL earlier tool results: if
+any line anywhere matched a specific query token, answer with that anchor
+(`?` if weak) instead — a weak anchor beats a false miss.

package/src/rules/lead/02-channels.md

@@ -1,3 +1,3 @@
-# Channels
-
-- Channel features are handled by the runtime.
+# Channels
+
+- Channel features are handled by the runtime.

package/src/rules/lead/lead-tool.md

@@ -1,7 +1,8 @@
 # Lead Tool Use
 
-- Lead owns repo-local shell work: run git/build/test/verification via `shell`
-  directly; do not delegate to agents.
+- Write-role agents run their own build/test verification via `shell`; Lead
+  runs cross-scope verification, benches, and everything git via `shell`
+  directly.
 - Use the session's current project/workspace. Change the work project only
   when the user asks for another project or a tool call needs another root.
 - Use `agent` for scoped implementation, research, review, and debugging — not

package/src/rules/shared/01-tool.md

@@ -1,32 +1,27 @@
 # Tool Use
 
-- Batch independent lookups in one turn; serialize only when a call needs a
-  prior result — including edit loops: batch the post-edit verification read
-  with the next target's lookup.
-- Pick by target: symbols/callers/deps → `code_graph`; exact text in a verified
-  scope → `grep`; dirs → `list`; verified file → `read`.
-  Locating files: concept-level or cross-file questions ("where is X handled",
-  "how does Y flow") → `explore`, even when you could guess a keyword — its
-  fan-out spends explorer context, not yours, and guess-and-retry keywords
-  belong to it, not grep. Confident name fragment → `find`; exact name
-  pattern → `glob`; exact content literal → `grep`. Flow/trace with a known
-  symbol → `code_graph`, never `explore` — it returns entry-point anchors
-  only; follow the chain yourself. Never `grep`/`read` guessed paths.
-- One concept → ONE search call: all synonyms/variants in one
-  `grep pattern:[...]` (or `code_graph symbols[]`), scopes as `path[]`;
-  single-pattern bursts = packing failure. A second call on the same concept
-  is a defect unless the first returned zero — then change tokens or scope,
-  never reword.
-- Content-mode `grep` always carries `-C 5`+ ; re-reading the same file after
-  a content grep is a wasted round-trip. Bare match lines = existence checks
-  only.
-- Any path not returned by a tool this session is a guess: find first, then
-  grep/read the returned path. On ENOENT the next call is find on the
-  basename — never a second guess or the same path with changed args.
-- Retrieval serves the NEXT action (edit, answer, handoff), not certainty:
-  the FIRST anchor ends the search — no verifying, ranking, or re-checking a
-  hit already on screen. When acting and looking are both possible, act.
-- `read` uses `offset`/`limit` only; 2+ spans from known file(s) = ONE batched
-  `read` with `{path,offset,limit}` regions. Adjacent spans in one file
-  (within a few hundred lines) are ONE window, not repeated reads.
+- Batch independent calls in one turn; serialize only when a call needs a
+  prior result. Merge equivalent variants/scopes into ONE call wherever the
+  schema accepts arrays (`pattern[]`, `path[]`, `symbols[]`, `query[]`).
+- Route by what is already known: known symbol/relation → `code_graph`;
+  exact text in a known scope → `grep`; unknown location or concept-level
+  question → `explore`; name fragment → `find`; exact name pattern → `glob`;
+  known directory → `list`; known file/region → `read`.
+- Valid anchors come from user input or tool output in this session; locate
+  anything else with `find` before `grep`/`read`. On ENOENT the next call is
+  `find` on the basename — never a retried guess.
+- Retrieval stops when evidence covers the deliverable: single-answer tasks
+  end at the first sufficient anchor; enumeration tasks (review, audit) end
+  when the stated scope is covered. Never re-verify a hit already on screen;
+  a plausible anchor means the next call is the action itself
+  (patch/answer/handoff) — never "one more confirming read".
+- Content-mode `grep` requests enough context (`-C`) to act without
+  re-reading the same file; bare match lines are existence checks only.
+- Repeat a search concept only after a zero-result call, changing tokens or
+  scope — never wording alone.
+- `read` windows use `offset`/`limit`; multiple spans or files = ONE call
+  with `{path,offset,limit}[]` regions. Size the window to the whole logical
+  unit (function/section) — over-read once instead of paging the same file
+  in small windows across turns; a 3rd window into one file means the first
+  should have been wider.
 - Don't mix `apply_patch` with shell or other state-changing calls in one turn.

package/src/runtime/agent/orchestrator/context/collect.mjs

@@ -319,16 +319,34 @@ export function bp1HasDeferredToolManifestBlock(text) {
 }
 
 /**
- * Names-only manifest for tools in the deferred pool (catalog minus active wire tools).
+ * Skill-style manifest for tools in the deferred pool (catalog minus active
+ * wire tools). Each entry is either a bare name string or `{ name, description }`;
+ * output lines are `- name: description` (description omitted when absent),
+ * mirroring the available-skills manifest so the model calls deferred tools
+ * directly. Descriptions are compacted and stripped of `<`/`>`.
  * Empty pool → '' (caller omits the block).
  */
-export function buildDeferredToolManifest(names) {
-    const list = [...new Set((Array.isArray(names) ? names : [])
-        .map((name) => sanitizeDeferredToolManifestName(name))
-        .filter(Boolean))]
-        .sort((a, b) => a.localeCompare(b));
+export function buildDeferredToolManifest(entries) {
+    const list = [];
+    const seen = new Set();
+    for (const entry of Array.isArray(entries) ? entries : []) {
+        const rawName = typeof entry === 'string' ? entry : entry?.name;
+        const name = sanitizeDeferredToolManifestName(rawName);
+        if (!name || seen.has(name)) continue;
+        seen.add(name);
+        const description = typeof entry === 'string'
+            ? ''
+            : compactSkillManifestText(String(entry?.description || '').replace(/[<>]/g, ''));
+        list.push({ name, description });
+    }
     if (!list.length) return '';
-    return ['<available-deferred-tools>', ...list, '</available-deferred-tools>'].join('\n');
+    list.sort((a, b) => a.name.localeCompare(b.name));
+    return [
+        '<available-deferred-tools>',
+        'You may call any tool listed below directly by name with its arguments; it auto-loads on first call.',
+        ...list.map((entry) => (entry.description ? `- ${entry.name}: ${entry.description}` : `- ${entry.name}`)),
+        '</available-deferred-tools>',
+    ].join('\n');
 }
 
 function sanitizeMcpManifestServerName(name) {
@@ -389,12 +407,18 @@ export function stripDeferredToolManifestBlock(text) {
         .trimEnd();
 }
 
-/** Inject names-only deferred pool into BP1 once at session start; never rewrite BP1 after. */
+/** Inject the skill-style deferred pool (name + description) into BP1 once at session start; never rewrite BP1 after. */
 export function applyInitialDeferredToolManifestToBp1(session, poolNames) {
     if (!session || !Array.isArray(session.messages) || session.deferredToolBp1Applied) return false;
     const pool = Array.isArray(poolNames) ? poolNames : [];
+    const descByName = new Map();
+    for (const tool of Array.isArray(session?.deferredToolCatalog) ? session.deferredToolCatalog : []) {
+        const name = String(tool?.name || '').trim();
+        if (name && !descByName.has(name)) descByName.set(name, String(tool?.description || ''));
+    }
+    const entries = pool.map((name) => ({ name, description: descByName.get(String(name).trim()) || '' }));
     const parts = [];
-    const deferredManifest = buildDeferredToolManifest(pool);
+    const deferredManifest = buildDeferredToolManifest(entries);
     if (deferredManifest) parts.push(deferredManifest);
     const mcpManifest = buildMcpInstructionsManifest(session.mcpServerInstructions, pool);
     if (mcpManifest) parts.push(mcpManifest);

package/src/runtime/agent/orchestrator/providers/anthropic-oauth.mjs

@@ -376,7 +376,7 @@ function toAnthropicMessages(messages) {
             continue;
         }
 
-        // Claude Code parity: fold a user text turn that directly follows a
+        // First-party client parity: fold a user text turn that directly follows a
         // tool_result turn into that tool_result's content. A sibling text
         // turn after tool_result renders as `</function_results>\n\nHuman:`
         // on the wire and trains the model toward 3-token empty end_turn

package/src/runtime/agent/orchestrator/providers/anthropic.mjs

@@ -378,7 +378,7 @@ function toAnthropicMessages(messages) {
             }
             continue;
         }
-        // Claude Code parity: fold a user text turn that directly follows a
+        // First-party client parity: fold a user text turn that directly follows a
         // tool_result turn into that tool_result's content (empty end_turn
         // livelock prevention; see foldUserTextIntoToolResultTail).
         if (m.role === 'user' && foldUserTextIntoToolResultTail(result, normalizeContentForAnthropic(m.content))) {

package/src/runtime/agent/orchestrator/providers/oauth-usage.mjs

@@ -241,14 +241,35 @@ function windowFromPercent(label, value, source) {
   return Object.keys(out).length > 2 ? out : null;
 }
 
+// Grok Build billing periods are migrating from monthly to a shared weekly
+// pool (xAI rollout is per-account). Derive the window cadence from the
+// actual billing period length instead of hardcoding monthly: <=10 days
+// means a weekly cycle, anything longer (or unknown) stays monthly.
+function grokBillingCadence(config) {
+  if (config?.weeklyLimit !== undefined || config?.weekly_limit !== undefined) {
+    return { label: 'W', period: 'weekly' };
+  }
+  const start = resetAtMs(config?.billingPeriodStart ?? config?.billing_period_start);
+  const end = resetAtMs(config?.billingPeriodEnd ?? config?.billing_period_end);
+  if (start && end && end > start && (end - start) <= 10 * 24 * 60 * 60_000) {
+    return { label: 'W', period: 'weekly' };
+  }
+  return { label: 'M', period: 'monthly' };
+}
+
 function creditWindowFromBilling(config) {
   if (!config || typeof config !== 'object') return null;
-  const limit = num(config.monthlyLimit?.val ?? config.monthlyLimit ?? config.includedLimit?.val, null);
+  const limit = num(
+    config.weeklyLimit?.val ?? config.weeklyLimit
+      ?? config.monthlyLimit?.val ?? config.monthlyLimit
+      ?? config.includedLimit?.val,
+    null,
+  );
   const used = num(config.used?.val ?? config.includedUsed?.val ?? config.used, null);
   if (limit === null || used === null || !(limit > 0)) return null;
   const resetAt = resetAtMs(config.billingPeriodEnd ?? config.billing_period_end);
   return {
-    label: 'M',
+    label: grokBillingCadence(config).label,
     source: 'grok-build-billing',
     usedPct: round(Math.min(100, used * 100 / limit), 2),
     usedCredits: round(used, 2),
@@ -265,7 +286,7 @@ function balanceFromGrokBilling(config) {
   if (cap === null || !(cap > 0)) return null;
   return {
     source: 'grok-build-on-demand',
-    period: 'monthly',
+    period: grokBillingCadence(config).period,
     budgetCredits: round(cap, 2),
     spentCredits: round(used, 2),
     remainingCredits: round(Math.max(0, cap - used), 2),

package/src/runtime/agent/orchestrator/providers/retry-classifier.mjs

@@ -29,15 +29,15 @@ import {
 //   408 — request timeout
 //   500/502/503/504 — server errors (overload / bad gateway / timeout)
 //   429 is excluded from blanket transient retry, but withRetry() honors a
-//   SHORT Retry-After header (< SHORT_RETRY_AFTER_MAX_MS) the way Claude Code
-//   does (refs/claude-code withRetry.ts SHORT_RETRY_THRESHOLD_MS = 20s):
+//   SHORT Retry-After header (< SHORT_RETRY_AFTER_MAX_MS): a short-retry
+//   threshold of 20s matches first-party client behavior:
 //   brief throttle windows retry once the server-stated wait elapses; long or
 //   headerless 429s still surface immediately (quota windows are
 //   deterministic — sleeping into an outer watchdog just relabels the error).
 const TRANSIENT_STATUSES = new Set([408, 500, 502, 503, 504])
 
 // Max server-stated Retry-After we are willing to sleep on a 429 before
-// surfacing it. Mirrors Claude Code's 20s short-retry threshold.
+// surfacing it. Mirrors the first-party client's 20s short-retry threshold.
 const SHORT_RETRY_AFTER_MAX_MS = 20_000
 
 // HTTP statuses that mean "permanent: stop retrying, surface to caller".