@nodetool-ai/agents 0.7.0-rc.22 → 0.8.1

package/dist/jtbd/run.js

@@ -0,0 +1,177 @@
+/**
+ * Running a job and recording everything the run produced.
+ *
+ * The loop itself is {@link runToolLoop}, unchanged — a job is not a new way to
+ * drive a model, it is a new thing to ask of one and a fuller record of what
+ * came back. What this file adds is the record: the transcript, the outcome
+ * checks in the user's own terms, and the derived friction.
+ *
+ * Jobs are heterogeneous — a timeline job grades a cut, a sketch job grades
+ * pixels — so {@link defineJob} closes over each job's state type and hands the
+ * runner a `start()` that builds a world and knows how to grade it. The runner
+ * never sees a surface's state, so nothing here is cast.
+ */
+import { runToolLoop } from "../app-build/tool-loop.js";
+import { deriveFriction } from "./friction.js";
+/** Seal a job's state type. The only way a job enters the registry. */
+export function defineJob(job) {
+    const erased = {
+        id: job.id,
+        statement: job.statement,
+        surfaces: job.surfaces,
+        difficulty: job.difficulty,
+        objective: job.objective,
+        outcomeNames: job.outcomes.map((o) => o.name),
+        start: () => {
+            const bridge = job.createBridge();
+            return {
+                tools: bridge.tools,
+                grade: () => {
+                    const state = bridge.finalState();
+                    return job.outcomes.map((outcome) => ({
+                        name: outcome.name,
+                        describe: outcome.describe,
+                        // A check that throws on a half-built world is a failed check, not
+                        // a failed run: the transcript is what the loop exists to produce
+                        // and losing it to a predicate would be the worst possible trade.
+                        passed: safeTest(() => outcome.test(state))
+                    }));
+                }
+            };
+        }
+    };
+    if (job.systemPrompt !== undefined)
+        erased.systemPrompt = job.systemPrompt;
+    if (job.maxIterations !== undefined)
+        erased.maxIterations = job.maxIterations;
+    if (job.needsModelProviders !== undefined) {
+        erased.needsModelProviders = job.needsModelProviders;
+    }
+    if (job.expectedToolCalls !== undefined) {
+        erased.expectedToolCalls = job.expectedToolCalls;
+    }
+    return erased;
+}
+function safeTest(test) {
+    try {
+        return test();
+    }
+    catch {
+        return false;
+    }
+}
+/** The prompt under test when a job names none. */
+export const DEFAULT_JOB_SYSTEM_PROMPT = `You are an agent operating NodeTool through its tools.
+
+Get the user's job done end to end. Discover what a tool does before guessing at
+its arguments, read each result before the next call, and stop calling tools once
+the job is done — then say in one line what you produced.
+
+For a workflow-authoring job, end to end requires a \`nodetool.output.*\` node
+wired to the final value. Do not call the workflow done until it surfaces the
+requested result.`;
+export async function runJob(job, opts) {
+    const startedAt = new Date().toISOString();
+    const base = {
+        jobId: job.id,
+        statement: job.statement,
+        provider: opts.provider.provider,
+        model: opts.model,
+        startedAt
+    };
+    const hasProviders = opts.providers !== undefined && Object.keys(opts.providers).length > 0;
+    if (job.needsModelProviders === true && !hasProviders) {
+        return {
+            ...base,
+            skipped: true,
+            completed: false,
+            achieved: false,
+            outcomes: [],
+            transcript: [],
+            toolCalls: [],
+            friction: [],
+            totalToolCalls: 0,
+            durationMs: 0,
+            costUsd: 0
+        };
+    }
+    opts.onEvent?.(`▶ ${job.id}: ${job.statement}`);
+    const world = job.start();
+    const loopArgs = {
+        provider: opts.provider,
+        model: opts.model,
+        tools: world.tools,
+        systemPrompt: job.systemPrompt ?? opts.systemPrompt ?? DEFAULT_JOB_SYSTEM_PROMPT,
+        userPrompt: job.objective
+    };
+    const iterations = job.maxIterations ?? opts.maxIterations;
+    if (iterations !== undefined)
+        loopArgs.maxIterations = iterations;
+    if (opts.signal !== undefined)
+        loopArgs.signal = opts.signal;
+    const run = await runToolLoop(loopArgs);
+    const outcomes = world.grade();
+    const achieved = run.completed && outcomes.length > 0 && outcomes.every((o) => o.passed);
+    const friction = deriveFriction({
+        job: job.expectedToolCalls === undefined
+            ? {}
+            : { expectedToolCalls: job.expectedToolCalls },
+        toolCalls: run.calls,
+        achieved
+    });
+    opts.onEvent?.(`${achieved ? "✔" : "✘"} ${job.id} — ${run.totalCalls} calls, ${friction.length} friction signal(s)`);
+    const report = {
+        ...base,
+        skipped: false,
+        completed: run.completed,
+        achieved,
+        outcomes,
+        transcript: run.transcript,
+        toolCalls: run.calls,
+        friction,
+        totalToolCalls: run.totalCalls,
+        durationMs: run.durationMs,
+        costUsd: run.costUsd
+    };
+    if (run.error !== undefined)
+        report.error = run.error;
+    return report;
+}
+export async function runJobSuite(opts) {
+    const { JOBS_TO_BE_DONE } = await import("./registry.js");
+    const jobs = opts.jobs ?? JOBS_TO_BE_DONE;
+    const startedAt = new Date().toISOString();
+    const reports = [];
+    for (const job of jobs) {
+        if (opts.signal?.aborted === true)
+            break;
+        reports.push(await runJob(job, opts));
+    }
+    const graded = reports.filter((r) => !r.skipped);
+    const achieved = graded.filter((r) => r.achieved).length;
+    const frictionByOwner = {
+        harness: 0,
+        prompt: 0,
+        unattributed: 0
+    };
+    for (const report of reports) {
+        for (const signal of report.friction) {
+            frictionByOwner[signal.owner] += 1;
+        }
+    }
+    return {
+        provider: opts.provider.provider,
+        model: opts.model,
+        startedAt,
+        jobs: reports,
+        summary: {
+            total: reports.length,
+            skipped: reports.length - graded.length,
+            achieved,
+            achievementRate: graded.length === 0 ? 0 : achieved / graded.length,
+            frictionByOwner,
+            totalCostUsd: reports.reduce((sum, r) => sum + r.costUsd, 0)
+        }
+    };
+}
+//# sourceMappingURL=run.js.map

