@spendgraph/tools 0.2.0

package/dist/builtin/date/index.js

@@ -0,0 +1,2 @@
+export { dateMath } from "./date.js";
+export { between, parseDate, shift } from "./shift.js";

package/dist/builtin/date/shift.d.ts

@@ -0,0 +1,12 @@
+export type Unit = "seconds" | "minutes" | "hours" | "days" | "weeks" | "months" | "years";
+/** Parses an ISO instant, or says which argument was not one. */
+export declare function parseDate(value: string, label: string): Date;
+/** Moves an instant by a whole number of units. Negative goes backwards. */
+export declare function shift(from: Date, amount: number, unit: Unit): Date;
+/**
+ * How far apart two instants are, in whole units.
+ *
+ * Calendar units count boundaries crossed rather than dividing elapsed
+ * milliseconds, because a month is not 30 days and a year is not 365.
+ */
+export declare function between(from: Date, to: Date, unit: Unit): number;

package/dist/builtin/date/shift.js

@@ -0,0 +1,62 @@
+const MS = {
+    seconds: 1000,
+    minutes: 60_000,
+    hours: 3_600_000,
+    days: 86_400_000,
+    weeks: 604_800_000,
+};
+/** Parses an ISO instant, or says which argument was not one. */
+export function parseDate(value, label) {
+    const at = new Date(value);
+    if (!Number.isFinite(at.getTime())) {
+        throw new Error(`${label} "${value}" is not a date. Use an ISO instant, as in 2026-03-31.`);
+    }
+    return at;
+}
+/**
+ * Adds calendar months, clamping rather than overflowing.
+ *
+ * `setUTCMonth` turns 31 January plus one month into 3 March, which is nobody's
+ * idea of a month later. The last day of a short month is the answer people
+ * mean, and the answer every billing system gives.
+ */
+function addMonths(from, months) {
+    const day = from.getUTCDate();
+    const shifted = new Date(from.getTime());
+    shifted.setUTCDate(1);
+    shifted.setUTCMonth(shifted.getUTCMonth() + months);
+    const lastOfMonth = new Date(Date.UTC(shifted.getUTCFullYear(), shifted.getUTCMonth() + 1, 0)).getUTCDate();
+    shifted.setUTCDate(Math.min(day, lastOfMonth));
+    return shifted;
+}
+/** Moves an instant by a whole number of units. Negative goes backwards. */
+export function shift(from, amount, unit) {
+    if (!Number.isInteger(amount))
+        throw new Error("amount must be a whole number.");
+    if (unit === "months")
+        return addMonths(from, amount);
+    if (unit === "years")
+        return addMonths(from, amount * 12);
+    const ms = MS[unit];
+    if (!ms)
+        throw new Error(`"${unit}" is not a unit this tool knows.`);
+    return new Date(from.getTime() + amount * ms);
+}
+/**
+ * How far apart two instants are, in whole units.
+ *
+ * Calendar units count boundaries crossed rather than dividing elapsed
+ * milliseconds, because a month is not 30 days and a year is not 365.
+ */
+export function between(from, to, unit) {
+    if (unit === "months" || unit === "years") {
+        const months = (to.getUTCFullYear() - from.getUTCFullYear()) * 12 +
+            (to.getUTCMonth() - from.getUTCMonth()) -
+            (to.getUTCDate() < from.getUTCDate() ? 1 : 0);
+        return unit === "years" ? Math.trunc(months / 12) : months;
+    }
+    const ms = MS[unit];
+    if (!ms)
+        throw new Error(`"${unit}" is not a unit this tool knows.`);
+    return Math.trunc((to.getTime() - from.getTime()) / ms);
+}

package/dist/builtin/deep-recall/deep-recall.d.ts

