zcode-supervisor 0.0.1__py3-none-any.whl

tools/__init__.py

@@ -0,0 +1,2 @@
+"""Project command modules."""
+

tools/zcode_control/__init__.py

@@ -0,0 +1,16 @@
+"""Python entrypoint wrapper for the bundled Node controller."""
+
+from __future__ import annotations
+
+import subprocess
+import sys
+from pathlib import Path
+
+
+def main(argv: list[str] | None = None) -> int:
+    controller = Path(__file__).resolve().with_name("zcodectl.mjs")
+    try:
+        return subprocess.call(["node", str(controller), *(argv if argv is not None else sys.argv[1:])])
+    except FileNotFoundError:
+        print("zcodectl requires Node.js on PATH. Install Node.js and retry.", file=sys.stderr)
+        return 127

tools/zcode_control/browser_scripts.mjs

@@ -0,0 +1,106 @@
+export function usageSnapshotExpression() {
+  return String.raw`(() => {
+    const bodyText = document.body?.innerText || "";
+    const parseHumanNumber = (raw, suffix) => {
+      const numeric = Number(String(raw).replace(/,/g, ""));
+      if (!Number.isFinite(numeric)) return null;
+      const multiplier = suffix === "K" ? 1_000 : suffix === "M" ? 1_000_000 : suffix === "B" ? 1_000_000_000 : 1;
+      return numeric * multiplier;
+    };
+    const lines = bodyText.split(/\n+/).map((line) => line.trim()).filter(Boolean);
+    const relevant = lines.filter((line) =>
+      /\b(token|tokens|quota|usage|remaining|used|coding plan|prompt pool|weekly|monthly|context|glm)\b/i.test(line),
+    );
+    const tokenCandidates = [];
+    const quotaPercentCandidates = [];
+    for (const line of relevant) {
+      for (const match of line.matchAll(/([\d,.]+)\s*([KMB])?\s*(?:tokens?|token)\b/gi)) {
+        const value = parseHumanNumber(match[1], match[2]?.toUpperCase());
+        if (value !== null) tokenCandidates.push({ line, value });
+      }
+      for (const match of line.matchAll(/(\d+(?:\.\d+)?)\s*%/g)) {
+        const value = Number(match[1]);
+        if (Number.isFinite(value)) quotaPercentCandidates.push({ line, value });
+      }
+    }
+    const tokenBest =
+      tokenCandidates.find((item) => /\b(total|token usage|all time)\b/i.test(item.line)) ||
+      tokenCandidates[0] ||
+      null;
+    const quotaBest =
+      quotaPercentCandidates.find((item) => /\b(quota|remaining|prompt pool|weekly|monthly)\b/i.test(item.line)) ||
+      quotaPercentCandidates.find((item) => !/\bcontext\b/i.test(item.line)) ||
+      quotaPercentCandidates[0] ||
+      null;
+    return {
+      captured_at: new Date().toISOString(),
+      title: document.title,
+      visible_usage_lines: relevant.slice(0, 80),
+      token_candidates: tokenCandidates.slice(0, 20),
+      quota_percent_candidates: quotaPercentCandidates.slice(0, 20),
+      best: {
+        tokens_total: tokenBest?.value ?? null,
+        tokens_line: tokenBest?.line ?? null,
+        quota_percent: quotaBest?.value ?? null,
+        quota_percent_line: quotaBest?.line ?? null,
+      },
+    };
+  })()`;
+}
+
+export function openUsageExpression() {
+  return `(() => {
+    const dispatchClick = (el) => {
+      const r = el.getBoundingClientRect();
+      const x = Math.round(r.x + r.width / 2);
+      const y = Math.round(r.y + r.height / 2);
+      for (const type of ['pointerdown', 'mousedown', 'pointerup', 'mouseup', 'click']) {
+        el.dispatchEvent(new MouseEvent(type, { bubbles: true, cancelable: true, view: window, clientX: x, clientY: y }));
+      }
+      return { x, y };
+    };
+    const clickCandidate = (needles) => {
+      const candidates = Array.from(document.querySelectorAll('button,[role=button],a,[role=menuitem],[data-testid]'));
+      const el = candidates.find((node) => {
+        const text = (node.innerText || node.textContent || node.getAttribute('aria-label') || '').trim().toLowerCase();
+        const testid = (node.getAttribute('data-testid') || '').toLowerCase();
+        const rect = node.getBoundingClientRect();
+        const visible = rect.width > 0 && rect.height > 0;
+        return visible && needles.some((needle) => text.includes(needle) || testid.includes(needle));
+      });
+      if (!el) return null;
+      return { text: (el.innerText || el.textContent || el.getAttribute('aria-label') || '').trim(), ...dispatchClick(el) };
+    };
+    const direct = clickCandidate(['usage stats', 'usage', 'quota', 'coding plan']);
+    if (direct) return { ok: true, phase: 'usage', clicked: direct };
+    const settings = clickCandidate(['settings', 'preferences']);
+    if (settings) return { ok: true, phase: 'settings', clicked: settings, next: 'run open-usage again if usage is not visible' };
+    return { ok: false, reason: 'usage entry not found' };
+  })()`;
+}
+
+export function summaryExpression() {
+  return `(() => {
+    const bodyText = document.body?.innerText || "";
+    const buttons = Array.from(document.querySelectorAll('button,[role=button]')).map((el) => {
+      const r = el.getBoundingClientRect();
+      return {
+        text: (el.innerText || el.textContent || el.getAttribute('aria-label') || '').trim().slice(0, 120),
+        aria: el.getAttribute('aria-label'),
+        disabled: Boolean(el.disabled) || el.getAttribute('aria-disabled') === 'true',
+        rect: { x: Math.round(r.x), y: Math.round(r.y), w: Math.round(r.width), h: Math.round(r.height) },
+      };
+    });
+    const visibleButtons = buttons.filter((button) => button.rect.w > 0 && button.rect.h > 0);
+    return {
+      running: /\\bWorking for\\b/.test(bodyText) || visibleButtons.some((button) => button.text === 'Stop' || button.aria === 'Stop'),
+      awaitingApproval: /Awaiting approval|Permission required/.test(bodyText),
+      workedFor: (bodyText.match(/Worked for\\s+([^\\n]+)/) || [])[1] || null,
+      contextUsage: (bodyText.match(/Context usage\\s+[^\\n]+/) || [])[0] || null,
+      activeMode: visibleButtons.find((button) => button.aria === 'Switch mode')?.text || null,
+      activeModel: visibleButtons.find((button) => button.aria === 'Choose model')?.text || null,
+      activeWorkspace: visibleButtons.find((button) => button.aria === 'Choose workspace')?.text || null,
+      lastText: bodyText.slice(-3000),
+    };
+  })()`;
+}

