@liy/agent-runner 0.1.0

package/dist/runner.d.ts

@@ -0,0 +1,76 @@
+import { type ExecuteTaskCompletionPayload, type ExecuteTaskRunnerSpec } from "@liy/mote-core";
+import { type AgentRunnerConfig, type ResolvedAgentRunnerHarnessConfig } from "./config.js";
+/**
+ * Optional runtime inputs for one agent-runner invocation.
+ *
+ * @public
+ */
+export interface RunTaskAgentRunnerOptions {
+    /**
+     * Already-loaded runner config, primarily used by tests.
+     */
+    config?: AgentRunnerConfig;
+    /**
+     * Config path used when `config` is not supplied.
+     */
+    configPath?: string;
+    /**
+     * Process environment inherited by the runner.
+     */
+    env?: NodeJS.ProcessEnv;
+}
+/**
+ * Run the Sprite Task Agent harness described by one task spec.
+ *
+ * @param spec - Host-authored task spec from `state/task-spec.json`.
+ * @returns Validated terminal completion payload.
+ *
+ * @public
+ */
+export declare function runTaskAgentRunner(spec: ExecuteTaskRunnerSpec, options?: RunTaskAgentRunnerOptions): Promise<ExecuteTaskCompletionPayload>;
+/**
+ * Create the child process environment for Codex/Pi harness commands.
+ *
+ * @remarks
+ * The harness receives configured model/tool endpoints and task workspace
+ * paths. Host credentials, DB credentials, Sprite tokens, and object storage
+ * credentials are deliberately omitted. A selected harness may declare the
+ * specific secret env vars it requires; those values must never be logged,
+ * persisted, or written to artifacts.
+ *
+ * @param input - Spec and inherited runner environment.
+ * @returns Sanitized harness process environment.
+ *
+ * @public
+ */
+export declare function createHarnessEnvironment(input: {
+    spec: ExecuteTaskRunnerSpec;
+    harness: ResolvedAgentRunnerHarnessConfig;
+    env?: NodeJS.ProcessEnv;
+}): Record<string, string>;
+/**
+ * Build the instruction prompt passed to the selected JSONL harness.
+ *
+ * @param spec - Task spec for one task.
+ * @returns Prompt text sent to harness stdin.
+ *
+ * @public
+ */
+export declare function buildHarnessPrompt(spec: ExecuteTaskRunnerSpec): string;
+/**
+ * Read a runner spec JSON file from disk.
+ *
+ * @param path - Absolute path to `state/task-spec.json`.
+ * @returns Parsed task spec.
+ *
+ * @public
+ */
+export declare function readTaskRunnerSpec(path: string): Promise<ExecuteTaskRunnerSpec>;
+/**
+ * Validate that one runner endpoint is an HTTP(S) URL.
+ *
+ * @param value - Candidate endpoint URL.
+ *
+ * @public
+ */
+export declare function validateRunnerEndpoint(value: string): void;

package/dist/runtime.d.ts

