@nylorun/harness 0.5.0-beta.1

package/dist/types/middleware.d.ts

@@ -0,0 +1,65 @@
+import type { ContextMutationOptions, ModelCandidate, ModelDirective, ModelToolCall, ModelConfigurationMutationOptions } from "./model.js";
+import type { InputEvent, TranscriptEntry } from "./session.js";
+import type { ContextItem, JsonObject, 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[];
+}
+export interface StepRequest {
+    /** Opaque identity of the Session that owns this Step. */
+    readonly sessionId: 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[];
+    readonly toolResults: readonly ToolResult[];
+    readonly transcript: readonly TranscriptEntry[];
+    readonly context: {
+        set(slot: string, items: readonly ContextItem[], options?: ContextMutationOptions): void;
+    };
+    readonly configuration: {
+        readonly instructions: {
+            set(slot: string, items: readonly string[], options?: ModelConfigurationMutationOptions): void;
+        };
+        readonly tools: {
+            set(slot: string, tools: readonly ToolDefinition[], options?: ModelConfigurationMutationOptions): void;
+        };
+        readonly model: {
+            select(directive: ModelDirective, options?: Omit<ModelConfigurationMutationOptions, "order">): void;
+            replace(directive: ModelDirective, options?: Omit<ModelConfigurationMutationOptions, "order">): void;
+            clear(options?: Omit<ModelConfigurationMutationOptions, "order">): void;
+        };
+    };
+    tripwire(error: Tripwire): StepResponse;
+}
+export interface StepResponse {
+    candidate(): Readonly<ModelCandidate> | undefined;
+    toolCalls(): readonly ModelToolCall[];
+    replace(candidate: ModelCandidate): void;
+    deny(callId: string, reason: string): void;
+    requireInteraction(callId: string, interaction: Interaction): void;
+    requirePreflight(callId: string, kind: "sandbox" | "validation"): void;
+    tripwire(error: Tripwire): StepResponse;
+}
+export type StepMiddleware = (request: StepRequest, next: () => Promise<StepResponse>) => Promise<StepResponse>;
+export interface BoundMiddleware {
+    readonly id: string;
+    readonly handle: StepMiddleware;
+}

package/dist/types/middleware.js

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

package/dist/types/model.d.ts

