handyman-harness 3.0.0

package/dist/toolbox_llm.js

@@ -0,0 +1,291 @@
+import { createRequire } from 'node:module'; const require = createRequire(import.meta.url);
+
+// ../packages/toolbox-core/dist/llm.js
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+var LlmError = class extends Error {
+  code;
+  constructor(code, message) {
+    super(message);
+    this.name = "LlmError";
+    this.code = code;
+  }
+};
+var DEFAULT_MAX_TOKENS = 16e3;
+var OPENAI_MAX_TOKENS_CAP = 131072;
+var DRAFT_TIMEOUT_MS = 3e5;
+var HEALTH_TIMEOUT_MS = 1500;
+var FUTURE_PROVIDER_IDS = ["copilot"];
+async function raiseHttp(res) {
+  const body = (await res.text().catch(() => "")).slice(0, 300);
+  let code = "provider_error";
+  if (res.status === 401) {
+    code = "unauthorized";
+  } else if (body.includes('"1113"')) {
+    code = "insufficient_balance";
+  }
+  throw new LlmError(code, `HTTP ${res.status}: ${body}`);
+}
+async function* sseData(body) {
+  if (!body) {
+    return;
+  }
+  const decoder = new TextDecoder();
+  let buf = "";
+  for await (const chunk of body) {
+    buf += decoder.decode(chunk, { stream: true });
+    let idx = buf.indexOf("\n");
+    while (idx !== -1) {
+      const line = buf.slice(0, idx).trimEnd();
+      buf = buf.slice(idx + 1);
+      if (line.startsWith("data:")) {
+        yield line.slice(5).trim();
+      }
+      idx = buf.indexOf("\n");
+    }
+  }
+}
+function parseJson(payload) {
+  try {
+    const value = JSON.parse(payload);
+    return value && typeof value === "object" ? value : null;
+  } catch {
+    return null;
+  }
+}
+function anthropicProvider(options) {
+  const doFetch = options.fetchImpl ?? fetch;
+  const base = options.baseUrl.replace(/\/$/, "");
+  return {
+    id: options.id,
+    model: options.model,
+    available: async () => options.apiKey.length > 0,
+    async draft(req, onDelta) {
+      const headers = {
+        "Content-Type": "application/json",
+        "anthropic-version": "2023-06-01"
+      };
+      if ((options.auth ?? "x-api-key") === "bearer") {
+        headers.Authorization = `Bearer ${options.apiKey}`;
+      } else {
+        headers["x-api-key"] = options.apiKey;
+      }
+      const model = req.model ?? options.model;
+      const res = await doFetch(`${base}/v1/messages`, {
+        method: "POST",
+        headers,
+        signal: AbortSignal.timeout(DRAFT_TIMEOUT_MS),
+        body: JSON.stringify({
+          model,
+          max_tokens: req.maxTokens ?? DEFAULT_MAX_TOKENS,
+          stream: true,
+          ...req.system ? { system: req.system } : {},
+          messages: [{ role: "user", content: req.prompt }]
+        })
+      });
+      if (!res.ok) {
+        await raiseHttp(res);
+      }
+      let text = "";
+      let stopReason = null;
+      for await (const payload of sseData(res.body)) {
+        const event = parseJson(payload);
+        if (!event) {
+          continue;
+        }
+        if (event.type === "content_block_delta") {
+          const delta = event.delta;
+          if (delta?.type === "text_delta" && typeof delta.text === "string") {
+            text += delta.text;
+            onDelta(delta.text);
+          }
+        } else if (event.type === "message_delta") {
+          const delta = event.delta;
+          if (typeof delta?.stop_reason === "string") {
+            stopReason = delta.stop_reason;
+          }
+        }
+      }
+      return { text, model, stopReason };
+    }
+  };
+}
+function openAiCompatProvider(options) {
+  const doFetch = options.fetchImpl ?? fetch;
+  const base = options.baseUrl.replace(/\/$/, "");
+  return {
+    id: options.id,
+    model: options.model,
+    async available() {
+      if (!options.healthCheck) {
+        return (options.apiKey ?? "").length > 0;
+      }
+      try {
+        const res = await doFetch(`${base}/models`, {
+          signal: AbortSignal.timeout(HEALTH_TIMEOUT_MS)
+        });
+        return res.ok;
+      } catch {
+        return false;
+      }
+    },
+    async draft(req, onDelta) {
+      const headers = { "Content-Type": "application/json" };
+      if (options.apiKey) {
+        headers.Authorization = `Bearer ${options.apiKey}`;
+      }
+      const messages = [
+        ...req.system ? [{ role: "system", content: req.system }] : [],
+        { role: "user", content: req.prompt }
+      ];
+      const model = req.model ?? options.model;
+      const res = await doFetch(`${base}/chat/completions`, {
+        method: "POST",
+        headers,
+        signal: AbortSignal.timeout(DRAFT_TIMEOUT_MS),
+        body: JSON.stringify({
+          model,
+          messages,
+          stream: true,
+          max_tokens: Math.min(req.maxTokens ?? DEFAULT_MAX_TOKENS, OPENAI_MAX_TOKENS_CAP),
+          ...options.thinkingControl && !req.reasoning ? { thinking: { type: "disabled" } } : {}
+        })
+      });
+      if (!res.ok) {
+        await raiseHttp(res);
+      }
+      let text = "";
+      let stopReason = null;
+      for await (const payload of sseData(res.body)) {
+        if (payload === "[DONE]") {
+          continue;
+        }
+        const event = parseJson(payload);
+        const choice = event?.choices?.[0];
+        if (!choice) {
+          continue;
+        }
+        const delta = choice.delta;
+        if (typeof delta?.content === "string" && delta.content.length > 0) {
+          text += delta.content;
+          onDelta(delta.content);
+        }
+        if (typeof choice.finish_reason === "string") {
+          stopReason = choice.finish_reason;
+        }
+      }
+      return { text, model, stopReason };
+    }
+  };
+}
+var PROVIDER_REGISTRY = [
+  {
+    id: "zai",
+    apiKeyEnvKey: "Z_AI_API_KEY",
+    modelEnvKey: "Z_AI_MODEL",
+    defaultModel: "glm-5.2",
+    resolveVariant: (env) => env.Z_AI_API_MODE === "paas" ? {
+      adapter: "openai-compat",
+      baseUrl: "https://api.z.ai/api/paas/v4",
+      thinkingControl: true
+    } : {
+      adapter: "anthropic",
+      baseUrl: "https://api.z.ai/api/anthropic",
+      auth: "bearer"
+    }
+  },
+  {
+    id: "claude",
+    apiKeyEnvKey: "ANTHROPIC_API_KEY",
+    modelEnvKey: "ANTHROPIC_MODEL",
+    defaultModel: "claude-opus-4-8",
+    resolveVariant: () => ({
+      adapter: "anthropic",
+      baseUrl: "https://api.anthropic.com"
+    })
+  },
+  {
+    id: "ollama",
+    modelEnvKey: "OLLAMA_MODEL",
+    defaultModel: "llama3.2",
+    resolveVariant: (env) => ({
+      adapter: "openai-compat",
+      baseUrl: env.OLLAMA_BASE_URL ?? "http://127.0.0.1:11434/v1",
+      healthCheck: true
+    })
+  }
+];
+function buildProviders(env, fetchImpl) {
+  const providers = [];
+  for (const entry of PROVIDER_REGISTRY) {
+    const apiKey = entry.apiKeyEnvKey ? env[entry.apiKeyEnvKey] ?? "" : "";
+    if (entry.apiKeyEnvKey && !apiKey) {
+      continue;
+    }
+    const model = entry.modelEnvKey ? env[entry.modelEnvKey] ?? entry.defaultModel : entry.defaultModel;
+    const variant = entry.resolveVariant(env);
+    providers.push(variant.adapter === "anthropic" ? anthropicProvider({
+      id: entry.id,
+      model,
+      baseUrl: variant.baseUrl,
+      apiKey,
+      auth: variant.auth,
+      fetchImpl
+    }) : openAiCompatProvider({
+      id: entry.id,
+      model,
+      baseUrl: variant.baseUrl,
+      apiKey: apiKey || void 0,
+      thinkingControl: variant.thinkingControl,
+      healthCheck: variant.healthCheck,
+      fetchImpl
+    }));
+  }
+  return providers;
+}
+async function providersInfo(providers) {
+  const infos = await Promise.all(providers.map(async (p) => ({
+    id: p.id,
+    available: await p.available().catch(() => false),
+    model: p.model
+  })));
+  for (const id of FUTURE_PROVIDER_IDS) {
+    infos.push({ id, available: false, model: null });
+  }
+  return infos;
+}
+function loadDotEnv(root, env = process.env) {
+  let raw;
+  try {
+    raw = readFileSync(join(root, ".env"), "utf-8");
+  } catch {
+    return;
+  }
+  for (const line of raw.split("\n")) {
+    if (line.trimStart().startsWith("#")) {
+      continue;
+    }
+    const match = /^\s*(?:export\s+)?([A-Za-z_][A-Za-z0-9_]*)\s*=\s*(.*?)\s*$/.exec(line);
+    if (!match) {
+      continue;
+    }
+    const key = match[1];
+    let value = match[2];
+    if (value.startsWith('"') && value.endsWith('"') || value.startsWith("'") && value.endsWith("'")) {
+      value = value.slice(1, -1);
+    }
+    if (env[key] === void 0) {
+      env[key] = value;
+    }
+  }
+}
+export {
+  FUTURE_PROVIDER_IDS,
+  LlmError,
+  PROVIDER_REGISTRY,
+  anthropicProvider,
+  buildProviders,
+  loadDotEnv,
+  openAiCompatProvider,
+  providersInfo
+};

