@odla-ai/harness 0.1.0

package/dist/types-D12vK3K9.d.ts

@@ -0,0 +1,249 @@
+import { OracleResponse, ChatInput } from '@odla-ai/ai';
+
+/** Current JSONL protocol version exchanged between a runner and an agent container. */
+declare const HARNESS_PROTOCOL_VERSION: 1;
+/** Default control-plane route used for model inference requested by coding agents. */
+declare const DEFAULT_AI_ROUTE: "coding";
+/** Lifecycle state reported for a harness task and its active attempt. */
+type HarnessTaskStatus = "queued" | "running" | "cancel_requested" | "completed" | "failed" | "cancelled";
+/** Lifecycle state of one execution attempt for a task. */
+type HarnessAttemptStatus = HarnessTaskStatus;
+/** Trusted or untrusted participant that emitted a harness event. */
+type HarnessActor = "operator" | "runner" | "agent" | "model" | "system";
+/** Resource and isolation limits enforced while an untrusted task executes. */
+interface HarnessPolicy {
+    network: "none";
+    timeoutMs: number;
+    maxOutputBytes: number;
+    maxPatchBytes: number;
+}
+/** Immutable task instructions and execution policy delivered with a lease. */
+interface HarnessTaskSpec {
+    taskId: string;
+    attemptId: string;
+    title: string;
+    prompt: string;
+    workspace: string;
+    aiRoute: string;
+    policy: HarnessPolicy;
+    parentAttemptId?: string | null;
+    checkpointSeq?: number | null;
+}
+/** Time-bound assignment authorizing a runner to execute one task attempt. */
+interface HarnessLease {
+    protocolVersion: typeof HARNESS_PROTOCOL_VERSION;
+    leaseId: string;
+    generation: number;
+    expiresAt: number;
+    task: HarnessTaskSpec;
+}
+/** Runner-supplied event before the control plane assigns sequence and task metadata. */
+interface HarnessEventInput {
+    eventId: string;
+    kind: string;
+    actor: HarnessActor;
+    payload: unknown;
+    createdAt: number;
+}
+/** Persisted, ordered event associated with a specific task attempt. */
+interface HarnessEvent extends HarnessEventInput {
+    seq: number;
+    taskId: string;
+    attemptId: string;
+}
+/** List-view metadata for a task and its current attempt. */
+interface HarnessTaskSummary {
+    taskId: string;
+    attemptId: string;
+    appId: string;
+    env: string;
+    title: string;
+    prompt: string;
+    workspace: string;
+    aiRoute: string;
+    status: HarnessTaskStatus;
+    parentAttemptId: string | null;
+    checkpointSeq: number | null;
+    runnerId: string | null;
+    generation: number;
+    createdAt: number;
+    updatedAt: number;
+}
+/** List-view metadata for one attempt, including retry ancestry and runner ownership. */
+interface HarnessAttemptSummary {
+    attemptId: string;
+    taskId: string;
+    parentAttemptId: string | null;
+    checkpointSeq: number | null;
+    status: HarnessAttemptStatus;
+    runnerId: string | null;
+    generation: number;
+    createdAt: number;
+    updatedAt: number;
+}
+/** Complete task view including attempts, events, result, and generated patch. */
+interface HarnessTaskDetail extends HarnessTaskSummary {
+    attempts: HarnessAttemptSummary[];
+    events: HarnessEvent[];
+    patch: string | null;
+    result: unknown;
+}
+/** Public control-plane view of a registered harness runner. */
+interface HarnessRunnerView {
+    runnerId: string;
+    appId: string;
+    env: string;
+    name: string;
+    createdAt: number;
+    lastSeenAt: number | null;
+    revokedAt: number | null;
+}
+/** Credential-free normalized model request sent from an agent through the runner. */
+interface HarnessInferenceRequest {
+    requestId: string;
+    /** Exact initial, follow-up, or resume command whose budget this call consumes. */
+    interactionId?: string;
+    call: ChatInput;
+}
+/** Normalized model response plus auditable provider, policy, and token metadata. */
+interface HarnessInferenceResponse {
+    requestId: string;
+    response: OracleResponse;
+    receipt: {
+        provider: string;
+        model: string;
+        policyVersion: number;
+        inputTokens: number;
+        outputTokens: number;
+    };
+}
+/** Bounded, content-free session activity emitted by a Code runtime. Message
+ * bodies are projected separately into the app's owner-private odla-db chat. */
+type CodeSessionEventData = {
+    type: "message";
+    actor: "agent" | "system";
+    body: string;
+} | {
+    type: "diagnostic";
+    level: "error";
+    message: string;
+} | {
+    type: "thinking";
+    available: true;
+    durationMs: number;
+} | {
+    type: "tool";
+    phase: "started";
+    tool: HarnessToolName;
+} | {
+    type: "tool";
+    phase: "completed";
+    tool: HarnessToolName;
+    ok: boolean;
+    durationMs: number;
+} | {
+    type: "usage";
+    provider: string;
+    model: string;
+    inputTokens: number;
+    outputTokens: number;
+    durationMs: number;
+    interactionId?: string;
+    interactionTokens?: number;
+    interactionMaxTokens?: number;
+} | {
+    type: "status";
+    status: "running" | "idle" | "failed" | "checkpointed";
+    durationMs?: number;
+};
+/** Registry-assigned cursor and timestamp for an owner-visible Code event. */
+type CodeSessionEvent = CodeSessionEventData & {
+    eventId: string;
+    sequence: number;
+    createdAt: number;
+};
+/** Closed set of effects an agent container may request from its trusted broker. */
+type HarnessToolName = "sandbox.read" | "sandbox.apply_patch" | "sandbox.run_recipe";
+/** Correlated, structured tool request emitted by an untrusted agent container. */
+interface HarnessToolRequest {
+    requestId: string;
+    tool: HarnessToolName;
+    input: Record<string, unknown>;
+}
+/** Bounded tool result returned to an agent after trusted policy evaluation. */
+interface HarnessToolResponse {
+    requestId: string;
+    ok: boolean;
+    content: string;
+    details?: Record<string, unknown>;
+}
+/** Validated JSONL message emitted by an untrusted agent container. */
+type HarnessAgentOutput = {
+    protocolVersion: typeof HARNESS_PROTOCOL_VERSION;
+    type: "event";
+    kind: string;
+    payload?: unknown;
+} | {
+    protocolVersion: typeof HARNESS_PROTOCOL_VERSION;
+    type: "inference.request";
+    requestId: string;
+    call: ChatInput;
+} | ({
+    protocolVersion: typeof HARNESS_PROTOCOL_VERSION;
+    type: "tool.request";
+} & HarnessToolRequest) | {
+    protocolVersion: typeof HARNESS_PROTOCOL_VERSION;
+    type: "attempt.complete";
+    status: "completed" | "failed" | "cancelled";
+    result?: unknown;
+};
+/** JSONL command or inference result written by the trusted runner to an agent. */
+type HarnessAgentInput = {
+    protocolVersion: typeof HARNESS_PROTOCOL_VERSION;
+    type: "task.start";
+    task: HarnessTaskSpec;
+} | {
+    protocolVersion: typeof HARNESS_PROTOCOL_VERSION;
+    type: "inference.response";
+    requestId: string;
+    response: OracleResponse;
+} | ({
+    protocolVersion: typeof HARNESS_PROTOCOL_VERSION;
+    type: "tool.response";
+} & HarnessToolResponse) | {
+    protocolVersion: typeof HARNESS_PROTOCOL_VERSION;
+    type: "attempt.cancel";
+    reason: string;
+};
+/** Terminal attempt report submitted by a runner to the control plane. */
+interface HarnessCompletion {
+    status: "completed" | "failed" | "cancelled";
+    result?: unknown;
+    patch?: string;
+    error?: string;
+}
+/** Operations a credentialed runner may perform against the harness control plane. */
+interface HarnessControlPlane {
+    lease(workspaces: string[]): Promise<HarnessLease | null>;
+    heartbeat(attemptId: string, leaseId: string): Promise<{
+        cancelRequested: boolean;
+        expiresAt: number;
+    }>;
+    appendEvents(attemptId: string, leaseId: string, events: HarnessEventInput[]): Promise<void>;
+    infer(attemptId: string, leaseId: string, request: HarnessInferenceRequest): Promise<HarnessInferenceResponse>;
+    complete(attemptId: string, leaseId: string, completion: HarnessCompletion): Promise<void>;
+}
+/** Trusted inference bridge used to keep model credentials outside agent containers. */
+interface HarnessAiConnection {
+    infer(request: HarnessInferenceRequest): Promise<HarnessInferenceResponse>;
+}
+/** Trusted tool boundary. Implementations must evaluate CaMeL policy before effects. */
+interface HarnessToolBroker {
+    execute(context: {
+        lease: HarnessLease;
+        workspaceDir: string;
+        signal?: AbortSignal;
+    }, request: HarnessToolRequest): Promise<HarnessToolResponse>;
+}
+
+export { type CodeSessionEvent as C, DEFAULT_AI_ROUTE as D, type HarnessControlPlane as H, type HarnessLease as a, type HarnessEventInput as b, type HarnessCompletion as c, type HarnessInferenceRequest as d, type HarnessInferenceResponse as e, type HarnessAgentInput as f, type HarnessAgentOutput as g, type HarnessAiConnection as h, type CodeSessionEventData as i, HARNESS_PROTOCOL_VERSION as j, type HarnessActor as k, type HarnessAttemptStatus as l, type HarnessAttemptSummary as m, type HarnessEvent as n, type HarnessPolicy as o, type HarnessRunnerView as p, type HarnessTaskDetail as q, type HarnessTaskSpec as r, type HarnessTaskStatus as s, type HarnessTaskSummary as t, type HarnessToolBroker as u, type HarnessToolName as v, type HarnessToolRequest as w, type HarnessToolResponse as x };