@@ -0,0 +1,134 @@
+import { type ExecuteTaskCompletionPayload, type Dataset, type JsonValue } from "@liy/mote-core";
+/**
+ * Directory layout used by one Sprite task workspace.
+ *
+ * @public
+ */
+export interface TaskAgentWorkspacePaths {
+    workspaceDir: string;
+    stateDir: string;
+    artifactsDir: string;
+}
+/**
+ * Allocate a UUID for one task artifact.
+ *
+ * @returns RFC 4122 artifact id.
+ *
+ * @public
+ */
+export declare function allocateTaskArtifactId(): string;
+/**
+ * Create the canonical directory paths for a task workspace.
+ *
+ * @param workspaceDir - Absolute Sprite workspace directory for one run.
+ * @returns Workspace, state, and artifact directory paths.
+ *
+ * @public
+ */
+export declare function createTaskAgentWorkspacePaths(workspaceDir: string): TaskAgentWorkspacePaths;
+/**
+ * Ensure the runtime workspace directories exist.
+ *
+ * @param paths - Canonical task workspace paths.
+ *
+ * @public
+ */
+export declare function ensureTaskAgentWorkspace(paths: TaskAgentWorkspacePaths): Promise<void>;
+/**
+ * Write one Markdown artifact to its canonical artifact directory.
+ *
+ * @param input - Artifact directory plus Markdown payload.
+ * @returns The artifact id that was written.
+ *
+ * @public
+ */
+export declare function writeMarkdownTaskArtifact(input: {
+    paths: TaskAgentWorkspacePaths;
+    artifactId?: string;
+    description?: string;
+    markdown: string;
+    metadata?: Record<string, JsonValue>;
+}): Promise<string>;
+/**
+ * Write one JSON artifact to its canonical artifact directory.
+ *
+ * @param input - Artifact directory plus JSON payload.
+ * @returns The artifact id that was written.
+ *
+ * @public
+ */
+export declare function writeJsonTaskArtifact(input: {
+    paths: TaskAgentWorkspacePaths;
+    artifactId?: string;
+    description?: string;
+    payload: JsonValue;
+    metadata?: Record<string, JsonValue>;
+}): Promise<string>;
+/**
+ * Write one dataset artifact with a required CSV sidecar.
+ *
+ * @param input - Artifact directory, preview dataset, and full CSV contents.
+ * @returns The artifact id that was written.
+ *
+ * @public
+ */
+export declare function writeDatasetTaskArtifact(input: {
+    paths: TaskAgentWorkspacePaths;
+    artifactId?: string;
+    description?: string;
+    dataset: Dataset;
+    csv: string | Buffer;
+    metadata?: Record<string, JsonValue>;
+}): Promise<string>;
+/**
+ * Parse CSV text into a preview dataset.
+ *
+ * @param input - CSV source, dataset id, and optional row preview limit.
+ * @returns Dataset using the first row as headers.
+ *
+ * @public
+ */
+export declare function datasetFromCsv(input: {
+    id: string;
+    csv: string;
+    previewRows?: number;
+}): Dataset;
+/**
+ * Write terminal completion to `state/completion.json`.
+ *
+ * @param input - Workspace paths plus terminal completion payload.
+ *
+ * @public
+ */
+export declare function writeTaskCompletion(input: {
+    paths: TaskAgentWorkspacePaths;
+    completion: ExecuteTaskCompletionPayload;
+}): Promise<void>;
+/**
+ * Read and validate terminal completion from `state/completion.json`.
+ *
+ * @param paths - Canonical task workspace paths.
+ * @returns Validated terminal completion payload.
+ *
+ * @public
+ */
+export declare function readTaskCompletion(paths: TaskAgentWorkspacePaths): Promise<ExecuteTaskCompletionPayload>;
+/**
+ * Validate every artifact file referenced by terminal completion.
+ *
+ * @param input - Workspace paths plus terminal completion payload.
+ *
+ * @public
+ */
+export declare function validateTaskArtifactFiles(input: {
+    paths: TaskAgentWorkspacePaths;
+    completion: ExecuteTaskCompletionPayload;
+}): Promise<void>;
+/**
+ * Validate that a candidate artifact id is safe for path construction.
+ *
+ * @param artifactId - Candidate artifact id.
+ *
+ * @public
+ */
+export declare function assertTaskArtifactId(artifactId: string): void;

package/package.json

@@ -0,0 +1,62 @@
+{
+  "name": "@liy/agent-runner",
+  "version": "0.1.0",
+  "private": false,
+  "description": "Sprite-local Task Agent runner for Mote remote task execution.",
+  "license": "UNLICENSED",
+  "publishConfig": {
+    "access": "public"
+  },
+  "type": "module",
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
+    }
+  },
+  "bin": {
+    "agent-runner": "dist/bin/agent-runner.js"
+  },
+  "files": [
+    "dist"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/liy/mote-app.git",
+    "directory": "agent-runner"
+  },
+  "homepage": "https://github.com/liy/mote-app.git",
+  "bugs": {
+    "url": "https://github.com/liy/mote-app/issues"
+  },
+  "keywords": [
+    "mote",
+    "agent",
+    "runner",
+    "sprites"
+  ],
+  "engines": {
+    "node": ">=24.0.0"
+  },
+  "dependencies": {},
+  "devDependencies": {
+    "@types/node": "^24.5.2",
+    "typescript": "^5.9.3",
+    "vitest": "^3.2.4",
+    "@liy/mote-core": "0.1.2"
+  },
+  "scripts": {
+    "agent-runner": "node ./dist/bin/agent-runner.js",
+    "start": "node ./dist/bin/agent-runner.js",
+    "build:local": "rm -rf dist && tsc -p tsconfig.json && pnpm exec esbuild src/index.ts src/bin/agent-runner.ts --bundle --platform=node --format=esm --target=node24 --sourcemap --outdir=dist --outbase=src && find dist -type f \\( -name '*.js' -o -name '*.js.map' \\) ! -path 'dist/index.js' ! -path 'dist/index.js.map' ! -path 'dist/bin/agent-runner.js' ! -path 'dist/bin/agent-runner.js.map' -delete && chmod +x dist/bin/agent-runner.js",
+    "build": "pnpm --dir ../mote-core build && pnpm build:local",
+    "test:local": "vitest run --passWithNoTests",
+    "test": "pnpm --dir ../mote-core build && pnpm test:local",
+    "typecheck:local": "tsc --noEmit -p tsconfig.json",
+    "typecheck": "pnpm --dir ../mote-core build && pnpm typecheck:local"
+  }
+}