@vauban-org/agent-sdk 1.0.0 → 1.3.0

package/dist/container/protocol.d.ts

@@ -0,0 +1,134 @@
+/**
+ * Container Execution Protocol — standard contract for running automations
+ * inside containers or as local binaries.
+ *
+ * Contract:
+ *
+ *   Input (via env vars):
+ *     VAUBAN_EXECUTION_ID    — unique execution identifier (UUID)
+ *     VAUBAN_AUTOMATION_NAME — automation name (kebab-case)
+ *     VAUBAN_INPUT           — JSON-encoded input parameters
+ *     VAUBAN_TIMEOUT         — timeout in seconds
+ *     VAUBAN_MODE            — execution mode (default: "execute")
+ *
+ *   Output (via stdout, last non-empty line, JSON):
+ *     { "status": "completed", "output": <any> }
+ *     { "status": "failed", "error": { "code": "...", "message": "...", "details"?: <any> } }
+ *
+ *   Diagnostics (via stderr, optional, one JSON object per line):
+ *     { "level": "info", "message": "...", "timestamp": "..." }
+ *     { "progress": 0.5, "message": "..." }
+ *
+ * @public @since 1.2.0
+ */
+/**
+ * Reserved environment variable names. All caller env merged on top must NOT
+ * shadow these keys, or the automation's view of its own context becomes
+ * undefined.
+ *
+ * @public
+ */
+export declare const PROTOCOL_ENV: {
+    readonly EXECUTION_ID: "VAUBAN_EXECUTION_ID";
+    readonly AUTOMATION_NAME: "VAUBAN_AUTOMATION_NAME";
+    readonly INPUT: "VAUBAN_INPUT";
+    readonly TIMEOUT: "VAUBAN_TIMEOUT";
+    readonly MODE: "VAUBAN_MODE";
+};
+/**
+ * Default protocol mode set when caller does not specify one.
+ * @public
+ */
+export declare const DEFAULT_PROTOCOL_MODE = "execute";
+/**
+ * Final status reported by a container/binary on stdout.
+ * @public
+ */
+export type ProtocolStatus = "completed" | "failed";
+/**
+ * Discriminated union of protocol outputs parsed from stdout.
+ * @public
+ */
+export type ProtocolResult<T = unknown> = {
+    readonly status: "completed";
+    readonly output: T;
+} | {
+    readonly status: "failed";
+    readonly error: {
+        readonly code: string;
+        readonly message: string;
+        readonly details?: unknown;
+    };
+};
+/**
+ * Outcome of an execution attempt, combining protocol result with timing,
+ * captured logs, and propagated metadata.
+ *
+ * @public
+ */
+export interface ExecutionResult<T = unknown> {
+    readonly executionId: string;
+    readonly automationName: string;
+    readonly status: "completed" | "failed" | "timeout";
+    readonly input: unknown;
+    readonly output?: T;
+    readonly error?: {
+        code: string;
+        message: string;
+        details?: unknown;
+    };
+    readonly startedAt: Date;
+    readonly completedAt: Date;
+    readonly durationMs: number;
+    readonly logs: ReadonlyArray<{
+        readonly level: string;
+        readonly message: string;
+        readonly timestamp: string;
+    }>;
+}
+/**
+ * Thrown when stdout does not contain a parseable protocol result on its last
+ * non-empty line.
+ *
+ * @public
+ */
+export declare class ProtocolParseError extends Error {
+    readonly rawTail: string;
+    constructor(reason: string, rawTail: string);
+}
+/**
+ * Build the protocol's environment variables. Caller `extraEnv` is merged
+ * AFTER protocol env, so it cannot accidentally override reserved keys.
+ *
+ * @public
+ */
+export declare function buildProtocolEnv(args: {
+    executionId: string;
+    automationName: string;
+    input: unknown;
+    timeoutSeconds: number;
+    mode?: string;
+    extraEnv?: Readonly<Record<string, string>>;
+}): Record<string, string>;
+/**
+ * Parse the last non-empty line of stdout as a {@link ProtocolResult}.
+ *
+ * @throws {@link ProtocolParseError} when stdout is empty, has no JSON tail,
+ *   or the JSON does not match the protocol shape.
+ *
+ * @public
+ */
+export declare function parseProtocolOutput<T = unknown>(stdout: string): ProtocolResult<T>;
+/**
+ * Parse stderr lines as JSON log entries when possible; fall back to plain
+ * text wrapped at level "info". Used by {@link ContainerRuntime} to populate
+ * `ExecutionResult.logs`.
+ *
+ * @public
+ */
+export declare function parseStderrLogs(stderr: string): Array<{
+    level: string;
+    message: string;
+    timestamp: string;
+}>;
+//# sourceMappingURL=protocol.d.ts.map