@@ -0,0 +1,166 @@
+import type { ContextItem, JsonObject } from "./shared.js";
+import type { InputEvent, TranscriptEntry } from "./session.js";
+import type { BoundToolDefinition, ToolResult } from "./tool.js";
+export interface ModelToolCall {
+    readonly id: string;
+    readonly name: string;
+    readonly args: JsonObject;
+}
+export type ModelOutputBlock = {
+    readonly type: "text";
+    readonly text: string;
+} | {
+    readonly type: "reasoning";
+    readonly text: string;
+} | {
+    readonly type: "tool-call";
+    readonly id: string;
+    readonly name: string;
+    readonly args: JsonObject;
+    readonly raw?: string;
+};
+export interface ModelUsage {
+    readonly inputTokens?: number;
+    readonly outputTokens?: number;
+    readonly totalTokens?: number;
+    readonly cachedTokens?: number;
+    readonly reasoningTokens?: number;
+    readonly costUsd?: number;
+}
+export type ModelFinishReason = "stop" | "length" | "tool-calls" | "content-filter" | "other";
+export interface ModelEvidence {
+    readonly requestId?: string;
+    readonly resolvedModel?: string;
+    readonly warnings?: readonly string[];
+    readonly extras?: JsonObject;
+}
+export interface ModelCandidate {
+    readonly output: readonly ModelOutputBlock[];
+    readonly finishReason?: ModelFinishReason;
+    readonly usage?: ModelUsage;
+    readonly evidence?: ModelEvidence;
+}
+export interface ModelControls {
+    readonly temperature?: number;
+    readonly maxOutputTokens?: number;
+}
+export interface ModelDirective {
+    readonly id?: string;
+    readonly controls?: ModelControls;
+    readonly config?: JsonObject;
+}
+/** A middleware-owned declaration for the model-visible configuration. */
+export interface ModelConfigurationMutationOptions {
+    readonly order?: number;
+    readonly reason?: string;
+}
+export interface ModelConfigurationContributor {
+    readonly middlewareId: string;
+    readonly slot: string;
+    readonly order: number;
+    readonly digest: string;
+    readonly reason?: string;
+}
+export interface ModelConfigurationTool {
+    readonly name: string;
+    readonly description?: string;
+    readonly inputSchema: JsonObject;
+    readonly digest: string;
+    readonly contributor: ModelConfigurationContributor;
+}
+export interface ModelConfigurationInstruction {
+    readonly text: string;
+    readonly digest: string;
+    readonly contributor: ModelConfigurationContributor;
+}
+export interface ModelConfigurationSnapshot {
+    readonly version: 1;
+    readonly model?: ModelDirective;
+    readonly instructions: readonly ModelConfigurationInstruction[];
+    /** Bound tools are retained for execution; their digest covers only their provider-visible contract. */
+    readonly tools: readonly BoundToolDefinition[];
+    readonly toolContracts: readonly ModelConfigurationTool[];
+    readonly contributors: readonly ModelConfigurationContributor[];
+    readonly digests: Readonly<{
+        readonly logical: string;
+        readonly model: string;
+        readonly request: string;
+    }>;
+}
+/** A middleware-owned declaration for this model call's runtime context. */
+export interface ContextMutationOptions {
+    readonly order?: number;
+    readonly reason?: string;
+}
+export interface ContextContributor {
+    readonly middlewareId: string;
+    readonly slot: string;
+    readonly order: number;
+    readonly digest: string;
+    readonly reason?: string;
+}
+/** Canonical runtime context for one model call. Not part of the configuration digest. */
+export interface ContextSnapshot {
+    readonly items: readonly ContextItem[];
+    readonly contributors: readonly ContextContributor[];
+    readonly digest: string;
+}
+export interface ModelRequest {
+    readonly sessionId: string;
+    readonly turnId: string;
+    readonly stepId: string;
+    readonly model?: ModelDirective;
+    /** Canonical, immutable Harness-owned model configuration for this call. */
+    readonly configuration: ModelConfigurationSnapshot;
+    readonly instructions: readonly string[];
+    readonly context: ContextSnapshot;
+    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[];
+}
+export type PromptContentPart = {
+    readonly type: "text";
+    readonly text: string;
+} | {
+    readonly type: "tool-call";
+    readonly id: string;
+    readonly name: string;
+    readonly args: JsonObject;
+};
+export type PromptItem = {
+    readonly kind: "instructions";
+    readonly role: "system";
+    readonly content: readonly PromptContentPart[];
+} | {
+    readonly kind: "message";
+    readonly role: "user" | "assistant";
+    readonly content: readonly PromptContentPart[];
+} | {
+    readonly kind: "tool-result";
+    readonly toolCallId: string;
+    readonly toolName: string;
+    readonly status: "completed" | "denied" | "failed";
+    readonly content: readonly PromptContentPart[];
+} | {
+    readonly kind: "context";
+    readonly role: "user";
+    readonly content: readonly PromptContentPart[];
+};
+export interface ModelCallTool {
+    readonly name: string;
+    readonly description?: string;
+    readonly inputSchema: JsonObject;
+}
+export interface ModelCall {
+    readonly model?: ModelDirective;
+    readonly prompt: readonly PromptItem[];
+    readonly tools: readonly ModelCallTool[];
+    readonly sessionId: string;
+}
+export interface ModelAdapterContext {
+    readonly request: ModelRequest;
+    readonly signal: AbortSignal;
+}
+export type ModelAdapter = (call: ModelCall, context: ModelAdapterContext) => Promise<ModelCandidate | string>;

package/dist/types/model.js

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

package/dist/types/session.d.ts

