@foldrun/core 0.2.0 → 0.4.0

package/README.md

@@ -1,5 +1,9 @@
 # foldrun
 
+[![ci](https://github.com/foldrun-io/foldrun-core/actions/workflows/ci.yml/badge.svg)](https://github.com/foldrun-io/foldrun-core/actions/workflows/ci.yml)
+[![npm](https://img.shields.io/npm/v/@foldrun/core)](https://www.npmjs.com/package/@foldrun/core)
+[![licence](https://img.shields.io/badge/licence-Apache--2.0-blue)](LICENSE)
+
 **Agents are just folders. Write them, check them, run them.**
 
 An agent is a folder. Its instructions, skills, knowledge, memory, tools and
@@ -184,19 +188,36 @@ a hand-edited template cannot ship an index that disagrees with its own files.
 ## Hosting it
 
 This package is the framework: everything needed to read a workspace and
-run it on the machine you are on. The hosted platform at
-[foldrun.io](https://foldrun.io) — a queue and its worker, one gVisor pod
-per step, a vault, metering, a team — is built on it, in a separate private
-package that plugs in through `src/platform.ts`. Nothing in this repository
-imports it, so what is here is exactly what is open. There is no
-self-hosted platform; `foldrun deploy` and `git push` move a workspace from
-your machine to the hosted one unchanged.
+run it on the machine you are on. The platform — the dashboard, a queue and
+its worker, one sandbox per step, a vault, metering, a team — is built on
+it, in a separate package that plugs in through `src/platform.ts`. Nothing
+in this repository imports it, so what is here is exactly what is open.
+
+**Run the platform yourself:** one container, one command —
+[self-hosting/](self-hosting/). Sign up at `localhost:3900`, and
+`foldrun deploy` moves a workspace from your machine to it unchanged. The
+images are the same builds that run foldrun's own installation, published
+under the same versions.
 
 ## Requirements
 
-Node 22+. Docker or Podman if your agents run scripts. Credentials come from
-`ANTHROPIC_API_KEY` or an existing Claude Code login — `foldrun check` needs
-neither.
+Node 22+. Docker or Podman if your agents run scripts. `foldrun check` needs
+no credential at all.
+
+To *run* an agent you need one of:
+
+- **`ANTHROPIC_API_KEY`** — an API key from
+  [console.anthropic.com](https://console.anthropic.com).
+- **Your own provider.** An agent that names a `provider:` needs no
+  Anthropic key: 29 endpoints are known by name, including `ollama`,
+  `lmstudio` and `vllm`, so a local model is a complete answer. Anything
+  not in that list works by spelling out `base_url:`, `format:` and
+  `auth:`. See [providers](https://docs.foldrun.io/providers).
+
+A **Claude Code or claude.ai subscription login is not one of them**, and
+the CLI will not look for one. Anthropic does not permit products built on
+its Agent SDK to run on consumer subscriptions, so using that login here
+would put you outside their terms — an API key is the supported path.
 
 ## Status
 

package/dist/src/approvals.d.ts

@@ -1,4 +1,4 @@
-import { type RunRecord } from "./store.ts";
+import { type FlowInfo, type RunRecord } from "./store.ts";
 export interface ApprovalDecision {
     decision: "approve" | "reject";
     /** Guidance for the step being approved — rides the record into its prompt. */
@@ -9,7 +9,97 @@ export interface ApprovalDecision {
     step?: number;
     /** Who decided, as it reads after the verb: "by a human", "via emailed link". */
     by: string;
+    /**
+     * The person behind the decision, when a session made it: their email and
+     * the role they hold. A link and an external event have neither, and are
+     * checked by their token instead — the token IS the authority there.
+     *
+     * Two rules read this. `approvers:` in the flow file names who may decide
+     * that flow's gates at all. And nobody approves a run they started
+     * themselves: a gate exists so that a second person looks, and a flow a
+     * person kicked off and then waved through is a gate that never happened.
+     */
+    actor?: {
+        email?: string | null;
+        role?: string | null;
+    } | null;
+    /**
+     * The emailed link's token, when a link is deciding. Read here rather
+     * than trusted from the route, because what a link may decide is policy:
+     * the step it was minted for, before it expires, once, and never a gate
+     * whose flow names its approvers unless the link was minted for one of
+     * them. See readApproveLink.
+     */
+    link?: string;
 }
+/** How long an emailed link decides for when the flow does not say. */
+export declare const APPROVE_LINK_DEFAULT_TTL_MS: number;
+/** What a link may decide: one step, until a moment, as somebody or as
+ *  nobody. A `run` link is the older kind — bound to the run alone, and
+ *  kept working, once, for runs that were already waiting when this
+ *  changed. */
+export type ApproveLink = {
+    kind: "step";
+    step: number;
+    expiresAt: string;
+    approver: string | null;
+} | {
+    kind: "run";
+};
+/** The link's lifetime: the flow's `approve_within:` when it has one —
+ *  after that the gate has expired on its own — else a week. */
+export declare function approveLinkTtlMs(flow: Pick<FlowInfo, "approveWithin"> | null | undefined): number;
+/**
+ * The token an emailed link carries. Bound to one step of one run and to
+ * a moment, and — when the notification went to a named approver — to
+ * that person, so the link decides as them. A link that was only bound
+ * to the run approved every later gate of that run for as long as it ran,
+ * and a forwarded one let anyone past `approvers:`.
+ *
+ * `step.expires.approver.signature`; the signature covers all of it plus
+ * the run's identity, under the install key, so rotating the key kills
+ * every link at once, the way it kills every hook.
+ */
+export declare function approveLinkToken(tenant: string, workspace: string, runId: string, link: {
+    step: number;
+    expiresAt: number;
+    approver?: string | null;
+}): string;
+/** The path an emailed link opens — absolute when the caller prefixes the
+ *  install's public origin. `decision=reject` pre-selects; a GET never
+ *  decides. */
+export declare function approveLinkPath(tenant: string, workspace: string, runId: string, link: {
+    step: number;
+    expiresAt: number;
+    approver?: string | null;
+}): string;
+/**
+ * What a presented token is, or why it is nothing. 401 for a token that
+ * was never minted for this run, 410 for one that was and has expired —
+ * the second deserves a sentence, because the person holding it did
+ * nothing wrong.
+ */
+export declare function readApproveLink(tenant: string, workspace: string, runId: string, presented: string, now?: number): {
+    link: ApproveLink;
+} | {
+    error: string;
+    status: 401 | 410;
+};
+/**
+ * Everything a link has to pass before it decides anything, answered the
+ * same way for the page that shows the gate and the POST that decides it.
+ * Returns which waiting steps the link may decide and who it decides as.
+ */
+export declare function checkApproveLink(tenant: string, workspace: string, run: RunRecord, presented: string, now?: number): {
+    ok: true;
+    link: ApproveLink;
+    steps: number[];
+    approver: string | null;
+} | {
+    ok: false;
+    status: number;
+    message: string;
+};
 /**
  * Apply a decision to every step the run is waiting on, and line the run up
  * again if a worker had parked it. Returns the record as written and which
@@ -23,6 +113,19 @@ export declare function decideApproval(tenant: string, workspace: string, runId:
     run: RunRecord;
     steps: number[];
 }>;
+/**
+ * A gate that ran out of time. `approve_within:` in the flow file stamps a
+ * deadline when the run parks; past it, the gate is rejected and the run
+ * fails, exactly as if a person had said no.
+ *
+ * Rejection, not approval, is the only safe way for a clock to answer a
+ * question a person was asked. The whole reason the step is parked is that
+ * someone wanted to look at it first.
+ *
+ * Returns whether it acted. Called from the same sweep that closes abandoned
+ * runs, so an expiry needs nothing running of its own.
+ */
+export declare function expireStaleGate(tenant: string, workspace: string, run: RunRecord, now?: number): Promise<boolean>;
 /**
  * Release a run parked on `wait: event` with what arrived. The payload is
  * stored on the step — not as an approval note, which is a person's

package/dist/src/approvals.js

@@ -9,8 +9,125 @@
 // or a run approved from a phone would resume differently from one approved
 // at a desk. So the decision lives in core and the routes only say who made
 // it.
-import { readRun, writeRun } from "./store.js";
+import crypto from "node:crypto";
+import { readRun, writeRun, readFlow, mayApprove } from "./store.js";
 import { platform } from "./platform.js";
+import { approveToken, installKey } from "./webhook.js";
+// ----------------------------------------------------------------- links
+/** How long an emailed link decides for when the flow does not say. */
+export const APPROVE_LINK_DEFAULT_TTL_MS = 7 * 24 * 60 * 60 * 1000;
+/** The link's lifetime: the flow's `approve_within:` when it has one —
+ *  after that the gate has expired on its own — else a week. */
+export function approveLinkTtlMs(flow) {
+    return flow?.approveWithin ? flow.approveWithin * 1000 : APPROVE_LINK_DEFAULT_TTL_MS;
+}
+const b64 = (s) => Buffer.from(s, "utf8").toString("base64url");
+const unb64 = (s) => Buffer.from(s, "base64url").toString("utf8");
+function signLink(tenant, workspace, runId, step, expires, approver) {
+    return crypto
+        .createHmac("sha256", installKey())
+        .update(`approve-link:${tenant}/${workspace}/${runId}/${step}/${expires}/${approver}`)
+        .digest("hex")
+        .slice(0, 32);
+}
+/**
+ * The token an emailed link carries. Bound to one step of one run and to
+ * a moment, and — when the notification went to a named approver — to
+ * that person, so the link decides as them. A link that was only bound
+ * to the run approved every later gate of that run for as long as it ran,
+ * and a forwarded one let anyone past `approvers:`.
+ *
+ * `step.expires.approver.signature`; the signature covers all of it plus
+ * the run's identity, under the install key, so rotating the key kills
+ * every link at once, the way it kills every hook.
+ */
+export function approveLinkToken(tenant, workspace, runId, link) {
+    const approver = (link.approver ?? "").trim().toLowerCase();
+    const expires = Math.floor(link.expiresAt);
+    return `${link.step}.${expires}.${approver ? b64(approver) : "-"}.${signLink(tenant, workspace, runId, link.step, expires, approver)}`;
+}
+/** The path an emailed link opens — absolute when the caller prefixes the
+ *  install's public origin. `decision=reject` pre-selects; a GET never
+ *  decides. */
+export function approveLinkPath(tenant, workspace, runId, link) {
+    return `/api/approve/${tenant}/${workspace}/${runId}?token=${approveLinkToken(tenant, workspace, runId, link)}`;
+}
+const same = (a, b) => a.length === b.length && crypto.timingSafeEqual(Buffer.from(a), Buffer.from(b));
+/**
+ * What a presented token is, or why it is nothing. 401 for a token that
+ * was never minted for this run, 410 for one that was and has expired —
+ * the second deserves a sentence, because the person holding it did
+ * nothing wrong.
+ */
+export function readApproveLink(tenant, workspace, runId, presented, now = Date.now()) {
+    const invalid = { error: "invalid token", status: 401 };
+    if (!presented)
+        return invalid;
+    const parts = presented.split(".");
+    if (parts.length === 4) {
+        const [stepText, expText, approverText, sig] = parts;
+        if (!/^\d+$/.test(stepText) || !/^\d+$/.test(expText))
+            return invalid;
+        let approver = "";
+        try {
+            approver = approverText === "-" ? "" : unb64(approverText);
+        }
+        catch {
+            return invalid;
+        }
+        const step = Number(stepText);
+        const expires = Number(expText);
+        if (!same(sig, signLink(tenant, workspace, runId, step, expires, approver)))
+            return invalid;
+        if (now >= expires)
+            return { error: "this link has expired — open the run in the dashboard to decide it", status: 410 };
+        return { link: { kind: "step", step, expiresAt: new Date(expires).toISOString(), approver: approver || null } };
+    }
+    if (same(presented, approveToken(tenant, workspace, runId)))
+        return { link: { kind: "run" } };
+    return invalid;
+}
+/** A used link is written on the run as a digest, never the token. */
+const linkDigest = (token) => crypto.createHash("sha256").update(token).digest("hex").slice(0, 24);
+/**
+ * Everything a link has to pass before it decides anything, answered the
+ * same way for the page that shows the gate and the POST that decides it.
+ * Returns which waiting steps the link may decide and who it decides as.
+ */
+export function checkApproveLink(tenant, workspace, run, presented, now = Date.now()) {
+    const read = readApproveLink(tenant, workspace, run.id, presented, now);
+    if ("error" in read)
+        return { ok: false, status: read.status, message: read.error };
+    const { link } = read;
+    if (run.approvalLinksUsed?.includes(linkDigest(presented))) {
+        return { ok: false, status: 409, message: "this link was already used — a link decides once" };
+    }
+    // The older, run-bound link: kept for runs already waiting, but not for
+    // longer than a new link would have been.
+    if (link.kind === "run") {
+        const since = Date.parse(run.parkedAt ?? run.startedAt);
+        if (Number.isFinite(since) && now - since > APPROVE_LINK_DEFAULT_TTL_MS) {
+            return { ok: false, status: 410, message: "this link has expired — open the run in the dashboard to decide it" };
+        }
+    }
+    const waiting = run.steps
+        .map((s, i) => ({ s, i }))
+        .filter(({ s, i }) => s.status === "awaiting-approval" && s.waitFor !== "event" && (link.kind === "run" || i === link.step))
+        .map(({ i }) => i);
+    const approver = link.kind === "step" ? link.approver : null;
+    // A flow that names its approvers is asking for a person; a link is a
+    // possession. Only a link minted for one of the named approvers carries
+    // enough of an identity to be checked against the list.
+    const flow = readFlow(tenant, workspace, run.flow);
+    if (flow?.approvers?.length && !approver) {
+        return {
+            ok: false,
+            status: 403,
+            message: `this flow names who may approve it (${flow.approvers.join(", ")}), and an emailed link carries no identity — sign in to the dashboard to decide it`,
+        };
+    }
+    return { ok: true, link, steps: waiting, approver };
+}
 /** An error the HTTP layer can map straight to a status — see errorResponse. */
 class ApprovalError extends Error {
     status;
@@ -32,9 +149,19 @@ export async function decideApproval(tenant, workspace, runId, d) {
     const run = readRun(tenant, workspace, runId);
     if (!run)
         throw new ApprovalError("run not found", 404);
+    // A link decides what it was minted for, as whom it was minted for.
+    let allowed = null;
+    if (d.link !== undefined) {
+        const check = checkApproveLink(tenant, workspace, run, d.link);
+        if (!check.ok)
+            throw new ApprovalError(check.message, check.status);
+        allowed = check.steps;
+        d = { ...d, actor: check.approver ? { email: check.approver, role: null } : null };
+    }
+    assertMayDecide(tenant, workspace, run, d);
     const waiting = run.steps
         .map((s, i) => ({ s, i }))
-        .filter(({ s, i }) => s.status === "awaiting-approval" && (d.step === undefined || d.step === i));
+        .filter(({ s, i }) => s.status === "awaiting-approval" && (d.step === undefined || d.step === i) && (allowed === null || allowed.includes(i)));
     if (waiting.length === 0)
         throw new ApprovalError("nothing is awaiting approval", 409);
     const note = typeof d.note === "string" ? d.note.trim() : "";
@@ -62,6 +189,17 @@ export async function decideApproval(tenant, workspace, runId, d) {
                 : `rejected ${d.by}${reason ? `: ${reason.slice(0, 200)}` : ""}`,
         });
     }
+    // The deadline belonged to the gate that just closed. Leaving it on the
+    // record would hand a later gate in the same run a deadline that has
+    // already passed.
+    if (run.steps.every((s) => s.status !== "awaiting-approval"))
+        run.approveBy = null;
+    // A link decides once. Written as a digest on the record, so a step that
+    // parks again — a loop, a rerun from the gate — is not decided by the
+    // same forwarded mail.
+    if (d.link !== undefined) {
+        run.approvalLinksUsed = [...(run.approvalLinksUsed ?? []), linkDigest(d.link)].slice(-50);
+    }
     writeRun(tenant, workspace, run);
     // A parked run has no process polling for this decision — the worker
     // that was driving it gave its slot back at the gate. Line it up again.
@@ -72,6 +210,58 @@ export async function decideApproval(tenant, workspace, runId, d) {
     }
     return { run, steps: waiting.map(({ i }) => i) };
 }
+/**
+ * The two rules a person's decision has to pass. A token-bearing door — the
+ * emailed link, an external event — carries no actor and is not checked
+ * here: possession of a token derived from the run is its own authority,
+ * and the link was mailed to whoever the account told us to ask.
+ *
+ * Throws 403, which the routes surface verbatim: a refusal that does not say
+ * which rule refused sends someone to the wrong settings page.
+ */
+function assertMayDecide(tenant, workspace, run, d) {
+    if (!d.actor)
+        return;
+    const email = (d.actor.email ?? "").trim().toLowerCase();
+    // Rejecting your own run is always allowed: stopping something you started
+    // needs no second opinion, and the gate's whole purpose is that it does
+    // not proceed. Only approval needs someone else.
+    if (d.decision === "approve" && email && run.startedBy && run.startedBy === email) {
+        throw new ApprovalError("you started this run — an approval gate asks a second person, so someone else has to answer it", 403);
+    }
+    const flow = readFlow(tenant, workspace, run.flow);
+    if (!mayApprove(flow, d.actor)) {
+        throw new ApprovalError(`this flow's approvers: list does not include you (${flow?.approvers?.join(", ")})`, 403);
+    }
+}
+/**
+ * A gate that ran out of time. `approve_within:` in the flow file stamps a
+ * deadline when the run parks; past it, the gate is rejected and the run
+ * fails, exactly as if a person had said no.
+ *
+ * Rejection, not approval, is the only safe way for a clock to answer a
+ * question a person was asked. The whole reason the step is parked is that
+ * someone wanted to look at it first.
+ *
+ * Returns whether it acted. Called from the same sweep that closes abandoned
+ * runs, so an expiry needs nothing running of its own.
+ */
+export async function expireStaleGate(tenant, workspace, run, now = Date.now()) {
+    if (run.status !== "awaiting-approval" || !run.approveBy)
+        return false;
+    if (now < new Date(run.approveBy).getTime())
+        return false;
+    // A step waiting on `wait: event` is not waiting on a person and is not
+    // this deadline's business.
+    if (!run.steps.some((s) => s.status === "awaiting-approval" && s.waitFor !== "event"))
+        return false;
+    await decideApproval(tenant, workspace, run.id, {
+        decision: "reject",
+        by: "automatically — nobody answered in time",
+        reason: `no decision within the flow's approve_within: (due ${run.approveBy})`,
+    });
+    return true;
+}
 /**
  * Release a run parked on `wait: event` with what arrived. The payload is
  * stored on the step — not as an approval note, which is a person's

package/dist/src/budget.d.ts

@@ -0,0 +1,32 @@
+export type BudgetPeriod = "run" | "day" | "week" | "month";
+export interface Budget {
+    usd: number;
+    period: BudgetPeriod;
+}
+/**
+ * The budget a frontmatter value declares, or null for "no cap".
+ *
+ * Lenient on purpose: a value nobody can read is treated as no cap rather
+ * than as a cap of zero, because refusing every run over a typo is the worse
+ * failure. `budgetProblem` is the strict reading, for lint and the editor.
+ */
+export declare function parseBudget(raw: unknown, defaultPeriod: BudgetPeriod): Budget | null;
+/**
+ * What is wrong with a `budget:` value, in a sentence, or null when it is
+ * fine. `allowed` names the periods this file may use — an agent's or a
+ * flow's budget is per run and nothing else; a workspace's or the account's
+ * is over time and never per run.
+ */
+export declare function budgetProblem(raw: unknown, allowed: BudgetPeriod[]): string | null;
+/** "$60/day", "$500/month", "$6/run". */
+export declare function formatBudget(b: Budget): string;
+/** "today", "this week", "this month" — the window a spend is measured in. */
+export declare function windowName(period: BudgetPeriod): string;
+/** What to wait for when the cap is reached. */
+export declare function windowTurnsHint(period: BudgetPeriod): string;
+/**
+ * When the current window began, as a UTC instant — the moment spend is
+ * summed from. Today's midnight, Monday's midnight, or the first of the
+ * month, all in the given calendar. A per-run budget has no window.
+ */
+export declare function windowStartMs(period: BudgetPeriod, timeZone: string, now?: Date): number | null;

package/dist/src/budget.js

@@ -0,0 +1,177 @@
+// A budget is a number and a period — what may be spent, and over what.
+//
+// One grammar, read in four places: an agent's `budget:` (the most that
+// agent may spend in one run), a flow's (the most one run may spend), a
+// workspace's and the account's (a cap over a window of time). The value
+// was a bare number meaning "per month" in a workspace or account file and
+// "per run" in a flow; it still is, and it can now also say which:
+//
+//     budget: 60            a number alone: per run in a flow or an agent,
+//                           per month in a workspace or the account
+//     budget: 60/day        or 60/week, 60/month
+//     budget: unlimited     no cap — the same as leaving the key out
+//
+// Unset means no limit. That is the platform's rule, not an accident of
+// parsing: a customer who has not written a cap has not asked for one, and
+// nothing here invents a default they would then have to find and raise.
+//
+// Windows follow the account's calendar (`timezone:` in AGENTS.md), the
+// same one the scheduler and "today" already use, because a daily cap that
+// resets at 10am Sydney time is not a daily cap anyone meant.
+/** Words that mean "no cap", case-insensitively. */
+const UNLIMITED = new Set(["unlimited", "none", "no limit", "no-limit", "off", "-", "~"]);
+const PERIODS = {
+    run: "run",
+    day: "day",
+    daily: "day",
+    week: "week",
+    weekly: "week",
+    month: "month",
+    monthly: "month",
+};
+// `\d+(?:\.\d+)?` with an optional separator and one period word: every
+// part has one way to match, so a hostile string cannot make it backtrack.
+const FORM_RE = /^\$?(\d+(?:\.\d+)?)(?:\s*(?:\/|per|a|each)?\s*([a-z]+))?$/;
+/**
+ * The budget a frontmatter value declares, or null for "no cap".
+ *
+ * Lenient on purpose: a value nobody can read is treated as no cap rather
+ * than as a cap of zero, because refusing every run over a typo is the worse
+ * failure. `budgetProblem` is the strict reading, for lint and the editor.
+ */
+export function parseBudget(raw, defaultPeriod) {
+    if (raw === undefined || raw === null)
+        return null;
+    if (typeof raw === "number")
+        return Number.isFinite(raw) && raw > 0 ? { usd: raw, period: defaultPeriod } : null;
+    if (typeof raw !== "string")
+        return null;
+    const s = raw.trim().toLowerCase();
+    if (!s || UNLIMITED.has(s))
+        return null;
+    const m = FORM_RE.exec(s);
+    if (!m)
+        return null;
+    const usd = Number(m[1]);
+    if (!Number.isFinite(usd) || usd <= 0)
+        return null;
+    const period = m[2] ? PERIODS[m[2]] : defaultPeriod;
+    if (!period)
+        return null;
+    return { usd, period };
+}
+/**
+ * What is wrong with a `budget:` value, in a sentence, or null when it is
+ * fine. `allowed` names the periods this file may use — an agent's or a
+ * flow's budget is per run and nothing else; a workspace's or the account's
+ * is over time and never per run.
+ */
+export function budgetProblem(raw, allowed) {
+    if (raw === undefined || raw === null)
+        return null;
+    if (typeof raw === "number") {
+        if (!Number.isFinite(raw) || raw < 0)
+            return `budget: ${String(raw)} is not an amount in USD`;
+        return null;
+    }
+    if (typeof raw !== "string")
+        return `budget: must be a number, "<number>/<day|week|month>", or unlimited`;
+    const s = raw.trim().toLowerCase();
+    if (!s || UNLIMITED.has(s))
+        return null;
+    const m = FORM_RE.exec(s);
+    if (!m)
+        return `budget: "${raw}" is not a number, "<number>/<day|week|month>", or unlimited`;
+    if (m[2]) {
+        const period = PERIODS[m[2]];
+        if (!period)
+            return `budget: "${m[2]}" is not a period — day, week or month`;
+        if (!allowed.includes(period)) {
+            return period === "run"
+                ? `budget: is per run here already — write the number alone`
+                : `budget: "${period}" does not apply here — this cap is per run; a cap over time belongs in the workspace's or the account's AGENTS.md`;
+        }
+    }
+    return null;
+}
+/** "$60/day", "$500/month", "$6/run". */
+export function formatBudget(b) {
+    const usd = Number.isInteger(b.usd) ? String(b.usd) : b.usd.toFixed(2);
+    return `$${usd}/${b.period}`;
+}
+/** "today", "this week", "this month" — the window a spend is measured in. */
+export function windowName(period) {
+    return period === "day" ? "today" : period === "week" ? "this week" : period === "month" ? "this month" : "this run";
+}
+/** What to wait for when the cap is reached. */
+export function windowTurnsHint(period) {
+    return period === "day" ? "wait for tomorrow" : period === "week" ? "wait for next week" : "wait for the new month";
+}
+// ------------------------------------------------------------ the window
+function partsIn(timeZone, at) {
+    const f = new Intl.DateTimeFormat("en-US", {
+        timeZone,
+        hourCycle: "h23",
+        year: "numeric",
+        month: "numeric",
+        day: "numeric",
+        hour: "numeric",
+        minute: "numeric",
+        second: "numeric",
+        weekday: "short",
+    });
+    const p = {};
+    for (const { type, value } of f.formatToParts(at))
+        p[type] = value;
+    const weekdays = ["Sun", "Mon", "Tue", "Wed", "Thu", "Fri", "Sat"];
+    return {
+        y: Number(p.year),
+        m: Number(p.month),
+        d: Number(p.day),
+        h: Number(p.hour),
+        min: Number(p.minute),
+        s: Number(p.second),
+        weekday: weekdays.indexOf(p.weekday),
+    };
+}
+/** The zone's offset from UTC at an instant, in ms (positive east). */
+function offsetMs(timeZone, atMs) {
+    const p = partsIn(timeZone, new Date(atMs));
+    return Date.UTC(p.y, p.m - 1, p.d, p.h, p.min, p.s) - Math.floor(atMs / 1000) * 1000;
+}
+/** Midnight at the start of a local calendar date, as a UTC instant. */
+function localMidnightMs(timeZone, y, m, d) {
+    const naive = Date.UTC(y, m - 1, d);
+    let t = naive - offsetMs(timeZone, naive);
+    // Once more from the answer: across a DST change the first guess can be
+    // off by the shift, and the second pass lands on the real midnight.
+    const again = naive - offsetMs(timeZone, t);
+    if (again !== t)
+        t = again;
+    return t;
+}
+/**
+ * When the current window began, as a UTC instant — the moment spend is
+ * summed from. Today's midnight, Monday's midnight, or the first of the
+ * month, all in the given calendar. A per-run budget has no window.
+ */
+export function windowStartMs(period, timeZone, now = new Date()) {
+    if (period === "run")
+        return null;
+    let tz = timeZone;
+    try {
+        new Intl.DateTimeFormat("en-US", { timeZone: tz });
+    }
+    catch {
+        tz = "UTC";
+    }
+    const p = partsIn(tz, now);
+    if (period === "day")
+        return localMidnightMs(tz, p.y, p.m, p.d);
+    if (period === "month")
+        return localMidnightMs(tz, p.y, p.m, 1);
+    // Monday. Walk back on the naive calendar, then take that date's midnight.
+    const back = (p.weekday + 6) % 7;
+    const monday = new Date(Date.UTC(p.y, p.m - 1, p.d - back));
+    return localMidnightMs(tz, monday.getUTCFullYear(), monday.getUTCMonth() + 1, monday.getUTCDate());
+}

package/dist/src/catalog.js

@@ -21,6 +21,7 @@ import fs from "node:fs";
 import path from "node:path";
 import { dataRoot } from "./paths.js";
 import { resolveModel, resolveTier, MODEL_TIERS, EFFORT_LEVELS } from "./store.js";
+import { trimSlashes } from "./paths.js";
 /** A day. Model lists move weekly, not hourly, and a stale price in an
  *  autocomplete hint is a smaller failure than a fetch on every keystroke. */
 const TTL_MS = 24 * 60 * 60 * 1000;
@@ -83,7 +84,7 @@ export async function loadCatalog(baseUrl) {
     if (cached && Date.now() - Date.parse(cached.fetchedAt) < TTL_MS)
         return cached;
     try {
-        const res = await fetch(`${baseUrl.replace(/\/+$/, "")}/v1/models`, {
+        const res = await fetch(`${trimSlashes(baseUrl)}/v1/models`, {
             signal: AbortSignal.timeout(10_000),
         });
         if (!res.ok)

package/dist/src/confine.js

@@ -123,7 +123,12 @@ export const isFilesystemTool = (toolName) => FS_TOOLS.has(toolName);
  */
 export function suggestPath(raw) {
     const posix = raw.split(path.sep).join("/");
-    const m = posix.match(/(?:^|\/)(outputs|storage|state|memory|knowledge)\/(.+)$/);
+    // By segments, not by regex: an unanchored `(.+)$` re-scans from every
+    // slash, and this runs on a path an agent chose.
+    const KNOWN = ["outputs", "storage", "state", "memory", "knowledge"];
+    const segs = posix.split("/");
+    const at = segs.findIndex((seg, i) => KNOWN.includes(seg) && segs.slice(i + 1).join("/") !== "");
+    const m = at === -1 ? null : [null, segs[at], segs.slice(at + 1).join("/")];
     if (m) {
         const [, dir, rest] = m;
         return dir === "outputs"