@nylorun/harness 0.12.0-beta → 0.13.0-beta

package/dist/index.js

@@ -1,6 +1,6 @@
-export { Agent, AgentBuilder, AgentBuildError, AgentLifecycleError } from "./build/builder.js";
+export { Agent, AgentBuilder, AgentBuildError, AgentLifecycleError } from "./definition/builder.js";
 export { HarnessError, isHarnessError } from "./errors.js";
-export { BuiltAgent } from "./build/agent.js";
-export { middleware, model, tool } from "./build/helpers.js";
-export { defineSchema } from "./build/schema.js";
-export { preparedModel } from "./model/prepared.js";
+export { middleware, model, tool } from "./definition/helpers.js";
+export { defineSchema } from "./definition/schema.js";
+export { preparedModel } from "./execution/model/prepared.js";
+export { createExecutionState, validateExecutionState } from "./execution/state.js";

package/dist/types/agent.d.ts

@@ -0,0 +1,9 @@
+import type { AgentManifest } from "./manifest.js";
+import type { RunOptions, RunResult } from "./execution.js";
+/** An agent definition built with Agent(...).use(...).build(). */
+export interface BuiltAgent<Info = unknown, Output = string> {
+    readonly id: string;
+    readonly name: string;
+    readonly manifest: AgentManifest;
+    run(options: RunOptions<Info>): Promise<RunResult<Output>>;
+}

package/dist/types/agent.js

@@ -0,0 +1 @@
+export {};

package/dist/types/execution.d.ts

@@ -0,0 +1,97 @@
+import type { ModelAdapter } from "./model.js";
+import type { InputEvent, MessageInput, TranscriptEntry } from "./transcript.js";
+import type { ObserveEvent } from "./observe.js";
+import type { JsonObject, JsonValue, Tripwire } from "./shared.js";
+import type { RequiredInteraction, ToolExecutionResume, ToolOutcome, ToolResult } from "./tool.js";
+export type ExecutionInput = MessageInput | InputEvent | {
+    readonly kind: "continue";
+} | {
+    readonly kind: "settle";
+    readonly invocationId: string;
+    readonly outcome: Extract<ToolOutcome, {
+        kind: "completed" | "failed" | "denied";
+    }>;
+};
+/** Portable reference to deployed code. Applications must preserve this value intact. */
+export interface ToolReference {
+    readonly capabilityId: string;
+    readonly toolName: string;
+    readonly descriptor: {
+        readonly name: string;
+        readonly description?: string;
+        readonly inputSchema: JsonObject;
+        readonly outputSchema?: JsonObject;
+    };
+}
+export interface SavedToolCall {
+    readonly callId: string;
+    readonly invocationId: string;
+    readonly toolName: string;
+    readonly args: JsonValue;
+    readonly rawArgs: JsonValue;
+    readonly reference: ToolReference;
+    readonly status: "pending" | "active" | "settled" | "interaction" | "deferred";
+    readonly result?: ToolResult;
+    readonly interaction?: RequiredInteraction;
+    readonly interactionPhase?: "before" | "execute";
+    readonly resume?: ToolExecutionResume;
+    readonly token?: JsonValue;
+}
+export interface ExecutionPlan {
+    readonly turnId: string;
+    readonly stepId: string;
+    readonly stepNumber: number;
+    readonly order: readonly {
+        readonly callId: string;
+        readonly toolName: string;
+    }[];
+    readonly immediate: readonly ToolResult[];
+    readonly calls: readonly SavedToolCall[];
+}
+/** Versioned continuation data, not a live execution object. */
+export interface ExecutionState {
+    readonly version: 1;
+    readonly agentId: string;
+    readonly executionId: string;
+    readonly outputContract?: JsonObject;
+    readonly revision: number;
+    readonly turnCount: number;
+    readonly transcript: readonly TranscriptEntry[];
+    readonly status: "ready" | "active" | "completed" | "paused" | "cancelled" | "failed";
+    readonly plan?: ExecutionPlan;
+    /** Abandoned actions retained for reconciliation, never automatically dispatched. */
+    readonly cancelledCalls?: readonly SavedToolCall[];
+}
+export type ExecutionEvent = (ObserveEvent | {
+    readonly type: "execution.completed" | "execution.paused" | "execution.cancelled" | "execution.failed" | "observation.failed";
+    readonly attributes?: JsonObject;
+}) & {
+    readonly executionId: string;
+    readonly sequence: number;
+    readonly runId: string;
+};
+export interface RunOptions<Info = unknown> {
+    readonly state?: ExecutionState;
+    readonly input: ExecutionInput;
+    readonly onModelCall: ModelAdapter;
+    readonly info?: Info;
+    readonly signal?: AbortSignal;
+    readonly onEvent?: (event: ExecutionEvent) => void | Promise<void>;
+    readonly record?: (state: ExecutionState) => void | Promise<void>;
+}
+export type RunResult<Output = string> = {
+    readonly status: "completed";
+    readonly state: ExecutionState;
+    readonly output: Output;
+} | {
+    readonly status: "paused";
+    readonly state: ExecutionState;
+    readonly pending: readonly SavedToolCall[];
+} | {
+    readonly status: "cancelled";
+    readonly state: ExecutionState;
+} | {
+    readonly status: "failed";
+    readonly state: ExecutionState;
+    readonly error: Tripwire;
+};

