@foldrun/core 1.4.2 → 2.1.0

package/src/translator.ts

@@ -22,7 +22,9 @@
 // and their results, streaming — and drops what a Chat-Completions endpoint
 // has no word for (cache_control, top_k, server-side tools, thinking on
 // endpoints that lack reasoning_effort). Anything dropped is said once in
-// the run trace. The translation is pure functions over JSON so the tests
+// the run trace. Those endpoints cache prompt prefixes on their own side;
+// the cached share they report comes back as cache_read_input_tokens, so a
+// step's record says how much of its context was re-read. The translation is pure functions over JSON so the tests
 // can drive every mapping without a network; the server around them is a
 // few dozen lines.
 
@@ -37,6 +39,34 @@ import { captureRefusalHeaders, isRefusalStatus, refusalLine } from "./refusal.t
 
 type Json = Record<string, unknown>;
 
+/**
+ * An OpenAI-shaped usage object as Anthropic's: fresh input, cached input,
+ * output. Both OpenAI shapes count the cached part INSIDE the prompt total
+ * (Chat's prompt_tokens_details.cached_tokens, Responses'
+ * input_tokens_details.cached_tokens; DeepSeek says prompt_cache_hit_tokens),
+ * so it is taken out of input here or the step would count it twice.
+ */
+export function anthropicUsage(u: Json | undefined, wire: TranslatorWire): { input: number; cached: number; output: number } {
+  if (!u) return { input: 0, cached: 0, output: 0 };
+  const total = Number((wire === "chat" ? u.prompt_tokens : u.input_tokens) ?? 0);
+  const details = (wire === "chat" ? u.prompt_tokens_details : u.input_tokens_details) as Json | undefined;
+  const raw = Number(details?.cached_tokens ?? u.prompt_cache_hit_tokens ?? 0);
+  const cached = Number.isFinite(raw) ? Math.max(0, Math.min(raw, total)) : 0;
+  return {
+    input: total - cached,
+    cached,
+    output: Number((wire === "chat" ? u.completion_tokens : u.output_tokens) ?? 0),
+  };
+}
+
+function usageBlock(u: { input: number; cached: number; output: number } | null): Json {
+  return {
+    input_tokens: u?.input ?? 0,
+    output_tokens: u?.output ?? 0,
+    ...(u && u.cached > 0 ? { cache_read_input_tokens: u.cached } : {}),
+  };
+}
+
 export type TranslatorWire = "chat" | "responses";
 
 export interface TranslatorSpec {
@@ -493,10 +523,7 @@ export function fromChatCompletion(res: Json, requestedModel: string, stopSequen
     content,
     stop_reason: stop.reason,
     stop_sequence: stop.sequence,
-    usage: {
-      input_tokens: Number(usage.prompt_tokens ?? 0),
-      output_tokens: Number(usage.completion_tokens ?? 0),
-    },
+    usage: usageBlock(anthropicUsage(usage, "chat")),
   };
 }
 