@@ -0,0 +1,27 @@
+import type { LocusGraphClient } from "@locusgraph/client";
+export interface DeepRecallOptions {
+    /** A `LocusGraphClient`, or anything carrying its `deepRecall`. */
+    client: Pick<LocusGraphClient, "deepRecall">;
+    /** Graph the walk runs over. Unset, the client's own default is used. */
+    graphId?: string;
+    /** Longest evidence list handed back. Default 20. */
+    maxFacts?: number;
+}
+/**
+ * Your own knowledge base, answered with cited evidence.
+ *
+ * Cost comes back as micro-USD because deep recall runs model calls of its own,
+ * and that spend is invisible to whatever loop called this.
+ */
+export declare function deepRecall(opts: DeepRecallOptions): import("../../index.js").Tool<import("../../index.js").ArgsOf<readonly [{
+    readonly name: "question";
+    readonly type: "string";
+    readonly required: true;
+    readonly maxLength: 1000;
+    readonly description: "One focused question, not a conversation and not several at once.";
+}, {
+    readonly name: "context_ids";
+    readonly type: "list";
+    readonly required: false;
+    readonly description: string;
+}]>>;

package/dist/builtin/deep-recall/deep-recall.js

@@ -0,0 +1,51 @@
+import { tool } from "../../tool/index.js";
+const DEFAULT_MAX_FACTS = 20;
+/**
+ * Your own knowledge base, answered with cited evidence.
+ *
+ * Cost comes back as micro-USD because deep recall runs model calls of its own,
+ * and that spend is invisible to whatever loop called this.
+ */
+export function deepRecall(opts) {
+    const maxFacts = opts.maxFacts ?? DEFAULT_MAX_FACTS;
+    return tool({
+        name: "deep_recall",
+        description: "Searches your own knowledge base and returns an answer with the evidence it rests " +
+            "on. A walker follows linked contexts, so it answers questions spread across several " +
+            "notes — what do we know about X, what was decided and why. Ask one focused thing. " +
+            "Prefer it over a web search whenever the answer could already be in your records.",
+        effect: "readonly",
+        args: [
+            {
+                name: "question",
+                type: "string",
+                required: true,
+                maxLength: 1000,
+                description: "One focused question, not a conversation and not several at once.",
+            },
+            {
+                name: "context_ids",
+                type: "list",
+                required: false,
+                description: "Contexts to start the walk from, as type:name — take them from the contexts of " +
+                    "an earlier result. A hint, not a filter; the walk may go elsewhere.",
+            },
+        ],
+        run: async ({ question, context_ids }) => {
+            const result = await opts.client.deepRecall({
+                question,
+                ...(opts.graphId ? { graphId: opts.graphId } : {}),
+                ...(context_ids?.length ? { contextIds: context_ids } : {}),
+            });
+            return {
+                summary: result.summary,
+                facts: result.facts.slice(0, maxFacts),
+                truncated: result.facts.length > maxFacts,
+                contextsWalked: result.contexts_walked,
+                coverage: result.coverage,
+                fallback: result.fallback,
+                costMicroUsd: Math.round(result.usage.cost_usd * 1_000_000),
+            };
+        },
+    });
+}

package/dist/builtin/deep-recall/index.d.ts

@@ -0,0 +1 @@
+export { type DeepRecallOptions, deepRecall } from "./deep-recall.js";

package/dist/builtin/deep-recall/index.js

@@ -0,0 +1 @@
+export { deepRecall } from "./deep-recall.js";

package/dist/builtin/escalate/escalate.d.ts

