@midsummer-ai/sdk 0.0.0-stage → 0.1.0-next.1305

package/agents/index.mjs

@@ -0,0 +1,203 @@
+import { AsyncLocalStorage } from "node:async_hooks";
+//#region src/agents/index.ts
+/**
+* Agents: what an Agent's one file is, and the runtime that runs it. An Agent's file exports its
+* Agent as default:
+*
+*   import type { Agent } from "@midsummer-ai/sdk/agents"
+*   export default {
+*     tools: { async greet(input: { name: string }) { return `Hello, ${input.name}!` } },
+*     async run(input, agent) {
+*       const greeting = await agent.tool("greet", { name: input.name })
+*       await agent.memory.set("last", input.name)
+*       return { greeting }
+*     },
+*   } satisfies Agent
+*
+* `execute(agent, wire)` runs one Agent run: it begins the run, calls `run` with its input, and
+* finishes it with what `run` returns, or fails it with what `run` throws. Every await on `agent`
+* is a call the wire keeps, numbered in the order the code makes them, before it gets a reply. A
+* run that stopped part way and is executed again makes the same calls and gets the results already
+* recorded, so a completed step is not run again: keep work that should happen once in a step
+* (`agent.step`), and keep `run` itself deterministic outside its calls. A step interrupted before
+* its result is recorded can run again, so make its outside writes idempotent with an identifier
+* that stays the same across attempts. A tool runs only when the version allows it.
+*
+* `httpWire(url, token)` is the wire of a run on the platform; `@midsummer-ai/sdk/agents/stand-in` is
+* one in memory, for running an Agent on this computer.
+*
+* This file imports only what the runtime itself has (`node:async_hooks`): the platform runs it
+* beside an Agent's file, its types taken out, in the Agent version's Worker, with nothing installed.
+* A run reads its Environment's values as `agent.env`.
+*/
+var AgentError = class extends Error {
+	code;
+	constructor(code, message) {
+		super(message);
+		this.code = code;
+		this.name = "AgentError";
+	}
+};
+function base64(content) {
+	const bytes = typeof content === "string" ? new TextEncoder().encode(content) : content;
+	let text = "";
+	for (const byte of bytes) text += String.fromCharCode(byte);
+	return btoa(text);
+}
+/**
+* Runs one Agent run to its end and returns how it ended. A run that already ended is not run
+* again. When the wire itself fails, so the run can't be kept, it throws, and the run waits to be
+* executed again.
+*/
+async function execute(agent, wire, env = {}) {
+	const start = await wire.begin();
+	if (start.status !== "queued" && start.status !== "running") return {
+		status: start.status,
+		...start.output !== void 0 ? { output: start.output } : {},
+		...start.error ? { error: start.error } : {}
+	};
+	const root = {
+		prefix: "",
+		next: 0
+	};
+	const scopes = new AsyncLocalStorage();
+	const nextId = () => {
+		const scope = scopes.getStore() ?? root;
+		return `${scope.prefix}${scope.next++}`;
+	};
+	const once = async (kind, name, input, work) => {
+		const id = nextId();
+		const asked = {
+			kind,
+			name,
+			...input === void 0 ? {} : { input }
+		};
+		const kept = await wire.call(id, asked);
+		if (kept.done) return kept.value;
+		const value = await scopes.run({
+			prefix: `${id}.`,
+			next: 0
+		}, work);
+		return (await wire.call(id, {
+			...asked,
+			done: true,
+			value: value === void 0 ? null : value
+		})).value;
+	};
+	const context = {
+		runId: start.runId,
+		agent: start.agent,
+		environment: start.environment,
+		version: start.version,
+		instructions: start.instructions,
+		tools: start.tools,
+		env,
+		log: async (message, data) => {
+			await wire.call(nextId(), {
+				kind: "log",
+				message: String(message),
+				...data === void 0 ? {} : { data }
+			});
+		},
+		step: (name, work) => once("step", name, void 0, work),
+		tool: (name, input) => once("tool", name, input, () => {
+			const tool = agent.tools?.[name];
+			if (!tool) throw new AgentError("invalid", `The Agent has no tool ${name}.`);
+			return tool(input, context);
+		}),
+		memory: {
+			get: (key) => wire.call(nextId(), {
+				kind: "memory.get",
+				key
+			}),
+			set: async (key, value) => {
+				await wire.call(nextId(), {
+					kind: "memory.set",
+					key,
+					value
+				});
+			},
+			delete: async (key) => {
+				await wire.call(nextId(), {
+					kind: "memory.delete",
+					key
+				});
+			}
+		},
+		artifact: async (name, content, type = "text/plain") => {
+			await wire.call(nextId(), {
+				kind: "artifact",
+				name,
+				type,
+				data: base64(content)
+			});
+		},
+		ask: async (prompt) => await wire.call(nextId(), {
+			kind: "ask",
+			prompt
+		})
+	};
+	let output;
+	try {
+		output = await agent.run(start.input, context);
+	} catch (error) {
+		if (error instanceof AgentError && error.code === "ended") return {
+			status: "cancelled",
+			error: error.message
+		};
+		if (error instanceof AgentError && error.code === "unavailable") throw error;
+		const message = error instanceof Error ? error.message : String(error);
+		await wire.finish({ error: message });
+		return {
+			status: "failed",
+			error: message
+		};
+	}
+	await wire.finish({ output: output === void 0 ? null : output });
+	return {
+		status: "completed",
+		output: output === void 0 ? null : output
+	};
+}
+/** The wire of a run on the platform, at `url` with the run's token. */
+function httpWire(url, token, fetcher = fetch) {
+	const post = async (body) => {
+		let response;
+		try {
+			response = await fetcher(url, {
+				method: "POST",
+				headers: {
+					Authorization: `Bearer ${token}`,
+					"Content-Type": "application/json"
+				},
+				body: JSON.stringify(body)
+			});
+		} catch (error) {
+			throw new AgentError("unavailable", `The run could not be reached: ${error instanceof Error ? error.message : String(error)}`);
+		}
+		const answer = await response.json().catch(() => ({}));
+		if (!response.ok) throw new AgentError(answer.code ?? (response.status >= 500 ? "unavailable" : "invalid"), answer.error ?? `The run answered ${response.status}.`);
+		return answer.answer;
+	};
+	return {
+		begin: () => post({ op: "begin" }),
+		call: (id, call) => post({
+			op: "call",
+			call: id,
+			request: call
+		}),
+		finish: (end) => post({
+			op: "finish",
+			...end
+		})
+	};
+}
+/** Runs the run the environment names, as the platform's host does: `MIDSUMMER_AGENT_WIRE` and `MIDSUMMER_AGENT_TOKEN`; the rest is the run's `env`. */
+async function executeFromEnvironment(agent, env) {
+	const url = env.MIDSUMMER_AGENT_WIRE, token = env.MIDSUMMER_AGENT_TOKEN;
+	if (!url || !token) throw new Error("MIDSUMMER_AGENT_WIRE and MIDSUMMER_AGENT_TOKEN name the run to execute.");
+	const values = Object.fromEntries(Object.entries(env).filter((entry) => entry[1] !== void 0 && !entry[0].startsWith("MIDSUMMER_AGENT_")));
+	return execute(agent, httpWire(url, token), values);
+}
+//#endregion
+export { AgentError, execute, executeFromEnvironment, httpWire };