@@ -515,7 +542,7 @@ export class StreamTranslator {
   private tools = new Map<number, { block: number; argsSeen: boolean }>();
   /** The last choice's stop fields: finish_reason and any matched stop. */
   private finish: Json = {};
-  private usage: { input: number; output: number } | null = null;
+  private usage: { input: number; cached: number; output: number } | null = null;
   private id = `msg_${crypto.randomBytes(8).toString("hex")}`;
   private readonly model: string;
   private readonly stops: string[];
@@ -561,7 +588,7 @@ export class StreamTranslator {
     const out = this.start(chunk);
     const u = chunk.usage as Json | undefined;
     if (u && (u.prompt_tokens !== undefined || u.completion_tokens !== undefined)) {
-      this.usage = { input: Number(u.prompt_tokens ?? 0), output: Number(u.completion_tokens ?? 0) };
+      this.usage = anthropicUsage(u, "chat");
     }
     const choice = ((chunk.choices as Json[] | undefined) ?? [])[0];
     if (!choice) return out;
@@ -650,7 +677,7 @@ export class StreamTranslator {
       this.event("message_delta", {
         type: "message_delta",
         delta: { stop_reason: stop.reason, stop_sequence: stop.sequence },
-        usage: { input_tokens: this.usage?.input ?? 0, output_tokens: this.usage?.output ?? 0 },
+        usage: usageBlock(this.usage),
       }),
     );
     out.push(this.event("message_stop", { type: "message_stop" }));
@@ -691,10 +718,7 @@ export function fromResponses(res: Json, requestedModel: string): Json {
     content,
     stop_reason: stop,
     stop_sequence: null,
-    usage: {
-      input_tokens: Number(usage.input_tokens ?? 0),
-      output_tokens: Number(usage.output_tokens ?? 0),
-    },
+    usage: usageBlock(anthropicUsage(usage, "responses")),
   };
 }
 
@@ -710,7 +734,7 @@ export class ResponsesStreamTranslator {
   private nextIndex = 0;
   /** Responses output_index → Anthropic block index and kind. */
   private blocks = new Map<number, { block: number; kind: "text" | "tool"; argsSeen: boolean }>();
-  private usage: { input: number; output: number } | null = null;
+  private usage: { input: number; cached: number; output: number } | null = null;
   private incomplete: string | null = null;
   private sawTool = false;
   private sawRefusal = false;
@@ -812,7 +836,7 @@ export class ResponsesStreamTranslator {
     if (type === "response.completed" || type === "response.incomplete" || type === "response.failed") {
       const r = (ev.response as Json | undefined) ?? {};
       const u = r.usage as Json | undefined;
-      if (u) this.usage = { input: Number(u.input_tokens ?? 0), output: Number(u.output_tokens ?? 0) };
+      if (u) this.usage = anthropicUsage(u, "responses");
       const reason = (r.incomplete_details as Json | undefined)?.reason;
       if (typeof reason === "string") this.incomplete = reason;
       return out;
@@ -834,7 +858,7 @@ export class ResponsesStreamTranslator {
       this.event("message_delta", {
         type: "message_delta",
         delta: { stop_reason: reason, stop_sequence: null },
-        usage: { input_tokens: this.usage?.input ?? 0, output_tokens: this.usage?.output ?? 0 },
+        usage: usageBlock(this.usage),
       }),
     );
     out.push(this.event("message_stop", { type: "message_stop" }));

package/dist/src/git-hook.d.ts

@@ -1 +0,0 @@
-export {};

package/dist/src/git-hook.js

@@ -1,70 +0,0 @@
-// The pre-receive check, run by git inside a push.
-//
-// git feeds "<old> <new> <ref>" lines on stdin. For a push to main, read the
-// tree at the new commit straight from the object store and run the deploy
-// checks on it. Any issue: print them and exit non-zero — the push is refused
-// and the person sees exactly what a dashboard deploy would have told them,
-// in their terminal, before anything changed.
-//
-// Runs as its own process under git's environment. GIT_DIR is set by git.
-import fs from "node:fs";
-import path from "node:path";
-import { spawnSync } from "node:child_process";
-import { deployIssues, runsInFlight } from "./deploy.js";
-const dir = process.env.GIT_DIR;
-if (!dir)
-    process.exit(0);
-// `_library.git` is the account shelf, not a workspace: it holds tools,
-// skills and knowledge and has no agents by definition. The workspace rules
-// refused every push to it with "no agents". Its sync (syncLibraryFromTree)
-// validates what it accepts on receive; nothing here to add yet.
-// Inside a hook git sets GIT_DIR relative to the repo ("."), so resolve it
-// against the cwd before asking for its name.
-if (path.basename(path.resolve(process.cwd(), dir)) === "_library.git")
-    process.exit(0);
-const input = fs.readFileSync(0, "utf8");
-const git = (args) => {
-    const r = spawnSync("git", ["--git-dir", dir, ...args], { maxBuffer: 64 * 1024 * 1024 });
-    return r.status === 0 ? r.stdout.toString() : null;
-};
-// The client is gone by the time the deploy runs, so this is the only moment
-// a person can be told their push will not take effect yet. A warning, not a
-// refusal: the commit is fine and the scheduler applies it when the runs end.
-const here = path.basename(path.resolve(process.cwd(), dir));
-if (here.endsWith(".git")) {
-    const workspace = here.slice(0, -4);
-    const tenant = path.basename(path.resolve(process.cwd(), dir, "..", ".."));
-    try {
-        const live = runsInFlight(tenant, workspace);
-        if (live.length) {
-            process.stderr.write(`\nfoldrun: ${live.length} run${live.length === 1 ? " is" : "s are"} in flight, so this push is not live yet.\n` +
-                `  It is on main and will be applied automatically when they finish.\n\n`);
-        }
-    }
-    catch {
-        // A warning that cannot be computed must never fail a push.
-    }
-}
-let refused = false;
-for (const line of input.split("\n").filter(Boolean)) {
-    const [, newSha, ref] = line.split(" ");
-    if (ref !== "refs/heads/main" || /^0+$/.test(newSha))
-        continue;
-    const tree = git(["ls-tree", "-r", "--name-only", newSha]) ?? "";
-    const files = tree
-        .split("\n")
-        .filter(Boolean)
-        .flatMap((p) => {
-        const content = git(["show", `${newSha}:${p}`]);
-        return content === null ? [] : [{ path: p, content }];
-    });
-    const issues = deployIssues(files);
-    if (issues.length) {
-        refused = true;
-        process.stderr.write(`\nfoldrun: refusing this push — ${issues.length} problem${issues.length === 1 ? "" : "s"} the checks would have stopped at deploy:\n`);
-        for (const i of issues)
-            process.stderr.write(`  ${i.where}: ${i.message}\n`);
-        process.stderr.write(`\nFix and push again. (foldrun check runs the same rules locally.)\n\n`);
-    }
-}
-process.exit(refused ? 1 : 0);

package/dist/src/git.d.ts

@@ -1,37 +0,0 @@
-/**
- * The secret a repository signs its pushes with.
- *
- * Derived rather than stored, exactly like a flow's webhook token: HMAC of the
- * workspace's identity under the install key. Nothing new to persist, unique
- * per workspace, and rotating FOLDRUN_SECRET_KEY invalidates every connection
- * at once.
- */
-export declare function gitSecret(tenant: string, workspace: string): string;
-export declare function gitHookPath(tenant: string, workspace: string): string;
-/**
- * Whether a request really came from the repository it claims to.
- *
- * Compared in constant time: a byte-by-byte early return leaks the expected
- * signature to anyone willing to time enough requests. The raw body is
- * required — re-serializing parsed JSON changes bytes GitHub signed.
- */
-export declare function verifySignature(secret: string, rawBody: string, header: string | null): boolean;
-export interface PushEvent {
-    repo: string;
-    /** Full ref, e.g. refs/heads/main. */
-    ref: string;
-    branch: string;
-    commit: string;
-    message: string | null;
-    pusher: string | null;
-}
-/** What we need out of a GitHub push payload, or null if it isn't one. */
-export declare function parsePush(payload: unknown): PushEvent | null;
-/**
- * The repository at one commit, as a gzipped tarball.
- *
- * A token is only needed for a private repository. It is read from the
- * environment rather than taken as an argument so a caller cannot be tricked
- * into forwarding one somewhere else.
- */
-export declare function fetchTarball(repo: string, commit: string): Promise<Buffer>;

package/dist/src/git.js

@@ -1,101 +0,0 @@
-// git push → deployed.
-//
-// A workspace is markdown, so there is no build to run: a push is a fetch of
-// the tree at that commit, a check, and a swap. This module is the GitHub half
-// — the secret a repository signs with, the payload shape, and pulling the
-// tarball. `deploy.ts` decides whether the result is allowed to go live.
-//
-// The tarball, not a clone: one HTTP call, no git binary, no working copy kept
-// on the server. A markdown workspace is a few hundred kilobytes.
-import crypto from "node:crypto";
-import { installKey } from "./webhook.js";
-/** GitHub refuses to fetch anything larger, and neither should we. */
-const MAX_TARBALL = 25 * 1024 * 1024;
-/**
- * The secret a repository signs its pushes with.
- *
- * Derived rather than stored, exactly like a flow's webhook token: HMAC of the
- * workspace's identity under the install key. Nothing new to persist, unique
- * per workspace, and rotating FOLDRUN_SECRET_KEY invalidates every connection
- * at once.
- */
-export function gitSecret(tenant, workspace) {
-    return crypto
-        .createHmac("sha256", installKey())
-        .update(`git/${tenant}/${workspace}`)
-        .digest("hex");
-}
-export function gitHookPath(tenant, workspace) {
-    return `/api/git/${tenant}/${workspace}`;
-}
-/**
- * Whether a request really came from the repository it claims to.
- *
- * Compared in constant time: a byte-by-byte early return leaks the expected
- * signature to anyone willing to time enough requests. The raw body is
- * required — re-serializing parsed JSON changes bytes GitHub signed.
- */
-export function verifySignature(secret, rawBody, header) {
-    if (!header)
-        return false;
-    const expected = `sha256=${crypto.createHmac("sha256", secret).update(rawBody).digest("hex")}`;
-    const a = Buffer.from(expected);
-    const b = Buffer.from(header);
-    return a.length === b.length && crypto.timingSafeEqual(a, b);
-}
-/** What we need out of a GitHub push payload, or null if it isn't one. */
-export function parsePush(payload) {
-    if (!payload || typeof payload !== "object")
-        return null;
-    const p = payload;
-    const repo = p.repository?.full_name;
-    const ref = p.ref;
-    const commit = p.after;
-    if (typeof repo !== "string" || typeof ref !== "string" || typeof commit !== "string") {
-        return null;
-    }
-    // A deleted branch reports all zeros and ships no tree.
-    if (/^0+$/.test(commit))
-        return null;
-    return {
-        repo,
-        ref,
-        branch: ref.replace(/^refs\/heads\//, ""),
-        commit,
-        message: typeof p.head_commit?.message === "string" ? p.head_commit.message : null,
-        pusher: typeof p.pusher?.name === "string" ? p.pusher.name : null,
-    };
-}
-/**
- * The repository at one commit, as a gzipped tarball.
- *
- * A token is only needed for a private repository. It is read from the
- * environment rather than taken as an argument so a caller cannot be tricked
- * into forwarding one somewhere else.
- */
-export async function fetchTarball(repo, commit) {
-    if (!/^[\w.-]+\/[\w.-]+$/.test(repo))
-        throw new Error(`refusing to fetch "${repo}"`);
-    if (!/^[0-9a-f]{7,40}$/i.test(commit))
-        throw new Error(`refusing to fetch commit "${commit}"`);
-    const headers = {
-        accept: "application/vnd.github+json",
-        "user-agent": "foldrun",
-        "x-github-api-version": "2022-11-28",
-    };
-    const token = process.env.GITHUB_TOKEN;
-    if (token)
-        headers.authorization = `Bearer ${token}`;
-    const res = await fetch(`https://api.github.com/repos/${repo}/tarball/${commit}`, { headers });
-    if (!res.ok) {
-        throw new Error(`GitHub returned ${res.status} for ${repo}@${commit.slice(0, 8)}` +
-            (res.status === 404 && !token
-                ? " — a private repository needs GITHUB_TOKEN set on the server"
-                : ""));
-    }
-    const buf = Buffer.from(await res.arrayBuffer());
-    if (buf.length > MAX_TARBALL) {
-        throw new Error(`${repo} is ${Math.round(buf.length / 1e6)}MB — too large to deploy`);
-    }
-    return buf;
-}

package/dist/src/gitrepo.d.ts

@@ -1,113 +0,0 @@
-import type { DiffOp, Revision, RevisionFile, RevisionSummary } from "./history.ts";
-/** Where a workspace's bare repository lives. `@library` is the account shelf. */
-export declare function repoDir(tenant: string, scope: string): string;
-/** Is there a git binary? Checked once; an install without one keeps the journal. */
-export declare function gitAvailable(): boolean;
-export declare function repoExists(tenant: string, scope: string): boolean;
-/** Create the repository if it is not there. Idempotent. */
-export declare function ensureRepo(tenant: string, scope: string): string;
-export declare function headSha(tenant: string, scope: string, ref?: string): string | null;
-/**
- * Apply a change set as one commit on main, using plumbing against a scratch
- * index seeded from HEAD. No working copy, no checkout: each changed path is
- * hashed straight from its content into the object store.
- *
- * Returns the new commit, or null when the tree did not change.
- */
-export declare function commitChanges(tenant: string, scope: string, files: RevisionFile[], meta?: {
-    by?: string;
-    message?: string;
-    at?: string;
-}): string | null;
-/** Commits on main, newest first, as the same summary the journal gave. */
-export declare function listCommits(tenant: string, scope: string, opts?: {
-    forPath?: string;
-    limit?: number;
-    ref?: string;
-}): RevisionSummary[];
-/** One commit in full: every changed file with its before and after. */
-export declare function readCommit(tenant: string, scope: string, sha: string, forPath?: string): Revision | null;
-export interface RefInfo {
-    name: string;
-    sha: string;
-    /** Commit subject and time, for a branch list that says what each is. */
-    subject: string;
-    at: string;
-}
-export declare function listRefs(tenant: string, scope: string, kind: "heads" | "tags"): RefInfo[];
-/**
- * The commit a restore means by `to`, on main's history:
- *
- *   a sha or a prefix of one      that commit
- *   a branch or tag name          where it points
- *   an ISO date or time           the last commit on main at or before it
- *   "3d", "12h", "90m", "2w"      the same, that long ago
- *
- * Null when nothing matches — before the first commit, or a name that is
- * not there. Throws on a `to` that cannot be any of these, so a typo is a
- * 400 rather than a silent "nothing found".
- */
-export declare function resolveRestorePoint(tenant: string, scope: string, to: string, now?: number): {
-    sha: string;
-    at: string;
-    by: string;
-    message: string;
-} | null;
-/** The files at a commit, for a browser or a deploy. */
-export declare function listTree(tenant: string, scope: string, ref?: string): {
-    path: string;
-    mode: string;
-}[];
-export declare function readBlob(tenant: string, scope: string, ref: string, p: string): string | null;
-/** The whole tree at a ref as deploy files — what a push turns into a workspace. */
-export declare function filesAt(tenant: string, scope: string, ref: string): {
-    path: string;
-    content: string;
-}[];
-/**
- * What a ref would change on main: every file that differs, with both sides.
- * The branch's own commits are `listCommits({ ref })`; this is the net
- * effect, which is what a reviewer reads.
- */
-export declare function diffRefs(tenant: string, scope: string, base: string, head: string): RevisionFile[];
-/**
- * Merge a branch into main and return the new main. A fast-forward when it
- * is one; otherwise a merge commit whose tree is the BRANCH's — the branch
- * is what the person reviewed and chose, and a three-way textual merge of
- * markdown with no one to resolve conflicts would deploy text nobody wrote.
- * Both parents are recorded, so history shows the merge for what it was.
- */
-export declare function mergeBranch(tenant: string, scope: string, branch: string, meta?: {
-    by?: string;
-}): {
-    sha: string;
-    fastForward: boolean;
-};
-export declare function deleteBranch(tenant: string, scope: string, branch: string): void;
-/** Push main to another remote — a GitHub or GitLab mirror. Blocking; callers
- *  run it off the request path. The token never touches disk: it is in the
- *  URL for this one process and nowhere else. */
-export declare function pushMirror(tenant: string, scope: string, url: string): {
-    ok: boolean;
-    detail: string;
-};
-/**
- * Where the compiled pre-receive check is, found on disk rather than through
- * require.resolve — a bundler rewrites require.resolve("pkg") into a module
- * id, and the hook was once told to run a script called "51113". Searched
- * from the working directory upward: the monorepo layout, then an installed
- * package. Empty when there is no compiled check (a dev server on the source
- * tree), in which case a push is checked at deploy instead of refused — the
- * same rules, one step later.
- */
-export declare function hookScriptPath(): string;
-/**
- * The pre-receive hook: a push that fails the deploy checks is refused with
- * the errors in the pusher's terminal, instead of accepted and then not
- * deployed. The hook shells out to node with the compiled check, so it runs
- * the same rules as a dashboard deploy; which node and which script are
- * passed in the environment by the HTTP route, because a hook inherits git's
- * environment and nothing else.
- */
-export declare function installHooks(dir: string): void;
-export { type DiffOp };