@rarebit-one/harness-kernel 0.5.1

package/dist/models/registry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"registry.d.ts","sourceRoot":"","sources":["../../src/models/registry.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAA;AAEjD,OAAO,KAAK,EAAE,eAAe,EAAE,SAAS,EAAE,MAAM,YAAY,CAAA;AAE5D;;;;GAIG;AACH,MAAM,WAAW,QAAQ;IACvB,IAAI,EAAE,SAAS,CAAA;IACf,EAAE,EAAE,MAAM,CAAA;CACX;AAED,4EAA4E;AAC5E,MAAM,MAAM,YAAY,CAAC,GAAG,EAAE,GAAG,IAAI,MAAM,eAAe,CAAC,GAAG,EAAE,GAAG,CAAC,CAAA;AASpE,6EAA6E;AAC7E,MAAM,MAAM,YAAY,GAAG;IAAE,EAAE,EAAE,IAAI,CAAA;CAAE,GAAG;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAAA;AAEvE,kEAAkE;AAClE,qBAAa,iBAAkB,SAAQ,KAAK;IAC1C,QAAQ,CAAC,GAAG,EAAE,QAAQ,CAAA;gBAEV,GAAG,EAAE,QAAQ,EAAE,KAAK,EAAE,MAAM,EAAE;CAM3C;AAID;;;;;;;;;;;;GAYG;AACH,qBAAa,aAAa;IACxB,OAAO,CAAC,QAAQ,CAAC,SAAS,CAA4C;IACtE,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAmB;IAE9C;;;OAGG;IACH,QAAQ,CAAC,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,QAAQ,EAAE,OAAO,EAAE,YAAY,CAAC,GAAG,EAAE,GAAG,CAAC,GAAG,IAAI;IASxE,4EAA4E;IAC5E,gBAAgB,CAAC,GAAG,EAAE,GAAG,EAAE,KAAK,EAAE,eAAe,CAAC,GAAG,EAAE,GAAG,CAAC,GAAG,IAAI;IAIlE;;;;OAIG;IACH,GAAG,CAAC,GAAG,UAAU,EAAE,UAAU,EAAE,GAAG,IAAI;IAKtC,GAAG,CAAC,GAAG,EAAE,QAAQ,GAAG,OAAO;IAI3B,2EAA2E;IAC3E,QAAQ,CAAC,GAAG,EAAE,QAAQ,GAAG,YAAY;IAKrC;;;;;;;;;;;OAWG;IACH,OAAO,CAAC,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,QAAQ,GAAG,eAAe,CAAC,GAAG,EAAE,GAAG,CAAC;IAO3D,oDAAoD;IACpD,KAAK,IAAI,SAAS,EAAE;IASpB,yCAAyC;IACzC,GAAG,CAAC,IAAI,EAAE,SAAS,GAAG,MAAM,EAAE;IAO9B,mEAAmE;IACnE,UAAU,IAAI,MAAM,EAAE;CAGvB"}