package/dist/container/protocol.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"protocol.d.ts","sourceRoot":"","sources":["../../src/container/protocol.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAEH;;;;;;GAMG;AACH,eAAO,MAAM,YAAY;;;;;;CAMf,CAAC;AAEX;;;GAGG;AACH,eAAO,MAAM,qBAAqB,YAAY,CAAC;AAE/C;;;GAGG;AACH,MAAM,MAAM,cAAc,GAAG,WAAW,GAAG,QAAQ,CAAC;AAEpD;;;GAGG;AACH,MAAM,MAAM,cAAc,CAAC,CAAC,GAAG,OAAO,IAClC;IAAE,QAAQ,CAAC,MAAM,EAAE,WAAW,CAAC;IAAC,QAAQ,CAAC,MAAM,EAAE,CAAC,CAAA;CAAE,GACpD;IACE,QAAQ,CAAC,MAAM,EAAE,QAAQ,CAAC;IAC1B,QAAQ,CAAC,KAAK,EAAE;QACd,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;QACtB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;QACzB,QAAQ,CAAC,OAAO,CAAC,EAAE,OAAO,CAAC;KAC5B,CAAC;CACH,CAAC;AAEN;;;;;GAKG;AACH,MAAM,WAAW,eAAe,CAAC,CAAC,GAAG,OAAO;IAC1C,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;IAChC,QAAQ,CAAC,MAAM,EAAE,WAAW,GAAG,QAAQ,GAAG,SAAS,CAAC;IACpD,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAC;IACxB,QAAQ,CAAC,MAAM,CAAC,EAAE,CAAC,CAAC;IACpB,QAAQ,CAAC,KAAK,CAAC,EAAE;QACf,IAAI,EAAE,MAAM,CAAC;QACb,OAAO,EAAE,MAAM,CAAC;QAChB,OAAO,CAAC,EAAE,OAAO,CAAC;KACnB,CAAC;IACF,QAAQ,CAAC,SAAS,EAAE,IAAI,CAAC;IACzB,QAAQ,CAAC,WAAW,EAAE,IAAI,CAAC;IAC3B,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,IAAI,EAAE,aAAa,CAAC;QAC3B,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;QACvB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;QACzB,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;KAC5B,CAAC,CAAC;CACJ;AAED;;;;;GAKG;AACH,qBAAa,kBAAmB,SAAQ,KAAK;IAC3C,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;gBACb,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM;CAK5C;AAED;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE;IACrC,WAAW,EAAE,MAAM,CAAC;IACpB,cAAc,EAAE,MAAM,CAAC;IACvB,KAAK,EAAE,OAAO,CAAC;IACf,cAAc,EAAE,MAAM,CAAC;IACvB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,QAAQ,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;CAC7C,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAazB;AAED;;;;;;;GAOG;AACH,wBAAgB,mBAAmB,CAAC,CAAC,GAAG,OAAO,EAC7C,MAAM,EAAE,MAAM,GACb,cAAc,CAAC,CAAC,CAAC,CAsDnB;AAED;;;;;;GAMG;AACH,wBAAgB,eAAe,CAAC,MAAM,EAAE,MAAM,GAAG,KAAK,CAAC;IACrD,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,EAAE,MAAM,CAAC;IAChB,SAAS,EAAE,MAAM,CAAC;CACnB,CAAC,CA6BD"}