@@ -0,0 +1,122 @@
+import type { ModelCandidate } from "./model.js";
+import type { JsonObject, JsonValue, Observer, Tripwire } from "./shared.js";
+import type { RequiredInteraction, ToolResult } from "./tool.js";
+export type InputEvent = {
+    readonly kind: "user-message";
+    readonly text: string;
+    readonly metadata?: JsonObject;
+} | {
+    readonly kind: "interrupt";
+    readonly text: string;
+    readonly metadata?: JsonObject;
+} | {
+    readonly kind: "approve";
+    readonly interactionId: string;
+    readonly approved: boolean;
+} | {
+    readonly kind: "respond";
+    readonly interactionId: string;
+    readonly value: JsonValue;
+};
+export type SessionEvent = {
+    readonly type: "input";
+    readonly event: InputEvent;
+    readonly turnId: string;
+} | {
+    readonly type: "candidate";
+    readonly turnId: string;
+    readonly stepId: string;
+    readonly candidate: ModelCandidate;
+} | {
+    readonly type: "final";
+    readonly output: string;
+    readonly turnId: string;
+} | {
+    readonly type: "interaction.required";
+    readonly interaction: RequiredInteraction;
+    readonly turnId: string;
+} | {
+    readonly type: "tripwire";
+    readonly tripwire: Tripwire;
+    readonly turnId: string;
+} | {
+    readonly type: "input.queued";
+    readonly inputId: string;
+} | {
+    readonly type: "input.rejected";
+    readonly inputId: string;
+    readonly reason: string;
+} | {
+    readonly type: "input.cancelled";
+    readonly inputId: string;
+    readonly reason: string;
+} | {
+    readonly type: "session.stopped";
+    readonly sessionId: string;
+};
+export interface InputCompletion {
+    readonly inputId: string;
+    readonly status: "completed" | "waiting" | "rejected" | "cancelled" | "stopped";
+    readonly events: readonly SessionEvent[];
+}
+export interface InputHandle {
+    readonly inputId: string;
+    readonly completed: Promise<InputCompletion>;
+}
+export interface SessionOptions {
+    readonly id?: string;
+    readonly userId?: string;
+    readonly context?: JsonObject;
+}
+export interface InputOptions {
+    readonly signal?: AbortSignal;
+}
+export type MessageInput = string | {
+    readonly text: string;
+    readonly metadata?: JsonObject;
+};
+export type InteractionReply = Extract<InputEvent, {
+    kind: "approve" | "respond";
+}>;
+/** Ordinary user text or an interaction reply. Use `Session.interrupt()` for barge-in text. */
+export type SessionInput = MessageInput | InteractionReply;
+export interface TranscriptInputEntry {
+    readonly kind: "input";
+    readonly turnId: string;
+    readonly event: InputEvent;
+}
+export interface TranscriptCandidateEntry {
+    readonly kind: "candidate";
+    readonly turnId: string;
+    readonly stepId: string;
+    readonly candidate: ModelCandidate;
+}
+export interface TranscriptToolsEntry {
+    readonly kind: "tool-results";
+    readonly turnId: string;
+    readonly stepId: string;
+    readonly results: readonly ToolResult[];
+}
+export interface TranscriptFinalEntry {
+    readonly kind: "final";
+    readonly turnId: string;
+    readonly stepId: string;
+    readonly output: string;
+}
+export type TranscriptEntry = TranscriptInputEntry | TranscriptCandidateEntry | TranscriptToolsEntry | TranscriptFinalEntry;
+export interface SessionSnapshot {
+    readonly id: string;
+    readonly status: "idle" | "running" | "waiting" | "stopped";
+    readonly turnCount: number;
+    readonly transcript: readonly TranscriptEntry[];
+    readonly pendingInteraction?: RequiredInteraction;
+}
+export interface Session {
+    readonly id: string;
+    readonly state: SessionSnapshot;
+    input(event: SessionInput, options?: InputOptions): InputHandle;
+    interrupt(event: MessageInput, options?: InputOptions): InputHandle;
+    stream(): AsyncIterable<SessionEvent>;
+    observe(listener: Observer): () => void;
+    stop(reason?: string): Promise<void>;
+}

package/dist/types/session.js

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

package/dist/types/shared.d.ts