package/agents/stand-in.d.mts

@@ -0,0 +1,35 @@
+import { Agent, RunEnd, RunStatus, RunWire } from "./index.mjs";
+//#region src/agents/stand-in.d.ts
+interface StandInEvent {
+  readonly sequence: number;
+  readonly type: string;
+  readonly call?: string;
+  readonly data?: unknown;
+}
+interface AgentStandIn {
+  /** A new run's wire, for `execute`, with its events and how it ended so far. */
+  start(input?: unknown): {
+    readonly wire: RunWire;
+    readonly events: ReadonlyArray<StandInEvent>;
+    status(): RunStatus;
+  };
+  /** Runs `agent` once on `input`, to its end. */
+  run(agent: Agent, input?: unknown): Promise<{
+    readonly end: RunEnd;
+    readonly events: ReadonlyArray<StandInEvent>;
+  }>;
+  /** The memory its runs keep, by key. */
+  readonly memory: ReadonlyMap<string, unknown>;
+  /** The artifacts its runs kept, by run and name. */
+  readonly artifacts: ReadonlyMap<string, {
+    readonly type: string;
+    readonly data: Uint8Array;
+  }>;
+}
+declare function agentStandIn(options?: {
+  readonly tools?: ReadonlyArray<string>;
+  readonly instructions?: string;
+  readonly ask?: (prompt: string) => Promise<string> | string;
+}): AgentStandIn;
+//#endregion
+export { AgentStandIn, StandInEvent, agentStandIn };