package/dist/models/registry.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"registry.js","sourceRoot":"","sources":["../../src/models/registry.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,cAAc,EAAE,MAAM,iBAAiB,CAAA;AA0BhD,kEAAkE;AAClE,MAAM,OAAO,iBAAkB,SAAQ,KAAK;IACjC,GAAG,CAAU;IAEtB,YAAY,GAAa,EAAE,KAAe;QACxC,MAAM,YAAY,GAAG,KAAK,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,sBAAsB,CAAA;QACjF,KAAK,CAAC,2BAA2B,GAAG,CAAC,IAAI,IAAI,GAAG,CAAC,EAAE,kBAAkB,YAAY,EAAE,CAAC,CAAA;QACpF,IAAI,CAAC,IAAI,GAAG,mBAAmB,CAAA;QAC/B,IAAI,CAAC,GAAG,GAAG,GAAG,CAAA;IAChB,CAAC;CACF;AAED,MAAM,GAAG,GAAG,CAAC,GAAa,EAAU,EAAE,CAAC,GAAG,GAAG,CAAC,IAAI,IAAI,GAAG,CAAC,EAAE,EAAE,CAAA;AAE9D;;;;;;;;;;;;GAYG;AACH,MAAM,OAAO,aAAa;IACP,SAAS,GAAG,IAAI,GAAG,EAAkC,CAAA;IACrD,UAAU,GAAiB,EAAE,CAAA;IAE9C;;;OAGG;IACH,QAAQ,CAAW,GAAa,EAAE,OAA+B;QAC/D,MAAM,CAAC,GAAG,GAAG,CAAC,GAAG,CAAC,CAAA;QAClB,IAAI,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC;YAC1B,MAAM,IAAI,KAAK,CAAC,gCAAgC,GAAG,CAAC,IAAI,IAAI,GAAG,CAAC,EAAE,EAAE,CAAC,CAAA;QACvE,CAAC;QACD,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,CAAC,EAAE,OAAO,CAAC,CAAA;QAC9B,OAAO,IAAI,CAAA;IACb,CAAC;IAED,4EAA4E;IAC5E,gBAAgB,CAAW,KAAgC;QACzD,OAAO,IAAI,CAAC,QAAQ,CAAC,EAAE,IAAI,EAAE,KAAK,CAAC,IAAI,EAAE,EAAE,EAAE,KAAK,CAAC,EAAE,EAAE,EAAE,GAAG,EAAE,CAAC,KAAK,CAAC,CAAA;IACvE,CAAC;IAED;;;;OAIG;IACH,GAAG,CAAC,GAAG,UAAwB;QAC7B,IAAI,CAAC,UAAU,CAAC,IAAI,CAAC,GAAG,UAAU,CAAC,CAAA;QACnC,OAAO,IAAI,CAAA;IACb,CAAC;IAED,GAAG,CAAC,GAAa;QACf,OAAO,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC,CAAA;IACrC,CAAC;IAED,2EAA2E;IAC3E,QAAQ,CAAC,GAAa;QACpB,IAAI,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC;YAAE,OAAO,EAAE,EAAE,EAAE,IAAI,EAAE,CAAA;QACtC,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,MAAM,EAAE,IAAI,iBAAiB,CAAC,GAAG,EAAE,IAAI,CAAC,UAAU,EAAE,CAAC,CAAC,OAAO,EAAE,CAAA;IACrF,CAAC;IAED;;;;;;;;;;;OAWG;IACH,OAAO,CAAW,GAAa;QAC7B,MAAM,OAAO,GAAG,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC,CAAA;QAC5C,IAAI,CAAC,OAAO;YAAE,MAAM,IAAI,iBAAiB,CAAC,GAAG,EAAE,IAAI,CAAC,UAAU,EAAE,CAAC,CAAA;QACjE,MAAM,KAAK,GAAG,OAAO,EAA0C,CAAA;QAC/D,OAAO,IAAI,CAAC,UAAU,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,cAAc,CAAC,KAAK,EAAE,IAAI,CAAC,UAAU,CAAC,CAAC,CAAC,CAAC,KAAK,CAAA;IACpF,CAAC;IAED,oDAAoD;IACpD,KAAK;QACH,MAAM,IAAI,GAAG,IAAI,GAAG,EAAa,CAAA;QACjC,KAAK,MAAM,CAAC,IAAI,IAAI,CAAC,SAAS,CAAC,IAAI,EAAE,EAAE,CAAC;YACtC,MAAM,IAAI,GAAG,CAAC,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAA;YAC5B,IAAI,IAAI,KAAK,SAAS;gBAAE,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,CAAA;QACxC,CAAC;QACD,OAAO,CAAC,GAAG,IAAI,CAAC,CAAA;IAClB,CAAC;IAED,yCAAyC;IACzC,GAAG,CAAC,IAAe;QACjB,MAAM,MAAM,GAAG,GAAG,IAAI,GAAG,CAAA;QACzB,OAAO,CAAC,GAAG,IAAI,CAAC,SAAS,CAAC,IAAI,EAAE,CAAC;aAC9B,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,UAAU,CAAC,MAAM,CAAC,CAAC;aACnC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,KAAK,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC,CAAA;IACvC,CAAC;IAED,mEAAmE;IACnE,UAAU;QACR,OAAO,CAAC,GAAG,IAAI,CAAC,SAAS,CAAC,IAAI,EAAE,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,OAAO,CAAC,GAAG,EAAE,GAAG,CAAC,CAAC,CAAA;IACnE,CAAC;CACF"}

package/dist/models/types.d.ts