@@ -0,0 +1,180 @@
+import type { ContextSnapshot, ModelCandidate, ModelCall, ModelConfigurationSnapshot } from "./model.js";
+import type { InputEvent, TranscriptEntry } from "./session.js";
+import type { RequiredInteraction, ToolResult } from "./tool.js";
+export type JsonPrimitive = string | number | boolean | null;
+export type JsonValue = JsonPrimitive | JsonObject | readonly JsonValue[];
+export type JsonObject = {
+    readonly [key: string]: JsonValue;
+};
+export interface BuildDiagnostic {
+    readonly code: string;
+    readonly message: string;
+    readonly toolName?: string;
+    readonly details?: Readonly<Record<string, string | number | boolean>>;
+    readonly cause?: unknown;
+}
+export interface ContextItem {
+    readonly type?: string;
+    readonly value: JsonValue;
+}
+export interface Tripwire {
+    readonly code: string;
+    readonly message: string;
+    readonly scope?: "step" | "session";
+}
+export interface ObserveToolSnapshot {
+    readonly name: string;
+    readonly description?: string;
+    readonly executeWith: string;
+    readonly parameters: {
+        readonly jsonSchema: JsonObject;
+    };
+}
+/** 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 executeWith: string;
+    readonly invocationId: string;
+    readonly preflight?: "sandbox" | "validation";
+    readonly interaction?: RequiredInteraction;
+}
+export interface ObserveModelRequested {
+    /** The exact immutable logical input supplied to the ModelAdapter. */
+    readonly call: ModelCall;
+    /** Canonical configuration facts and attribution; hashes have no policy semantics. */
+    readonly configuration: ObserveModelConfigurationSnapshot;
+    /** Current-step runtime context and attribution. */
+    readonly context: ContextSnapshot;
+}
+export type ObserveEvent = {
+    readonly type: "session.stopped";
+    readonly reason: string;
+} | {
+    readonly type: "input.received";
+    readonly inputId: string;
+    readonly kind: string;
+} | {
+    readonly type: "input.queued";
+    readonly inputId: string;
+} | {
+    readonly type: "input.rejected";
+    readonly inputId: string;
+    readonly reason: string;
+} | {
+    readonly type: "input.cancelled";
+    readonly inputId: string;
+    readonly reason: string;
+} | {
+    readonly type: "model.requested";
+    readonly turnId: string;
+    readonly stepId: string;
+    readonly inputId?: string;
+    readonly requestedModelId?: string;
+    readonly attributes: ObserveModelRequested;
+} | {
+    readonly type: "model.completed";
+    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 session?: {
+            readonly userId?: string;
+            readonly context?: JsonObject;
+        };
+        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: "adapter.preflight.started" | "adapter.started";
+    readonly turnId: string;
+    readonly stepId: string;
+    readonly inputId?: string;
+    readonly adapterId: string;
+    readonly toolName: string;
+    readonly callId: string;
+    readonly invocationId?: string;
+    readonly attributes: {
+        readonly args: JsonValue;
+    };
+} | {
+    readonly type: "adapter.preflight.completed" | "adapter.completed";
+    readonly turnId: string;
+    readonly stepId: string;
+    readonly inputId?: string;
+    readonly adapterId: string;
+    readonly toolName: string;
+    readonly callId: string;
+    readonly outcome: string;
+    readonly code?: string;
+    readonly attributes?: ToolResult;
+} | {
+    readonly type: "turn.completed";
+    readonly turnId: string;
+    readonly stepId: string;
+    readonly inputId?: string;
+    readonly attributes: {
+        readonly output: string;
+    };
+} | {
+    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" | "preflight" | "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/shared.js

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

package/dist/types/tool.d.ts

@@ -0,0 +1,101 @@
+import type { ZodObject, output } from "zod";
+import type { JsonObject, JsonValue } from "./shared.js";
+type SchemaValidationSuccess<T> = {
+    readonly ok: true;
+    readonly value: T;
+};
+type SchemaValidationFailure = {
+    readonly ok: false;
+    readonly issues: readonly string[];
+};
+type SchemaValidation<T> = SchemaValidationSuccess<T> | SchemaValidationFailure;
+/** Harness tool parameters are synchronous Zod object schemas. */
+export type ToolObjectSchema = ZodObject;
+export interface BoundToolSchema<T> {
+    readonly jsonSchema: JsonObject;
+    validate(value: unknown): SchemaValidation<T>;
+}
+export interface ToolDefinition<Parameters extends ToolObjectSchema = ToolObjectSchema> {
+    readonly name: string;
+    readonly description?: string;
+    readonly parameters: Parameters;
+    readonly executeWith: string;
+}
+export interface BoundToolDefinition<Parameters extends ToolObjectSchema = ToolObjectSchema> extends Omit<ToolDefinition<Parameters>, "parameters"> {
+    readonly parameters: BoundToolSchema<output<Parameters>>;
+}
+export interface Interaction {
+    readonly id?: string;
+    readonly kind: "approval" | "response";
+    readonly prompt: string;
+    readonly metadata?: JsonObject;
+}
+export interface RequiredInteraction extends Interaction {
+    readonly id: string;
+}
+export interface ToolExecutionResume {
+    readonly interactionId: string;
+    readonly kind: "approval" | "response";
+    readonly approved?: boolean;
+    readonly value?: JsonValue;
+    readonly token?: JsonValue;
+}
+export interface SealedToolCall {
+    readonly callId: string;
+    readonly toolName: string;
+    readonly args: JsonValue;
+    readonly executeWith: string;
+}
+export type ToolContent = JsonValue;
+export type ToolOutcome = {
+    readonly kind: "completed";
+    readonly output: ToolContent;
+} | {
+    readonly kind: "denied";
+    readonly reason: string;
+} | {
+    readonly kind: "failed";
+    readonly code: string;
+    readonly message: string;
+} | {
+    readonly kind: "interaction-required";
+    readonly interaction: Interaction;
+    readonly token?: JsonValue;
+};
+export type PreflightOutcome = {
+    readonly kind: "completed";
+} | Exclude<ToolOutcome, {
+    readonly kind: "completed";
+}>;
+export interface ToolAdapter {
+    readonly id: string;
+    preflight?(call: SealedToolCall, context: {
+        readonly kind: "sandbox" | "validation";
+        readonly invocationId: string;
+        readonly signal: AbortSignal;
+        readonly resume?: ToolExecutionResume;
+    }): Promise<PreflightOutcome>;
+    execute(call: SealedToolCall, context: {
+        readonly invocationId: string;
+        readonly signal: AbortSignal;
+        readonly resume?: ToolExecutionResume;
+    }): Promise<ToolOutcome>;
+}
+/** Scheduling policy for one adapter registration on an Agent. */
+export interface AdapterExecutionOptions {
+    /**
+     * Maximum concurrent execute() calls across all Sessions from the built Agent.
+     * Omit for unbounded parallel execution.
+     */
+    readonly maxConcurrentCalls?: number;
+}
+export interface ToolResult {
+    readonly callId: string;
+    readonly toolName: string;
+    readonly kind: "completed" | "denied" | "failed";
+    readonly output?: ToolContent;
+    readonly reason?: string;
+    readonly code?: string;
+    readonly message?: string;
+}
+export {};

package/dist/types/tool.js

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

package/dist/utils/digest.d.ts

@@ -0,0 +1 @@
+export declare const digest: (value: unknown) => string;

package/dist/utils/digest.js

@@ -0,0 +1,14 @@
+import { sha256 } from "@noble/hashes/sha2.js";
+import { bytesToHex, utf8ToBytes } from "@noble/hashes/utils.js";
+function canonical(value) {
+    if (Array.isArray(value))
+        return `[${value.map(canonical).join(",")}]`;
+    if (value && typeof value === "object") {
+        return `{${Object.entries(value)
+            .sort(([a], [b]) => a.localeCompare(b))
+            .map(([key, item]) => `${JSON.stringify(key)}:${canonical(item)}`)
+            .join(",")}}`;
+    }
+    return JSON.stringify(value);
+}
+export const digest = (value) => bytesToHex(sha256(utf8ToBytes(canonical(value))));

package/dist/utils/ids.d.ts

@@ -0,0 +1 @@
+export declare function createId(prefix: string): string;

package/dist/utils/ids.js

@@ -0,0 +1,3 @@
+export function createId(prefix) {
+    return `${prefix}_${globalThis.crypto.randomUUID()}`;
+}

package/dist/utils/immutable.d.ts

@@ -0,0 +1,5 @@
+import type { JsonObject, JsonValue } from "../types/shared.js";
+export declare function assertJson(value: unknown, path?: string): asserts value is JsonValue;
+export declare function copyJson<T>(value: T): T;
+export declare function copyJsonObject(value: unknown, path: string): JsonObject;
+export declare function deepFreeze<T>(value: T): T;