@avow-finance/sdk 0.0.0-stage → 0.2.0

package/dist/session/session.js

@@ -0,0 +1,312 @@
+import { formatUsd, SAID_TEXT_MAX, speakerName, } from '@avow-finance/spec';
+import { JobExecutor } from './executor.js';
+import { ProviderError } from './provider.js';
+import { CUSTOMER_REFUSED_PROMPT, ORDER_PROMPT, SWITCH_OFF_PROMPT } from './scripted.js';
+import { policyChanges } from './service.js';
+import { newSessionState, Toolbox } from './toolbox.js';
+import { isJobTool, toolSpecs } from './tools.js';
+/**
+ * The lines that take the next order. `job` or `/job` takes one that runs to payment, and
+ * `job cancels` takes one the test customer cancels after work starts.
+ */
+export const JOB_COMMAND = /^\/?job(\s+cancels)?$/i;
+/** The scenario a job command asks for, or null for a plain order. */
+export const scenarioOf = (line) => JOB_COMMAND.exec(line.trim())?.[1] ? 'cancels_late' : null;
+/** The most steps a model takes in one turn before the session stops it. */
+const MAX_STEPS = 12;
+export const SYSTEM_PROMPT = `You are a business's job agent in Avow's testnet sandbox. Avow's test customer sends paid fine-tuning jobs. A job needs GPUs from its start to its deadline, and the customer accepts your quote only when it names your accepted compute booking that holds those GPUs for the whole job, past its free cancellation.
+
+For each order, call read_order, then compute_offers, then book_compute for the cheapest offer that is firm (no free cancellation left), holds the order's GPUs from before the job starts to past its deadline, takes that many GPUs in one booking and fits the compute budget. Then call submit_quote naming that booking. If the compute switch in service.ts is off, book nothing and call submit_quote with no booking.
+
+Code outside you checks everything. service.ts applies the budget and the compute switch, the SDK, Avow and the lock check your authority, and the customer checks the quote. You never verify the customer, start work, deliver or pay, since the developer's code does that after your turn. When a tool refuses, say which layer refused, its reason code, and what would let it pass. Nothing typed can undo a transaction already sent. Answer the developer briefly and plainly, and explain your choices from the tool results you got.`;
+/** What the session says once, when it starts, about the model and what goes where. */
+export function whatGoesWhere(provider, brief = false) {
+    if (brief) {
+        return [
+            `Model: ${provider.line}.`,
+            provider.reaches === 'this machine'
+                ? 'Your keys and the whole conversation stay on this machine. Your browser shows what your agent says and does.'
+                : 'Your keys stay on this machine, and the conversation goes to Anthropic. Your browser shows what your agent says and does.',
+        ];
+    }
+    return [
+        `Model: ${provider.line}.`,
+        "Stays on this machine: your business's keys, its passphrase and the sealed key file.",
+        provider.reaches === 'this machine'
+            ? 'Stays on this machine too: the whole conversation, since the model runs here.'
+            : 'Goes to Anthropic: the conversation, meaning the order, the offers, tool results and what you type.',
+        "Goes to your screen through Avow's relay: the agent's speech, its tool calls and their results, facts, receipts and refusals. What you type isn't posted, though the agent's replies can repeat it.",
+    ];
+}
+/** Text in pieces the event schema takes. */
+function chunks(text) {
+    const out = [];
+    for (let i = 0; i < text.length; i += SAID_TEXT_MAX)
+        out.push(text.slice(i, i + SAID_TEXT_MAX));
+    return out;
+}
+const IN_FLIGHT = {
+    book_compute: 'the compute booking being sent',
+    submit_quote: 'the quote being sent',
+    cancel_compute: 'the cancellation being sent',
+};
+export async function runSession(deps) {
+    const { world, provider, view } = deps;
+    const model = speakerName(provider.model);
+    const state = newSessionState();
+    const turns = [];
+    let policy = await deps.readPolicy();
+    const inFlight = (what) => deps.input?.inFlight(what);
+    const toolbox = new Toolbox(world, () => policy, deps.emit, state, refresh);
+    const executor = new JobExecutor({
+        world,
+        emit: deps.emit,
+        checkBeforeWork: deps.checkBeforeWork,
+        note: (line) => view.quiet(line),
+        busy: inFlight,
+        ...(deps.pollMs === undefined ? {} : { pollMs: deps.pollMs }),
+        ...(deps.workMs === undefined ? {} : { workMs: deps.workMs }),
+    });
+    view.intro([
+        ...whatGoesWhere(provider, deps.brief),
+        ...(deps.input && !deps.afterJob
+            ? [
+                'Type job to take the next order, or job cancels for one the customer cancels after work starts. Anything else you type goes to your agent.',
+            ]
+            : []),
+    ]);
+    // One model turn at a time, whichever started it.
+    let queue = Promise.resolve();
+    const oneAtATime = (work) => {
+        const next = queue.then(work);
+        queue = next.catch(() => { });
+        return next;
+    };
+    /** What service.ts held when it was last read, apart from a switch a guide holds off. */
+    let inFile = policy;
+    /**
+     * Reads service.ts again, says what changed, and gives the note the model needs about it. A
+     * guide can hold the compute switch off for an order, which is said as the guide's doing and
+     * never as a change to the file.
+     */
+    async function refresh() {
+        const read = await deps.readPolicy();
+        for (const line of policyChanges(inFile, read))
+            view.quiet(line);
+        inFile = read;
+        const held = read.computeSwitch === 'on' && deps.withoutCompute?.() === true;
+        const next = held ? { ...read, computeSwitch: 'off' } : read;
+        if (policy.computeSwitch === 'on' && next.computeSwitch === 'off') {
+            if (held) {
+                view.quiet('For this order your agent books no compute, as bookCompute: false in service.ts would have it.');
+            }
+            notes.push(`The developer ${SWITCH_OFF_PROMPT} ${held ? 'for this order' : 'in service.ts'} and still wants a quote.`);
+        }
+        else if (policy.computeSwitch === 'off' && next.computeSwitch === 'on') {
+            notes.push('Compute booking is on again.');
+        }
+        policy = next;
+    }
+    /** Notes the model needs about service.ts, each given once, with the next prompt. */
+    const notes = [];
+    /** One turn of the model, with each tool call run by the tool layer, until it ends its turn. */
+    async function turn(run, orderId, prompt) {
+        turns.push({ role: 'user', text: prompt });
+        let call = 0;
+        for (let step = 0; step < MAX_STEPS; step++) {
+            const speech = view.speak(model);
+            let reply;
+            try {
+                reply = await provider.reply({
+                    system: SYSTEM_PROMPT,
+                    turns,
+                    tools: toolSpecs(policy.computeSwitch),
+                    onText: speech.write,
+                });
+            }
+            finally {
+                speech.end();
+            }
+            for (const text of chunks(reply.text.trim())) {
+                deps.emit({
+                    run,
+                    source: 'session',
+                    orderId,
+                    type: 'said',
+                    speaker: { kind: 'model', model },
+                    text,
+                });
+            }
+            turns.push({ role: 'assistant', text: reply.text, calls: reply.calls, native: reply.native });
+            if (reply.calls.length === 0)
+                return;
+            for (const c of reply.calls) {
+                if (!isJobTool(c.name)) {
+                    const why = `There's no tool named ${c.name}. The tools are the seven you were given.`;
+                    turns.push({
+                        role: 'tool',
+                        call: c,
+                        ok: false,
+                        content: JSON.stringify({ refused: true, why }),
+                    });
+                    continue;
+                }
+                inFlight(IN_FLIGHT[c.name] ?? null);
+                try {
+                    const outcome = await toolbox.run(c.name, c.input, { run, orderId, call: ++call });
+                    turns.push({ role: 'tool', call: c, content: outcome.content, ok: outcome.ok });
+                }
+                finally {
+                    inFlight(null);
+                }
+            }
+        }
+        view.quiet(`The model took ${MAX_STEPS} steps without ending its turn, so the session stopped it.`);
+    }
+    /** A job: the order comes in, the model quotes it, then the executor follows the quote. */
+    async function job(notes, scenario = null) {
+        let order;
+        try {
+            order = await world.pullOrder(scenario ?? undefined);
+        }
+        catch (error) {
+            // A customer that can't play a scenario out refuses the order, and the session goes on.
+            if (scenario === null)
+                throw error;
+            const why = `Avow's test customer didn't offer a job it cancels. ${error instanceof Error ? error.message : String(error)}`;
+            // A guide says how each job ended itself.
+            if (!deps.afterJob)
+                view.quiet(why);
+            return { kind: 'stopped', why };
+        }
+        state.order = order;
+        const run = deps.nextRun();
+        const t = order.terms;
+        deps.emit({
+            run,
+            source: 'session',
+            orderId: order.orderId,
+            type: 'job_order_received',
+            customer: order.customer,
+            work: t.subject.work,
+            price: t.consideration.kind === 'fixed' ? t.consideration.amount : 0n,
+            deliverBy: t.subject.deliverBy,
+            requirement: order.requirement,
+        });
+        const prompt = [`${ORDER_PROMPT} ${order.orderId} from Avow's test customer.`, ...notes];
+        await oneAtATime(() => turn(run, order.orderId, prompt.join(' ')));
+        const quoted = state.quotes.get(order.orderId);
+        if (!quoted)
+            return null;
+        const outcome = await executor.follow({
+            run,
+            order,
+            quote: quoted.quote,
+            ...(scenario ? { scenario } : {}),
+        });
+        if (outcome.kind === 'refused') {
+            const { code, layer } = outcome.refusal;
+            await oneAtATime(() => turn(run, order.orderId, `${CUSTOMER_REFUSED_PROMPT} with ${code}, at the ${layer} layer. Explain to the developer what that means and what would let a quote pass.`));
+        }
+        else if (outcome.kind === 'stopped') {
+            view.quiet(outcome.why);
+        }
+        return outcome;
+    }
+    /** Whether an order is still waiting for its quote. */
+    const openOrder = () => state.order !== null && !state.quotes.has(state.order.orderId);
+    /** The recorded listing and booking beside an answer to "why", as results shown again. */
+    function showEvidence(run) {
+        const listing = state.listing;
+        if (!listing)
+            return;
+        const listed = state.recorded.find((r) => r.run === listing.run && r.call === listing.call);
+        const booked = [...state.recorded].reverse().find((r) => r.tool === 'book_compute' && r.offer);
+        for (const r of [listed, booked]) {
+            if (r)
+                deps.emit({ ...r.event, run, orderId: null, recalled: { run: r.run, call: r.call } });
+        }
+        const { offers, listedAt } = listing.listing;
+        const limits = listing.limits;
+        const marked = offers.findIndex((o) => o.id === booked?.offer);
+        view.evidence({
+            title: `The offers the agent compared in run ${listing.run}, as the tool layer recorded them`,
+            columns: ['offer', 'GPUs', 'per GPU-hour', 'reserve per GPU', 'free cancellation'],
+            rows: offers.map((o) => [
+                o.id,
+                o.gpus.min === o.gpus.max ? `${o.gpus.min}` : `${o.gpus.min} to ${o.gpus.max}`,
+                formatUsd(o.pricePerGpuHour),
+                formatUsd(o.reservePerGpu),
+                o.freeCancelBy <= listedAt ? 'none, firm' : 'still open',
+            ]),
+            ...(marked >= 0 ? { marked } : {}),
+            notes: [
+                `The budget in service.ts was ${formatUsd(limits.budgetPerGpuHour)} per GPU-hour, with the compute switch ${limits.computeSwitch}.`,
+                `The agent could commit ${formatUsd(limits.capPerCommitment)} for one commitment, with ${formatUsd(limits.openReservesLeft)} left of ${formatUsd(limits.capOpenReserves)} held at once.`,
+            ],
+        });
+    }
+    let firstJob = null;
+    const jobs = [];
+    try {
+        if (!deps.input) {
+            firstJob = await job([]);
+            return { firstJob, stopped: null };
+        }
+        // The first job runs on its own, and the developer can type while it goes on, except on a
+        // guided first run, which shows the whole job before it asks for anything.
+        const first = job([]).then((outcome) => {
+            firstJob = outcome;
+        });
+        jobs.push(first);
+        if (deps.afterJob) {
+            await first;
+            deps.afterJob(firstJob);
+        }
+        let failed = null;
+        first.catch((error) => {
+            failed = error;
+        });
+        for (;;) {
+            const line = await deps.input.next();
+            if (failed)
+                throw failed;
+            if (line === null)
+                break;
+            const text = line.trim();
+            if (!text)
+                continue;
+            await refresh();
+            // Only the job command takes the next order. Everything else goes to the model.
+            if (JOB_COMMAND.test(text)) {
+                if (openOrder())
+                    view.quiet('An order is still waiting for its quote, so the session takes no other yet.');
+                else {
+                    const next = job(notes.splice(0), scenarioOf(text) ?? deps.scenario?.() ?? null);
+                    jobs.push(next);
+                    if (deps.afterJob)
+                        deps.afterJob(await next);
+                }
+                continue;
+            }
+            const run = deps.nextRun();
+            await oneAtATime(() => turn(run, null, [...notes.splice(0), text].join(' ')));
+            if (/\bwhy\b/i.test(text))
+                showEvidence(run);
+        }
+        await Promise.allSettled(jobs);
+        return { firstJob, stopped: null };
+    }
+    catch (error) {
+        if (error instanceof ProviderError) {
+            view.fail(`${provider.line} failed. ${error.message} The session switches to no other model.`);
+            return { firstJob, stopped: error.message };
+        }
+        throw error;
+    }
+    finally {
+        // A charge still inside its contest window is followed only while the session runs.
+        executor.stop();
+    }
+}
+//# sourceMappingURL=session.js.map