package/dist/toolbox_retro.js

@@ -0,0 +1,191 @@
+import { createRequire } from 'node:module'; const require = createRequire(import.meta.url);
+
+// ../packages/toolbox-core/dist/retro.js
+import { readdirSync as readdirSync2 } from "node:fs";
+import { join as join2 } from "node:path";
+
+// ../packages/toolbox-core/dist/llm.js
+var LlmError = class extends Error {
+  code;
+  constructor(code, message) {
+    super(message);
+    this.name = "LlmError";
+    this.code = code;
+  }
+};
+
+// ../packages/toolbox-core/dist/state.js
+import { readdirSync, readFileSync, statSync } from "node:fs";
+import { join, resolve, sep } from "node:path";
+var INTAKE_MAX_BYTES = 256 * 1024;
+var CSP_HEADER = "default-src 'self'; script-src 'self' 'unsafe-inline'; style-src 'self' 'unsafe-inline'; img-src 'self' data:; connect-src 'self'";
+var HTML_CSP_HEADER = CSP_HEADER.replace("img-src 'self' data:", "img-src 'self' data: https://picsum.photos");
+function readText(path) {
+  try {
+    return readFileSync(path, "utf-8");
+  } catch {
+    return null;
+  }
+}
+function readFeatures(workspace) {
+  const raw = readText(join(workspace, "feature_list.json"));
+  if (raw === null) {
+    return [];
+  }
+  let data;
+  try {
+    data = JSON.parse(raw);
+  } catch {
+    return [];
+  }
+  const features = data && typeof data === "object" && !Array.isArray(data) ? data.features : [];
+  if (!Array.isArray(features)) {
+    return [];
+  }
+  return features.filter((f) => !!f && typeof f === "object" && !Array.isArray(f)).map((f) => ({
+    id: typeof f.id === "number" ? f.id : null,
+    name: String(f.name ?? ""),
+    title: String(f.title ?? f.name ?? ""),
+    status: String(f.status ?? "pending"),
+    sprint: f.sprint ? String(f.sprint) : null,
+    blocked_reason: f.blocked_reason ? String(f.blocked_reason) : null,
+    depends_on: Array.isArray(f.depends_on) ? f.depends_on.filter(Number.isInteger) : []
+  }));
+}
+var MD_TOKEN_PATHS = {
+  current: (workspace) => join(workspace, "progress", "current.md"),
+  history: (workspace) => join(workspace, "progress", "history.md"),
+  index: (workspace) => join(workspace, "index.md"),
+  checkpoints: (_workspace, root) => join(root, "CHECKPOINTS.md")
+};
+var MD_TOKENS = Object.keys(MD_TOKEN_PATHS);
+
+// ../packages/toolbox-core/dist/retro.js
+var RETRO_MIN_EVIDENCE = 2;
+var RETRO_EXCERPT_CHARS = 1200;
+var RETRO_MAX_PATTERNS = 5;
+function readRetroCorpus(workspace) {
+  const history = readText(join2(workspace, "progress", "history.md")) ?? "";
+  const closed = readFeatures(workspace).filter((f) => f.status === "done" && f.name).map((f) => f.name);
+  const closedSet = new Set(closed);
+  let names;
+  try {
+    names = readdirSync2(join2(workspace, "backlog")).filter((n) => n.endsWith(".md"));
+  } catch {
+    return { history, docs: [], closed };
+  }
+  names.sort();
+  const docs = [];
+  for (const name of names) {
+    const feature = name.replace(/^(impl|review|explore)_/, "").replace(/\.md$/, "");
+    if (!closedSet.has(feature)) {
+      continue;
+    }
+    docs.push({
+      id: name,
+      feature,
+      excerpt: (readText(join2(workspace, "backlog", name)) ?? "").slice(0, RETRO_EXCERPT_CHARS)
+    });
+  }
+  return { history, docs, closed };
+}
+function composeRetroSystem() {
+  return [
+    "Destilas lecciones de las features ya cerradas de un harness Handyman.",
+    "",
+    "Responde SOLO un objeto JSON, sin texto alrededor y sin bloque de codigo:",
+    '{"patterns":[{"titulo":"<frase corta>","tipo":"patron|antipatron","features":["<nombre de feature>","<otro>"],"detalle":"<que se repitio y por que importa>"}]}',
+    "",
+    "Reglas duras:",
+    `- Entre 3 y ${RETRO_MAX_PATTERNS} patrones. Ni uno mas.`,
+    `- Cada patron necesita AL MENOS ${RETRO_MIN_EVIDENCE} features distintas como`,
+    "  evidencia, citadas por nombre en 'features'. Un patron con una sola",
+    "  feature es una anecdota: DESCARTALO en vez de generalizarlo.",
+    "- Usa solo nombres de features que aparezcan en el material recibido.",
+    "- Si el material no da para 3 patrones con esa evidencia, devuelve menos.",
+    "  Es correcto decir que no hay suficiente historia todavia.",
+    "- No propongas editar docs/conventions.md: son sugerencias, decide un humano."
+  ].join("\n");
+}
+function composeRetroPrompt(corpus) {
+  const docs = corpus.docs.map((d) => `--- ${d.id} (feature: ${d.feature})
+${d.excerpt}`).join("\n\n");
+  return [
+    `Features cerradas (${corpus.closed.length}): ${corpus.closed.join(", ") || "(ninguna)"}`,
+    "",
+    "---- progress/history.md",
+    corpus.history || "(sin historia registrada)",
+    "",
+    `---- backlog de features cerradas (${corpus.docs.length})`,
+    docs || "(sin documentos de backlog cerrados)"
+  ].join("\n");
+}
+function parseRetroPatterns(raw) {
+  const fenced = raw.match(/```(?:json)?\s*([\s\S]*?)```/);
+  const candidate = fenced?.[1] ?? raw;
+  const start = candidate.indexOf("{");
+  const end = candidate.lastIndexOf("}");
+  if (start === -1 || end <= start) {
+    return { patterns: [], discarded: 0 };
+  }
+  let data;
+  try {
+    data = JSON.parse(candidate.slice(start, end + 1));
+  } catch {
+    return { patterns: [], discarded: 0 };
+  }
+  const list = data?.patterns;
+  if (!Array.isArray(list)) {
+    return { patterns: [], discarded: 0 };
+  }
+  const patterns = [];
+  let discarded = 0;
+  for (const entry of list) {
+    if (!entry || typeof entry !== "object" || Array.isArray(entry)) {
+      discarded += 1;
+      continue;
+    }
+    const e = entry;
+    const titulo = typeof e.titulo === "string" ? e.titulo.trim() : "";
+    const features = Array.isArray(e.features) ? [...new Set(e.features.filter((f) => typeof f === "string" && f.length > 0))] : [];
+    if (!titulo || features.length < RETRO_MIN_EVIDENCE) {
+      discarded += 1;
+      continue;
+    }
+    patterns.push({
+      titulo,
+      tipo: e.tipo === "antipatron" ? "antipatron" : "patron",
+      features,
+      detalle: typeof e.detalle === "string" ? e.detalle : ""
+    });
+  }
+  if (patterns.length > RETRO_MAX_PATTERNS) {
+    discarded += patterns.length - RETRO_MAX_PATTERNS;
+    patterns.length = RETRO_MAX_PATTERNS;
+  }
+  return { patterns, discarded };
+}
+async function relayRetro(options) {
+  const { system, prompt, draft, onDelta, onResult, onError } = options;
+  try {
+    const result = await draft({ prompt, system }, onDelta);
+    const { patterns, discarded } = parseRetroPatterns(result.text);
+    onResult({ patterns, discarded, model: result.model });
+  } catch (error) {
+    if (error instanceof LlmError) {
+      onError(error);
+      return;
+    }
+    onError(new LlmError("provider_error", error instanceof Error ? error.message : String(error)));
+  }
+}
+export {
+  RETRO_EXCERPT_CHARS,
+  RETRO_MAX_PATTERNS,
+  RETRO_MIN_EVIDENCE,
+  composeRetroPrompt,
+  composeRetroSystem,
+  parseRetroPatterns,
+  readRetroCorpus,
+  relayRetro
+};