@@ -0,0 +1,46 @@
+export interface EscalateOptions {
+    /**
+     * What actually happens — page someone, open a ticket, write to a queue.
+     *
+     * Without it this records the request and nothing else, which is honest but
+     * not useful; the model will believe a human was reached either way.
+     */
+    onEscalate?: (request: EscalationRequest) => Promise<unknown> | unknown;
+    /**
+     * Offered whatever selection decides. Default true.
+     *
+     * A refusal route lost to a similarity score is the failure `pinned` exists
+     * for: the one turn that needed it is the one where nothing else fit.
+     */
+    pinned?: boolean;
+}
+export interface EscalationRequest {
+    reason: string;
+    summary?: string;
+    urgency: "low" | "normal" | "high";
+}
+/**
+ * Hand back to a person rather than guess.
+ *
+ * An agent with no way to stop answers anyway, and a confident wrong answer to
+ * something it could not do is worse than a handover.
+ *
+ * Its `effect` is left unset on purpose: `onEscalate` is yours, and paging
+ * someone twice is not the same as paging them once.
+ */
+export declare function escalate(opts?: EscalateOptions): import("../../index.js").Tool<import("../../index.js").ArgsOf<readonly [{
+    readonly name: "reason";
+    readonly type: "text";
+    readonly required: true;
+    readonly maxLength: 2000;
+}, {
+    readonly name: "summary";
+    readonly type: "text";
+    readonly required: false;
+    readonly maxLength: 4000;
+}, {
+    readonly name: "urgency";
+    readonly type: "enum";
+    readonly required: false;
+    readonly options: readonly ["low", "normal", "high"];
+}]>>;

package/dist/builtin/escalate/escalate.js

@@ -0,0 +1,29 @@
+import { tool } from "../../tool/index.js";
+/**
+ * Hand back to a person rather than guess.
+ *
+ * An agent with no way to stop answers anyway, and a confident wrong answer to
+ * something it could not do is worse than a handover.
+ *
+ * Its `effect` is left unset on purpose: `onEscalate` is yours, and paging
+ * someone twice is not the same as paging them once.
+ */
+export function escalate(opts = {}) {
+    return tool({
+        name: "escalate",
+        description: "Hand this over to a person. Call it when you are missing something you cannot " +
+            "get, when the request needs an authority you do not have, or when acting on a " +
+            "guess would be worse than waiting. Say plainly why.",
+        pinned: opts.pinned ?? true,
+        args: [
+            { name: "reason", type: "text", required: true, maxLength: 2000 },
+            { name: "summary", type: "text", required: false, maxLength: 4000 },
+            { name: "urgency", type: "enum", required: false, options: ["low", "normal", "high"] },
+        ],
+        run: async ({ reason, summary, urgency = "normal" }) => {
+            const request = { reason, summary, urgency };
+            const handled = opts.onEscalate ? await opts.onEscalate(request) : undefined;
+            return { escalated: true, delivered: Boolean(opts.onEscalate), request, handled };
+        },
+    });
+}

package/dist/builtin/escalate/index.d.ts

@@ -0,0 +1 @@
+export { type EscalateOptions, type EscalationRequest, escalate } from "./escalate.js";

package/dist/builtin/escalate/index.js

@@ -0,0 +1 @@
+export { escalate } from "./escalate.js";

package/dist/builtin/finish/finish.d.ts

@@ -0,0 +1,27 @@
+import type { ToolResult } from "../../types/index.js";
+/** What `finish` returns, so a loop can recognise its own stop condition. */
+export interface Finished {
+    done: true;
+    answer: string;
+}
+/**
+ * True when this result is the model saying it is done.
+ *
+ * A loop that ends because the model stopped asking for tools cannot tell
+ * finished from confused. This makes the difference explicit.
+ */
+export declare function isFinished(result: ToolResult): boolean;
+/** Reads the answer out of a finished result, or null if it is not one. */
+export declare function answerOf(result: ToolResult): string | null;
+/**
+ * The model says it is done, and says what the answer is.
+ *
+ * Without it a loop ends by the model going quiet, which is indistinguishable
+ * from it losing the thread.
+ */
+export declare function finish(): import("../../index.js").Tool<import("../../index.js").ArgsOf<readonly [{
+    readonly name: "answer";
+    readonly type: "text";
+    readonly required: true;
+    readonly maxLength: 20000;
+}]>>;