package/agents/stand-in.mjs

@@ -0,0 +1,149 @@
+import { AgentError, execute } from "./index.mjs";
+//#region src/agents/stand-in.ts
+/**
+* Agents' Stand-in: runs in memory, for running an Agent's file on this computer and in tests.
+* It keeps a run's calls as the platform does, so a run executed again resumes, and it refuses
+* tools the run is not allowed. Its memory is kept between the runs one Stand-in starts.
+*
+*   import agent from "./agent.ts"
+*   import { agentStandIn } from "@midsummer-ai/sdk/agents/stand-in"
+*   const local = agentStandIn({ tools: ["greet"] })
+*   const { end, events } = await local.run(agent, { name: "Ada" })
+*
+* Model questions are replied to by `ask` when given, else refused as not set up; spend is not kept.
+*/
+const clone = (value) => value === void 0 ? value : JSON.parse(JSON.stringify(value));
+function agentStandIn(options = {}) {
+	const memory = /* @__PURE__ */ new Map();
+	const artifacts = /* @__PURE__ */ new Map();
+	let runs = 0;
+	function start(input) {
+		const runId = `run_${++runs}`;
+		const events = [{
+			sequence: 0,
+			type: "run.queued"
+		}];
+		let status = "queued";
+		let output, error;
+		const add = (type, data, call) => events.push({
+			sequence: events.length,
+			type,
+			...call === void 0 ? {} : { call },
+			...data === void 0 ? {} : { data: clone(data) }
+		});
+		const keptAt = (id) => events.find((event) => event.call === id);
+		const open = () => {
+			if (status !== "queued" && status !== "running") throw new AgentError("ended", `The run has ended: ${status}.`);
+		};
+		return {
+			wire: {
+				async begin() {
+					if (status === "queued") {
+						status = "running";
+						add("run.started");
+					} else if (status === "running") add("run.resumed");
+					return {
+						runId,
+						agent: "agent",
+						environment: "development",
+						version: 1,
+						input: clone(input ?? null),
+						instructions: options.instructions ?? "",
+						tools: [...options.tools ?? []],
+						status,
+						...output !== void 0 ? { output } : {},
+						...error ? { error } : {}
+					};
+				},
+				async call(number, call) {
+					const was = keptAt(number);
+					if (was) {
+						const data = was.data;
+						const name = "name" in call ? call.name : "key" in call ? call.key : void 0;
+						if (data.kind !== call.kind || (data.name ?? data.key) !== name) throw new AgentError("invalid", `The run's code no longer makes the calls it made: call ${number} was ${data.kind}.`);
+						return clone(data.answer);
+					}
+					open();
+					const keep = (type, answer, data) => {
+						add(type, {
+							kind: call.kind,
+							...data,
+							...answer === void 0 ? {} : { answer }
+						}, number);
+						return clone(answer);
+					};
+					switch (call.kind) {
+						case "log": return keep("log", void 0, {
+							message: call.message,
+							...call.data === void 0 ? {} : { data: call.data }
+						});
+						case "step":
+						case "tool":
+							if (call.kind === "tool" && !(options.tools ?? []).includes(call.name)) {
+								add("guardrail", { tool: call.name });
+								throw new AgentError("refused", `${call.name} is not a tool this version allows.`);
+							}
+							if (!call.done) return { done: false };
+							return keep(call.kind, {
+								done: true,
+								value: call.value ?? null
+							}, { name: call.name });
+						case "memory.get": return keep("memory.read", memory.has(call.key) ? memory.get(call.key) : null, { key: call.key });
+						case "memory.set":
+							memory.set(call.key, clone(call.value));
+							return keep("memory.written", null, {
+								key: call.key,
+								value: call.value
+							});
+						case "memory.delete":
+							memory.delete(call.key);
+							return keep("memory.deleted", null, { key: call.key });
+						case "artifact": {
+							const data = Uint8Array.from(atob(call.data), (char) => char.charCodeAt(0));
+							artifacts.set(`${runId}/${call.name}`, {
+								type: call.type,
+								data
+							});
+							return keep("artifact", null, {
+								name: call.name,
+								type: call.type,
+								size: data.length
+							});
+						}
+						case "ask":
+							if (!options.ask) throw new AgentError("invalid", "Model questions are not set up in this Stand-in: give it `ask`.");
+							return keep("model", await options.ask(call.prompt), { prompt: call.prompt });
+					}
+				},
+				async finish(end) {
+					if (status !== "queued" && status !== "running") return;
+					if ("error" in end) {
+						status = "failed";
+						error = end.error;
+						add("run.failed", { error: end.error });
+					} else {
+						status = "completed";
+						output = clone(end.output);
+						add("run.completed", { output: end.output });
+					}
+				}
+			},
+			events,
+			status: () => status
+		};
+	}
+	return {
+		start,
+		async run(agent, input) {
+			const started = start(input);
+			return {
+				end: await execute(agent, started.wire),
+				events: started.events
+			};
+		},
+		memory,
+		artifacts
+	};
+}
+//#endregion
+export { agentStandIn };