package/dist/toolbox_review_notes.js

@@ -0,0 +1,169 @@
+import { createRequire } from 'node:module'; const require = createRequire(import.meta.url);
+
+// ../packages/toolbox-core/dist/reviewNotes.js
+import { execFileSync } from "node:child_process";
+import { join as join3 } from "node:path";
+
+// ../packages/toolbox-core/dist/llm.js
+var LlmError = class extends Error {
+  code;
+  constructor(code, message) {
+    super(message);
+    this.name = "LlmError";
+    this.code = code;
+  }
+};
+
+// ../packages/toolbox-core/dist/state.js
+import { readdirSync, readFileSync as readFileSync2, statSync as statSync2 } from "node:fs";
+import { join as join2, resolve, sep } from "node:path";
+
+// ../packages/toolbox-core/dist/workspace.js
+import { readFileSync, statSync } from "node:fs";
+import { isAbsolute, join } from "node:path";
+function isFile(path) {
+  try {
+    return statSync(path).isFile();
+  } catch {
+    return false;
+  }
+}
+function readJsonSwallow(path) {
+  try {
+    return JSON.parse(readFileSync(path, "utf-8"));
+  } catch {
+    return void 0;
+  }
+}
+function usableWorkspaceValue(ws) {
+  return typeof ws === "string" && ws.length > 0;
+}
+function resolveAgainstRoot(root, ws) {
+  return isAbsolute(ws) ? ws : join(root, ws);
+}
+function resolveWorkspace(root) {
+  const configPath = join(root, "harness.config.json");
+  if (isFile(configPath)) {
+    const data = readJsonSwallow(configPath);
+    const ws = data && typeof data === "object" ? data.harness_workspace : void 0;
+    if (usableWorkspaceValue(ws)) {
+      return resolveAgainstRoot(root, ws);
+    }
+  }
+  const rootFeatureList = join(root, "feature_list.json");
+  if (isFile(rootFeatureList)) {
+    const data = readJsonSwallow(rootFeatureList);
+    const config = data && typeof data === "object" ? data.config : void 0;
+    const ws = config && typeof config === "object" ? config.harness_workspace : void 0;
+    if (usableWorkspaceValue(ws)) {
+      return resolveAgainstRoot(root, ws);
+    }
+  }
+  if (isFile(join(root, ".handyman", "feature_list.json"))) {
+    return join(root, ".handyman");
+  }
+  return root;
+}
+
+// ../packages/toolbox-core/dist/state.js
+var INTAKE_MAX_BYTES = 256 * 1024;
+var CSP_HEADER = "default-src 'self'; script-src 'self' 'unsafe-inline'; style-src 'self' 'unsafe-inline'; img-src 'self' data:; connect-src 'self'";
+var HTML_CSP_HEADER = CSP_HEADER.replace("img-src 'self' data:", "img-src 'self' data: https://picsum.photos");
+function readText(path) {
+  try {
+    return readFileSync2(path, "utf-8");
+  } catch {
+    return null;
+  }
+}
+var MD_TOKEN_PATHS = {
+  current: (workspace) => join2(workspace, "progress", "current.md"),
+  history: (workspace) => join2(workspace, "progress", "history.md"),
+  index: (workspace) => join2(workspace, "index.md"),
+  checkpoints: (_workspace, root) => join2(root, "CHECKPOINTS.md")
+};
+var MD_TOKENS = Object.keys(MD_TOKEN_PATHS);
+
+// ../packages/toolbox-core/dist/reviewNotes.js
+var REVIEW_DIFF_MAX_CHARS = 6e4;
+function readImplReport(workspace, feature) {
+  return readText(join3(workspace, "backlog", `impl_${feature}.md`));
+}
+function readFeatureDiff(root, maxChars = REVIEW_DIFF_MAX_CHARS) {
+  let raw;
+  try {
+    raw = execFileSync("git", ["diff", "HEAD"], {
+      cwd: root,
+      encoding: "utf-8",
+      maxBuffer: 32 * 1024 * 1024,
+      stdio: ["ignore", "pipe", "ignore"]
+    });
+  } catch {
+    return { diff: "", truncated: false };
+  }
+  if (raw.length <= maxChars) {
+    return { diff: raw, truncated: false };
+  }
+  return { diff: raw.slice(0, maxChars), truncated: true };
+}
+function composeReviewNotesSystem() {
+  return [
+    "Eres un asistente que prepara la revision de una feature en un harness Handyman.",
+    "Produces un CHECKLIST de revision en markdown: puntos criticos, invariantes en",
+    "riesgo y preguntas concretas que el reviewer debe verificar contra la evidencia.",
+    "",
+    "Reglas duras:",
+    "- Tu salida es un BORRADOR: el reviewer verifica TODO. Dilo en la primera linea.",
+    "- Escribes PREGUNTAS y PUNTOS A VERIFICAR, no conclusiones.",
+    "  Ej: '- invariante X respetada?', '- hay test que cubra el caso Y?'.",
+    "- NUNCA emites un veredicto: no escribas APPROVED ni CHANGES_REQUESTED ni",
+    "  equivalentes ('esta listo', 'se puede cerrar'). No es tu decision.",
+    "- NUNCA propongas un patch ni escribas codigo de reemplazo.",
+    "- Si el diff o el reporte no alcanzan para juzgar algo, dilo explicitamente",
+    "  ('no hay evidencia suficiente para X') en vez de suponer."
+  ].join("\n");
+}
+function composeReviewNotesPrompt(feature, implReport, diff, truncated) {
+  const parts = [`Feature bajo revision: ${feature}`, ""];
+  parts.push("---- reporte del implementer (backlog/impl_" + feature + ".md)");
+  parts.push(implReport ?? "(no hay reporte del implementer para esta feature)");
+  parts.push("");
+  parts.push("---- diff de trabajo (git diff HEAD)");
+  parts.push(diff.length > 0 ? diff : "(diff vacio o el root no es un repo git)");
+  if (truncated) {
+    parts.push("");
+    parts.push("[el diff fue truncado por tamano: senala que quedo sin revisar]");
+  }
+  return parts.join("\n");
+}
+function composeReviewNotesRequest(root, feature) {
+  const implReport = readImplReport(resolveWorkspace(root), feature);
+  const { diff, truncated } = readFeatureDiff(root);
+  return {
+    system: composeReviewNotesSystem(),
+    prompt: composeReviewNotesPrompt(feature, implReport, diff, truncated),
+    diffTruncated: truncated
+  };
+}
+async function relayReviewNotes(options) {
+  const { system, prompt, draft, diffTruncated, onDelta, onResult, onError } = options;
+  try {
+    const result = await draft({ prompt, system }, onDelta);
+    onResult({ checklist_md: result.text, model: result.model, diff_truncated: diffTruncated });
+  } catch (error) {
+    if (error instanceof LlmError) {
+      onError(error);
+      return;
+    }
+    onError(new LlmError("provider_error", error instanceof Error ? error.message : String(error)));
+  }
+}
+export {
+  REVIEW_DIFF_MAX_CHARS,
+  composeReviewNotesPrompt,
+  composeReviewNotesRequest,
+  composeReviewNotesSystem,
+  readFeatureDiff,
+  readImplReport,
+  relayReviewNotes
+};