package/dist/container/protocol.js

@@ -0,0 +1,157 @@
+/**
+ * Container Execution Protocol — standard contract for running automations
+ * inside containers or as local binaries.
+ *
+ * Contract:
+ *
+ *   Input (via env vars):
+ *     VAUBAN_EXECUTION_ID    — unique execution identifier (UUID)
+ *     VAUBAN_AUTOMATION_NAME — automation name (kebab-case)
+ *     VAUBAN_INPUT           — JSON-encoded input parameters
+ *     VAUBAN_TIMEOUT         — timeout in seconds
+ *     VAUBAN_MODE            — execution mode (default: "execute")
+ *
+ *   Output (via stdout, last non-empty line, JSON):
+ *     { "status": "completed", "output": <any> }
+ *     { "status": "failed", "error": { "code": "...", "message": "...", "details"?: <any> } }
+ *
+ *   Diagnostics (via stderr, optional, one JSON object per line):
+ *     { "level": "info", "message": "...", "timestamp": "..." }
+ *     { "progress": 0.5, "message": "..." }
+ *
+ * @public @since 1.2.0
+ */
+/**
+ * Reserved environment variable names. All caller env merged on top must NOT
+ * shadow these keys, or the automation's view of its own context becomes
+ * undefined.
+ *
+ * @public
+ */
+export const PROTOCOL_ENV = {
+    EXECUTION_ID: "VAUBAN_EXECUTION_ID",
+    AUTOMATION_NAME: "VAUBAN_AUTOMATION_NAME",
+    INPUT: "VAUBAN_INPUT",
+    TIMEOUT: "VAUBAN_TIMEOUT",
+    MODE: "VAUBAN_MODE",
+};
+/**
+ * Default protocol mode set when caller does not specify one.
+ * @public
+ */
+export const DEFAULT_PROTOCOL_MODE = "execute";
+/**
+ * Thrown when stdout does not contain a parseable protocol result on its last
+ * non-empty line.
+ *
+ * @public
+ */
+export class ProtocolParseError extends Error {
+    rawTail;
+    constructor(reason, rawTail) {
+        super(`container-protocol: ${reason}`);
+        this.name = "ProtocolParseError";
+        this.rawTail = rawTail;
+    }
+}
+/**
+ * Build the protocol's environment variables. Caller `extraEnv` is merged
+ * AFTER protocol env, so it cannot accidentally override reserved keys.
+ *
+ * @public
+ */
+export function buildProtocolEnv(args) {
+    const env = {};
+    if (args.extraEnv) {
+        for (const [k, v] of Object.entries(args.extraEnv)) {
+            env[k] = v;
+        }
+    }
+    env[PROTOCOL_ENV.EXECUTION_ID] = args.executionId;
+    env[PROTOCOL_ENV.AUTOMATION_NAME] = args.automationName;
+    env[PROTOCOL_ENV.INPUT] = JSON.stringify(args.input);
+    env[PROTOCOL_ENV.TIMEOUT] = String(args.timeoutSeconds);
+    env[PROTOCOL_ENV.MODE] = args.mode ?? DEFAULT_PROTOCOL_MODE;
+    return env;
+}
+/**
+ * Parse the last non-empty line of stdout as a {@link ProtocolResult}.
+ *
+ * @throws {@link ProtocolParseError} when stdout is empty, has no JSON tail,
+ *   or the JSON does not match the protocol shape.
+ *
+ * @public
+ */
+export function parseProtocolOutput(stdout) {
+    const trimmed = stdout.trim();
+    if (trimmed.length === 0) {
+        throw new ProtocolParseError("stdout is empty", "");
+    }
+    const lines = trimmed.split("\n");
+    const lastLine = lines[lines.length - 1].trim();
+    if (lastLine.length === 0) {
+        throw new ProtocolParseError("last stdout line is empty", trimmed.slice(-200));
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(lastLine);
+    }
+    catch {
+        throw new ProtocolParseError("last stdout line is not valid JSON", lastLine.slice(0, 500));
+    }
+    if (typeof parsed !== "object" || parsed === null || !("status" in parsed)) {
+        throw new ProtocolParseError("protocol JSON missing 'status' field", lastLine.slice(0, 500));
+    }
+    const obj = parsed;
+    const status = obj["status"];
+    if (status === "completed") {
+        return { status: "completed", output: (obj["output"] ?? null) };
+    }
+    if (status === "failed") {
+        const err = obj["error"] ?? {};
+        const code = typeof err["code"] === "string" ? err["code"] : "UNKNOWN";
+        const message = typeof err["message"] === "string"
+            ? err["message"]
+            : "(no message)";
+        const details = err["details"];
+        return { status: "failed", error: { code, message, details } };
+    }
+    throw new ProtocolParseError(`unknown protocol status: ${String(status)}`, lastLine.slice(0, 500));
+}
+/**
+ * Parse stderr lines as JSON log entries when possible; fall back to plain
+ * text wrapped at level "info". Used by {@link ContainerRuntime} to populate
+ * `ExecutionResult.logs`.
+ *
+ * @public
+ */
+export function parseStderrLogs(stderr) {
+    const logs = [];
+    const lines = stderr.split("\n");
+    for (const raw of lines) {
+        const line = raw.trim();
+        if (line.length === 0)
+            continue;
+        try {
+            const obj = JSON.parse(line);
+            logs.push({
+                level: typeof obj["level"] === "string" ? obj["level"] : "info",
+                message: typeof obj["message"] === "string"
+                    ? obj["message"]
+                    : line.slice(0, 500),
+                timestamp: typeof obj["timestamp"] === "string"
+                    ? obj["timestamp"]
+                    : new Date().toISOString(),
+            });
+        }
+        catch {
+            logs.push({
+                level: "info",
+                message: line.slice(0, 500),
+                timestamp: new Date().toISOString(),
+            });
+        }
+    }
+    return logs;
+}
+//# sourceMappingURL=protocol.js.map