package/dist/session/session.js.map

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

package/dist/session/toolbox.d.ts

@@ -0,0 +1,69 @@
+import { type ComputeOffers, type JobOffer, type JobTool, type QuoteRequest, type SessionEvent, type ToolLimits } from '@avow-finance/spec';
+import type { ServicePolicy } from './service.js';
+import type { JobWorld, WorldBooking } from './world.js';
+/**
+ * The tool layer: it reads a model's tool call, applies the developer's policy from `service.ts`,
+ * calls the world, and writes every result in code. The model sees only what this returns, which is
+ * public data, and every event it emits says what happened, apart from anything the model said.
+ */
+/** Where a tool call runs: its run, the run's order, and the call's number in the run. */
+export interface CallContext {
+    run: number;
+    orderId: string | null;
+    call: number;
+}
+/** What a tool returned to the model, and whether it succeeded. */
+export interface ToolOutcome {
+    ok: boolean;
+    /** What the model reads, as JSON text. */
+    content: string;
+}
+/** A result the session recorded, so it can show it again as evidence beside an answer. */
+export interface Recorded {
+    run: number;
+    call: number;
+    tool: JobTool;
+    event: Extract<SessionEvent, {
+        type: 'tool_result';
+    }>;
+    /** The offer a booking call named, or null for any other result. */
+    offer: string | null;
+}
+/** What the session keeps between tool calls. */
+export interface SessionState {
+    /** The order the current job is for, or the last one. */
+    order: JobOffer | null;
+    /** The latest listing the model saw, with the call that listed it. */
+    listing: {
+        run: number;
+        call: number;
+        listing: ComputeOffers;
+        limits: ToolLimits;
+    } | null;
+    /** Every compute booking the session made, by its id. */
+    bookings: Map<string, WorldBooking>;
+    /** Each order's quote once it went out, with the booking it named. */
+    quotes: Map<string, {
+        quote: QuoteRequest;
+        booking: WorldBooking | null;
+        run: number;
+    }>;
+    /** The results of compute_offers and book_compute, for the evidence beside an answer. */
+    recorded: Recorded[];
+}
+export declare function newSessionState(): SessionState;
+export declare class Toolbox {
+    #private;
+    private readonly world;
+    private readonly policy;
+    private readonly emit;
+    readonly state: SessionState;
+    /** Reads service.ts again before a booking, so an edit made mid-turn applies to it. */
+    private readonly beforeBooking;
+    constructor(world: JobWorld, policy: () => ServicePolicy, emit: (event: SessionEvent) => void, state: SessionState, 
+    /** Reads service.ts again before a booking, so an edit made mid-turn applies to it. */
+    beforeBooking?: () => Promise<void>);
+    /** Runs one tool call the model made, and gives the model what it returned. */
+    run(tool: JobTool, input: unknown, ctx: CallContext): Promise<ToolOutcome>;
+}
+//# sourceMappingURL=toolbox.d.ts.map