package/dist/builtin/finish/finish.js

@@ -0,0 +1,39 @@
+import { tool } from "../../tool/index.js";
+/**
+ * True when this result is the model saying it is done.
+ *
+ * A loop that ends because the model stopped asking for tools cannot tell
+ * finished from confused. This makes the difference explicit.
+ */
+export function isFinished(result) {
+    if (result.name !== "finish" || result.status !== "completed")
+        return false;
+    try {
+        return JSON.parse(result.output).done === true;
+    }
+    catch {
+        return false;
+    }
+}
+/** Reads the answer out of a finished result, or null if it is not one. */
+export function answerOf(result) {
+    if (!isFinished(result))
+        return null;
+    return JSON.parse(result.output).answer;
+}
+/**
+ * The model says it is done, and says what the answer is.
+ *
+ * Without it a loop ends by the model going quiet, which is indistinguishable
+ * from it losing the thread.
+ */
+export function finish() {
+    return tool({
+        name: "finish",
+        effect: "readonly",
+        description: "Call this when you have the answer and need no more tools. Pass the final " +
+            "answer as it should be given to the person who asked.",
+        args: [{ name: "answer", type: "text", required: true, maxLength: 20_000 }],
+        run: ({ answer }) => ({ done: true, answer }),
+    });
+}

package/dist/builtin/finish/index.d.ts

@@ -0,0 +1 @@
+export { answerOf, type Finished, finish, isFinished } from "./finish.js";

package/dist/builtin/finish/index.js

@@ -0,0 +1 @@
+export { answerOf, finish, isFinished } from "./finish.js";

package/dist/builtin/http/allow.d.ts

@@ -0,0 +1,8 @@
+/**
+ * The URL a request may go to, or the reason it may not.
+ *
+ * An allowlist rather than a blocklist, and https only. A tool that fetches
+ * whatever a model names is how an agent reads a cloud metadata endpoint and
+ * hands back the credentials it finds.
+ */
+export declare function checkUrl(raw: string, allow: string[]): URL;

package/dist/builtin/http/allow.js

@@ -0,0 +1,45 @@
+const PRIVATE_V4 = /^(10\.|127\.|0\.|169\.254\.|192\.168\.|172\.(1[6-9]|2\d|3[01])\.|100\.(6[4-9]|[7-9]\d|1[01]\d|12[0-7])\.)/;
+const LOCAL_NAMES = new Set(["localhost", "metadata.google.internal"]);
+function isPrivateHost(host) {
+    const name = host.toLowerCase();
+    if (LOCAL_NAMES.has(name))
+        return true;
+    if (name.endsWith(".local") || name.endsWith(".internal") || name.endsWith(".localhost")) {
+        return true;
+    }
+    if (name.startsWith("["))
+        return true;
+    return PRIVATE_V4.test(name);
+}
+/** Matches a host exactly, or any subdomain when the rule starts with a dot. */
+function matches(host, rule) {
+    const h = host.toLowerCase();
+    const r = rule.toLowerCase();
+    return r.startsWith(".") ? h === r.slice(1) || h.endsWith(r) : h === r;
+}
+/**
+ * The URL a request may go to, or the reason it may not.
+ *
+ * An allowlist rather than a blocklist, and https only. A tool that fetches
+ * whatever a model names is how an agent reads a cloud metadata endpoint and
+ * hands back the credentials it finds.
+ */
+export function checkUrl(raw, allow) {
+    let url;
+    try {
+        url = new URL(raw);
+    }
+    catch {
+        throw new Error(`"${raw}" is not a URL.`);
+    }
+    if (url.protocol !== "https:") {
+        throw new Error(`Only https is allowed, and this is ${url.protocol.replace(":", "")}.`);
+    }
+    if (isPrivateHost(url.hostname)) {
+        throw new Error(`${url.hostname} is a private or link-local address.`);
+    }
+    if (!allow.some((rule) => matches(url.hostname, rule))) {
+        throw new Error(`${url.hostname} is not in the allowlist: ${allow.join(", ")}.`);
+    }
+    return url;
+}