@@ -0,0 +1,149 @@
+/**
+ * The neutral model-invocation seam.
+ *
+ * A chat LLM is not the only kind of model a harness calls. Object detection,
+ * speech recognition and forecasting are all "hand a model a request, get a
+ * typed result" — they differ in payload, not in shape. So this seam unifies the
+ * **arrow and the envelope** (`invoke`, {@link ModelResult}, {@link InvokeContext},
+ * {@link ModelCaps}, `probe`) and deliberately leaves `Req`/`Res` **generic per
+ * kind**.
+ *
+ * That generic-per-kind rule is load-bearing. Collapsing a chat request and an
+ * image buffer into one `unknown` payload would erase exactly the typing that
+ * makes a `DetectionResult` or a `ForecastResult` worth having. A kind declares
+ * its own request and result types; the seam only guarantees how they travel.
+ */
+/**
+ * What a model does. The listed kinds are conventions, not a closed set — an
+ * application registers whatever kinds it needs, and the `(string & {})` arm
+ * keeps editor completion for the common ones without restricting the type.
+ */
+export type ModelKind = "chat" | "vision.detect" | "audio.asr" | "timeseries.forecast" | (string & {});
+/**
+ * What an invocation can actually do. Declared by the implementation and
+ * **checked** at the call site: asking for an unsupported capability fails loud
+ * rather than silently degrading to a lesser path.
+ */
+export interface ModelCaps {
+    /** `invokeStream` is implemented and may be called. */
+    streaming: boolean;
+    /** The request may carry tool definitions and the result may carry tool calls. */
+    tools: boolean;
+    /** The request may carry image/audio/binary parts. */
+    multimodalInput: boolean;
+    /** Results carry a populated `usage`. */
+    usage: boolean;
+}
+/** Token accounting, for kinds billed per token. */
+export interface TokenUsage {
+    inputTokens?: number;
+    outputTokens?: number;
+    totalTokens?: number;
+}
+/**
+ * Accounting for kinds that aren't billed per token — frames processed, seconds
+ * of audio, rows forecast. A perception call's "usage" is the same idea in a
+ * different unit, which is why the envelope carries both shapes.
+ */
+export interface UnitUsage {
+    units: number;
+    /** What the units are (e.g. "frames", "seconds"). Free-form. */
+    unit?: string;
+}
+export type Usage = TokenUsage | UnitUsage;
+/** The uniform envelope every invocation returns, whatever its kind. */
+export interface ModelResult<Res> {
+    /** The typed result. Its shape is the kind's contract. */
+    value: Res;
+    /** Cost/consumption, when the implementation reports it (`caps.usage`). */
+    usage?: Usage;
+    /** Implementation-specific detail — latency, model revision, cache hits. */
+    meta?: Record<string, unknown>;
+}
+/**
+ * Ambient per-call context. Carries the concerns that are cross-cutting rather
+ * than payload-specific, so middleware can act on them uniformly across kinds.
+ */
+export interface InvokeContext {
+    /** Append a line to the caller's run log. */
+    log: (line: string) => void;
+    /** Cooperative cancellation. Implementations should honour it where they can. */
+    signal?: AbortSignal;
+    /** Ties this call to a wider trace. Middleware propagates it. */
+    correlationId?: string;
+    /** Wall-clock budget for this single call. */
+    budget?: {
+        maxDurationMs?: number;
+    };
+}
+export type HealthStatus = "up" | "down" | "degraded" | "unknown";
+/** The outcome of a {@link ModelInvocation.probe}. */
+export interface Health {
+    status: HealthStatus;
+    /** Human-readable explanation, especially for `down`/`degraded`/`unknown`. */
+    detail?: string;
+    meta?: Record<string, unknown>;
+}
+/**
+ * The normalized streaming event stream. Every implementation emits the same
+ * three-event sequence per tool call — `onToolCallStart`, one or more
+ * `onToolCallDelta`, then `onToolCallComplete` — even when the underlying API
+ * delivers arguments in one piece. Consumers therefore write one handler, not
+ * one per provider. Every handler is optional; a sink may care only about text.
+ */
+export interface StreamSink {
+    onTextDelta?: (delta: string) => void;
+    onToolCallStart?: (toolCallId: string, toolName: string) => void;
+    onToolCallDelta?: (toolCallId: string, argumentsDelta: string) => void;
+    onToolCallComplete?: (toolCallId: string, toolName: string, args: string) => void;
+}
+/**
+ * Emit the canonical three-event sequence for a tool call whose arguments
+ * arrived whole. Implementations backed by an API that doesn't stream argument
+ * fragments call this so their output is indistinguishable from one that does.
+ */
+export declare function emitCompleteToolCall(sink: StreamSink, toolCallId: string, toolName: string, args: string): void;
+/**
+ * One callable model capability. `Req` and `Res` belong to the kind: the chat
+ * kind's `Req` carries messages and tools and its `Res` carries tool calls;
+ * a `vision.detect` kind's `Req` is an image reference and its `Res` is a
+ * detection struct with `caps.tools === false`.
+ */
+export interface ModelInvocation<Req, Res> {
+    /** Identifies the concrete model within its kind (cf. a provider's name). */
+    readonly id: string;
+    readonly kind: ModelKind;
+    readonly caps: ModelCaps;
+    invoke(req: Req, ctx: InvokeContext): Promise<ModelResult<Res>>;
+    /** Present only when `caps.streaming`. Use {@link invokeStreaming} to call it safely. */
+    invokeStream?(req: Req, sink: StreamSink, ctx: InvokeContext): Promise<ModelResult<Res>>;
+    probe(): Promise<Health>;
+}
+/** The identity of an invocation, without its payload types — what middleware sees. */
+export interface ModelIdentity {
+    id: string;
+    kind: ModelKind;
+    caps: ModelCaps;
+}
+/** Narrow a {@link ModelInvocation} to its identity. */
+export declare function modelIdentity(model: ModelInvocation<never, unknown>): ModelIdentity;
+/**
+ * Thrown when a call asks for something the invocation declared it cannot do.
+ * The kernel never silently degrades — a caller that asked to stream and got a
+ * buffered response back would have no way to notice.
+ */
+export declare class CapabilityError extends Error {
+    readonly model: ModelIdentity;
+    readonly capability: keyof ModelCaps;
+    constructor(model: ModelIdentity, capability: keyof ModelCaps, detail?: string);
+}
+/** Assert a capability before relying on it, failing loud when it's absent. */
+export declare function requireCapability(model: ModelIdentity, capability: keyof ModelCaps, detail?: string): void;
+/**
+ * Stream an invocation, enforcing the capability gate. Fails loud when the
+ * model declared `streaming: false` or left `invokeStream` unimplemented —
+ * never falls back to the buffered path, because a caller that wanted deltas
+ * would otherwise get none and be unable to tell.
+ */
+export declare function invokeStreaming<Req, Res>(model: ModelInvocation<Req, Res>, req: Req, sink: StreamSink, ctx: InvokeContext): Promise<ModelResult<Res>>;
+//# sourceMappingURL=types.d.ts.map