package/ai/contract.d.mts

@@ -0,0 +1,10 @@
+import { Ai } from "./index.mjs";
+//#region src/ai/contract.d.ts
+interface AiContractCase {
+  /** A line of the specification. */
+  readonly name: string;
+  run(ai: Ai): Promise<void>;
+}
+declare const aiContract: ReadonlyArray<AiContractCase>;
+//#endregion
+export { AiContractCase, aiContract };

package/ai/contract.mjs

@@ -0,0 +1,77 @@
+import { AiError } from "./index.mjs";
+//#region src/ai/contract.ts
+/**
+* AI's contract: what every engine promises, as cases any test runner can run. The Stand-in runs
+* them in this package; the platform runs the same cases through the wire, against a provider of
+* its own. A behaviour that is not a case here is not promised.
+*
+*   for (const c of aiContract) test(c.name, () => c.run(ai(makeEngine())))
+*
+* Each case gets an `Ai` whose default Model replies, and throws when the engine breaks a promise.
+* Replies differ between Models, so the cases hold their shape, never their words.
+*/
+const aiContract = [
+	{
+		name: "a whole answer has text, the Model that gave it, whole-number tokens and the credits they cost",
+		async run(ai) {
+			const answer = await ai.complete({ prompt: "Say hello." });
+			check(answer.text.length > 0, "the answer has text");
+			check(answer.model.length > 0, "the answer names its Model");
+			check(Number.isInteger(answer.inputTokens) && answer.inputTokens > 0, "input tokens are a whole number above zero");
+			check(Number.isInteger(answer.outputTokens) && answer.outputTokens > 0, "output tokens are a whole number above zero");
+			check(answer.credits >= 0 && answer.catalogue.length > 0, "credits are zero or more, under a named catalogue");
+		}
+	},
+	{
+		name: "a streamed answer arrives in pieces, and done then settles with what it spent",
+		async run(ai) {
+			const stream = ai.stream({ messages: [{
+				role: "system",
+				content: "Be brief."
+			}, {
+				role: "user",
+				content: "Count to three."
+			}] });
+			const pieces = [];
+			for await (const text of stream) pieces.push(text);
+			check(pieces.length > 0 && pieces.join("").length > 0, "pieces of text arrived");
+			check((await stream.done).outputTokens > 0, "done counts the answer's tokens");
+		}
+	},
+	{
+		name: "a Model that is not offered is refused as invalid",
+		async run(ai) {
+			await refused(() => ai.complete({
+				model: "no-such-model-anywhere",
+				prompt: "Hi"
+			}), "invalid");
+		}
+	},
+	{
+		name: "a question that is neither a prompt nor messages, or a conversation not ending with a user message, is refused as invalid",
+		async run(ai) {
+			await refused(() => ai.complete({}), "invalid");
+			await refused(() => ai.complete({ messages: [{
+				role: "user",
+				content: "Hi"
+			}, {
+				role: "assistant",
+				content: "Hello"
+			}] }), "invalid");
+		}
+	}
+];
+function check(holds, what) {
+	if (!holds) throw new Error(`Broken promise: ${what}.`);
+}
+async function refused(call, code) {
+	try {
+		await call();
+	} catch (error) {
+		if (error instanceof AiError && error.code === code) return;
+		throw new Error(`Expected an AiError ${code}, got ${error instanceof AiError ? error.code : String(error)}.`);
+	}
+	throw new Error(`Expected an AiError ${code}, but the call succeeded.`);
+}
+//#endregion
+export { aiContract };

package/ai/index.d.mts

