@orkestrel/agent 0.0.6 → 0.0.8

package/README.md

@@ -14,7 +14,7 @@ npm install @orkestrel/agent
 
 ## Requirements
 
-- Node.js >= 24
+- Node.js >= 22
 - Dual ESM + CommonJS builds (`import` and `require` both supported)
 
 ## Usage

package/dist/src/core/index.cjs

@@ -74,6 +74,24 @@ var THINK_CLOSE = "</think>";
 */
 var WORKSPACE_SECTION_HEADER = "## Workspace";
 /**
+* The estimated per-message role/framing overhead {@link import('./helpers.js').estimateMessages}
+* adds on top of a message's content estimate — accounts for the fixed wire framing every
+* conversation turn carries (its role tag, delimiters) that {@link import('./helpers.js').estimateTokens}'s
+* content-only heuristic does not otherwise capture.
+*/
+var MESSAGE_TOKEN_OVERHEAD = 4;
+/**
+* The coarse, deliberately-approximate per-image token cost {@link import('./helpers.js').estimateMessages}
+* charges for each attached image.
+*
+* @remarks
+* A base64 image payload's LENGTH is NOT a reliable token proxy (a vision model's actual image
+* token cost depends on resolution / tiling, not byte size), so this is a fixed, coarse
+* per-image estimate rather than a derivation from `image.length` — a planning heuristic, not an
+* exact count.
+*/
+var IMAGE_TOKEN_ESTIMATE = 512;
+/**
 * The extension→language table {@link import('./helpers.js').inferLanguage} reads to
 * map a file path's extension to a fenced-code language tag. Covers the common source /
 * markup / data extensions; an unlisted extension falls back to `'text'`.
@@ -202,18 +220,21 @@ function isAgentJobError(value) {
 }
 /**
 * Thrown by a {@link ConversationInterface}'s `compact()` when the conversation has no
-* {@link ConversationSummarizer} to fold its messages with — carries a machine-readable
-* `code`.
+* {@link ConversationSummarizer} to fold its messages with, or when its `sections` cap is
+* structurally invalid — carries a machine-readable `code`.
 *
 * @remarks
 * Compaction REQUIRES a summarizer (it digests the folded slice into a section summary and
 * regenerates the rollup); a conversation created without one can still store + `view()` its
-* live tail, but a `compact()` is a programmer error (§12) and throws this. `code` is
-* `'SUMMARIZER'` (the only condition so far). Narrow a caught value with
+* live tail, but a `compact()` is a programmer error (§12) and throws this with `'SUMMARIZER'`.
+* A `sections` cap (§F2, on {@link import('./types.js').ConversationOptions} /
+* {@link import('./types.js').ConversationManagerOptions} /
+* {@link import('./types.js').CompactOptions}) must be `>= 1` — a sub-1 cap is a programmer
+* error and throws this with `'SECTIONS'`. Narrow a caught value with
 * {@link isConversationError} and branch on `error.code`.
 */
 var ConversationError = class extends Error {
-	/** The machine-readable condition — `'SUMMARIZER'`: a `compact()` with no summarizer. */
+	/** The machine-readable condition — `'SUMMARIZER'`: a `compact()` with no summarizer; `'SECTIONS'`: a sub-1 `sections` cap. */
 	code;
 	constructor(code, message) {
 		super(message);
@@ -278,6 +299,45 @@ var WorkspaceError = class extends Error {
 function isWorkspaceError(value) {
 	return value instanceof WorkspaceError;
 }
+/**
+* Thrown synchronously by an {@link AgentInterface}'s `stream()` when a concurrent run would
+* corrupt SHARED per-agent accounting — carries a machine-readable `code`.
+*
+* @remarks
+* A run already in flight on the same agent, PLUS a construction-level `window` (a shared
+* context budget) or a construction-level `budget` with no per-run override (a shared cost
+* budget), means a second concurrent `stream()` would race its charges against the same
+* shared instance — corrupting the accounting. `code` is `'CONCURRENCY'` (the only condition
+* so far). Use separate agents, or per-run `budget` overrides with no `window`, for genuinely
+* concurrent runs. Narrow a caught value with {@link isAgentError} and branch on `error.code`.
+*/
+var AgentError = class extends Error {
+	/** The machine-readable condition — `'CONCURRENCY'`: a concurrent run on a shared accounting agent. */
+	code;
+	constructor(code, message) {
+		super(message);
+		this.name = "AgentError";
+		this.code = code;
+	}
+};
+/**
+* Narrow an unknown caught value to an {@link AgentError}.
+*
+* @param value - The value to test (typically a `catch` binding)
+* @returns `true` when `value` is an {@link AgentError}
+*
+* @example
+* ```ts
+* try {
+* 	agent.stream()
+* } catch (error) {
+* 	if (isAgentError(error) && error.code === 'CONCURRENCY') useSeparateAgents()
+* }
+* ```
+*/
+function isAgentError(value) {
+	return value instanceof AgentError;
+}
 //#endregion
 //#region src/core/conversations/Conversation.ts
 /**
@@ -331,6 +391,7 @@ var Conversation = class {
 	#emitter;
 	#summarize;
 	#keep;
+	#cap;
 	#sections = [];
 	#summary;
 	#messages = /* @__PURE__ */ new Map();
@@ -342,6 +403,8 @@ var Conversation = class {
 		});
 		this.#summarize = options?.summarize;
 		this.#keep = options?.keep ?? 0;
+		if (options?.sections !== void 0 && options.sections < 1) throw new ConversationError("SECTIONS", "a sections cap must be >= 1");
+		this.#cap = options?.sections;
 		if (seed) {
 			this.#summary = seed.summary;
 			for (const section of seed.sections) this.#sections.push(section);
@@ -393,6 +456,8 @@ var Conversation = class {
 	async compact(options) {
 		const summarize = this.#summarize;
 		if (summarize === void 0) throw new ConversationError("SUMMARIZER", "cannot compact a conversation without a summarizer");
+		const cap = options?.sections ?? this.#cap;
+		if (cap !== void 0 && cap < 1) throw new ConversationError("SECTIONS", "a sections cap must be >= 1");
 		const keep = options?.keep ?? this.#keep;
 		const live = [...this.#messages.values()];
 		const fold = keep <= 0 ? live.length : live.length - keep;
@@ -406,6 +471,23 @@ var Conversation = class {
 		};
 		for (const message of slice) this.#messages.delete(message.id);
 		this.#sections.push(section);
+		if (cap !== void 0 && this.#sections.length > cap) {
+			const overflow = this.#sections.length - cap + 1;
+			const folded = this.#sections.slice(0, overflow);
+			try {
+				const merged = {
+					id: crypto.randomUUID(),
+					summary: await summarize(folded.map((one) => this.#summaryMessage(one))),
+					messages: folded.flatMap((one) => one.messages)
+				};
+				this.#sections.splice(0, overflow, merged);
+				this.#emitter.emit("collapse", merged);
+			} catch (error) {
+				this.#summary = await summarize(this.#sections.map((one) => this.#summaryMessage(one)));
+				this.#emitter.emit("summary", this.#summary);
+				throw error;
+			}
+		}
 		this.#summary = await summarize(this.#sections.map((one) => this.#summaryMessage(one)));
 		this.#emitter.emit("summary", this.#summary);
 		this.#emitter.emit("compact", section);
@@ -505,10 +587,12 @@ var ConversationManager = class {
 	#active;
 	#summarize;
 	#keep;
+	#sections;
 	#store;
 	constructor(options) {
 		this.#summarize = options?.summarize;
 		this.#keep = options?.keep ?? 0;
+		this.#sections = options?.sections;
 		this.#store = options?.store;
 	}
 	get count() {
@@ -524,11 +608,13 @@ var ConversationManager = class {
 		return [...this.#conversations.values()];
 	}
 	add(input) {
+		const sections = input?.sections ?? this.#sections;
 		const conversation = new Conversation({
 			...input?.id === void 0 ? {} : { id: input.id },
 			...input?.on === void 0 ? {} : { on: input.on },
 			summarize: input?.summarize ?? this.#summarize,
-			keep: input?.keep ?? this.#keep
+			keep: input?.keep ?? this.#keep,
+			...sections === void 0 ? {} : { sections }
 		}, input?.snapshot);
 		this.#conversations.set(conversation.id, conversation);
 		if (this.#active === void 0) this.#active = conversation.id;
@@ -669,23 +755,40 @@ function estimateTokens(text) {
 * (the {@link import('./types.js').AgentOptions} `window`).
 *
 * @remarks
-* Sums {@link estimateTokens} over each message's `content` (the `ceil(length / 4)` char
-* heuristic), so it is deterministic and provider-free — the same messages always yield the
-* same estimate, with an empty batch `0`. It is the fully-swappable default an agent's
-* auto-compaction context budget charges each turn's new messages through; a caller wanting a
-* sharper count supplies its own `consume` to `createBudget` instead. Total — never throws.
+* Sums, per message, {@link estimateTokens} over its `content` (the `ceil(length / 4)` char
+* heuristic) PLUS {@link import('./constants.js').MESSAGE_TOKEN_OVERHEAD} (a fixed per-message
+* role/framing overhead) PLUS, when present, {@link estimateTokens} over its JSON-stringified
+* `calls` PLUS `images.length * `{@link import('./constants.js').IMAGE_TOKEN_ESTIMATE} (a coarse,
+* deliberately-approximate per-image cost — a base64 length is NOT a token proxy). Deterministic
+* and provider-free — the same messages always yield the same estimate, with an empty batch `0`.
+* It is the fully-swappable default an agent's auto-compaction context budget charges each
+* turn's new messages through; a caller wanting a sharper count supplies its own `consume` to
+* `createBudget` instead. Total — never throws: a `calls` `JSON.stringify` that throws (a
+* circular `ToolCall.arguments`) is caught and replaced with a conservative fixed contribution of
+* {@link import('./constants.js').MESSAGE_TOKEN_OVERHEAD} (the same per-message overhead scale)
+* instead of estimating the (unreachable) serialized length.
 *
 * @param messages - The messages to estimate (a turn's appended assistant + tool messages)
-* @returns The summed estimated token count (`Σ estimateTokens(m.content)`; `0` when empty)
+* @returns The summed estimated token count (`0` when empty)
 *
 * @example
 * ```ts
 * estimateMessages([]) // 0
-* estimateMessages([{ id: '1', role: 'user', content: 'hello' }]) // 2
+* estimateMessages([{ id: '1', role: 'user', content: 'hello' }]) // 6  (2 content + 4 overhead)
 * ```
 */
 function estimateMessages(messages) {
-	return messages.reduce((sum, message) => sum + estimateTokens(message.content), 0);
+	return messages.reduce((sum, message) => {
+		const content = estimateTokens(message.content) + 4;
+		let calls = 0;
+		if (message.calls?.length) try {
+			calls = estimateTokens(JSON.stringify(message.calls));
+		} catch {
+			calls = 4;
+		}
+		const images = (message.images?.length ?? 0) * 512;
+		return sum + content + calls + images;
+	}, 0);
 }
 /**
 * Run one rehydrated agent and apply the partial-as-configurable-failure policy — the
@@ -1311,6 +1414,32 @@ function fencedFile(path, language, content) {
 function escapeRegExp(value) {
 	return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
 }
+/**
+* Sanitize a {@link TokenUsage} into safe, non-negative integers — the guard an agent's
+* abort-usage path applies to a provider's partial usage before it is charged against a
+* budget or folded into the run total.
+*
+* @remarks
+* Per field (`prompt` / `completion` / `total`): a non-finite value (`NaN`, `+Infinity`,
+* `-Infinity`) or a negative value floors to `0`; a fractional value floors to its
+* non-negative integer part. No upper cap is applied. Total — never throws.
+*
+* @param usage - The token usage to sanitize (e.g. a provider's abort-partial usage)
+* @returns A new {@link TokenUsage} with every field a safe non-negative integer
+*
+* @example
+* ```ts
+* sanitizeUsage({ prompt: -5, completion: NaN, total: 12.7 }) // { prompt: 0, completion: 0, total: 12 }
+* ```
+*/
+function sanitizeUsage(usage) {
+	const clean = (value) => Number.isFinite(value) && value > 0 ? Math.floor(value) : 0;
+	return {
+		prompt: clean(usage.prompt),
+		completion: clean(usage.completion),
+		total: clean(usage.total)
+	};
+}
 //#endregion
 //#region src/core/instructions/Instruction.ts
 /**
@@ -2236,6 +2365,7 @@ var Agent = class {
 	#signal;
 	#authority;
 	#window;
+	#strict;
 	#emitter;
 	id = crypto.randomUUID();
 	#status = "idle";
@@ -2245,6 +2375,9 @@ var Agent = class {
 		this.#context = new AgentContext({
 			system: options?.system,
 			tools: options?.tools,
+			instructions: options?.instructions,
+			workspaces: options?.workspaces,
+			scope: options?.scope,
 			conversations: options?.conversations
 		});
 		this.#limit = options?.limit ?? 10;
@@ -2254,6 +2387,7 @@ var Agent = class {
 		this.#signal = options?.signal;
 		this.#authority = options?.authority;
 		this.#window = options?.window;
+		this.#strict = options?.strict ?? false;
 		this.#emitter = new _orkestrel_emitter.Emitter({
 			on: options?.on,
 			error: options?.error
@@ -2272,6 +2406,7 @@ var Agent = class {
 		return this.stream(options).result;
 	}
 	stream(options) {
+		if (this.#runs.size > 0 && (this.#window !== void 0 || this.#budget !== void 0 && options?.budget === void 0)) throw new AgentError("CONCURRENCY", "concurrent runs on one agent with a shared construction window/budget corrupt accounting; use separate agents or per-run budgets");
 		const timeoutMs = options?.timeout ?? this.#timeoutMs;
 		const timeout = timeoutMs === void 0 ? void 0 : (0, _orkestrel_timeout.createTimeout)({ ms: timeoutMs });
 		timeout?.start();
@@ -2391,7 +2526,7 @@ var Agent = class {
 					if (isProviderAbortError(error)) {
 						if (error.partial.thinking !== void 0) thinking = this.#thought(thinking, error.partial.thinking);
 						if (error.partial.usage !== void 0) {
-							const abortUsage = error.partial.usage;
+							const abortUsage = sanitizeUsage(error.partial.usage);
 							budget?.consume({
 								prompt: abortUsage.prompt,
 								completion: Math.max(0, abortUsage.completion - charged),
@@ -2408,16 +2543,17 @@ var Agent = class {
 			}
 			if (result.thinking !== void 0 && result.thinking.length > 0) thinking = this.#thought(thinking, result.thinking);
 			if (result.usage !== void 0) {
+				const resultUsage = sanitizeUsage(result.usage);
 				budget?.consume({
-					prompt: result.usage.prompt,
-					completion: Math.max(0, result.usage.completion - charged),
-					total: Math.max(0, result.usage.total - charged)
+					prompt: resultUsage.prompt,
+					completion: Math.max(0, resultUsage.completion - charged),
+					total: Math.max(0, resultUsage.total - charged)
 				});
-				usage = this.#sum(usage, result.usage);
-				this.#emitter.emit("usage", result.usage);
+				usage = this.#sum(usage, resultUsage);
+				this.#emitter.emit("usage", resultUsage);
 				yield {
 					type: "usage",
-					usage: result.usage
+					usage: resultUsage
 				};
 			}
 			if (result.tools !== void 0 && result.tools.length > 0) {
@@ -2476,6 +2612,7 @@ var Agent = class {
 			section = await conversation.compact();
 		} catch (error) {
 			this.#emitter.emit("compactError", error);
+			if (this.#strict) throw error;
 			return;
 		}
 		if (section === void 0) {
@@ -4064,6 +4201,7 @@ function createWorkspaceManager(options) {
 //#endregion
 exports.Agent = Agent;
 exports.AgentContext = AgentContext;
+exports.AgentError = AgentError;
 exports.AgentJobError = AgentJobError;
 exports.AgentRegistry = AgentRegistry;
 exports.Authority = Authority;
@@ -4078,8 +4216,10 @@ exports.DEFAULT_CONVERSATION_KEEP = DEFAULT_CONVERSATION_KEEP;
 exports.DatabaseConversationStore = DatabaseConversationStore;
 exports.DatabaseWorkspaceStore = DatabaseWorkspaceStore;
 exports.EXTENSION_TO_LANGUAGE = EXTENSION_TO_LANGUAGE;
+exports.IMAGE_TOKEN_ESTIMATE = IMAGE_TOKEN_ESTIMATE;
 exports.Instruction = Instruction;
 exports.InstructionManager = InstructionManager;
+exports.MESSAGE_TOKEN_OVERHEAD = MESSAGE_TOKEN_OVERHEAD;
 exports.MemoryConversationStore = MemoryConversationStore;
 exports.MemoryWorkspaceStore = MemoryWorkspaceStore;
 exports.ProviderAbortError = ProviderAbortError;
@@ -4130,6 +4270,7 @@ exports.estimateTokens = estimateTokens;
 exports.fencedFile = fencedFile;
 exports.filterAllowList = filterAllowList;
 exports.inferLanguage = inferLanguage;
+exports.isAgentError = isAgentError;
 exports.isAgentJobError = isAgentJobError;
 exports.isBinary = isBinary;
 exports.isConversationError = isConversationError;
@@ -4146,6 +4287,7 @@ exports.isWorkspaceError = isWorkspaceError;
 exports.isWorkspaceSnapshot = isWorkspaceSnapshot;
 exports.offsetAt = offsetAt;
 exports.rangeOf = rangeOf;
+exports.sanitizeUsage = sanitizeUsage;
 exports.settleAgentJob = settleAgentJob;
 exports.sliceRange = sliceRange;
 exports.spliceRange = spliceRange;