package/dist/types/execution.js

@@ -0,0 +1 @@
+export {};

package/dist/types/manifest.d.ts

@@ -1,19 +1,22 @@
-import type { BoundMiddleware, MiddlewareContributions } from "./middleware.js";
-import type { BuildDiagnostic } from "./shared.js";
-export interface MiddlewareManifest extends MiddlewareContributions {
+import type { ModelDirective } from "./model.js";
+import type { JsonObject } from "./shared.js";
+export interface ManifestTool {
+    readonly name: string;
+    readonly description?: string;
+    readonly inputSchema: JsonObject;
+    readonly outputSchema?: JsonObject;
+}
+export interface CapabilityManifest {
     readonly id: string;
+    readonly kind: "agent" | "capability" | "middleware";
+    readonly hasMiddleware: boolean;
+    readonly instructions?: readonly string[];
+    readonly tools?: readonly ManifestTool[];
+    readonly model?: Pick<ModelDirective, "id" | "controls">;
 }
 export interface AgentManifest {
     readonly id: string;
     readonly name: string;
-    readonly middleware: readonly MiddlewareManifest[];
+    readonly outputSchema?: JsonObject;
+    readonly capabilities: readonly CapabilityManifest[];
 }
-export type BuildResult<Agent> = {
-    readonly ok: true;
-    readonly agent: Agent;
-    readonly manifest: AgentManifest;
-} | {
-    readonly ok: false;
-    readonly diagnostics: readonly BuildDiagnostic[];
-};
-export type { BoundMiddleware };

package/dist/types/middleware.d.ts

@@ -1,31 +1,14 @@
 import type { ContextMutationOptions, ModelCandidate, ModelDirective, ModelToolCall, ModelConfigurationMutationOptions } from "./model.js";
-import type { InputEvent, SessionIdentity, TranscriptEntry } from "./session.js";
-import type { ContextItem, JsonObject, Tripwire } from "./shared.js";
+import type { InputEvent, TranscriptEntry } from "./transcript.js";
+import type { ContextItem, Tripwire } from "./shared.js";
 import type { Interaction, ToolDefinition, ToolResult } from "./tool.js";
-export interface StepInput {
-    readonly sessionId: string;
-    readonly turnId: string;
-    readonly stepId: string;
-    /** One-based position of this turn within the Session. */
-    readonly turnNumber: number;
-    /** One-based position of this Model Step within the Turn. */
-    readonly stepNumber: number;
-    readonly session: Readonly<{
-        readonly userId?: string;
-        readonly context?: JsonObject;
-    }>;
-    readonly arrivals: readonly InputEvent[];
-    readonly toolResults: readonly ToolResult[];
-    readonly transcript: readonly TranscriptEntry[];
-}
 interface StepRequestBase {
-    /** Opaque identity of the Session that owns this Step. */
-    readonly sessionId: string;
+    /** Opaque identity of the execution that owns this Step. */
+    readonly executionId: string;
     /** Opaque identity of the Turn that owns this Step. */
     readonly turnId: string;
     /** Opaque identity of this Model Step. */
     readonly stepId: string;
-    readonly session: StepInput["session"];
     readonly turnNumber: number;
     readonly stepNumber: number;
     readonly arrivals: readonly InputEvent[];
@@ -49,9 +32,9 @@ interface StepRequestBase {
     };
     tripwire(error: Tripwire): StepResponse;
 }
-export type StepRequest<State = never> = StepRequestBase & ([State] extends [never] ? object : {
-    readonly state: Promise<State>;
-});
+export type StepRequest<Info = unknown> = StepRequestBase & {
+    readonly info?: Info;
+};
 export interface StepResponse {
     candidate(): Readonly<ModelCandidate> | undefined;
     toolCalls(): readonly ModelToolCall[];
@@ -60,23 +43,17 @@ export interface StepResponse {
     requireInteraction(callId: string, interaction: Interaction): void;
     tripwire(error: Tripwire): StepResponse;
 }
-export type StepMiddleware<State = never> = (request: StepRequest<State>, next: () => Promise<StepResponse>) => Promise<StepResponse>;
-export interface CapabilityState<State> {
-    create(session: SessionIdentity, signal: AbortSignal): State | Promise<State>;
-    dispose?(value: State): void | Promise<void>;
-}
+export type StepMiddleware<Info = unknown> = (request: StepRequest<Info>, next: () => Promise<StepResponse>) => Promise<StepResponse>;
 export type CapabilityItems<Item> = readonly Item[] | Readonly<{
     readonly slot: string;
     readonly items: readonly Item[];
 }>;
-/** A named capability that may supply static model surface and one typed middleware handler. */
-export interface CapabilityDeclaration<State = never> {
+export interface CapabilityDeclaration<Info = unknown> {
     readonly id: string;
-    readonly tools?: CapabilityItems<ToolDefinition<ToolDefinition["inputSchema"], State>>;
+    readonly tools?: CapabilityItems<ToolDefinition<any, Info, any>>;
     readonly instructions?: CapabilityItems<string>;
     readonly model?: ModelDirective;
-    readonly state?: CapabilityState<State>;
-    readonly middleware?: StepMiddleware<State>;
+    readonly middleware?: StepMiddleware<Info>;
 }
 export interface MiddlewareContributions {
     readonly instructions?: readonly string[];
@@ -86,10 +63,4 @@ export interface MiddlewareContributions {
     }[];
     readonly model?: Pick<ModelDirective, "id" | "controls">;
 }
-export interface BoundMiddleware {
-    readonly id: string;
-    readonly handle: StepMiddleware;
-    readonly state?: CapabilityState<unknown>;
-    readonly contributions?: MiddlewareContributions;
-}
 export {};

package/dist/types/model.d.ts

@@ -1,6 +1,6 @@
-import type { ContextItem, DeferredOutcome, JsonObject, JsonValue } from "./shared.js";
-import type { InputEvent, TranscriptEntry } from "./session.js";
-import type { BoundToolDefinition, ToolResult } from "./tool.js";
+import type { ContextItem, JsonObject, JsonValue } from "./shared.js";
+import type { InputEvent, TranscriptEntry } from "./transcript.js";
+import type { ToolDescriptor, ToolResult } from "./tool.js";
 export interface ModelToolCall {
     readonly id: string;
     readonly name: string;
@@ -81,8 +81,8 @@ export interface ModelConfigurationSnapshot {
     readonly version: 1;
     readonly model?: ModelDirective;
     readonly instructions: readonly ModelConfigurationInstruction[];
-    /** Bound tools are retained for execution. */
-    readonly tools: readonly BoundToolDefinition[];
+    /** Data-only descriptions of the selected tools. */
+    readonly tools: readonly ToolDescriptor[];
     readonly toolContracts: readonly ModelConfigurationTool[];
     readonly contributors: readonly ModelConfigurationContributor[];
 }
@@ -103,7 +103,7 @@ export interface ContextSnapshot {
     readonly contributors: readonly ContextContributor[];
 }
 export interface ModelRequest {
-    readonly sessionId: string;
+    readonly executionId: string;
     readonly turnId: string;
     readonly stepId: string;
     readonly model?: ModelDirective;
@@ -114,8 +114,8 @@ export interface ModelRequest {
     readonly transcript: readonly TranscriptEntry[];
     readonly arrivals: readonly InputEvent[];
     readonly toolResults: readonly ToolResult[];
-    /** Tools are normalized and immutable by the time a Model sees them. */
-    readonly tools: readonly BoundToolDefinition[];
+    /** Immutable tool descriptions; executable definitions stay inside Harness. */
+    readonly tools: readonly ToolDescriptor[];
     /** Optional portable contract for this turn's terminal JSON result. */
     readonly outputSchema?: JsonObject;
 }
@@ -168,7 +168,7 @@ export interface ModelCall {
     readonly tools: readonly ModelCallTool[];
     /** Optional portable contract for this turn's terminal JSON result. */
     readonly outputSchema?: JsonObject;
-    readonly sessionId: string;
+    readonly executionId: string;
 }
 export interface ModelAdapterContext {
     readonly request: ModelRequest;
@@ -181,4 +181,4 @@ export interface ModelPreparedCall {
     readonly adapter: string;
     readonly call: JsonValue;
 }
-export type ModelAdapter = (call: ModelCall, context: ModelAdapterContext) => Promise<ModelCandidate | string | DeferredOutcome>;
+export type ModelAdapter = (call: ModelCall, context: ModelAdapterContext) => Promise<ModelCandidate | string>;

package/dist/types/observe.d.ts

@@ -0,0 +1,165 @@
+import type { ContextSnapshot, ModelCandidate, ModelCall, ModelConfigurationSnapshot } from "./model.js";
+import type { JsonObject, JsonValue } from "./shared.js";
+import type { InputEvent, TranscriptEntry } from "./transcript.js";
+import type { RequiredInteraction, ToolDescriptor, ToolResult } from "./tool.js";
+export type ObserveToolSnapshot = ToolDescriptor;
+/** JSON-only model-configuration view suitable for an observation stream. */
+export interface ObserveModelConfigurationSnapshot extends Omit<ModelConfigurationSnapshot, "tools"> {
+    readonly tools: readonly ObserveToolSnapshot[];
+}
+export interface ObserveSealedCall {
+    readonly callId: string;
+    readonly toolName: string;
+    readonly args: JsonValue;
+    readonly invocationId: string;
+    readonly owner: {
+        readonly middlewareId: string;
+        readonly slot: string;
+    };
+    readonly interaction?: RequiredInteraction;
+}
+export interface ObserveModelRequested {
+    /** The exact immutable logical input supplied to the ModelAdapter. */
+    readonly call: ModelCall;
+    /** Canonical configuration facts and attribution. */
+    readonly configuration: ObserveModelConfigurationSnapshot;
+    /** Current-step runtime context and attribution. */
+    readonly context: ContextSnapshot;
+}
+export type ObserveEvent = {
+    readonly type: "model.requested";
+    readonly invocationId: string;
+    readonly turnId: string;
+    readonly stepId: string;
+    readonly inputId?: string;
+    readonly requestedModelId?: string;
+    readonly attributes: ObserveModelRequested;
+} | {
+    readonly type: "model.prepared";
+    readonly invocationId: string;
+    readonly turnId: string;
+    readonly stepId: string;
+    readonly inputId?: string;
+    readonly requestedModelId?: string;
+    readonly attributes: {
+        readonly adapter: string;
+        readonly call: JsonValue;
+    };
+} | {
+    readonly type: "model.completed";
+    readonly invocationId?: string;
+    readonly turnId: string;
+    readonly stepId: string;
+    readonly inputId?: string;
+    readonly requestedModelId?: string;
+    readonly attributes: ModelCandidate;
+} | {
+    readonly type: "step.started";
+    readonly turnId: string;
+    readonly stepId: string;
+    readonly inputId?: string;
+    readonly turnNumber: number;
+    readonly stepNumber: number;
+    readonly attributes: {
+        readonly arrivals: readonly InputEvent[];
+        readonly toolResults: readonly ToolResult[];
+        readonly transcript: readonly TranscriptEntry[];
+    };
+} | {
+    readonly type: "middleware.entered" | "middleware.completed";
+    readonly turnId: string;
+    readonly stepId: string;
+    readonly inputId?: string;
+    readonly middlewareId: string;
+} | {
+    readonly type: "middleware.lease-violation";
+    readonly turnId: string;
+    readonly stepId: string;
+    readonly inputId?: string;
+    readonly middlewareId: string;
+    readonly reason: string;
+} | {
+    readonly type: "tool.sealed";
+    readonly turnId: string;
+    readonly stepId: string;
+    readonly inputId?: string;
+    readonly attributes: {
+        readonly executable: readonly ObserveSealedCall[];
+        readonly immediate: readonly ToolResult[];
+    };
+} | {
+    readonly type: "tool.started";
+    readonly executionId: string;
+    readonly turnId: string;
+    readonly stepId: string;
+    readonly inputId?: string;
+    readonly toolName: string;
+    readonly callId: string;
+    readonly invocationId: string;
+    readonly middlewareId: string;
+    readonly slot: string;
+    readonly attributes: {
+        readonly args: JsonValue;
+    };
+} | {
+    readonly type: "tool.completed";
+    readonly executionId: string;
+    readonly turnId: string;
+    readonly stepId: string;
+    readonly inputId?: string;
+    readonly toolName: string;
+    readonly callId: string;
+    readonly invocationId: string;
+    readonly middlewareId: string;
+    readonly slot: string;
+    readonly outcome: string;
+    readonly code?: string;
+    readonly attributes?: ToolResult;
+} | {
+    readonly type: "tool.deferred";
+    readonly executionId: string;
+    readonly turnId: string;
+    readonly stepId: string;
+    readonly inputId?: string;
+    readonly toolName: string;
+    readonly callId: string;
+    readonly invocationId: string;
+    readonly middlewareId: string;
+    readonly slot: string;
+    readonly attributes: {
+        readonly token?: JsonValue;
+    };
+} | {
+    readonly type: "turn.completed";
+    readonly turnId: string;
+    readonly stepId: string;
+    readonly inputId?: string;
+    readonly attributes: {
+        readonly output: JsonValue;
+    };
+} | {
+    readonly type: "interaction.required";
+    readonly turnId: string;
+    readonly stepId: string;
+    readonly inputId?: string;
+    readonly interactionId: string;
+    readonly kind: string;
+    readonly callId?: string;
+    readonly toolName?: string;
+    readonly phase?: "interaction" | "execute";
+    readonly attributes: {
+        readonly prompt: string;
+        readonly metadata?: JsonObject;
+    };
+} | {
+    readonly type: "tripwire";
+    readonly turnId: string;
+    readonly stepId?: string;
+    readonly inputId?: string;
+    readonly code: string;
+    readonly scope: string;
+    readonly attributes: {
+        readonly message: string;
+    };
+};
+export type Observer = (event: ObserveEvent) => void | Promise<void>;

package/dist/types/observe.js

@@ -0,0 +1 @@
+export {};