@actor0/harness 0.0.0-stage → 0.5.2

package/dist/types.d.ts

@@ -0,0 +1,241 @@
+export type ChatRole = "system" | "user" | "assistant" | "tool";
+export type ToolCall = {
+    id: string;
+    type: "function";
+    function: {
+        name: string;
+        arguments: string;
+    };
+};
+export type ChatMessage = {
+    role: ChatRole;
+    content: string;
+    tool_calls?: ToolCall[];
+    tool_call_id?: string;
+    name?: string;
+};
+export type ToolDefinition = {
+    type: "function";
+    function: {
+        name: string;
+        description: string;
+        parameters: Record<string, unknown>;
+    };
+};
+export type Usage = {
+    prompt_tokens: number;
+    completion_tokens: number;
+    total_tokens: number;
+    cached_tokens?: number;
+    reasoning_tokens?: number;
+};
+export type ModelEvent = {
+    type: "token";
+    delta: string;
+} | {
+    type: "reasoning";
+    delta: string;
+} | {
+    type: "tool_call";
+    tool_calls: ToolCall[];
+} | {
+    type: "usage";
+    usage: Usage;
+} | {
+    type: "status";
+    note: string;
+} | {
+    type: "provider";
+    name: string;
+} | {
+    type: "done";
+    /**
+     * The endpoint stopped mid-answer — the output-token cap, or the
+     * model's own window, ran out. The text so far is the beginning of
+     * an answer, not one, and a caller that cannot tell the difference
+     * will save a fragment and call it a reply.
+     */
+    truncated?: boolean;
+    /** The endpoint's own word for it, kept for a message that must name a cause. */
+    reason?: string;
+};
+/**
+ * A protocol block the answer filter refused. `call` is the synthetic call
+ * that carries the error tool result into the transcript (the harness authors
+ * the result itself; no tool host runs), and `reason` is the sentence both
+ * the model and the UI see.
+ */
+export type RejectedToolBlock = {
+    /** The name the model asked for — "unknown" when it emitted none. */
+    name: string;
+    call: ToolCall;
+    reason: string;
+};
+export type PlanPrefix = {
+    title: string;
+    plan: string;
+    consumed: number;
+};
+export type ReasoningSummary = {
+    title: string;
+    summary: string;
+};
+export type HarnessEvent = {
+    type: "token";
+    delta: string;
+} | {
+    type: "reasoning";
+    delta: string;
+} | {
+    type: "status";
+    status: string;
+    source: "marker" | "note";
+} | {
+    type: "plan";
+    plan: PlanPrefix;
+}
+/**
+ * A model attempt is about to stream. Everything a host renders from the
+ * events that follow belongs to this attempt; a host that snapshots its
+ * render state here can discard exactly this attempt's output when the
+ * matching `reset` arrives.
+ */
+ | {
+    type: "attempt_start";
+} | {
+    type: "reset";
+    attemptText: string;
+} | {
+    type: "tool_start";
+    call: ToolCall;
+} | {
+    type: "tool_result";
+    call: ToolCall;
+    output: string;
+    error?: string;
+} | {
+    type: "tool_call";
+    tool_calls: ToolCall[];
+}
+/**
+ * A tool-call block was refused (unoffered tool, or arguments that were not
+ * valid JSON). Nothing reaches the answer text; the UI shows a cross and
+ * the model receives the error result next round.
+ */
+ | {
+    type: "tool_rejected";
+    rejection: RejectedToolBlock;
+} | {
+    type: "provider";
+    name: string;
+} | {
+    type: "usage";
+    usage: Usage;
+} | {
+    type: "partial";
+    text: string;
+} | {
+    type: "done";
+    text: string;
+    complete: boolean;
+    /** The endpoint cut this answer off at its output cap. `complete` is then false. */
+    truncated?: boolean;
+    /** The endpoint's finish/stop reason, when it named one. */
+    reason?: string;
+}
+/**
+ * The turn stopped because it could not make progress on its own. The
+ * harness does not decide to give up here — it reports the condition and the
+ * host decides, typically by asking the user whether to keep going.
+ */
+ | {
+    type: "needs_user";
+    reason: "tool_errors" | "round_limit";
+    message: string;
+} | {
+    type: "error";
+    message: string;
+    retriable: boolean;
+};
+export type ModelClient = {
+    stream(messages: ChatMessage[], tools: ToolDefinition[], signal: AbortSignal): AsyncIterable<ModelEvent>;
+};
+export type ToolHost = {
+    definitions(): ToolDefinition[];
+    execute(call: ToolCall, signal: AbortSignal): Promise<string>;
+};
+export type HarnessObserver = {
+    event?(event: HarnessEvent): void | Promise<void>;
+};
+export type RoundResult = {
+    text: string;
+    toolCalls: ToolCall[];
+    /** Protocol blocks refused this round — see RejectedToolBlock. */
+    rejectedBlocks: RejectedToolBlock[];
+    complete: boolean;
+    /** The endpoint stopped this round's answer short — see the `done` event. */
+    truncated: boolean;
+    /** The endpoint's finish/stop reason, when it named one. */
+    truncationReason?: string;
+    reasoning: ReasoningSummary;
+    usage: Usage[];
+};
+export type ToolRoundPolicy = {
+    /** Return true when the completed tool round is already the final answer. */
+    shouldStopAfterTools?(input: {
+        calls: ToolCall[];
+        text: string;
+        round: number;
+    }): boolean;
+    /** Prompt used for the one permitted empty-answer continuation. */
+    emptyContinuationMessage?: string;
+    /** Prompt used for the one permitted continuation of a cut-off answer. */
+    truncationContinuationMessage?: string;
+};
+/**
+ * What one turn actually did, for a local audit log.
+ *
+ * `usage` is the token accounting; this is everything else a host would want
+ * to total up afterwards — how many rounds it took, which tools the model
+ * reached for and how often, and whether it finished. It is computed by the
+ * harness (which is the only thing that sees every round) and handed back on
+ * `RunResult`, so a host records it without re-deriving it from the event
+ * stream. It deliberately carries no model name or timestamp: the harness
+ * knows neither, and the host that does supplies them when it writes the log.
+ */
+export type TurnAudit = {
+    /** Model rounds that ran (a round is one model call plus its tool executions). */
+    rounds: number;
+    /** Whether the turn ended with a complete, untruncated answer. */
+    complete: boolean;
+    /** Tool calls the model made, by tool name. Counts attempts, including failures. */
+    toolCalls: Record<string, number>;
+    /** Total tool calls across the turn — the sum of `toolCalls`. */
+    toolCallCount: number;
+    /** Tokens summed across every round. */
+    promptTokens: number;
+    completionTokens: number;
+    totalTokens: number;
+};
+export type RunResult = {
+    messages: ChatMessage[];
+    text: string;
+    complete: boolean;
+    rounds: number;
+    usage: Usage[];
+    reasoning: ReasoningSummary;
+    /** What the turn did, for a host's audit log — see TurnAudit. */
+    audit: TurnAudit;
+    /** True when the turn stopped on `needs_user` and can be resumed. */
+    blocked?: boolean;
+    /**
+     * The turn ended with the model's answer cut off by the output cap, and
+     * the one permitted continuation did not finish it either. The text is
+     * real and is returned, but the host has to say it is unfinished.
+     */
+    truncated?: boolean;
+    /** The endpoint's finish/stop reason, when it named one. */
+    truncationReason?: string;
+};
+export declare const emptyUsage: () => Usage;
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"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"}

package/dist/types.js

@@ -0,0 +1,5 @@
+export const emptyUsage = () => ({
+    prompt_tokens: 0,
+    completion_tokens: 0,
+    total_tokens: 0,
+});

package/package.json

@@ -1,6 +1,30 @@
-{
-  "name": "@actor0/harness",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+{
+  "name": "@actor0/harness",
+  "version": "0.5.2",
+  "type": "module",
+  "files": [
+    "dist"
+  ],
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json --tsBuildInfoFile dist/.tsbuildinfo",
+    "prepack": "node -e \"require('fs').rmSync('dist/.tsbuildinfo',{force:true})\"",
+    "test": "node --import tsx --test \"src/**/*.test.ts\"",
+    "typecheck": "tsc -p tsconfig.json --noEmit"
+  },
+  "devDependencies": {
+    "@types/node": "^20",
+    "tsx": "^4.20",
+    "typescript": "^5.9"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/README.md

@@ -1,3 +0,0 @@
-# Temporary Holding Version
-
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.