package/dist/builtin/http/http.d.ts

@@ -0,0 +1,43 @@
+export interface HttpOptions {
+    /**
+     * Hosts this tool may reach. Required, and there is no default.
+     *
+     * `"api.example.com"` matches that host; `".example.com"` matches it and any
+     * subdomain.
+     */
+    allow: string[];
+    /** Sent on every request — an API key belongs here, never in the args. */
+    headers?: Record<string, string>;
+    /** Give up after this. Default 10000. */
+    timeoutMs?: number;
+    /** Longest body handed back. Default 100000 characters. */
+    maxChars?: number;
+    /** Injected for tests. */
+    fetch?: typeof fetch;
+}
+/**
+ * An HTTP GET or POST, to hosts you named.
+ *
+ * The allowlist is required because the alternative is a tool that fetches
+ * whatever a model is talked into naming. Headers are set here, not by the
+ * model, so a credential is never something it can redirect.
+ *
+ * Its `effect` is left unset on purpose: a GET is readonly and a POST to your
+ * allowlist may be anything at all, and one label cannot be true of both.
+ */
+export declare function httpRequest(opts: HttpOptions): import("../../index.js").Tool<import("../../index.js").ArgsOf<readonly [{
+    readonly name: "url";
+    readonly type: "string";
+    readonly required: true;
+    readonly maxLength: 2000;
+}, {
+    readonly name: "method";
+    readonly type: "enum";
+    readonly required: false;
+    readonly options: readonly ["GET", "POST"];
+}, {
+    readonly name: "body";
+    readonly type: "text";
+    readonly required: false;
+    readonly maxLength: 20000;
+}]>>;

package/dist/builtin/http/http.js

@@ -0,0 +1,51 @@
+import { tool } from "../../tool/index.js";
+import { checkUrl } from "./allow.js";
+const DEFAULT_TIMEOUT_MS = 10_000;
+const DEFAULT_MAX_CHARS = 100_000;
+/**
+ * An HTTP GET or POST, to hosts you named.
+ *
+ * The allowlist is required because the alternative is a tool that fetches
+ * whatever a model is talked into naming. Headers are set here, not by the
+ * model, so a credential is never something it can redirect.
+ *
+ * Its `effect` is left unset on purpose: a GET is readonly and a POST to your
+ * allowlist may be anything at all, and one label cannot be true of both.
+ */
+export function httpRequest(opts) {
+    if (!opts.allow?.length) {
+        throw new Error("httpRequest needs an allow list of hosts; there is no safe default.");
+    }
+    const doFetch = opts.fetch ?? globalThis.fetch;
+    const maxChars = opts.maxChars ?? DEFAULT_MAX_CHARS;
+    return tool({
+        name: "http_request",
+        description: `Fetches a URL and returns its status and body. Only these hosts are reachable: ` +
+            `${opts.allow.join(", ")}. Use it to read an API or a page you have been pointed at.`,
+        args: [
+            { name: "url", type: "string", required: true, maxLength: 2000 },
+            { name: "method", type: "enum", required: false, options: ["GET", "POST"] },
+            { name: "body", type: "text", required: false, maxLength: 20_000 },
+        ],
+        run: async ({ url, method = "GET", body }) => {
+            const target = checkUrl(url, opts.allow);
+            const signal = AbortSignal.timeout(opts.timeoutMs ?? DEFAULT_TIMEOUT_MS);
+            const res = await doFetch(target, {
+                method,
+                signal,
+                headers: {
+                    ...opts.headers,
+                    ...(body ? { "content-type": "application/json" } : {}),
+                },
+                ...(body && method === "POST" ? { body } : {}),
+            });
+            const text = await res.text();
+            return {
+                status: res.status,
+                ok: res.ok,
+                body: text.slice(0, maxChars),
+                truncated: text.length > maxChars,
+            };
+        },
+    });
+}