package/dist/container/protocol.js.map

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

package/dist/container/runtime.d.ts

@@ -0,0 +1,140 @@
+/**
+ * ContainerRuntime — execute automations as local binaries or as containers,
+ * speaking the {@link ./protocol.ts | Container Execution Protocol}.
+ *
+ * Two modes:
+ *
+ *   - **Binary**: spawn a local executable directly (Rust/Go/Python binary).
+ *     The runtime uses `node:child_process.spawn` by default; tests inject a
+ *     `SpawnFn` to avoid actually running anything.
+ *
+ *   - **Container**: delegate to a host-provided {@link SandboxExecutor}.
+ *     This is structurally compatible with Command Center's `DockerExecutor`
+ *     (hardened isolation), so the SDK stays decoupled from any specific
+ *     sandbox implementation.
+ *
+ * @public @since 1.2.0
+ */
+import { type ChildProcess } from "node:child_process";
+import { type ExecutionResult } from "./protocol.js";
+/**
+ * Description of a sandboxed job — structurally identical to Command Center's
+ * `SandboxJob`. Defined here so the SDK has no dependency on a specific
+ * sandbox implementation.
+ *
+ * @public
+ */
+export interface SandboxJob {
+    image: string;
+    command: string[];
+    stdin?: string;
+    env?: Record<string, string>;
+    cwd?: string;
+    timeoutMs: number;
+    networkMode?: "none" | "outbound" | "bridge";
+    readOnlyRoot?: boolean;
+    memoryMb?: number;
+    cpuQuota?: number;
+}
+/**
+ * Outcome of a sandbox run — structurally identical to Command Center's
+ * `SandboxResult`.
+ *
+ * @public
+ */
+export interface SandboxResult {
+    exitCode: number;
+    stdout: string;
+    stderr: string;
+    timedOut: boolean;
+    durationMs: number;
+}
+/**
+ * Port for a process sandbox (Docker, Firecracker, etc.). The host injects an
+ * implementation at runtime; the SDK never depends on a concrete sandbox.
+ *
+ * @public
+ */
+export interface SandboxExecutor {
+    run(job: SandboxJob): Promise<SandboxResult>;
+}
+/**
+ * Spawn function signature, mirrors `node:child_process.spawn`. Injectable so
+ * tests can avoid spawning real subprocesses.
+ *
+ * @public
+ */
+export type SpawnFn = (cmd: string, args: string[], opts: {
+    env?: NodeJS.ProcessEnv;
+    cwd?: string;
+    stdio: ["pipe", "pipe", "pipe"];
+    signal?: AbortSignal;
+}) => ChildProcess;
+/**
+ * Options for {@link ContainerRuntime.executeContainer}.
+ *
+ * @public
+ */
+export interface ContainerExecutionOptions {
+    executionId?: string;
+    timeoutSeconds?: number;
+    extraEnv?: Record<string, string>;
+    mode?: string;
+    networkMode?: "none" | "outbound" | "bridge";
+    readOnlyRoot?: boolean;
+    memoryMb?: number;
+    cpuQuota?: number;
+}
+/**
+ * Options for {@link ContainerRuntime.executeBinary}.
+ *
+ * @public
+ */
+export interface BinaryExecutionOptions {
+    executionId?: string;
+    timeoutSeconds?: number;
+    extraEnv?: Record<string, string>;
+    cwd?: string;
+    mode?: string;
+}
+/**
+ * Construct a {@link ContainerRuntime} bound to a {@link SandboxExecutor}
+ * (for container mode) and optionally a custom {@link SpawnFn} (for binary
+ * mode tests).
+ *
+ * @public
+ */
+export interface ContainerRuntimeOptions {
+    /** Sandbox executor for container mode. Required if executeContainer() is called. */
+    sandbox?: SandboxExecutor;
+    /** Spawn function for binary mode. Defaults to node:child_process.spawn. */
+    spawnFn?: SpawnFn;
+    /** Default timeout when callers don't specify one. */
+    defaultTimeoutSeconds?: number;
+}
+/**
+ * Run automations via either a sandboxed container (host-injected) or a local
+ * binary subprocess. Both paths produce a uniform {@link ExecutionResult}.
+ *
+ * @public
+ */
+export declare class ContainerRuntime {
+    private readonly sandbox;
+    private readonly spawnFn;
+    private readonly defaultTimeoutSeconds;
+    constructor(opts?: ContainerRuntimeOptions);
+    /**
+     * Execute an automation packaged as a container image. Delegates to the
+     * injected {@link SandboxExecutor} so isolation policy (caps, network,
+     * read-only FS) lives in the host implementation.
+     */
+    executeContainer<T = unknown>(image: string, automationName: string, input: unknown, options?: ContainerExecutionOptions): Promise<ExecutionResult<T>>;
+    /**
+     * Execute an automation packaged as a local binary (Rust release, Python
+     * wrapper, shell script). No container — just a hardened subprocess.
+     */
+    executeBinary<T = unknown>(command: string[], automationName: string, input: unknown, options?: BinaryExecutionOptions): Promise<ExecutionResult<T>>;
+    private runSubprocess;
+    private toExecutionResult;
+}
+//# sourceMappingURL=runtime.d.ts.map

package/dist/container/runtime.d.ts.map

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