@clemrig/factory 0.0.0-stage → 0.1.0

package/dist/ui/static/timeline.js

@@ -0,0 +1,180 @@
+// @ts-check
+/**
+ * The dashboard's pure logic: a run's events grouped into one block per stage
+ * execution, and the formats of durations and costs. Served as is to the browser.
+ */
+
+/** @typedef {import("../../engine/types.js").RunEvent} RunEvent */
+/** @typedef {import("../../engine/types.js").AgentActivity} AgentActivity */
+/** @typedef {import("../../engine/metrics.js").TokenCounts} TokenCounts */
+/** @typedef {import("../../engine/metrics.js").AgentUsage} AgentUsage */
+
+/**
+ * @typedef {object} Call
+ * @property {string} [runtime]
+ * @property {string} [model]
+ * @property {string} [session]
+ * @property {"running" | "completed" | "failed"} status
+ * @property {AgentUsage} [usage] As the runtime announced it at the end of the call.
+ * @property {"call" | "session"} [scope] Whether `usage` is the call's own or its session's total.
+ */
+
+/**
+ * @typedef {object} Tool
+ * @property {string} id
+ * @property {string} name
+ * @property {"running" | "completed" | "failed"} status
+ * @property {number} [durationMs]
+ */
+
+/**
+ * @typedef {object} Block
+ * @property {string} stage
+ * @property {string} kind
+ * @property {"running" | "passed" | "failed" | "completed"} status
+ * @property {string} startedAt
+ * @property {number | null} durationMs
+ * @property {{ verdict: string; reason: string; destination: string | null }} [decision]
+ * @property {{ key: string; count: number; max: number }} [retry]
+ * @property {string} [detail]
+ * @property {Call} [call]
+ * @property {Tool[]} tools
+ * @property {TokenCounts | null} tokens The call's responses so far.
+ * @property {boolean} provisional Whether `tokens` includes figures replaced at the end of the call.
+ * @property {string[]} warnings
+ * @property {{ at: string; message: string }[]} journal
+ */
+
+/**
+ * @param {string} stage
+ * @param {string} kind
+ * @param {string} at
+ * @returns {Block}
+ */
+const block = (stage, kind, at) => ({
+  stage,
+  kind,
+  status: "running",
+  startedAt: at,
+  durationMs: null,
+  tools: [],
+  tokens: null,
+  provisional: false,
+  warnings: [],
+  journal: [],
+});
+
+/**
+ * @param {Block} target
+ * @param {AgentActivity} activity
+ */
+function apply(target, activity) {
+  switch (activity.kind) {
+    case "call":
+      if (activity.status === "started") {
+        const { runtime, model, session } = activity;
+        target.call = { runtime, model, session, status: "running" };
+      } else
+        target.call = {
+          ...target.call,
+          runtime: activity.runtime,
+          status: activity.status,
+          usage: activity.usage,
+          scope: activity.scope,
+        };
+      break;
+    case "tool": {
+      const tool = target.tools.find(({ id }) => id === activity.id);
+      const update =
+        activity.status === "started"
+          ? { id: activity.id, name: activity.name, status: "running" }
+          : {
+              id: activity.id,
+              name: activity.name,
+              status: activity.status,
+              durationMs: activity.durationMs,
+            };
+      if (tool) Object.assign(tool, update);
+      else target.tools.push(/** @type {Tool} */ (update));
+      break;
+    }
+    case "response": {
+      const sum = target.tokens ?? {
+        input: 0,
+        output: 0,
+        cacheRead: 0,
+        cacheWrite: 0,
+      };
+      for (const field of /** @type {const} */ ([
+        "input",
+        "output",
+        "cacheRead",
+        "cacheWrite",
+      ]))
+        sum[field] += activity.tokens[field];
+      target.tokens = sum;
+      target.provisional ||= activity.provisional;
+      break;
+    }
+    case "warning":
+      target.warnings.push(activity.message);
+  }
+}
+
+/**
+ * One block per stage execution, in order: a stage's journal, agent activity
+ * and decision go to its latest block.
+ * @param {RunEvent[]} events
+ * @returns {Block[]}
+ */
+export function timeline(events) {
+  /** @type {Block[]} */
+  const blocks = [];
+  const latest = (/** @type {string} */ stage) =>
+    blocks.findLast((candidate) => candidate.stage === stage);
+  for (const event of events) {
+    if (event.type === "stage" && event.status === "started") {
+      blocks.push(block(event.stage, event.kind, event.at));
+      continue;
+    }
+    let target = latest(event.stage);
+    if (!target || (event.type === "stage" && target.status !== "running")) {
+      // A stage reported without a start, such as one failed by an interruption.
+      target = block(event.stage, event.kind, event.at);
+      blocks.push(target);
+    }
+    if (event.type === "stage") {
+      target.status = event.status === "started" ? "running" : event.status;
+      target.durationMs = Date.parse(event.at) - Date.parse(target.startedAt);
+      if (event.decision) target.decision = event.decision;
+      if (event.retry) target.retry = event.retry;
+      if (event.detail) target.detail = event.detail;
+    } else if (event.type === "log")
+      target.journal.push({ at: event.at, message: event.message });
+    else apply(target, event.activity);
+  }
+  return blocks;
+}
+
+/**
+ * @param {number | null} ms
+ * @returns {string}
+ */
+export function duration(ms) {
+  if (ms === null) return "—";
+  const seconds = Math.floor(ms / 1000);
+  const hours = Math.floor(seconds / 3600);
+  const minutes = Math.floor((seconds % 3600) / 60);
+  return `${hours ? `${hours} h ` : ""}${minutes} min ${seconds % 60} s`;
+}
+
+/**
+ * An estimated cost as the runtimes announced it; unknown without any measure.
+ * @param {number | null} usd
+ * @param {boolean} partial Some agent call announced no usage.
+ * @returns {string}
+ */
+export function cost(usd, partial) {
+  const value = usd === null ? "—" : `${usd.toFixed(4)} USD`;
+  return partial ? `${value} (partial)` : value;
+}