package/dist/models/types.d.ts.map

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

package/dist/models/types.js

@@ -0,0 +1,64 @@
+/**
+ * The neutral model-invocation seam.
+ *
+ * A chat LLM is not the only kind of model a harness calls. Object detection,
+ * speech recognition and forecasting are all "hand a model a request, get a
+ * typed result" — they differ in payload, not in shape. So this seam unifies the
+ * **arrow and the envelope** (`invoke`, {@link ModelResult}, {@link InvokeContext},
+ * {@link ModelCaps}, `probe`) and deliberately leaves `Req`/`Res` **generic per
+ * kind**.
+ *
+ * That generic-per-kind rule is load-bearing. Collapsing a chat request and an
+ * image buffer into one `unknown` payload would erase exactly the typing that
+ * makes a `DetectionResult` or a `ForecastResult` worth having. A kind declares
+ * its own request and result types; the seam only guarantees how they travel.
+ */
+/**
+ * Emit the canonical three-event sequence for a tool call whose arguments
+ * arrived whole. Implementations backed by an API that doesn't stream argument
+ * fragments call this so their output is indistinguishable from one that does.
+ */
+export function emitCompleteToolCall(sink, toolCallId, toolName, args) {
+    sink.onToolCallStart?.(toolCallId, toolName);
+    sink.onToolCallDelta?.(toolCallId, args);
+    sink.onToolCallComplete?.(toolCallId, toolName, args);
+}
+/** Narrow a {@link ModelInvocation} to its identity. */
+export function modelIdentity(model) {
+    return { id: model.id, kind: model.kind, caps: model.caps };
+}
+/**
+ * Thrown when a call asks for something the invocation declared it cannot do.
+ * The kernel never silently degrades — a caller that asked to stream and got a
+ * buffered response back would have no way to notice.
+ */
+export class CapabilityError extends Error {
+    model;
+    capability;
+    constructor(model, capability, detail) {
+        super(`model ${model.kind}:${model.id} does not support ${capability}${detail ? ` (${detail})` : ""}`);
+        this.name = "CapabilityError";
+        this.model = model;
+        this.capability = capability;
+    }
+}
+/** Assert a capability before relying on it, failing loud when it's absent. */
+export function requireCapability(model, capability, detail) {
+    if (!model.caps[capability])
+        throw new CapabilityError(model, capability, detail);
+}
+/**
+ * Stream an invocation, enforcing the capability gate. Fails loud when the
+ * model declared `streaming: false` or left `invokeStream` unimplemented —
+ * never falls back to the buffered path, because a caller that wanted deltas
+ * would otherwise get none and be unable to tell.
+ */
+export async function invokeStreaming(model, req, sink, ctx) {
+    const identity = modelIdentity(model);
+    requireCapability(identity, "streaming");
+    if (!model.invokeStream) {
+        throw new CapabilityError(identity, "streaming", "declared streaming but has no invokeStream");
+    }
+    return model.invokeStream(req, sink, ctx);
+}
+//# sourceMappingURL=types.js.map

