@liy/agent-runner 0.1.0

package/dist/config.d.ts

@@ -0,0 +1,121 @@
+/**
+ * Default Sprite-local agent-runner configuration path.
+ *
+ * @public
+ */
+export declare const DEFAULT_AGENT_RUNNER_CONFIG_PATH = "/home/sprite/.config/mote/agent-runner.json";
+/**
+ * Harness protocol supported by the Sprite-local runner.
+ *
+ * @public
+ */
+export type AgentRunnerHarnessDriver = "codex-jsonl" | "pi-rpc";
+/**
+ * Reasoning budget accepted by harnesses with thinking controls.
+ *
+ * @public
+ */
+export type AgentRunnerThinking = "off" | "minimal" | "low" | "medium" | "high" | "xhigh";
+/**
+ * Runtime configuration for one Sprite-local harness profile.
+ *
+ * @public
+ */
+export interface AgentRunnerHarnessConfig {
+    /**
+     * Harness driver id used by the runner.
+     */
+    driver: AgentRunnerHarnessDriver;
+    /**
+     * Executable name or absolute command path available inside the Sprite.
+     */
+    command: string;
+    /**
+     * Static arguments supplied before runner-generated prompt/spec arguments.
+     */
+    args?: string[];
+    /**
+     * Optional provider name for harnesses that route provider and model separately.
+     */
+    provider?: string;
+    /**
+     * Harness-local model used when the task spec does not select one.
+     */
+    defaultModel?: string;
+    /**
+     * Optional reasoning budget passed to harnesses with explicit thinking controls.
+     */
+    thinking?: AgentRunnerThinking;
+    /**
+     * Secret environment variables required by this harness profile.
+     */
+    secretEnv?: string[];
+}
+/**
+ * Sprite-local runner configuration.
+ *
+ * @public
+ */
+export interface AgentRunnerConfig {
+    /**
+     * Harness profile used when the task spec does not select one.
+     */
+    defaultHarness: string;
+    /**
+     * Harness profiles keyed by host-selectable name.
+     */
+    harnesses: Record<string, AgentRunnerHarnessConfig>;
+}
+/**
+ * Resolved harness config after applying task-level host selection.
+ *
+ * @public
+ */
+export interface ResolvedAgentRunnerHarnessConfig extends AgentRunnerHarnessConfig {
+    /**
+     * Selected harness profile name.
+     */
+    name: string;
+    /**
+     * Resolved model id after task-level override and harness default fallback.
+     */
+    model?: string;
+}
+/**
+ * Host-selected runner values accepted from task specs.
+ *
+ * @public
+ */
+export interface AgentRunnerSelection {
+    harness?: string;
+    model?: string;
+}
+/**
+ * Read and validate the Sprite-local runner config file.
+ *
+ * @param path - Config path; defaults to the Sprite baseline location.
+ * @returns Normalized runner config.
+ *
+ * @public
+ */
+export declare function readAgentRunnerConfig(path?: string): Promise<AgentRunnerConfig>;
+/**
+ * Parse and validate runner config JSON.
+ *
+ * @param source - Raw JSON config source.
+ * @param sourceName - Human-readable source used in errors.
+ * @returns Normalized runner config.
+ *
+ * @public
+ */
+export declare function parseAgentRunnerConfig(source: string, sourceName?: string): AgentRunnerConfig;
+/**
+ * Resolve one task's harness using runner config defaults.
+ *
+ * @param config - Validated runner config.
+ * @param selection - Optional host-selected harness and model.
+ * @returns Resolved harness config for driver launch.
+ *
+ * @public
+ */
+export declare function resolveAgentRunnerHarness(config: AgentRunnerConfig, selection: AgentRunnerSelection | undefined): ResolvedAgentRunnerHarnessConfig;

package/dist/harness-drivers/codex-jsonl.d.ts

@@ -0,0 +1,10 @@
+import type { HarnessSpawn, TaskAgentHarnessDriver } from "./types.js";
+/**
+ * Create the Codex JSONL driver adapter.
+ *
+ * @param spawnProcess - Optional subprocess factory used by tests.
+ * @returns Harness driver preserving the existing Codex JSONL behavior.
+ *
+ * @public
+ */
+export declare function createCodexJsonlHarnessDriver(spawnProcess?: HarnessSpawn): TaskAgentHarnessDriver;

package/dist/harness-drivers/pi-rpc.d.ts

