@orkestrel/agent 0.0.12 → 0.0.14

package/dist/src/core/index.d.cts

@@ -4,6 +4,7 @@ import { DriverInterface } from '@orkestrel/database';
 import { EmitterErrorHandler } from '@orkestrel/emitter';
 import { EmitterHooks } from '@orkestrel/emitter';
 import { EmitterInterface } from '@orkestrel/emitter';
+import { JSONValue } from '@orkestrel/contract';
 import { QueueExecution } from '@orkestrel/queue';
 import { QueueInterface } from '@orkestrel/queue';
 import { QueueStoreInterface } from '@orkestrel/queue';
@@ -848,6 +849,32 @@ export declare interface AgentResult {
     readonly partial: boolean;
 }
 
+/**
+ * Project an unknown value onto the canonical JSON representation of an
+ * {@link AgentResult}.
+ *
+ * @remarks
+ * This is a total hostile-boundary projection. Each structural field is captured once
+ * through Contract's sanctioned exception boundary, so conforming accessors and inherited
+ * properties are supported while a throwing getter or revoked proxy returns `undefined`.
+ * Present usage counts must be finite numbers; negative and fractional values are preserved,
+ * not normalized. Extra input properties are dropped while a fresh exact plain object is rebuilt
+ * and deep-gated through
+ * {@link import('@orkestrel/contract').parseJSONValue}.
+ *
+ * @param value - The unknown value to project
+ * @returns A fresh JSON value containing only AgentResult fields, or `undefined` when invalid
+ *
+ * @example
+ * ```ts
+ * import { agentResultToJSON } from '@orkestrel/agent'
+ *
+ * agentResultToJSON({ content: 'done', usage: { prompt: 2, completion: 1, total: 3 }, partial: false })
+ * // { content: 'done', usage: { prompt: 2, completion: 1, total: 3 }, partial: false }
+ * ```
+ */
+export declare function agentResultToJSON(value: unknown): JSONValue | undefined;
+
 /**
  * Options for `createAgentRunner` — the registry that rehydrates jobs, the partial-result
  * policy, and the substrate knobs threaded into the backing `createRunner`.

package/dist/src/core/index.d.ts

@@ -4,6 +4,7 @@ import { DriverInterface } from '@orkestrel/database';
 import { EmitterErrorHandler } from '@orkestrel/emitter';
 import { EmitterHooks } from '@orkestrel/emitter';
 import { EmitterInterface } from '@orkestrel/emitter';
+import { JSONValue } from '@orkestrel/contract';
 import { QueueExecution } from '@orkestrel/queue';
 import { QueueInterface } from '@orkestrel/queue';
 import { QueueStoreInterface } from '@orkestrel/queue';
@@ -848,6 +849,32 @@ export declare interface AgentResult {
     readonly partial: boolean;
 }
 
+/**
+ * Project an unknown value onto the canonical JSON representation of an
+ * {@link AgentResult}.
+ *
+ * @remarks
+ * This is a total hostile-boundary projection. Each structural field is captured once
+ * through Contract's sanctioned exception boundary, so conforming accessors and inherited
+ * properties are supported while a throwing getter or revoked proxy returns `undefined`.
+ * Present usage counts must be finite numbers; negative and fractional values are preserved,
+ * not normalized. Extra input properties are dropped while a fresh exact plain object is rebuilt
+ * and deep-gated through
+ * {@link import('@orkestrel/contract').parseJSONValue}.
+ *
+ * @param value - The unknown value to project
+ * @returns A fresh JSON value containing only AgentResult fields, or `undefined` when invalid
+ *
+ * @example
+ * ```ts
+ * import { agentResultToJSON } from '@orkestrel/agent'
+ *
+ * agentResultToJSON({ content: 'done', usage: { prompt: 2, completion: 1, total: 3 }, partial: false })
+ * // { content: 'done', usage: { prompt: 2, completion: 1, total: 3 }, partial: false }
+ * ```
+ */
+export declare function agentResultToJSON(value: unknown): JSONValue | undefined;
+
 /**
  * Options for `createAgentRunner` — the registry that rehydrates jobs, the partial-result
  * policy, and the substrate knobs threaded into the backing `createRunner`.

package/dist/src/core/index.js

@@ -1,4 +1,4 @@
-import { isArray, isRecord, isString, rawShape, stringShape } from "@orkestrel/contract";
+import { attempt, isArray, isBoolean, isFiniteNumber, isObject, isRecord, isString, parseJSONValue, rawShape, stringShape } from "@orkestrel/contract";
 import { createDatabase, createMemoryDriver } from "@orkestrel/database";
 import { createQueue } from "@orkestrel/queue";
 import { createDeferred, createRunner } from "@orkestrel/workflow";
@@ -582,6 +582,61 @@ var ConversationManager = class {
 //#endregion
 //#region src/core/helpers.ts
 /**
+* Project an unknown value onto the canonical JSON representation of an
+* {@link AgentResult}.
+*
+* @remarks
+* This is a total hostile-boundary projection. Each structural field is captured once
+* through Contract's sanctioned exception boundary, so conforming accessors and inherited
+* properties are supported while a throwing getter or revoked proxy returns `undefined`.
+* Present usage counts must be finite numbers; negative and fractional values are preserved,
+* not normalized. Extra input properties are dropped while a fresh exact plain object is rebuilt
+* and deep-gated through
+* {@link import('@orkestrel/contract').parseJSONValue}.
+*
+* @param value - The unknown value to project
+* @returns A fresh JSON value containing only AgentResult fields, or `undefined` when invalid
+*
+* @example
+* ```ts
+* import { agentResultToJSON } from '@orkestrel/agent'
+*
+* agentResultToJSON({ content: 'done', usage: { prompt: 2, completion: 1, total: 3 }, partial: false })
+* // { content: 'done', usage: { prompt: 2, completion: 1, total: 3 }, partial: false }
+* ```
+*/
+function agentResultToJSON(value) {
+	const captured = attempt(() => {
+		if (!isObject(value)) return void 0;
+		const content = Reflect.get(value, "content");
+		const thinking = Reflect.get(value, "thinking");
+		const usage = Reflect.get(value, "usage");
+		const partial = Reflect.get(value, "partial");
+		if (!isString(content) || !isBoolean(partial)) return void 0;
+		if (thinking !== void 0 && !isString(thinking)) return void 0;
+		let projectedUsage;
+		if (usage !== void 0) {
+			if (!isObject(usage)) return void 0;
+			const prompt = Reflect.get(usage, "prompt");
+			const completion = Reflect.get(usage, "completion");
+			const total = Reflect.get(usage, "total");
+			if (!isFiniteNumber(prompt) || !isFiniteNumber(completion) || !isFiniteNumber(total)) return;
+			projectedUsage = {
+				prompt,
+				completion,
+				total
+			};
+		}
+		return {
+			content,
+			...thinking === void 0 ? {} : { thinking },
+			...projectedUsage === void 0 ? {} : { usage: projectedUsage },
+			partial
+		};
+	});
+	return captured.success ? parseJSONValue(captured.value) : void 0;
+}
+/**
 * Filter a list of items by a {@link import('./types.js').ScopeInterface} allow-list of
 * keys — the pure, total set-membership primitive the context's build step and the agent
 * loop's tool-advertise step apply a scope through.
@@ -2743,6 +2798,6 @@ function createAgentRunner(options) {
 	});
 }
 //#endregion
-export { Agent, AgentContext, AgentError, AgentJobError, AgentRegistry, Authority, CONVERSATION_RECAP_PREFIX, Channel, Conversation, ConversationError, ConversationManager, DEFAULT_AGENT_LIMIT, DEFAULT_AUTHORITY_ZONE, DEFAULT_CONVERSATION_KEEP, DatabaseConversationStore, IMAGE_TOKEN_ESTIMATE, Instruction, InstructionManager, MESSAGE_TOKEN_OVERHEAD, MemoryConversationStore, ProviderAbortError, Scope, ScopeManager, THINK_CLOSE, THINK_OPEN, ThinkSplitter, WORKSPACE_SECTION_HEADER, createAgent, createAgentContext, createAgentQueue, createAgentRegistry, createAgentRunner, createAuthority, createConversation, createConversationManager, createDatabaseConversationStore, createInstruction, createInstructionManager, createMemoryConversationStore, createScope, createScopeManager, createThinkSplitter, estimateMessages, estimateTokens, fencedFile, filterAllowList, handleAgentQueueJob, handleAgentRunnerJob, isAgentError, isAgentJobError, isConversationError, isConversationSnapshot, isMessage, isProviderAbortError, isSection, sanitizeToken, sanitizeUsage, settleAgentJob };
+export { Agent, AgentContext, AgentError, AgentJobError, AgentRegistry, Authority, CONVERSATION_RECAP_PREFIX, Channel, Conversation, ConversationError, ConversationManager, DEFAULT_AGENT_LIMIT, DEFAULT_AUTHORITY_ZONE, DEFAULT_CONVERSATION_KEEP, DatabaseConversationStore, IMAGE_TOKEN_ESTIMATE, Instruction, InstructionManager, MESSAGE_TOKEN_OVERHEAD, MemoryConversationStore, ProviderAbortError, Scope, ScopeManager, THINK_CLOSE, THINK_OPEN, ThinkSplitter, WORKSPACE_SECTION_HEADER, agentResultToJSON, createAgent, createAgentContext, createAgentQueue, createAgentRegistry, createAgentRunner, createAuthority, createConversation, createConversationManager, createDatabaseConversationStore, createInstruction, createInstructionManager, createMemoryConversationStore, createScope, createScopeManager, createThinkSplitter, estimateMessages, estimateTokens, fencedFile, filterAllowList, handleAgentQueueJob, handleAgentRunnerJob, isAgentError, isAgentJobError, isConversationError, isConversationSnapshot, isMessage, isProviderAbortError, isSection, sanitizeToken, sanitizeUsage, settleAgentJob };
 
 //# sourceMappingURL=index.js.map