package/dist/models/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/models/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AA+FH;;;;GAIG;AACH,MAAM,UAAU,oBAAoB,CAClC,IAAgB,EAChB,UAAkB,EAClB,QAAgB,EAChB,IAAY;IAEZ,IAAI,CAAC,eAAe,EAAE,CAAC,UAAU,EAAE,QAAQ,CAAC,CAAA;IAC5C,IAAI,CAAC,eAAe,EAAE,CAAC,UAAU,EAAE,IAAI,CAAC,CAAA;IACxC,IAAI,CAAC,kBAAkB,EAAE,CAAC,UAAU,EAAE,QAAQ,EAAE,IAAI,CAAC,CAAA;AACvD,CAAC;AA0BD,wDAAwD;AACxD,MAAM,UAAU,aAAa,CAAC,KAAsC;IAClE,OAAO,EAAE,EAAE,EAAE,KAAK,CAAC,EAAE,EAAE,IAAI,EAAE,KAAK,CAAC,IAAI,EAAE,IAAI,EAAE,KAAK,CAAC,IAAI,EAAE,CAAA;AAC7D,CAAC;AAED;;;;GAIG;AACH,MAAM,OAAO,eAAgB,SAAQ,KAAK;IAC/B,KAAK,CAAe;IACpB,UAAU,CAAiB;IAEpC,YAAY,KAAoB,EAAE,UAA2B,EAAE,MAAe;QAC5E,KAAK,CACH,SAAS,KAAK,CAAC,IAAI,IAAI,KAAK,CAAC,EAAE,qBAAqB,UAAU,GAAG,MAAM,CAAC,CAAC,CAAC,KAAK,MAAM,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAChG,CAAA;QACD,IAAI,CAAC,IAAI,GAAG,iBAAiB,CAAA;QAC7B,IAAI,CAAC,KAAK,GAAG,KAAK,CAAA;QAClB,IAAI,CAAC,UAAU,GAAG,UAAU,CAAA;IAC9B,CAAC;CACF;AAED,+EAA+E;AAC/E,MAAM,UAAU,iBAAiB,CAC/B,KAAoB,EACpB,UAA2B,EAC3B,MAAe;IAEf,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,UAAU,CAAC;QAAE,MAAM,IAAI,eAAe,CAAC,KAAK,EAAE,UAAU,EAAE,MAAM,CAAC,CAAA;AACnF,CAAC;AAED;;;;;GAKG;AACH,MAAM,CAAC,KAAK,UAAU,eAAe,CACnC,KAAgC,EAChC,GAAQ,EACR,IAAgB,EAChB,GAAkB;IAElB,MAAM,QAAQ,GAAG,aAAa,CAAC,KAAK,CAAC,CAAA;IACrC,iBAAiB,CAAC,QAAQ,EAAE,WAAW,CAAC,CAAA;IACxC,IAAI,CAAC,KAAK,CAAC,YAAY,EAAE,CAAC;QACxB,MAAM,IAAI,eAAe,CAAC,QAAQ,EAAE,WAAW,EAAE,4CAA4C,CAAC,CAAA;IAChG,CAAC;IACD,OAAO,KAAK,CAAC,YAAY,CAAC,GAAG,EAAE,IAAI,EAAE,GAAG,CAAC,CAAA;AAC3C,CAAC"}

package/dist/primitives/codeExec.d.ts

@@ -0,0 +1,25 @@
+export interface RunCodeOptions {
+    /** Working directory — normally the run sandbox. */
+    cwd: string;
+    command: string;
+    args?: string[];
+    /** Extra environment (e.g. secretsToEnv output). Merged over a minimal base. */
+    env?: NodeJS.ProcessEnv;
+    timeoutMs?: number;
+    stdin?: string;
+    maxBuffer?: number;
+}
+export interface RunCodeResult {
+    stdout: string;
+    stderr: string;
+    exitCode: number | null;
+    timedOut: boolean;
+}
+/**
+ * Run a command inside the sandbox. This is the general-purpose escape hatch the
+ * agent uses to run the workspace's OWN repo scripts — or code it writes on the
+ * fly — so domain logic lives in user code, never baked into the platform.
+ * Secrets are passed via `env` (see secretsToEnv) and are never logged here.
+ */
+export declare function runCode(options: RunCodeOptions): Promise<RunCodeResult>;
+//# sourceMappingURL=codeExec.d.ts.map

package/dist/primitives/codeExec.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"codeExec.d.ts","sourceRoot":"","sources":["../../src/primitives/codeExec.ts"],"names":[],"mappings":"AAEA,MAAM,WAAW,cAAc;IAC7B,oDAAoD;IACpD,GAAG,EAAE,MAAM,CAAA;IACX,OAAO,EAAE,MAAM,CAAA;IACf,IAAI,CAAC,EAAE,MAAM,EAAE,CAAA;IACf,gFAAgF;IAChF,GAAG,CAAC,EAAE,MAAM,CAAC,UAAU,CAAA;IACvB,SAAS,CAAC,EAAE,MAAM,CAAA;IAClB,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,SAAS,CAAC,EAAE,MAAM,CAAA;CACnB;AAED,MAAM,WAAW,aAAa;IAC5B,MAAM,EAAE,MAAM,CAAA;IACd,MAAM,EAAE,MAAM,CAAA;IACd,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAA;IACvB,QAAQ,EAAE,OAAO,CAAA;CAClB;AAKD;;;;;GAKG;AACH,wBAAgB,OAAO,CAAC,OAAO,EAAE,cAAc,GAAG,OAAO,CAAC,aAAa,CAAC,CAuEvE"}

