@orkestrel/agent 0.0.7 → 0.0.8

package/dist/src/core/index.js

@@ -73,6 +73,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'`.
@@ -201,18 +219,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);
@@ -277,6 +298,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
 /**
@@ -330,6 +390,7 @@ var Conversation = class {
 	#emitter;
 	#summarize;
 	#keep;
+	#cap;
 	#sections = [];
 	#summary;
 	#messages = /* @__PURE__ */ new Map();
@@ -341,6 +402,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);
@@ -392,6 +455,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;
@@ -405,6 +470,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);
@@ -504,10 +586,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() {
@@ -523,11 +607,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;
@@ -668,23 +754,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
@@ -1310,6 +1413,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
 /**
@@ -2235,6 +2364,7 @@ var Agent = class {
 	#signal;
 	#authority;
 	#window;
+	#strict;
 	#emitter;
 	id = crypto.randomUUID();
 	#status = "idle";
@@ -2244,6 +2374,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;
@@ -2253,6 +2386,7 @@ var Agent = class {
 		this.#signal = options?.signal;
 		this.#authority = options?.authority;
 		this.#window = options?.window;
+		this.#strict = options?.strict ?? false;
 		this.#emitter = new Emitter({
 			on: options?.on,
 			error: options?.error
@@ -2271,6 +2405,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 : createTimeout({ ms: timeoutMs });
 		timeout?.start();
@@ -2390,7 +2525,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),
@@ -2407,16 +2542,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) {
@@ -2475,6 +2611,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) {
@@ -4061,6 +4198,6 @@ function createWorkspaceManager(options) {
 	return new WorkspaceManager(options);
 }
 //#endregion
-export { Agent, AgentContext, AgentJobError, AgentRegistry, Authority, CONVERSATION_RECAP_PREFIX, Channel, Conversation, ConversationError, ConversationManager, DEFAULT_AGENT_LIMIT, DEFAULT_AUTHORITY_ZONE, DEFAULT_CONVERSATION_KEEP, DatabaseConversationStore, DatabaseWorkspaceStore, EXTENSION_TO_LANGUAGE, Instruction, InstructionManager, MemoryConversationStore, MemoryWorkspaceStore, ProviderAbortError, Scope, ScopeManager, THINK_CLOSE, THINK_OPEN, ThinkSplitter, Tool, ToolManager, WORKSPACE_SECTION_HEADER, Workspace, WorkspaceError, WorkspaceManager, buildToolResult, clampPosition, clampRange, computeSize, countLines, createAgent, createAgentContext, createAgentQueue, createAgentRegistry, createAgentRunner, createAuthority, createBinaryContent, createConversation, createConversationManager, createDatabaseConversationStore, createDatabaseWorkspaceStore, createFile, createInstruction, createInstructionManager, createMemoryConversationStore, createMemoryWorkspaceStore, createScope, createScopeManager, createTextContent, createThinkSplitter, createTool, createToolManager, createWorkspace, createWorkspaceManager, decodedSize, escapeRegExp, estimateMessages, estimateTokens, fencedFile, filterAllowList, inferLanguage, isAgentJobError, isBinary, isConversationError, isConversationSnapshot, isFile, isImage, isMessage, isProviderAbortError, isSection, isText, isToolCall, isValidRange, isWorkspaceError, isWorkspaceSnapshot, offsetAt, rangeOf, settleAgentJob, sliceRange, spliceRange };
+export { Agent, AgentContext, AgentError, AgentJobError, AgentRegistry, Authority, CONVERSATION_RECAP_PREFIX, Channel, Conversation, ConversationError, ConversationManager, DEFAULT_AGENT_LIMIT, DEFAULT_AUTHORITY_ZONE, DEFAULT_CONVERSATION_KEEP, DatabaseConversationStore, DatabaseWorkspaceStore, EXTENSION_TO_LANGUAGE, IMAGE_TOKEN_ESTIMATE, Instruction, InstructionManager, MESSAGE_TOKEN_OVERHEAD, MemoryConversationStore, MemoryWorkspaceStore, ProviderAbortError, Scope, ScopeManager, THINK_CLOSE, THINK_OPEN, ThinkSplitter, Tool, ToolManager, WORKSPACE_SECTION_HEADER, Workspace, WorkspaceError, WorkspaceManager, buildToolResult, clampPosition, clampRange, computeSize, countLines, createAgent, createAgentContext, createAgentQueue, createAgentRegistry, createAgentRunner, createAuthority, createBinaryContent, createConversation, createConversationManager, createDatabaseConversationStore, createDatabaseWorkspaceStore, createFile, createInstruction, createInstructionManager, createMemoryConversationStore, createMemoryWorkspaceStore, createScope, createScopeManager, createTextContent, createThinkSplitter, createTool, createToolManager, createWorkspace, createWorkspaceManager, decodedSize, escapeRegExp, estimateMessages, estimateTokens, fencedFile, filterAllowList, inferLanguage, isAgentError, isAgentJobError, isBinary, isConversationError, isConversationSnapshot, isFile, isImage, isMessage, isProviderAbortError, isSection, isText, isToolCall, isValidRange, isWorkspaceError, isWorkspaceSnapshot, offsetAt, rangeOf, sanitizeUsage, settleAgentJob, sliceRange, spliceRange };
 
 //# sourceMappingURL=index.js.map