package/dist/builtin/http/index.d.ts

@@ -0,0 +1,2 @@
+export { checkUrl } from "./allow.js";
+export { type HttpOptions, httpRequest } from "./http.js";

package/dist/builtin/http/index.js

@@ -0,0 +1,2 @@
+export { checkUrl } from "./allow.js";
+export { httpRequest } from "./http.js";

package/dist/builtin/index.d.ts

@@ -0,0 +1,11 @@
+export { calculate, evaluate } from "./calculate/index.js";
+export { type ClockOptions, currentTime } from "./clock/index.js";
+export { dateMath } from "./date/index.js";
+export { type DeepRecallOptions, deepRecall } from "./deep-recall/index.js";
+export { type EscalateOptions, type EscalationRequest, escalate } from "./escalate/index.js";
+export { answerOf, type Finished, finish, isFinished } from "./finish/index.js";
+export { checkUrl, type HttpOptions, httpRequest } from "./http/index.js";
+export { type JsonQueryOptions, jsonQuery } from "./json/index.js";
+export { think } from "./think/index.js";
+export { type SearchDepth, type WebSearchOptions, webSearch } from "./web-search/index.js";
+export { type ArtifactFormat, CommissionAbortedError, type CommissionClient, CommissionTimeoutError, DEFAULT_DESIGN, type DesignGuide, mergeDesign, renderDesign, type WriteDocumentOptions, writeDocument, } from "./write-document/index.js";

package/dist/builtin/index.js

@@ -0,0 +1,11 @@
+export { calculate, evaluate } from "./calculate/index.js";
+export { currentTime } from "./clock/index.js";
+export { dateMath } from "./date/index.js";
+export { deepRecall } from "./deep-recall/index.js";
+export { escalate } from "./escalate/index.js";
+export { answerOf, finish, isFinished } from "./finish/index.js";
+export { checkUrl, httpRequest } from "./http/index.js";
+export { jsonQuery } from "./json/index.js";
+export { think } from "./think/index.js";
+export { webSearch } from "./web-search/index.js";
+export { CommissionAbortedError, CommissionTimeoutError, DEFAULT_DESIGN, mergeDesign, renderDesign, writeDocument, } from "./write-document/index.js";

package/dist/builtin/json/index.d.ts

@@ -0,0 +1,2 @@
+export { type JsonQueryOptions, jsonQuery } from "./json.js";
+export { readPath } from "./path.js";

package/dist/builtin/json/index.js

@@ -0,0 +1,2 @@
+export { jsonQuery } from "./json.js";
+export { readPath } from "./path.js";

package/dist/builtin/json/json.d.ts

@@ -0,0 +1,22 @@
+export interface JsonQueryOptions {
+    /** Longest value handed back, once stringified. Default 20000. */
+    maxChars?: number;
+}
+/**
+ * Pulls one value out of a JSON document.
+ *
+ * The alternative is putting the whole reply in the context and asking the model
+ * to read it, which costs tokens on every turn and gets the field wrong when the
+ * document is long.
+ */
+export declare function jsonQuery(opts?: JsonQueryOptions): import("../../index.js").Tool<import("../../index.js").ArgsOf<readonly [{
+    readonly name: "json";
+    readonly type: "text";
+    readonly required: true;
+    readonly maxLength: 200000;
+}, {
+    readonly name: "path";
+    readonly type: "string";
+    readonly required: true;
+    readonly maxLength: 500;
+}]>>;

package/dist/builtin/json/json.js