package/dist/primitives/codeExec.js

@@ -0,0 +1,69 @@
+import { spawn } from "node:child_process";
+const DEFAULT_TIMEOUT_MS = 60_000;
+const DEFAULT_MAX_BUFFER = 8 * 1024 * 1024;
+/**
+ * Run a command inside the sandbox. This is the general-purpose escape hatch the
+ * agent uses to run the workspace's OWN repo scripts — or code it writes on the
+ * fly — so domain logic lives in user code, never baked into the platform.
+ * Secrets are passed via `env` (see secretsToEnv) and are never logged here.
+ */
+export function runCode(options) {
+    const { cwd, command, args = [], env, stdin, timeoutMs = DEFAULT_TIMEOUT_MS, maxBuffer = DEFAULT_MAX_BUFFER, } = options;
+    return new Promise((resolve, reject) => {
+        // A minimal base env with the caller's env — including resolved secrets —
+        // layered on top. We forward only non-secret runtime vars: PATH (so binaries
+        // resolve) and HOME (so npm/tooling use a stable cache dir — `$HOME/.npm`
+        // persists across runs on the warm pool, so a beat's `setup: [npm ci]` relinks
+        // instead of re-downloading). The runner's other env (tokens, provider keys)
+        // is deliberately NOT forwarded. `detached` puts the child in its own process
+        // group so the timeout can kill the WHOLE tree (a repo script that spawns
+        // subprocesses would otherwise orphan them).
+        const child = spawn(command, args, {
+            cwd,
+            env: { PATH: process.env.PATH, HOME: process.env.HOME, ...env },
+            detached: true,
+        });
+        let stdout = "";
+        let stderr = "";
+        let timedOut = false;
+        let settled = false;
+        const cap = (current, chunk) => current.length >= maxBuffer ? current : (current + chunk.toString()).slice(0, maxBuffer);
+        const killTree = () => {
+            try {
+                if (child.pid !== undefined)
+                    process.kill(-child.pid, "SIGKILL"); // negative pid = process group
+            }
+            catch {
+                child.kill("SIGKILL");
+            }
+        };
+        const timer = setTimeout(() => {
+            timedOut = true;
+            killTree();
+        }, timeoutMs);
+        child.stdout?.on("data", (c) => {
+            stdout = cap(stdout, c);
+        });
+        child.stderr?.on("data", (c) => {
+            stderr = cap(stderr, c);
+        });
+        child.on("error", (err) => {
+            if (settled)
+                return;
+            settled = true;
+            clearTimeout(timer);
+            reject(err);
+        });
+        child.on("close", (code) => {
+            if (settled)
+                return;
+            settled = true;
+            clearTimeout(timer);
+            resolve({ stdout, stderr, exitCode: code, timedOut });
+        });
+        if (stdin !== undefined)
+            child.stdin?.write(stdin);
+        child.stdin?.end();
+    });
+}
+//# sourceMappingURL=codeExec.js.map

package/dist/primitives/codeExec.js.map

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

package/dist/primitives/download.d.ts

@@ -0,0 +1,19 @@
+import { type Lookup } from "./http.js";
+export interface DownloadOptions {
+    maxBytes?: number;
+    timeoutMs?: number;
+    /** DNS resolver, injectable to test the SSRF guard without real DNS. */
+    lookup?: Lookup;
+}
+/**
+ * Download a (binary) URL to a file on disk, bounded by a byte cap and a timeout,
+ * with the same SSRF guard as httpFetch (internal hosts refused, every redirect
+ * hop re-validated). Unlike httpFetch this streams to disk — snapshot tarballs are
+ * binary and can be far larger than httpFetch's in-memory string cap. Used to fetch
+ * a run's snapshot `.tar.gz` from a presigned object-store URL (or, in local dev, a
+ * co-located `file://` URL).
+ *
+ * On any failure the partial file is removed and the error re-thrown.
+ */
+export declare function downloadToFile(url: string, destPath: string, opts?: DownloadOptions): Promise<void>;
+//# sourceMappingURL=download.d.ts.map