package/package.json

@@ -1,6 +1,54 @@
 {
   "name": "@clemrig/factory",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "description": "Write agent workflows in TypeScript inside any repository, run them in the terminal and watch them in a local dashboard",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/clementchesneau/clemrig-factory-v2.git"
+  },
+  "type": "module",
+  "bin": {
+    "factory": "dist/main.js"
+  },
+  "exports": {
+    ".": {
+      "default": "./dist/index.js"
+    },
+    "./cli": {
+      "default": "./dist/cli/application.js"
+    }
+  },
+  "files": [
+    "dist",
+    "templates"
+  ],
+  "engines": {
+    "node": ">=24"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "node -e \"require('node:fs').rmSync('dist',{recursive:true,force:true})\" && tsc -p tsconfig.build.json && node -e \"require('node:fs').cpSync('src/ui/static','dist/ui/static',{recursive:true})\"",
+    "typecheck": "tsc --noEmit && tsc --noEmit -p tsconfig.ui.json",
+    "lint": "biome lint --error-on-warnings .",
+    "format": "biome format .",
+    "format:write": "biome format --write .",
+    "test": "vitest run",
+    "test:coverage": "vitest run --coverage",
+    "check": "npm run lint && npm run format && npm run typecheck && npm run test:coverage && npm run build",
+    "prepack": "npm run build"
+  },
+  "dependencies": {
+    "zod": "4.6.5"
+  },
+  "devDependencies": {
+    "@biomejs/biome": "2.5.15",
+    "@types/node": "24.19.1",
+    "@vitest/coverage-v8": "5.0.3",
+    "tsx": "4.23.15",
+    "typescript": "7.0.2",
+    "vitest": "5.0.3"
+  }
+}

package/templates/init/factory.ts

@@ -0,0 +1,4 @@
+import ask from "./workflows/ask/index.ts";
+
+/** The workflows of this repository, run with `factory run <name>`. */
+export default [ask];

package/templates/init/gitignore

@@ -0,0 +1,3 @@
+node_modules/
+runs/
+.env

package/templates/init/tsconfig.json

@@ -0,0 +1,13 @@
+{
+  "compilerOptions": {
+    "target": "ES2023",
+    "module": "NodeNext",
+    "moduleResolution": "NodeNext",
+    "strict": true,
+    "noEmit": true,
+    "allowImportingTsExtensions": true,
+    "verbatimModuleSyntax": true,
+    "erasableSyntaxOnly": true,
+    "skipLibCheck": true
+  }
+}

package/templates/init/workflows/ask/index.ts

@@ -0,0 +1,57 @@
+import {
+  agent,
+  defineWorkflow,
+  END,
+  node,
+  pick,
+  retry,
+  runProcess,
+  schemaGate,
+  step,
+  z,
+} from "@clemrig/factory";
+
+const answer = z.strictObject({ answer: z.string().min(1) });
+
+/** Answers a question about this repository from its recent commits. */
+export default defineWorkflow({
+  name: "ask",
+  input: z.object({ question: z.string().min(1) }),
+  initial: "commits",
+  nodes: {
+    // CODE: deterministic work in the repository.
+    commits: node(
+      step(async ({ dir }) => {
+        const log = await runProcess(
+          ["git", "log", "--oneline", "-n", "10"],
+          dir,
+          30_000,
+        );
+        if (log.exitCode !== 0)
+          throw new Error(`git log failed: ${log.stderr.trim()}`);
+        return { commits: log.stdout.trim().split("\n").filter(Boolean) };
+      }),
+      { ok: "answer" },
+    ),
+    // AGENT: prompts/answer.md, with the question and the commits as context.
+    // Read-only by default: its tools can read the repository, not change it.
+    answer: node(
+      agent({
+        profile: {
+          runtime: "claude-code",
+          model: "claude-sonnet-5-5",
+          thinking: "low",
+          tools: ["Read", "Grep", "Glob"],
+        },
+        schema: answer,
+        context: pick("input", "commits"),
+      }),
+      { ok: "check" },
+    ),
+    // GATE: an invalid answer goes back to the agent with feedback, at most 3 times.
+    check: node(schemaGate({ schema: answer, into: "answer" }), {
+      ok: END,
+      invalid: retry("answer", 3),
+    }),
+  },
+});

package/templates/init/workflows/ask/prompts/answer.md

@@ -0,0 +1,7 @@
+You answer the operator's question about this repository.
+
+- The context holds the question (`input.question`) and the ten most recent commits (`commits`).
+- Read files with your tools when the commits are not enough.
+- Answer in a few sentences, in the language of `input.question`, whatever language the rest of the context suggests.
+- When the context holds `feedback`, your previous answer was refused: correct what it describes.
+- Return `{"answer": "…"}`.