@@ -0,0 +1,44 @@
+import { tool } from "../../tool/index.js";
+import { readPath } from "./path.js";
+const DEFAULT_MAX_CHARS = 20_000;
+/**
+ * Pulls one value out of a JSON document.
+ *
+ * The alternative is putting the whole reply in the context and asking the model
+ * to read it, which costs tokens on every turn and gets the field wrong when the
+ * document is long.
+ */
+export function jsonQuery(opts = {}) {
+    const maxChars = opts.maxChars ?? DEFAULT_MAX_CHARS;
+    return tool({
+        name: "json_query",
+        effect: "readonly",
+        description: "Reads one value out of a JSON document by path. Paths look like " +
+            "`invoices[0].total`, or `invoices[*].total` for every element. Use it instead " +
+            "of reading a long document yourself.",
+        args: [
+            { name: "json", type: "text", required: true, maxLength: 200_000 },
+            { name: "path", type: "string", required: true, maxLength: 500 },
+        ],
+        run: ({ json, path }) => {
+            let document;
+            try {
+                document = JSON.parse(json);
+            }
+            catch (err) {
+                throw new Error(`json is not valid JSON: ${err.message}`);
+            }
+            const value = readPath(document, path);
+            if (value === undefined)
+                return { found: false, path, value: null };
+            const rendered = JSON.stringify(value) ?? "null";
+            return {
+                found: true,
+                path,
+                value,
+                truncated: rendered.length > maxChars,
+                ...(rendered.length > maxChars ? { value: `${rendered.slice(0, maxChars)}…` } : {}),
+            };
+        },
+    });
+}

package/dist/builtin/json/path.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Reads a value out of parsed JSON by path.
+ *
+ * `a.b`, `a[0].b`, and `a[*].b` for every element — enough to pull a field out
+ * of an API reply, and small enough that the syntax is guessable from one
+ * example, which matters when the thing writing the path is a model.
+ */
+export declare function readPath(document: unknown, path: string): unknown;

package/dist/builtin/json/path.js

@@ -0,0 +1,63 @@
+function parsePath(path) {
+    const segments = [];
+    for (const part of path.split(".")) {
+        if (!part)
+            continue;
+        const [, name, brackets] = /^([^[\]]*)((?:\[[^\]]*\])*)$/.exec(part) ?? [];
+        if (name === undefined)
+            throw new Error(`"${part}" is not a path segment.`);
+        if (name)
+            segments.push({ kind: "key", name });
+        for (const [, inner] of (brackets ?? "").matchAll(/\[([^\]]*)\]/g)) {
+            if (inner === "*") {
+                segments.push({ kind: "all" });
+                continue;
+            }
+            const at = Number(inner);
+            if (!Number.isInteger(at))
+                throw new Error(`"[${inner}]" is not an index or a *.`);
+            segments.push({ kind: "index", at });
+        }
+    }
+    return segments;
+}
+function step(value, segment) {
+    if (value === null || value === undefined)
+        return undefined;
+    if (segment.kind === "key") {
+        if (typeof value !== "object" || Array.isArray(value))
+            return undefined;
+        return value[segment.name];
+    }
+    if (!Array.isArray(value))
+        return undefined;
+    if (segment.kind === "index") {
+        return value.at(segment.at);
+    }
+    return value;
+}
+/**
+ * Reads a value out of parsed JSON by path.
+ *
+ * `a.b`, `a[0].b`, and `a[*].b` for every element — enough to pull a field out
+ * of an API reply, and small enough that the syntax is guessable from one
+ * example, which matters when the thing writing the path is a model.
+ */
+export function readPath(document, path) {
+    let cursor = document;
+    let spread = false;
+    for (const segment of parsePath(path)) {
+        if (segment.kind === "all") {
+            if (!Array.isArray(cursor))
+                return undefined;
+            cursor = spread ? cursor.flat() : [...cursor];
+            spread = true;
+            continue;
+        }
+        cursor =
+            spread && Array.isArray(cursor)
+                ? cursor.map((item) => step(item, segment))
+                : step(cursor, segment);
+    }
+    return cursor;
+}