package/dist/primitives/download.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"download.d.ts","sourceRoot":"","sources":["../../src/primitives/download.ts"],"names":[],"mappings":"AAGA,OAAO,EAAiB,KAAK,MAAM,EAAE,MAAM,WAAW,CAAA;AAMtD,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB,SAAS,CAAC,EAAE,MAAM,CAAA;IAClB,wEAAwE;IACxE,MAAM,CAAC,EAAE,MAAM,CAAA;CAChB;AAYD;;;;;;;;;GASG;AACH,wBAAsB,cAAc,CAClC,GAAG,EAAE,MAAM,EACX,QAAQ,EAAE,MAAM,EAChB,IAAI,GAAE,eAAoB,GACzB,OAAO,CAAC,IAAI,CAAC,CAqFf"}

package/dist/primitives/download.js

@@ -0,0 +1,113 @@
+import { createWriteStream } from "node:fs";
+import { copyFile, rm } from "node:fs/promises";
+import { fileURLToPath } from "node:url";
+import { assertSafeUrl } from "./http.js";
+const FALLBACK_MAX_BYTES = 1024 * 1024 * 1024; // 1 GiB
+const FALLBACK_TIMEOUT_MS = 120_000;
+const MAX_REDIRECTS = 5;
+function defaultMaxBytes() {
+    const raw = Number(process.env.RUNNER_BUNDLE_MAX_BYTES);
+    return Number.isFinite(raw) && raw > 0 ? raw : FALLBACK_MAX_BYTES;
+}
+function defaultTimeoutMs() {
+    const raw = Number(process.env.RUNNER_BUNDLE_TIMEOUT_MS);
+    return Number.isFinite(raw) && raw > 0 ? raw : FALLBACK_TIMEOUT_MS;
+}
+/**
+ * Download a (binary) URL to a file on disk, bounded by a byte cap and a timeout,
+ * with the same SSRF guard as httpFetch (internal hosts refused, every redirect
+ * hop re-validated). Unlike httpFetch this streams to disk — snapshot tarballs are
+ * binary and can be far larger than httpFetch's in-memory string cap. Used to fetch
+ * a run's snapshot `.tar.gz` from a presigned object-store URL (or, in local dev, a
+ * co-located `file://` URL).
+ *
+ * On any failure the partial file is removed and the error re-thrown.
+ */
+export async function downloadToFile(url, destPath, opts = {}) {
+    // Local/dev handoff: the LocalAdapter object store hands a `file://` URL (the
+    // caller and the kernel are co-located on one machine). Copy it straight from
+    // disk — never through fetch/the SSRF guard. This reads an arbitrary local path, so
+    // it is OPT-IN via RUNNER_ALLOW_FILE_URLS (dev/test only); production uses https
+    // presigned URLs and leaves it off, so a misconfigured `file://` URL is refused.
+    if (url.startsWith("file://")) {
+        if (process.env.RUNNER_ALLOW_FILE_URLS !== "1") {
+            throw new Error("file:// URLs are disabled; set RUNNER_ALLOW_FILE_URLS=1 for local dev");
+        }
+        await copyFile(fileURLToPath(url), destPath);
+        return;
+    }
+    const maxBytes = opts.maxBytes ?? defaultMaxBytes();
+    const timeoutMs = opts.timeoutMs ?? defaultTimeoutMs();
+    const controller = new AbortController();
+    let timedOut = false;
+    const timer = setTimeout(() => {
+        timedOut = true;
+        controller.abort();
+    }, timeoutMs);
+    try {
+        // Follow redirects manually so each hop is re-validated against the SSRF guard.
+        // Private/VPC object stores (and the MinIO-backed load-test rig) hand out
+        // presigned URLs on hosts that resolve to private addresses, which the guard
+        // refuses. OPT-IN escape hatch in the spirit of RUNNER_ALLOW_FILE_URLS: skip
+        // the guard for the snapshot download only (byte cap, timeout, and redirect
+        // bounds still apply). Leave unset in production with a public object store.
+        // NOTE: when set, the skip DELIBERATELY applies to every hop, redirect
+        // targets included — once private hosts are trusted there is no meaningful
+        // boundary left for per-hop re-validation to defend. Don't "fix" that by
+        // reinstating per-hop checks under the flag; it would break private stores
+        // that redirect internally.
+        const allowPrivate = process.env.RUNNER_ALLOW_PRIVATE_BUNDLE_HOSTS === "1";
+        let current = url;
+        let res;
+        for (let hops = 0;; hops++) {
+            if (!allowPrivate)
+                await assertSafeUrl(current, { lookup: opts.lookup });
+            res = await fetch(current, { redirect: "manual", signal: controller.signal });
+            if (res.status >= 300 && res.status < 400 && res.headers.has("location")) {
+                if (hops >= MAX_REDIRECTS)
+                    throw new Error("too many redirects");
+                current = new URL(res.headers.get("location"), current).toString();
+                continue;
+            }
+            break;
+        }
+        if (res.status < 200 || res.status >= 300) {
+            throw new Error(`download failed: HTTP ${res.status} for ${url}`);
+        }
+        if (!res.body)
+            throw new Error(`download failed: empty body for ${url}`);
+        const out = createWriteStream(destPath);
+        // undici's ReadableStream types are non-generic, so the reader yields `any`;
+        // fetch response bodies are always byte streams.
+        const reader = res.body.getReader();
+        let total = 0;
+        try {
+            for (;;) {
+                const { done, value } = await reader.read();
+                if (done)
+                    break;
+                total += value.byteLength;
+                if (total > maxBytes) {
+                    await reader.cancel();
+                    throw new Error(`download exceeds ${maxBytes} bytes`);
+                }
+                await new Promise((resolve, reject) => {
+                    out.write(value, (err) => (err ? reject(err) : resolve()));
+                });
+            }
+        }
+        finally {
+            await new Promise((resolve, reject) => out.end((err) => (err ? reject(err) : resolve())));
+        }
+    }
+    catch (err) {
+        await rm(destPath, { force: true });
+        if (timedOut)
+            throw new Error(`download timeout after ${timeoutMs}ms: ${url}`, { cause: err });
+        throw err;
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}
+//# sourceMappingURL=download.js.map

package/dist/primitives/download.js.map

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

package/dist/primitives/fs.d.ts

@@ -0,0 +1,5 @@
+/** Read a UTF-8 file within the sandbox, or null if missing / not a file / too big / a symlink escape. */
+export declare function readFileSafe(dir: string, relPath: string, maxBytes?: number): Promise<string | null>;
+/** List files (recursively, `.git` excluded) under `relDir`, as sandbox-relative paths. */
+export declare function listFiles(dir: string, relDir?: string): Promise<string[]>;
+//# sourceMappingURL=fs.d.ts.map

package/dist/primitives/fs.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"fs.d.ts","sourceRoot":"","sources":["../../src/primitives/fs.ts"],"names":[],"mappings":"AAsBA,0GAA0G;AAC1G,wBAAsB,YAAY,CAChC,GAAG,EAAE,MAAM,EACX,OAAO,EAAE,MAAM,EACf,QAAQ,GAAE,MAA0B,GACnC,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAWxB;AAED,2FAA2F;AAC3F,wBAAsB,SAAS,CAAC,GAAG,EAAE,MAAM,EAAE,MAAM,SAAM,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC,CAqB5E"}