@@ -0,0 +1,20 @@
+import type { ResolvedAgentRunnerHarnessConfig } from "../config.js";
+import type { HarnessSpawn, TaskAgentHarnessDriver } from "./types.js";
+/**
+ * Create the Pi RPC driver adapter.
+ *
+ * @param spawnProcess - Optional subprocess factory used by tests.
+ * @returns Harness driver that owns Pi RPC protocol framing and lifecycle.
+ *
+ * @public
+ */
+export declare function createPiRpcHarnessDriver(spawnProcess?: HarnessSpawn): TaskAgentHarnessDriver;
+/**
+ * Build Pi RPC command arguments from a harness config.
+ *
+ * @param harness - Pi RPC harness configuration.
+ * @returns Complete Pi command arguments owned by the driver.
+ *
+ * @public
+ */
+export declare function buildPiRpcArgs(harness: ResolvedAgentRunnerHarnessConfig): string[];

package/dist/harness-drivers/shared.d.ts

@@ -0,0 +1,98 @@
+import type { Readable } from "node:stream";
+import type { ControlChannel, HarnessChildProcess, HarnessProcessResult } from "./types.js";
+/**
+ * Text and JSON redactor for harness process output.
+ *
+ * @public
+ */
+export interface HarnessOutputSanitizer {
+    /**
+     * Redact sensitive env names and secret values from text.
+     *
+     * @param text - Raw harness output.
+     * @returns Redacted output safe for control-channel forwarding.
+     */
+    redactText(text: string): string;
+    /**
+     * Redact sensitive strings recursively inside a JSON-compatible value.
+     *
+     * @param value - Parsed JSON payload.
+     * @returns Redacted JSON-compatible payload.
+     */
+    redactJson(value: unknown): unknown;
+}
+/**
+ * Create an output sanitizer from the child-process environment.
+ *
+ * @param env - Environment passed to the harness subprocess.
+ * @param extraSensitiveNames - Explicit env names to redact even when absent.
+ * @returns Output redactor for text and parsed JSON values.
+ *
+ * @public
+ */
+export declare function createHarnessOutputSanitizer(env: Record<string, string>, extraSensitiveNames?: string[]): HarnessOutputSanitizer;
+/**
+ * Byte-buffer JSONL parser that only treats LF as a record delimiter.
+ *
+ * @public
+ */
+export declare class JsonlByteBufferParser {
+    private readonly decoder;
+    private buffer;
+    /**
+     * Push one stream chunk into the parser.
+     *
+     * @param chunk - Buffer or string chunk from a stream.
+     * @param onLine - Callback invoked for each full JSONL record.
+     */
+    push(chunk: Buffer | string, onLine: (line: string) => void): void;
+    /**
+     * Flush decoder state at stream end.
+     *
+     * @param onLine - Callback invoked for a trailing unterminated record.
+     */
+    end(onLine: (line: string) => void): void;
+    private drain;
+}
+/**
+ * Attach the protocol-compliant JSONL byte parser to a stream.
+ *
+ * @param stream - Subprocess output stream.
+ * @param onLine - Callback invoked for each complete line.
+ * @returns Promise resolved when the stream ends.
+ */
+export declare function forwardJsonlByteStream(stream: Readable, onLine: (line: string) => void): Promise<void>;
+/**
+ * Forward one generic harness output line as JSON progress or text log.
+ *
+ * @param channel - Connected control channel.
+ * @param line - Raw harness output line.
+ * @param streamName - Source stream name.
+ * @param sanitizer - Output sanitizer.
+ * @param driver - Optional driver id to include in forwarded payloads.
+ */
+export declare function forwardHarnessLine(channel: ControlChannel, line: string, streamName: "stdout" | "stderr", sanitizer: HarnessOutputSanitizer, driver?: string): void;
+/**
+ * Wait for one child process to close.
+ *
+ * @param child - Harness subprocess.
+ * @returns Child close result.
+ */
+export declare function waitForChildClose(child: HarnessChildProcess): Promise<HarnessProcessResult>;
+/**
+ * Terminate a child process with SIGTERM and delayed SIGKILL fallback.
+ *
+ * @param child - Harness subprocess.
+ * @param killAfterMs - Milliseconds before SIGKILL fallback.
+ * @returns Cleanup function that cancels the fallback timer.
+ *
+ * @public
+ */
+export declare function terminateChildProcess(child: HarnessChildProcess, killAfterMs?: number): () => void;
+/**
+ * Format a harness exit result for diagnostics.
+ *
+ * @param result - Child process result.
+ * @returns Human-readable exit description.
+ */
+export declare function formatHarnessExit(result: HarnessProcessResult): string;