tools/zcode_control/provider_errors.mjs

@@ -0,0 +1,135 @@
+const OVERLOAD_RE = /temporarily overloaded|try again later|overloaded_error/i;
+
+export const DEFAULT_PROVIDER_MAX_ATTEMPTS = 2;
+export const DEFAULT_PROVIDER_RETRY_DELAY_MS = 60_000;
+
+function firstMatch(text, patterns) {
+  for (const pattern of patterns) {
+    const match = text.match(pattern);
+    if (match?.[1]) return match[1];
+  }
+  return null;
+}
+
+function firstProviderLine(text) {
+  return text.split(/\r?\n/).find((line) => /ProviderBusinessError|PROVIDER_BUSINESS_ERROR/i.test(line)) ?? null;
+}
+
+export function classifyProviderError({ stdout = "", stderr = "", exitCode = null } = {}) {
+  const text = `${stderr}\n${stdout}`;
+  const exitCodeNumber = Number(exitCode);
+  const exit143 = Number.isFinite(exitCodeNumber) && exitCodeNumber === 143;
+  const providerBusiness = /ProviderBusinessError|PROVIDER_BUSINESS_ERROR|isProviderBusinessError:\s*true/i.test(text);
+  const providerCode = firstMatch(text, [
+    /providerCode:\s*['"]?(\d+)['"]?/,
+    /"providerCode"\s*:\s*"(\d+)"/,
+    /\[(\d{3,})\]\[/,
+    /\bcode:\s*['"]?(\d{3,})['"]?/,
+    /"code"\s*:\s*"(\d{3,})"/,
+  ]);
+  const temporary = OVERLOAD_RE.test(text) || providerCode === "1305";
+  const providerError = providerBusiness || temporary || providerCode === "1305" || exit143;
+  const providerMessage = firstMatch(text, [
+    /providerMessage:\s*'([^']+)'/,
+    /providerMessage:\s*"([^"]+)"/,
+    /"providerMessage"\s*:\s*"([^"]+)"/,
+    /ProviderBusinessError:\s*([^\n]+)/,
+  ]) ?? (exit143 ? "ZCode CLI exited with code 143" : null);
+
+  return {
+    provider_error: providerError,
+    provider_code: providerCode,
+    provider_message: providerMessage,
+    provider_id: firstMatch(text, [/providerId:\s*'([^']+)'/, /providerId:\s*"([^"]+)"/, /"providerId"\s*:\s*"([^"]+)"/]),
+    provider_kind: firstMatch(text, [/providerKind:\s*'([^']+)'/, /providerKind:\s*"([^"]+)"/, /"providerKind"\s*:\s*"([^"]+)"/]),
+    provider_request_id: firstMatch(text, [
+      /providerRequestId:\s*'([^']+)'/,
+      /providerRequestId:\s*"([^"]+)"/,
+      /"providerRequestId"\s*:\s*"([^"]+)"/,
+      /request_id:\s*'([^']+)'/,
+      /"request_id"\s*:\s*"([^"]+)"/,
+    ]),
+    provider_error_line: firstProviderLine(text),
+    provider_error_temporary: temporary,
+    retryable_provider_error: providerError && (temporary || exit143),
+  };
+}
+
+function parsedJsonObjects(stdout) {
+  const trimmed = stdout.trim();
+  if (!trimmed) return [];
+  const candidates = [trimmed, ...trimmed.split(/\r?\n/).filter((line) => line.trim().startsWith("{"))];
+  const objects = [];
+  for (const candidate of candidates) {
+    try {
+      const parsed = JSON.parse(candidate);
+      if (parsed && typeof parsed === "object" && !Array.isArray(parsed)) objects.push(parsed);
+    } catch {
+      // CLI output may be prose, JSONL, or empty; non-JSON chunks are ignored.
+    }
+  }
+  return objects;
+}
+
+function hasUsageShape(value) {
+  if (!value || typeof value !== "object") return false;
+  const usage = value.usage;
+  if (usage && typeof usage === "object") return true;
+  return [
+    "tokens_total",
+    "total_tokens",
+    "input_tokens",
+    "output_tokens",
+    "cache_read_tokens",
+  ].some((key) => typeof value[key] === "number");
+}
+
+export function usageAvailableFromStdout(stdout = "") {
+  return parsedJsonObjects(stdout).some(hasUsageShape);
+}
+
+export function classifyProviderRunState({ cliOk, provider, audit }) {
+  if (cliOk) {
+    if (audit?.ok === false) {
+      const changedCount = Number.isFinite(Number(audit?.changed_count)) ? Number(audit.changed_count) : null;
+      return {
+        supervisor_state: "audit_failed",
+        partial_artifacts_possible: changedCount === null ? true : changedCount > 0,
+        safe_to_retry_later: false,
+      };
+    }
+    return {
+      supervisor_state: "success",
+      partial_artifacts_possible: false,
+      safe_to_retry_later: false,
+    };
+  }
+  if (!provider?.provider_error) {
+    return {
+      supervisor_state: "cli_error",
+      partial_artifacts_possible: false,
+      safe_to_retry_later: false,
+    };
+  }
+
+  const changedCount = Number.isFinite(Number(audit?.changed_count)) ? Number(audit.changed_count) : null;
+  if (changedCount === 0 && provider.retryable_provider_error) {
+    return {
+      supervisor_state: "retryable_provider_error",
+      partial_artifacts_possible: false,
+      safe_to_retry_later: true,
+    };
+  }
+  if (changedCount !== null && changedCount > 0 && audit?.ok === true) {
+    return {
+      supervisor_state: "partial_success",
+      partial_artifacts_possible: true,
+      safe_to_retry_later: false,
+    };
+  }
+  return {
+    supervisor_state: "unsafe_partial",
+    partial_artifacts_possible: changedCount === null ? true : changedCount > 0,
+    safe_to_retry_later: false,
+  };
+}