package/dist/primitives/fs.js

@@ -0,0 +1,59 @@
+import { readFile, readdir, stat, realpath } from "node:fs/promises";
+import path from "node:path";
+const DEFAULT_MAX_BYTES = 64 * 1024;
+/** Lexical guard: refuse a relative path that escapes the sandbox via `..`. */
+function resolveWithin(dir, relPath) {
+    const base = path.resolve(dir);
+    const target = path.resolve(base, relPath);
+    if (target !== base && !target.startsWith(base + path.sep)) {
+        throw new Error(`path escapes sandbox: ${relPath}`);
+    }
+    return target;
+}
+/** True if `target`'s real (symlink-resolved) path stays within the real base. */
+async function realWithin(base, target) {
+    const realBase = await realpath(base);
+    const real = await realpath(target);
+    return real === realBase || real.startsWith(realBase + path.sep);
+}
+/** Read a UTF-8 file within the sandbox, or null if missing / not a file / too big / a symlink escape. */
+export async function readFileSafe(dir, relPath, maxBytes = DEFAULT_MAX_BYTES) {
+    const target = resolveWithin(dir, relPath);
+    try {
+        // Resolve symlinks and re-check: a link inside the sandbox must not point out.
+        if (!(await realWithin(dir, target)))
+            return null;
+        const info = await stat(target);
+        if (!info.isFile() || info.size > maxBytes)
+            return null;
+        return await readFile(target, "utf8");
+    }
+    catch {
+        return null;
+    }
+}
+/** List files (recursively, `.git` excluded) under `relDir`, as sandbox-relative paths. */
+export async function listFiles(dir, relDir = ".") {
+    const base = path.resolve(dir);
+    const root = resolveWithin(dir, relDir);
+    const out = [];
+    async function walk(current) {
+        const entries = await readdir(current, { withFileTypes: true });
+        for (const entry of entries) {
+            const abs = path.join(current, entry.name);
+            if (entry.isSymbolicLink())
+                continue; // don't follow symlinks out of the sandbox
+            if (entry.isDirectory()) {
+                if (entry.name === ".git")
+                    continue;
+                await walk(abs);
+            }
+            else if (entry.isFile()) {
+                out.push(path.relative(base, abs));
+            }
+        }
+    }
+    await walk(root);
+    return out.sort();
+}
+//# sourceMappingURL=fs.js.map

package/dist/primitives/fs.js.map

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