@@ -0,0 +1,94 @@
+//#region src/ai/index.d.ts
+/**
+ * AI: Model calls from a Project's code, through one AI key, streamed or whole, each with the tokens
+ * and credits it spent.
+ *
+ *   const models = ai(aiClient("https://api.midsummer.new", { key: process.env.MIDSUMMER_AI_KEY! }))
+ *   const answer = await models.complete({ prompt: "Name three rivers" })
+ *   const stream = models.stream({ model: "claude-sonnet-5-5", messages: [{ role: "user", content: "Hi" }] })
+ *   for await (const text of stream) write(text)
+ *   const { credits } = await stream.done
+ *
+ * The engine is where calls go: the Stand-in (`@midsummer-ai/sdk/ai/stand-in`) for `midsummer dev`,
+ * or the platform (`aiClient`). Every engine is held to the cases in `@midsummer-ai/sdk/ai/contract`.
+ * A Model is named as `midsummer ai model list` lists it; leaving it out picks the default.
+ *
+ * Every failure is an `AiError`; its `code` tells you which kind: `invalid` (no such Model, nothing
+ * asked), `forbidden` (the key is not valid), `quota` (the Team's usage is holding back its calls),
+ * `conflict` (a retry by `idempotencyKey` of a call still under way) or `unavailable` (try again).
+ */
+type AiErrorCode = "invalid" | "forbidden" | "quota" | "conflict" | "unavailable";
+declare class AiError extends Error {
+  readonly code: AiErrorCode;
+  constructor(code: AiErrorCode, why: string);
+}
+interface Message {
+  readonly role: "system" | "user" | "assistant";
+  readonly content: string;
+}
+/** What to ask: a `prompt` (after an optional `system` prompt) or a conversation of `messages`. */
+interface Ask {
+  readonly model?: string;
+  readonly prompt?: string;
+  readonly system?: string;
+  readonly messages?: ReadonlyArray<Message>;
+  /** The most tokens the answer may have: 1 to 32,000, 1,024 unless given. */
+  readonly maxTokens?: number;
+  /** 0 to 2. */
+  readonly temperature?: number;
+  /**
+   * Names this call for a day. A retry with it after a lost answer gets the first call's answer and
+   * is not charged again; while the first still runs, it fails as `conflict`.
+   */
+  readonly idempotencyKey?: string;
+}
+/** What a call spent: its tokens, and their price in credits under the catalogue version `catalogue`. */
+interface Spent {
+  readonly model: string;
+  readonly inputTokens: number;
+  readonly outputTokens: number;
+  readonly credits: number;
+  readonly catalogue: string;
+}
+/** A piece of the answer, or, last, what the call spent. */
+type AiEvent = {
+  readonly text: string;
+} | {
+  readonly done: Spent;
+};
+/** Where calls go. `ask` streams one call's events and throws `AiError`. */
+interface AiEngine {
+  ask(input: Ask): AsyncIterable<AiEvent>;
+}
+interface Answer extends Spent {
+  readonly text: string;
+}
+/** An answer's text as it arrives; `done` settles with what it spent once it has all arrived. */
+interface AnswerStream extends AsyncIterable<string> {
+  readonly done: Promise<Spent>;
+}
+interface Ai {
+  complete(input: Ask): Promise<Answer>;
+  stream(input: Ask): AnswerStream;
+}
+declare function ai(engine: AiEngine): Ai;
+type Fetch = (url: string, init: RequestInit) => Promise<Response>;
+/**
+ * The platform's AI Gateway at `origin` (the API's), for the AI key `key`: each call is one POST to
+ * `<origin>/v1/ai/ask`, which replies with newline-delimited JSON events as the Model writes.
+ */
+declare function aiClient(origin: string, options: {
+  readonly key: string;
+  readonly fetch?: Fetch;
+}): AiEngine;
+/**
+ * What Midsummer hands a Deployment as `context.ai`: the Team's AI Gateway, with no key. Each call
+ * streams the events `aiClient` reads.
+ *
+ *   const answer = await ai(boundAi(context.ai)).complete({ prompt: "Hello" })
+ */
+declare function boundAi(handle: {
+  ask(input: Ask): Promise<ReadableStream<Uint8Array>>;
+}): AiEngine;
+//#endregion
+export { Ai, AiEngine, AiError, AiErrorCode, AiEvent, Answer, AnswerStream, Ask, Message, Spent, ai, aiClient, boundAi };