package/dist/harness-drivers/types.d.ts

@@ -0,0 +1,144 @@
+import type { ExecuteTaskRpcMessage, ExecuteTaskRunnerSpec } from "@liy/mote-core";
+import type { Readable, Writable } from "node:stream";
+import type { ResolvedAgentRunnerHarnessConfig } from "../config.js";
+/**
+ * Minimal Task Control Channel surface used by runner orchestration.
+ *
+ * @public
+ */
+export interface ControlChannel {
+    /**
+     * Send one JSON-RPC message to the host.
+     *
+     * @param message - Control-channel message to serialize and send.
+     */
+    send(message: ExecuteTaskRpcMessage): void;
+    /**
+     * Close the underlying channel.
+     */
+    close(): void;
+    /**
+     * Subscribe to host-originated control messages.
+     *
+     * @param handler - Callback invoked for each validated control message.
+     */
+    onControlMessage(handler: (message: ExecuteTaskRpcMessage) => void): void;
+}
+/**
+ * Result of one harness subprocess invocation.
+ *
+ * @public
+ */
+export interface HarnessProcessResult {
+    /**
+     * Child process exit code when the process closed.
+     */
+    exitCode: number | null;
+    /**
+     * Child process signal when the process closed due to a signal.
+     */
+    signal: NodeJS.Signals | null;
+    /**
+     * Terminal condition that let the runner continue to completion validation.
+     */
+    completedBy: "agent-end" | "process-close";
+}
+/**
+ * Child process surface used by harness drivers and fake-process tests.
+ */
+export interface HarnessChildProcess {
+    /**
+     * Writable subprocess stdin.
+     */
+    stdin: Writable;
+    /**
+     * Readable subprocess stdout.
+     */
+    stdout: Readable;
+    /**
+     * Readable subprocess stderr.
+     */
+    stderr: Readable;
+    /**
+     * Exit code once known.
+     */
+    exitCode: number | null;
+    /**
+     * Exit signal once known.
+     */
+    signalCode: NodeJS.Signals | null;
+    /**
+     * Send a signal to the subprocess.
+     *
+     * @param signal - Signal name to send.
+     * @returns Whether Node accepted the signal request.
+     */
+    kill(signal?: NodeJS.Signals): boolean;
+    /**
+     * Subscribe to a child process event.
+     *
+     * @param event - Event name.
+     * @param listener - Event callback.
+     * @returns This child process.
+     */
+    once(event: "error", listener: (error: Error) => void): this;
+    once(event: "close", listener: (exitCode: number | null, signal: NodeJS.Signals | null) => void): this;
+}
+/**
+ * Dependency-injected process spawn function used by driver tests.
+ */
+export type HarnessSpawn = (command: string, args: string[], options: {
+    cwd: string;
+    env: Record<string, string>;
+    stdio: ["pipe", "pipe", "pipe"];
+}) => HarnessChildProcess;
+/**
+ * Common input passed from runner orchestration into one harness driver.
+ */
+export interface HarnessDriverInput {
+    /**
+     * Fully validated task runner spec.
+     */
+    spec: ExecuteTaskRunnerSpec;
+    /**
+     * Resolved Sprite-local harness config for this task.
+     */
+    harness: ResolvedAgentRunnerHarnessConfig;
+    /**
+     * Connected task-control channel.
+     */
+    channel: ControlChannel;
+    /**
+     * Mote task prompt written through the provider-specific harness protocol.
+     */
+    prompt: string;
+    /**
+     * Sanitized child process environment.
+     */
+    env: Record<string, string>;
+}
+/**
+ * Handle for an active harness subprocess run.
+ */
+export interface HarnessDriverRun {
+    /**
+     * Terminal process result promise.
+     */
+    result: Promise<HarnessProcessResult>;
+    /**
+     * Cancel the active harness run.
+     */
+    cancel(): void;
+}
+/**
+ * Driver adapter for one harness protocol.
+ */
+export interface TaskAgentHarnessDriver {
+    /**
+     * Start the harness subprocess.
+     *
+     * @param input - Validated runner spec, prompt, environment, and control channel.
+     * @returns Active run handle.
+     */
+    start(input: HarnessDriverInput): HarnessDriverRun;
+}

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+export * from "./config.js";
+export * from "./runtime.js";
+export * from "./runner.js";