package/dist/jtbd/run.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"run.js","sourceRoot":"","sources":["../../src/jtbd/run.ts"],"names":[],"mappings":"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"}

package/dist/jtbd/types.d.ts

@@ -0,0 +1,141 @@
+/**
+ * Jobs to be done — the agent-intent layer over NodeTool's surfaces.
+ *
+ * The repo already catalogues two things: `SURFACES` (what a product owner
+ * ships) and `CAPABILITY_COVERAGE` (what a tool call can do). Neither answers
+ * the question an optimizer needs to ask, which is what an agent was *trying to
+ * get done* and where the product stopped it. A capability check proves
+ * `add_track` returns a track id; it cannot notice that no model ever finds
+ * `add_track` because its description does not say the word "audio".
+ *
+ * A job is one objective an agent takes end to end across whatever surfaces it
+ * needs, run against the real tool contract, recorded in full. Three things
+ * come out of a run and all three matter:
+ *
+ *  - the **transcript** — the system prompt, every assistant turn, every tool
+ *    call and its result. Without it a failed run says "score 0.4" and nothing
+ *    an outer agent can act on.
+ *  - the **outcome** — did the job get done, per the case's own checks.
+ *  - the **friction** — where the run wasted turns, and whether the blame lands
+ *    on the harness or on the prompt. This is the attribution the optimizer
+ *    reads; see `friction.ts` for how it is derived and why it is a heuristic
+ *    that proposes rather than decides.
+ */
+import type { Message } from "@nodetool-ai/runtime";
+import type { ToolLoopCallRecord } from "../app-build/tool-loop.js";
+import type { HeadlessSurfaceBridge } from "../evals/tool-loop-eval.js";
+/**
+ * Where a job's friction lands. The split is the whole point of the loop: an
+ * outer agent fixes a `harness` finding by changing a tool — its schema, its
+ * error text, its result shape — and a `prompt` finding by changing what the
+ * agent was told. Getting the attribution wrong sends the fix to the wrong
+ * file, so the deriver leaves it `unattributed` rather than guessing.
+ */
+export type FrictionOwner = "harness" | "prompt" | "unattributed";
+export type FrictionSeverity = "blocking" | "wasteful" | "cosmetic";
+/** One thing that went wrong, with enough context to act on it. */
+export interface FrictionSignal {
+    /** Stable kind, e.g. `repeated-tool-error`, `schema-rejection`, `flailing`. */
+    kind: string;
+    owner: FrictionOwner;
+    severity: FrictionSeverity;
+    /** What happened, in one sentence, naming the tool where there is one. */
+    summary: string;
+    /** The tool this is about, when the signal is tool-scoped. */
+    tool?: string;
+    /** Indices into `JobRunReport.toolCalls` that evidence the signal. */
+    callIndices: number[];
+    /**
+     * The verbatim evidence — an error string the harness returned, the repeated
+     * arguments. An optimizer that only sees a summary is diagnosing our
+     * paraphrase instead of the run.
+     */
+    evidence: string[];
+}
+/** A named boolean assertion over the world the job left behind. */
+export interface JobOutcomeCheck<TFinal = unknown> {
+    name: string;
+    /** What the agent was supposed to have achieved, in the user's terms. */
+    describe: string;
+    test: (state: TFinal) => boolean;
+}
+/**
+ * One job an agent takes end to end.
+ *
+ * The `statement` is deliberately written in JTBD form ("when ... I want ... so
+ * I can ...") rather than as a task label. It is what the optimizer quotes back
+ * to a model when asking whether the run achieved anything, and a label like
+ * "timeline test 3" gives it nothing to judge against.
+ */
+export interface JobToBeDone<TFinal = unknown> {
+    id: string;
+    /** "When <situation>, I want to <motivation>, so I can <outcome>." */
+    statement: string;
+    /** Surface ids from the harness registry this job crosses. */
+    surfaces: string[];
+    /**
+     * How hard the job is meant to be. `smoke` jobs should never fail on a
+     * capable model — one that does is a harness regression, not a model gap.
+     */
+    difficulty: "smoke" | "standard" | "long-horizon";
+    /** The objective handed to the agent, in the user's own voice. */
+    objective: string;
+    /** Builds a fresh world per run. */
+    createBridge: () => HeadlessSurfaceBridge<TFinal>;
+    /** System prompt under test. Absent means the suite default is under test. */
+    systemPrompt?: string;
+    /** Turn cap. A long-horizon job declares the budget it needs. */
+    maxIterations?: number;
+    /** Needs configured model providers to be solvable at all. */
+    needsModelProviders?: boolean;
+    /** What "done" means for this job. */
+    outcomes: JobOutcomeCheck<TFinal>[];
+    /**
+     * Turn budget past which the run is doing the job the slow way. Exceeding it
+     * is friction, never failure — a job done in 30 calls is still done.
+     */
+    expectedToolCalls?: number;
+}
+/** Everything one run of a job produced. */
+export interface JobRunReport {
+    jobId: string;
+    statement: string;
+    provider: string;
+    model: string;
+    startedAt: string;
+    skipped: boolean;
+    /** The loop ran to a stop without a provider error. */
+    completed: boolean;
+    /** Every outcome check passed — the job actually got done. */
+    achieved: boolean;
+    outcomes: Array<{
+        name: string;
+        describe: string;
+        passed: boolean;
+    }>;
+    /** The full conversation, system prompt first. */
+    transcript: Message[];
+    toolCalls: ToolLoopCallRecord[];
+    friction: FrictionSignal[];
+    totalToolCalls: number;
+    durationMs: number;
+    costUsd: number;
+    error?: string;
+}
+export interface JobSuiteReport {
+    provider: string;
+    model: string;
+    startedAt: string;
+    jobs: JobRunReport[];
+    summary: {
+        total: number;
+        skipped: number;
+        achieved: number;
+        /** achieved / (total - skipped) — the number a gate reads. */
+        achievementRate: number;
+        /** Friction signals across the suite, by owner. */
+        frictionByOwner: Record<FrictionOwner, number>;
+        totalCostUsd: number;
+    };
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/jtbd/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/jtbd/types.ts"],"names":[],"mappings":"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"}

package/dist/jtbd/types.js

@@ -0,0 +1,25 @@
+/**
+ * Jobs to be done — the agent-intent layer over NodeTool's surfaces.
+ *
+ * The repo already catalogues two things: `SURFACES` (what a product owner
+ * ships) and `CAPABILITY_COVERAGE` (what a tool call can do). Neither answers
+ * the question an optimizer needs to ask, which is what an agent was *trying to
+ * get done* and where the product stopped it. A capability check proves
+ * `add_track` returns a track id; it cannot notice that no model ever finds
+ * `add_track` because its description does not say the word "audio".
+ *
+ * A job is one objective an agent takes end to end across whatever surfaces it
+ * needs, run against the real tool contract, recorded in full. Three things
+ * come out of a run and all three matter:
+ *
+ *  - the **transcript** — the system prompt, every assistant turn, every tool
+ *    call and its result. Without it a failed run says "score 0.4" and nothing
+ *    an outer agent can act on.
+ *  - the **outcome** — did the job get done, per the case's own checks.
+ *  - the **friction** — where the run wasted turns, and whether the blame lands
+ *    on the harness or on the prompt. This is the attribution the optimizer
+ *    reads; see `friction.ts` for how it is derived and why it is a heuristic
+ *    that proposes rather than decides.
+ */
+export {};
+//# sourceMappingURL=types.js.map

package/dist/jtbd/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/jtbd/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG"}

package/dist/model-prompting-skills.d.ts

@@ -0,0 +1,45 @@
+/**
+ * Which shipped prompting skill covers a model line.
+ *
+ * A generation model line has house rules — Seedance wants a sound brief,
+ * GPT Image wants five labelled slots, MiniMax H3 wants a job assigned to
+ * every reference — and a model that writes the same prompt for all of them
+ * gets the blandest reading each one has. The skills in
+ * `packages/system-skills` carry those rules; this table is what points at the
+ * right one before the prompt is written rather than after the render comes
+ * back wrong.
+ *
+ * Two paths reach the same skill. The always-on skill catalog names the model
+ * ids in each description, so an agent that already knows its model can call
+ * `load_skill` unprompted. `find_model` is the mechanical path: a matching
+ * route carries `prompting_skill`, which is the step immediately before the
+ * prompt gets written.
+ *
+ * Matching is on the model id alone. Every provider qualifies its ids enough
+ * to identify the line (`fal-ai/nano-banana-pro`, `google/nano-banana-pro/
+ * text-to-image`, `nano-banana-pro`), so the provider adds nothing and a new
+ * provider serving the same line is covered with no change here.
+ */
+/** One model line and the skill that teaches it. */
+export interface ModelPromptingSkill {
+    /** The system skill's name, as `load_skill` takes it. */
+    readonly skill: string;
+    /** The line, spelled the way a person says it. */
+    readonly line: string;
+    /** Matched against a lowercased model id. */
+    readonly pattern: RegExp;
+}
+/**
+ * The lines with a shipped guide, in the order a tie would be resolved. No two
+ * patterns overlap today; the order is fixed so that if two ever do, which one
+ * wins is a property of this list and not of object iteration.
+ *
+ * Each pattern is deliberately narrow at the version boundary. The Nano Banana
+ * Pro guide is not the Nano Banana 2 guide, and `gpt-image-2` must not answer
+ * for `gpt-image-1.5`, so a lookahead blocks the digit and the dot that would
+ * make a future version inherit an older line's rules by accident.
+ */
+export declare const MODEL_PROMPTING_SKILLS: readonly ModelPromptingSkill[];
+/** The skill covering `modelId`, or null when no shipped guide claims it. */
+export declare function promptingSkillFor(modelId: string): string | null;
+//# sourceMappingURL=model-prompting-skills.d.ts.map

package/dist/model-prompting-skills.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"model-prompting-skills.d.ts","sourceRoot":"","sources":["../src/model-prompting-skills.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAEH,oDAAoD;AACpD,MAAM,WAAW,mBAAmB;IAClC,yDAAyD;IACzD,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,kDAAkD;IAClD,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,6CAA6C;IAC7C,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;CAC1B;AAED;;;;;;;;;GASG;AACH,eAAO,MAAM,sBAAsB,EAAE,SAAS,mBAAmB,EA4EhE,CAAC;AAEF,6EAA6E;AAC7E,wBAAgB,iBAAiB,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAIhE"}

package/dist/model-prompting-skills.js

@@ -0,0 +1,116 @@
+/**
+ * Which shipped prompting skill covers a model line.
+ *
+ * A generation model line has house rules — Seedance wants a sound brief,
+ * GPT Image wants five labelled slots, MiniMax H3 wants a job assigned to
+ * every reference — and a model that writes the same prompt for all of them
+ * gets the blandest reading each one has. The skills in
+ * `packages/system-skills` carry those rules; this table is what points at the
+ * right one before the prompt is written rather than after the render comes
+ * back wrong.
+ *
+ * Two paths reach the same skill. The always-on skill catalog names the model
+ * ids in each description, so an agent that already knows its model can call
+ * `load_skill` unprompted. `find_model` is the mechanical path: a matching
+ * route carries `prompting_skill`, which is the step immediately before the
+ * prompt gets written.
+ *
+ * Matching is on the model id alone. Every provider qualifies its ids enough
+ * to identify the line (`fal-ai/nano-banana-pro`, `google/nano-banana-pro/
+ * text-to-image`, `nano-banana-pro`), so the provider adds nothing and a new
+ * provider serving the same line is covered with no change here.
+ */
+/**
+ * The lines with a shipped guide, in the order a tie would be resolved. No two
+ * patterns overlap today; the order is fixed so that if two ever do, which one
+ * wins is a property of this list and not of object iteration.
+ *
+ * Each pattern is deliberately narrow at the version boundary. The Nano Banana
+ * Pro guide is not the Nano Banana 2 guide, and `gpt-image-2` must not answer
+ * for `gpt-image-1.5`, so a lookahead blocks the digit and the dot that would
+ * make a future version inherit an older line's rules by accident.
+ */
+export const MODEL_PROMPTING_SKILLS = [
+    {
+        skill: "nano-banana-pro-prompting",
+        line: "Nano Banana Pro",
+        pattern: /nano-banana-pro/
+    },
+    {
+        skill: "gpt-image-2-prompting",
+        line: "GPT Image 2",
+        pattern: /gpt-image-2(?![.\d])/
+    },
+    {
+        skill: "flux-2-klein-prompting",
+        line: "FLUX.2 [klein]",
+        pattern: /flux-2[/-]klein/
+    },
+    {
+        skill: "seedance-2-prompting",
+        line: "Seedance 2",
+        pattern: /seedance-2(?!\d)/
+    },
+    {
+        skill: "veo-3-prompting",
+        line: "Veo 3",
+        pattern: /veo-?3(?!\d)/
+    },
+    {
+        skill: "minimax-h3-prompting",
+        line: "MiniMax H3",
+        pattern: /minimax\/h3(?![a-z0-9])/
+    },
+    {
+        skill: "wan-2-6-prompting",
+        line: "Wan 2.6",
+        pattern: /wan-?2[.-]6/
+    },
+    {
+        // Kling from 2.5-turbo on: the versions with a shot list, tagged elements
+        // and native audio. The alternation is what keeps 1.x, 2.0 and 2.1 out,
+        // and requiring a version right after the family name is what keeps
+        // `kling-image` — a different model with different rules — out too.
+        skill: "kling-video-prompting",
+        line: "Kling video 2.5-turbo and later",
+        pattern: /kling(?:-video)?[-/]v?(?:2[.-][56]|3(?:\.0)?|o[13])(?![.\d])/
+    },
+    {
+        // MiniMax's earlier video line. H3 is a separate guide, and no Hailuo id
+        // carries `minimax/h3`, so the two never contend for the same model.
+        skill: "hailuo-prompting",
+        line: "MiniMax Hailuo",
+        pattern: /hailuo|minimax\/video-01/
+    },
+    {
+        skill: "seedream-prompting",
+        line: "Seedream 4 and 5",
+        pattern: /seedream[/-]v?[45](?![\d])/
+    },
+    {
+        // The whole Qwen-Image family — text-to-image, the edit checkpoints and
+        // the layered variants share one set of house rules for typography.
+        skill: "qwen-image-prompting",
+        line: "Qwen-Image",
+        pattern: /qwen-image/
+    },
+    {
+        // Only the endpoints that take a prompt. Scribe, dubbing, isolation and
+        // voice-changer are ElevenLabs too and have nothing to prompt.
+        skill: "elevenlabs-audio-prompting",
+        line: "ElevenLabs speech, dialogue, sound effects and music",
+        pattern: /elevenlabs\/(?:tts|music|sound-effects|text-to-speech|text-to-dialogue|v3|v2-multilingual|turbo|flash)/
+    },
+    {
+        skill: "stable-audio-prompting",
+        line: "Stable Audio",
+        pattern: /stable-audio/
+    }
+];
+/** The skill covering `modelId`, or null when no shipped guide claims it. */
+export function promptingSkillFor(modelId) {
+    const id = modelId.toLowerCase();
+    const hit = MODEL_PROMPTING_SKILLS.find((entry) => entry.pattern.test(id));
+    return hit ? hit.skill : null;
+}
+//# sourceMappingURL=model-prompting-skills.js.map

package/dist/model-prompting-skills.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"model-prompting-skills.js","sourceRoot":"","sources":["../src/model-prompting-skills.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAYH;;;;;;;;;GASG;AACH,MAAM,CAAC,MAAM,sBAAsB,GAAmC;IACpE;QACE,KAAK,EAAE,2BAA2B;QAClC,IAAI,EAAE,iBAAiB;QACvB,OAAO,EAAE,iBAAiB;KAC3B;IACD;QACE,KAAK,EAAE,uBAAuB;QAC9B,IAAI,EAAE,aAAa;QACnB,OAAO,EAAE,sBAAsB;KAChC;IACD;QACE,KAAK,EAAE,wBAAwB;QAC/B,IAAI,EAAE,gBAAgB;QACtB,OAAO,EAAE,iBAAiB;KAC3B;IACD;QACE,KAAK,EAAE,sBAAsB;QAC7B,IAAI,EAAE,YAAY;QAClB,OAAO,EAAE,kBAAkB;KAC5B;IACD;QACE,KAAK,EAAE,iBAAiB;QACxB,IAAI,EAAE,OAAO;QACb,OAAO,EAAE,cAAc;KACxB;IACD;QACE,KAAK,EAAE,sBAAsB;QAC7B,IAAI,EAAE,YAAY;QAClB,OAAO,EAAE,yBAAyB;KACnC;IACD;QACE,KAAK,EAAE,mBAAmB;QAC1B,IAAI,EAAE,SAAS;QACf,OAAO,EAAE,aAAa;KACvB;IACD;QACE,0EAA0E;QAC1E,wEAAwE;QACxE,oEAAoE;QACpE,oEAAoE;QACpE,KAAK,EAAE,uBAAuB;QAC9B,IAAI,EAAE,iCAAiC;QACvC,OAAO,EAAE,8DAA8D;KACxE;IACD;QACE,yEAAyE;QACzE,qEAAqE;QACrE,KAAK,EAAE,kBAAkB;QACzB,IAAI,EAAE,gBAAgB;QACtB,OAAO,EAAE,0BAA0B;KACpC;IACD;QACE,KAAK,EAAE,oBAAoB;QAC3B,IAAI,EAAE,kBAAkB;QACxB,OAAO,EAAE,4BAA4B;KACtC;IACD;QACE,wEAAwE;QACxE,oEAAoE;QACpE,KAAK,EAAE,sBAAsB;QAC7B,IAAI,EAAE,YAAY;QAClB,OAAO,EAAE,YAAY;KACtB;IACD;QACE,wEAAwE;QACxE,+DAA+D;QAC/D,KAAK,EAAE,4BAA4B;QACnC,IAAI,EAAE,sDAAsD;QAC5D,OAAO,EAAE,wGAAwG;KAClH;IACD;QACE,KAAK,EAAE,wBAAwB;QAC/B,IAAI,EAAE,cAAc;QACpB,OAAO,EAAE,cAAc;KACxB;CACF,CAAC;AAEF,6EAA6E;AAC7E,MAAM,UAAU,iBAAiB,CAAC,OAAe;IAC/C,MAAM,EAAE,GAAG,OAAO,CAAC,WAAW,EAAE,CAAC;IACjC,MAAM,GAAG,GAAG,sBAAsB,CAAC,IAAI,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,KAAK,CAAC,OAAO,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC,CAAC;IAC3E,OAAO,GAAG,CAAC,CAAC,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC,CAAC,IAAI,CAAC;AAChC,CAAC"}

package/dist/network-guard.d.ts

@@ -0,0 +1,50 @@
+/**
+ * Which network addresses untrusted code may reach.
+ *
+ * Guest JavaScript and the host binaries it drives run inside the server, so
+ * "fetch this URL" is a request to open a socket from a process that sits
+ * behind the cloud's perimeter. The address that matters most is
+ * `169.254.169.254`, the instance metadata service, but loopback, the private
+ * ranges, CGNAT and the IPv6 spellings of all of them reach the same class of
+ * thing: services that trusted the network instead of the caller.
+ *
+ * This lives apart from `js-sandbox.ts` because the fetch bridge is no longer
+ * the only caller: `yt_dlp` hands a URL to a downloader that opens its own
+ * sockets, and one wrong answer there is the same breach. One table, one
+ * predicate, both surfaces.
+ *
+ * The table itself is `@nodetool-ai/runtime`'s: `isBlockedIpLiteral` in
+ * `providers/safe-url.ts`, imported through the leaf subpath so the browser
+ * bundle takes the module and not the rest of runtime. What stays here is the
+ * *policy* this surface applies on top of it — plain http is allowed (a Code
+ * node reaching an internal HTTP service is a supported thing to configure),
+ * and a host may waive the address check with `allowPrivate`, which NodeTool's
+ * default egress policy never does.
+ *
+ * The check reads the URL's host. A hostname that *resolves* to a blocked
+ * address is caught by {@link assertResolvedHostAllowed}, which the caller
+ * uses when it can afford a DNS round trip.
+ */
+import { isBlockedIpLiteral } from "@nodetool-ai/runtime/safe-url";
+export { isBlockedIpLiteral };
+/**
+ * SSRF allow-check for the sandbox fetch bridge. Rejects non-http(s) schemes
+ * and hosts that resolve to loopback/link-local/private literals or localhost.
+ * Throws on a blocked URL.
+ */
+export declare function assertFetchUrlAllowed(url: string, allowPrivate?: boolean): void;
+/**
+ * Refuse a URL whose hostname resolves to a blocked address, on top of the
+ * literal check {@link assertFetchUrlAllowed} makes.
+ *
+ * A literal check answers `metadata.example.com` with "that is not an IP", and
+ * the name resolves to `169.254.169.254` a millisecond later. Resolving here
+ * closes the ordinary case. It does not close every case — the process we hand
+ * the URL to resolves again (so a record that changes between the two answers
+ * wins) and follows its own redirects — which is why this is one layer, not
+ * the boundary. `label` names the caller in the refusal.
+ */
+export declare function assertResolvedHostAllowed(url: string, label: string, resolve?: HostResolver): Promise<void>;
+/** How {@link assertResolvedHostAllowed} turns a hostname into addresses. */
+export type HostResolver = (host: string) => Promise<string[]>;
+//# sourceMappingURL=network-guard.d.ts.map

package/dist/network-guard.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"network-guard.d.ts","sourceRoot":"","sources":["../src/network-guard.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AAGH,OAAO,EAAE,kBAAkB,EAAE,MAAM,+BAA+B,CAAC;AAEnE,OAAO,EAAE,kBAAkB,EAAE,CAAC;AAU9B;;;;GAIG;AACH,wBAAgB,qBAAqB,CAAC,GAAG,EAAE,MAAM,EAAE,YAAY,UAAQ,GAAG,IAAI,CAsB7E;AAED;;;;;;;;;;GAUG;AACH,wBAAsB,yBAAyB,CAC7C,GAAG,EAAE,MAAM,EACX,KAAK,EAAE,MAAM,EACb,OAAO,GAAE,YAA8B,GACtC,OAAO,CAAC,IAAI,CAAC,CAkBf;AAED,6EAA6E;AAC7E,MAAM,MAAM,YAAY,GAAG,CAAC,IAAI,EAAE,MAAM,KAAK,OAAO,CAAC,MAAM,EAAE,CAAC,CAAC"}