package/dist/session/toolbox.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"toolbox.d.ts","sourceRoot":"","sources":["../../src/session/toolbox.ts"],"names":[],"mappings":"AAAA,OAAO,EAEL,KAAK,aAAa,EAIlB,KAAK,QAAQ,EACb,KAAK,OAAO,EAGZ,KAAK,YAAY,EAKjB,KAAK,YAAY,EACjB,KAAK,UAAU,EAChB,MAAM,oBAAoB,CAAA;AAE3B,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,cAAc,CAAA;AAEjD,OAAO,KAAK,EAAgB,QAAQ,EAAE,YAAY,EAAE,MAAM,YAAY,CAAA;AAEtE;;;;GAIG;AAEH,0FAA0F;AAC1F,MAAM,WAAW,WAAW;IAC1B,GAAG,EAAE,MAAM,CAAA;IACX,OAAO,EAAE,MAAM,GAAG,IAAI,CAAA;IACtB,IAAI,EAAE,MAAM,CAAA;CACb;AAED,mEAAmE;AACnE,MAAM,WAAW,WAAW;IAC1B,EAAE,EAAE,OAAO,CAAA;IACX,0CAA0C;IAC1C,OAAO,EAAE,MAAM,CAAA;CAChB;AAED,2FAA2F;AAC3F,MAAM,WAAW,QAAQ;IACvB,GAAG,EAAE,MAAM,CAAA;IACX,IAAI,EAAE,MAAM,CAAA;IACZ,IAAI,EAAE,OAAO,CAAA;IACb,KAAK,EAAE,OAAO,CAAC,YAAY,EAAE;QAAE,IAAI,EAAE,aAAa,CAAA;KAAE,CAAC,CAAA;IACrD,oEAAoE;IACpE,KAAK,EAAE,MAAM,GAAG,IAAI,CAAA;CACrB;AAED,iDAAiD;AACjD,MAAM,WAAW,YAAY;IAC3B,yDAAyD;IACzD,KAAK,EAAE,QAAQ,GAAG,IAAI,CAAA;IACtB,sEAAsE;IACtE,OAAO,EAAE;QAAE,GAAG,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,aAAa,CAAC;QAAC,MAAM,EAAE,UAAU,CAAA;KAAE,GAAG,IAAI,CAAA;IACzF,yDAAyD;IACzD,QAAQ,EAAE,GAAG,CAAC,MAAM,EAAE,YAAY,CAAC,CAAA;IACnC,sEAAsE;IACtE,MAAM,EAAE,GAAG,CAAC,MAAM,EAAE;QAAE,KAAK,EAAE,YAAY,CAAC;QAAC,OAAO,EAAE,YAAY,GAAG,IAAI,CAAC;QAAC,GAAG,EAAE,MAAM,CAAA;KAAE,CAAC,CAAA;IACvF,yFAAyF;IACzF,QAAQ,EAAE,QAAQ,EAAE,CAAA;CACrB;AAED,wBAAgB,eAAe,IAAI,YAAY,CAE9C;AAkCD,qBAAa,OAAO;;IAIhB,OAAO,CAAC,QAAQ,CAAC,KAAK;IACtB,OAAO,CAAC,QAAQ,CAAC,MAAM;IACvB,OAAO,CAAC,QAAQ,CAAC,IAAI;IACrB,QAAQ,CAAC,KAAK,EAAE,YAAY;IAC5B,uFAAuF;IACvF,OAAO,CAAC,QAAQ,CAAC,aAAa;IANhC,YACmB,KAAK,EAAE,QAAQ,EACf,MAAM,EAAE,MAAM,aAAa,EAC3B,IAAI,EAAE,CAAC,KAAK,EAAE,YAAY,KAAK,IAAI,EAC3C,KAAK,EAAE,YAAY;IAC5B,uFAAuF;IACtE,aAAa,GAAE,MAAM,OAAO,CAAC,IAAI,CAAkB,EAClE;IAEJ,+EAA+E;IACzE,GAAG,CAAC,IAAI,EAAE,OAAO,EAAE,KAAK,EAAE,OAAO,EAAE,GAAG,EAAE,WAAW,GAAG,OAAO,CAAC,WAAW,CAAC,CA0C/E;CAqaF"}