package/package.json

@@ -0,0 +1,84 @@
+{
+  "name": "@odla-ai/harness",
+  "version": "0.1.0",
+  "description": "Safe, inspectable coding-task protocol and credentialless container runner for odla Studio.",
+  "license": "MIT",
+  "homepage": "https://odla.ai/docs/packages/harness",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/cory/odla-ai.git",
+    "directory": "packages/harness"
+  },
+  "type": "module",
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs"
+    },
+    "./node": {
+      "types": "./dist/node.d.ts",
+      "import": "./dist/node.js",
+      "require": "./dist/node.cjs"
+    },
+    "./testing": {
+      "types": "./dist/testing.d.ts",
+      "import": "./dist/testing.js",
+      "require": "./dist/testing.cjs"
+    }
+  },
+  "bin": {
+    "odla-harness": "./dist/cli.js",
+    "odla-code-runtime": "./dist/code-runtime-cli.js"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "sideEffects": false,
+  "engines": {
+    "node": ">=20"
+  },
+  "publishConfig": {
+    "access": "public",
+    "provenance": false
+  },
+  "keywords": [
+    "odla",
+    "odla-ai",
+    "coding-agent",
+    "container",
+    "sandbox",
+    "harness"
+  ],
+  "scripts": {
+    "build": "tsup",
+    "clean": "rm -rf dist",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "test:container": "ODLA_HARNESS_CONTAINER_TEST=1 vitest run test/container.integration.test.ts",
+    "prepublishOnly": "npm run test && npm run typecheck && npm run build"
+  },
+  "peerDependencies": {
+    "@odla-ai/ai": ">=0.4.0 <1.0.0"
+  },
+  "peerDependenciesMeta": {
+    "@odla-ai/ai": {
+      "optional": true
+    }
+  },
+  "dependencies": {
+    "@odla-ai/camel": "*"
+  },
+  "devDependencies": {
+    "@odla-ai/ai": "*",
+    "@types/node": "^26.1.0",
+    "tsup": "^8.5.1",
+    "typescript": "^6.0.3",
+    "vitest": "^4.1.9"
+  }
+}