@harness-control/runner 0.1.0

package/dist/local-actions/dispatcher.js

@@ -0,0 +1,407 @@
+import { parseLocalActionErrorPayload, parseLocalActionResponsePayload } from "@harness-control/protocol";
+import { LocalCapabilityPolicyError } from "./index.js";
+import { LocalCapabilityExecutionError, } from "./executors.js";
+export class LocalActionDispatcher {
+    #executor;
+    #resolveContext;
+    #emitEvents;
+    #now;
+    #stoppedSessionIds = new Set();
+    constructor(options) {
+        this.#executor = options.executor;
+        this.#resolveContext = options.resolveContext;
+        this.#emitEvents = options.emitEvents;
+        this.#now = options.now ?? (() => new Date());
+    }
+    async dispatch(request) {
+        if (this.#stoppedSessionIds.has(request.attribution.session_id)) {
+            return this.#errorOutcome(request, new LocalCapabilityPolicyError("local_capability_lease_revoked", "Local action session has already stopped."), []);
+        }
+        let context;
+        try {
+            context = await this.#resolveContext(request);
+        }
+        catch (error) {
+            return this.#errorOutcome(request, error, []);
+        }
+        try {
+            return await this.#dispatchWithContext(request, context);
+        }
+        catch (error) {
+            const executionEvents = error instanceof LocalCapabilityExecutionError ? error.events : [];
+            return this.#errorOutcome(request, error, executionEvents);
+        }
+    }
+    duplicatePayloadMismatch(request) {
+        const error = new LocalCapabilityPolicyError("local_capability_action_failed", `Local action request '${request.request_id}' was already seen with a different payload.`);
+        return this.#errorOutcome(request, error, [failedEventFor(request, error)]);
+    }
+    markSessionActive(sessionId) {
+        this.#stoppedSessionIds.delete(sessionId);
+    }
+    async stopDevServersForSession(sessionId) {
+        this.#stoppedSessionIds.add(sessionId);
+        await this.#executor.stopDevServersForSession(sessionId);
+    }
+    async #dispatchWithContext(request, context) {
+        switch (request.action) {
+            case "local.filesystem.read": {
+                const actionResult = await this.#executor.readFile(context, request.input.path, {
+                    encoding: request.input.encoding ?? "utf8",
+                    ...(request.input.range ? { range: request.input.range } : {}),
+                    ...(request.output_limits.content_bytes ? { contentByteLimit: request.output_limits.content_bytes } : {}),
+                });
+                const events = this.#emitRequestEvents(request, actionResult.events);
+                const payload = parseLocalActionResponsePayload({
+                    ...this.#responseBase(request, events),
+                    action: request.action,
+                    output: {
+                        path: actionResult.result.path,
+                        content: actionResult.result.content,
+                        encoding: actionResult.result.encoding,
+                        hash: actionResult.result.hash,
+                        ...(actionResult.result.truncated ? { truncated: true } : {}),
+                    },
+                });
+                return { type: "response", payload, events };
+            }
+            case "local.filesystem.list": {
+                const actionResult = await this.#executor.listDirectory(context, request.input.path, {
+                    recursive: request.input.recursive ?? false,
+                    includeHidden: request.input.include_hidden ?? false,
+                    ...(request.input.max_depth ? { maxDepth: request.input.max_depth } : {}),
+                    ...(request.output_limits.entries ? { entryLimit: request.output_limits.entries } : {}),
+                });
+                const events = this.#emitRequestEvents(request, actionResult.events);
+                const payload = parseLocalActionResponsePayload({
+                    ...this.#responseBase(request, events),
+                    action: request.action,
+                    output: {
+                        path: actionResult.result.path,
+                        entries: actionResult.result.entries,
+                        ...(actionResult.result.truncated ? { truncated: true } : {}),
+                    },
+                });
+                return { type: "response", payload, events };
+            }
+            case "local.filesystem.write": {
+                const actionResult = await this.#executor.writeFile(context, request.input.path, request.input.content, {
+                    encoding: request.input.encoding ?? "utf8",
+                    mode: request.input.mode,
+                    createParents: request.input.create_parents,
+                    ...(request.input.expected_base_hash ? { expectedBaseHash: request.input.expected_base_hash } : {}),
+                });
+                const events = this.#emitRequestEvents(request, actionResult.events);
+                const payload = parseLocalActionResponsePayload({
+                    ...this.#responseBase(request, events),
+                    action: request.action,
+                    output: {
+                        path: actionResult.result.path,
+                        bytes_written: actionResult.result.bytes_written,
+                        new_hash: actionResult.result.new_hash,
+                    },
+                });
+                return { type: "response", payload, events };
+            }
+            case "local.filesystem.patch": {
+                const actionResult = await this.#executor.patchFile(context, request.input.path, {
+                    expectedBaseHash: request.input.expected_base_hash,
+                    patchContent: request.input.patch.content,
+                    createIfMissing: request.input.create_if_missing ?? false,
+                });
+                const events = this.#emitRequestEvents(request, actionResult.events);
+                const payload = parseLocalActionResponsePayload({
+                    ...this.#responseBase(request, events),
+                    action: request.action,
+                    output: {
+                        path: actionResult.result.path,
+                        changed: actionResult.result.changed,
+                        new_hash: actionResult.result.new_hash,
+                    },
+                });
+                return { type: "response", payload, events };
+            }
+            case "local.git.status": {
+                const actionResult = await this.#executor.git(context, "status", {
+                    status: {
+                        porcelainVersion: request.input.porcelain_version,
+                        includeBranch: request.input.include_branch ?? false,
+                        ...(request.output_limits.status_bytes ? { outputByteLimit: request.output_limits.status_bytes } : {}),
+                    },
+                });
+                const events = this.#emitRequestEvents(request, actionResult.events);
+                const payload = parseLocalActionResponsePayload({
+                    ...this.#responseBase(request, events),
+                    action: request.action,
+                    output: {
+                        porcelain: actionResult.result.stdout,
+                        ...(actionResult.result.branch ? { branch: actionResult.result.branch } : {}),
+                        ...(actionResult.result.stdout_truncated ? { truncated: true } : {}),
+                    },
+                });
+                return { type: "response", payload, events };
+            }
+            case "local.git.diff": {
+                const actionResult = await this.#executor.git(context, "diff", {
+                    diff: {
+                        ...(request.input.paths ? { paths: request.input.paths } : {}),
+                        staged: request.input.staged ?? false,
+                        ...(request.input.base_ref ? { baseRef: request.input.base_ref } : {}),
+                        ...(request.output_limits.diff_bytes ? { outputByteLimit: request.output_limits.diff_bytes } : {}),
+                    },
+                });
+                const events = this.#emitRequestEvents(request, actionResult.events);
+                const payload = parseLocalActionResponsePayload({
+                    ...this.#responseBase(request, events),
+                    action: request.action,
+                    output: {
+                        diff: actionResult.result.stdout,
+                        ...(actionResult.result.stdout_truncated ? { truncated: true } : {}),
+                    },
+                });
+                return { type: "response", payload, events };
+            }
+            case "local.shell.exec": {
+                const actionResult = await this.#executor.shell(context, {
+                    executable: request.input.executable,
+                    argv: request.input.argv,
+                    cwd: request.input.cwd,
+                    use_shell: request.input.use_shell,
+                    env: request.input.env ?? {},
+                    timeout_seconds: timeoutSecondsFor(request),
+                    ...(request.input.stdin !== undefined ? { stdin: request.input.stdin } : {}),
+                    ...(request.output_limits.stdout_bytes ? { stdout_byte_limit: request.output_limits.stdout_bytes } : {}),
+                    ...(request.output_limits.stderr_bytes ? { stderr_byte_limit: request.output_limits.stderr_bytes } : {}),
+                });
+                const events = this.#emitRequestEvents(request, actionResult.events);
+                const payload = parseLocalActionResponsePayload({
+                    ...this.#responseBase(request, events),
+                    action: request.action,
+                    output: {
+                        executable: actionResult.result.executable,
+                        argv: actionResult.result.argv,
+                        cwd: actionResult.result.cwd,
+                        exit_code: actionResult.result.exit_code,
+                        signal: actionResult.result.signal,
+                        stdout: actionResult.result.stdout,
+                        stderr: actionResult.result.stderr,
+                        timed_out: actionResult.result.timed_out,
+                        ...(actionResult.result.stdout_truncated ? { stdout_truncated: true } : {}),
+                        ...(actionResult.result.stderr_truncated ? { stderr_truncated: true } : {}),
+                    },
+                });
+                return { type: "response", payload, events };
+            }
+            case "local.dev_server.start": {
+                const actionResult = await this.#executor.startDevServer(context, {
+                    server_id: request.input.server_id,
+                    executable: request.input.executable,
+                    argv: request.input.argv,
+                    cwd: request.input.cwd,
+                    host: request.input.host,
+                    port: request.input.port,
+                    use_shell: request.input.use_shell,
+                    env: request.input.env ?? {},
+                    timeout_seconds: timeoutSecondsFor(request),
+                    ...(request.input.readiness ? { readiness: request.input.readiness } : {}),
+                    session_active: () => !this.#stoppedSessionIds.has(context.session_id),
+                });
+                const events = this.#emitRequestEvents(request, actionResult.events);
+                const payload = parseLocalActionResponsePayload({
+                    ...this.#responseBase(request, events),
+                    action: request.action,
+                    output: {
+                        server_id: actionResult.result.server_id,
+                        pid: actionResult.result.pid,
+                        host: actionResult.result.host,
+                        port: actionResult.result.port,
+                        cwd: actionResult.result.cwd,
+                        started_at: actionResult.result.started_at,
+                        url: `http://${actionResult.result.host}:${actionResult.result.port}`,
+                    },
+                });
+                return { type: "response", payload, events };
+            }
+            case "local.dev_server.stop": {
+                const actionResult = await this.#executor.stopDevServer(context, request.input.server_id, request.input.signal ?? "SIGTERM", request.input.timeout_ms ?? 5_000);
+                const events = this.#emitRequestEvents(request, actionResult.events);
+                const payload = parseLocalActionResponsePayload({
+                    ...this.#responseBase(request, events),
+                    action: request.action,
+                    output: {
+                        server_id: actionResult.result.server_id,
+                        stopped_at: this.#now().toISOString(),
+                    },
+                });
+                return { type: "response", payload, events };
+            }
+        }
+    }
+    #responseBase(request, events) {
+        return {
+            request_id: request.request_id,
+            status: "completed",
+            completed_at: this.#now().toISOString(),
+            attribution: request.attribution,
+            lease: request.lease,
+            audit_events: responseAuditEvents(events),
+        };
+    }
+    #errorOutcome(request, error, executionEvents) {
+        const emittedEvents = executionEvents.length > 0 ? this.#emitErrorEvents(request, executionEvents) : [];
+        const localError = toLocalActionError(error);
+        const payload = parseLocalActionErrorPayload({
+            request_id: request.request_id,
+            action: request.action,
+            status: localError.code === "local_capability_timeout" ? "timed_out" : localError.code === "local_capability_cancelled" ? "cancelled" : "failed",
+            failed_at: this.#now().toISOString(),
+            attribution: request.attribution,
+            lease: request.lease,
+            error: localError,
+            audit_events: errorAuditEvents(emittedEvents),
+        });
+        return { type: "error", payload, events: emittedEvents };
+    }
+    #emitRequestEvents(request, events) {
+        const enrichedEvents = events.map((event) => ({
+            event_type: event.event_type,
+            data: {
+                ...event.data,
+                input: {
+                    request_id: request.request_id,
+                    protocol_action: request.action,
+                    ...(event.data.input === undefined ? {} : { details: event.data.input }),
+                },
+            },
+        }));
+        return this.#emitEvents(request.attribution.session_id, request.attribution.turn_id, enrichedEvents);
+    }
+    #emitErrorEvents(request, events) {
+        try {
+            return this.#emitRequestEvents(request, events);
+        }
+        catch (error) {
+            if (error instanceof LocalCapabilityPolicyError) {
+                return [];
+            }
+            throw error;
+        }
+    }
+}
+function timeoutSecondsFor(request) {
+    const timeoutMs = request.cancellation.timeout_ms ?? 30_000;
+    return Math.max(1, Math.ceil(timeoutMs / 1000));
+}
+function responseAuditEvents(events) {
+    const started = events.find((event) => event.event_type === "local_capability.action.started");
+    const completed = events.find((event) => event.event_type === "local_capability.action.completed");
+    return {
+        ...(started ? { started: { event_type: "local_capability.action.started", sequence: started.sequence } } : {}),
+        completed: completed
+            ? { event_type: "local_capability.action.completed", sequence: completed.sequence }
+            : { event_type: "local_capability.action.completed" },
+    };
+}
+function errorAuditEvents(events) {
+    const started = events.find((event) => event.event_type === "local_capability.action.started");
+    const failed = events.find((event) => event.event_type === "local_capability.action.failed");
+    return {
+        ...(started ? { started: { event_type: "local_capability.action.started", sequence: started.sequence } } : {}),
+        failed: failed
+            ? { event_type: "local_capability.action.failed", sequence: failed.sequence }
+            : { event_type: "local_capability.action.failed" },
+    };
+}
+function toLocalActionError(error) {
+    const cause = error instanceof LocalCapabilityExecutionError ? error.cause : error;
+    if (cause instanceof LocalCapabilityPolicyError) {
+        return {
+            code: mapPolicyErrorCode(cause.code),
+            message: cause.message,
+            retryable: false,
+        };
+    }
+    if (cause instanceof Error) {
+        return {
+            code: mapProcessErrorCode(cause),
+            message: cause.message,
+            retryable: false,
+        };
+    }
+    return {
+        code: "local_capability_action_failed",
+        message: "Local action failed.",
+        retryable: false,
+    };
+}
+function failedEventFor(request, error) {
+    return {
+        event_type: "local_capability.action.failed",
+        data: {
+            lease_id: request.lease.lease_id,
+            run_id: request.lease.run_id,
+            workspace_id: request.attribution.workspace_id,
+            provider_instance_id: request.attribution.provider_instance_id,
+            capability_id: request.lease.capability_id,
+            action: request.action,
+            status: "failed",
+            error: {
+                code: mapPolicyErrorCode(error.code),
+                message: error.message,
+                retryable: false,
+            },
+        },
+    };
+}
+function mapPolicyErrorCode(code) {
+    switch (code) {
+        case "local_capability_lease_missing":
+        case "local_capability_lease_expired":
+        case "local_capability_lease_revoked":
+        case "local_capability_session_mismatch":
+        case "local_capability_workspace_mismatch":
+        case "local_capability_provider_mismatch":
+        case "local_capability_scope_not_granted":
+        case "local_capability_approval_required":
+        case "local_capability_expected_hash_mismatch":
+        case "local_capability_output_limit_exceeded":
+        case "local_capability_timeout":
+        case "local_capability_cancelled":
+        case "local_capability_command_denied":
+        case "local_capability_dev_server_exists":
+        case "local_capability_dev_server_not_found":
+            return code;
+        case "local_capability_scope_unavailable":
+        case "local_capability_not_granted":
+        case "local_capability_unavailable":
+        case "local_capability_provider_unsupported":
+        case "local_capability_max_calls_exceeded":
+            return "local_capability_scope_not_granted";
+        case "local_capability_sandbox_read_only":
+            return "local_capability_sandbox_denied";
+        case "local_capability_path_denied":
+        case "local_capability_cwd_denied":
+        case "local_capability_path_unresolved":
+            return "local_capability_path_denied";
+        case "local_capability_shell_denied":
+        case "local_capability_timeout_exceeded":
+        case "local_capability_network_policy_unsupported":
+        case "local_capability_env_denied":
+        case "local_capability_executable_denied":
+        case "local_capability_executable_not_allowed":
+        case "local_capability_argv_denied":
+        case "local_capability_command_policy_required":
+        case "local_capability_command_policy_invalid":
+        case "local_capability_dev_server_host_denied":
+        case "local_capability_dev_server_port_denied":
+            return "local_capability_command_denied";
+        case "local_capability_dev_server_start_failed":
+            return "local_capability_process_failed";
+        default:
+            return "local_capability_action_failed";
+    }
+}
+function mapProcessErrorCode(error) {
+    return error.message.startsWith("spawn ") ? "local_capability_process_failed" : "local_capability_action_failed";
+}
+//# sourceMappingURL=dispatcher.js.map

package/dist/local-actions/executors.d.ts

@@ -0,0 +1,159 @@
+import type { HcpEventType, LocalCapabilityLease } from "@harness-control/protocol";
+import type { AuditLogger } from "../audit/index.js";
+import { LocalCapabilityEngine, type LocalGitAction } from "./index.js";
+export type LocalCapabilityExecutionContext = {
+    session_id: string;
+    turn_id: string;
+    workspace_id: string;
+    provider_instance_id: string;
+    workspace_root: string;
+    sandbox_mode: "read_only" | "workspace_write" | "danger_full_access";
+    lease: LocalCapabilityLease;
+};
+export type LocalCapabilityExecutionEvent = {
+    event_type: HcpEventType;
+    data: Record<string, unknown>;
+};
+export type LocalActionResult<TResult> = {
+    result: TResult;
+    events: LocalCapabilityExecutionEvent[];
+};
+export type FilesystemReadResult = {
+    path: string;
+    content: string;
+    encoding: "utf8" | "base64";
+    hash: string;
+    truncated?: boolean;
+};
+export type FilesystemReadOptions = {
+    encoding?: "utf8" | "base64";
+    range?: {
+        start?: number;
+        length?: number;
+    };
+    contentByteLimit?: number;
+};
+export type FilesystemListResult = {
+    path: string;
+    entries: Array<{
+        name: string;
+        type: "file" | "directory" | "other";
+    }>;
+    truncated?: boolean;
+};
+export type FilesystemListOptions = {
+    recursive?: boolean;
+    includeHidden?: boolean;
+    maxDepth?: number;
+    entryLimit?: number;
+};
+export type FilesystemWriteResult = {
+    path: string;
+    bytes_written: number;
+    new_hash: string;
+};
+export type FilesystemWriteOptions = {
+    encoding?: "utf8" | "base64";
+    mode?: "create" | "overwrite";
+    createParents?: boolean;
+    expectedBaseHash?: string;
+};
+export type FilesystemPatchResult = {
+    path: string;
+    changed: boolean;
+    new_hash: string;
+};
+export type FilesystemPatchOptions = {
+    expectedBaseHash: string;
+    patchContent: string;
+    createIfMissing?: boolean;
+};
+export type GitCommandResult = {
+    operation: LocalGitAction;
+    exit_code: number;
+    stdout: string;
+    stderr: string;
+    stdout_truncated?: boolean;
+    stderr_truncated?: boolean;
+    branch?: string;
+};
+export type GitCommandOptions = {
+    status?: {
+        porcelainVersion?: "v1" | "v2";
+        includeBranch?: boolean;
+        outputByteLimit?: number;
+    };
+    diff?: {
+        paths?: string[];
+        staged?: boolean;
+        baseRef?: string;
+        outputByteLimit?: number;
+    };
+};
+export type ShellCommandRequest = {
+    executable: string;
+    argv: string[];
+    cwd?: string;
+    timeout_seconds: number;
+    use_shell?: boolean;
+    env?: Record<string, string>;
+    stdin?: string;
+    stdout_byte_limit?: number;
+    stderr_byte_limit?: number;
+    session_active?: () => boolean;
+    signal?: AbortSignal;
+};
+export type ShellCommandResult = {
+    executable: string;
+    argv: string[];
+    cwd: string;
+    exit_code: number | null;
+    signal: NodeJS.Signals | null;
+    stdout: string;
+    stderr: string;
+    timed_out: boolean;
+    stdout_truncated?: boolean;
+    stderr_truncated?: boolean;
+};
+export type DevServerStartRequest = ShellCommandRequest & {
+    server_id: string;
+    host: string;
+    port: number;
+    readiness?: {
+        url?: string;
+        timeout_ms: number;
+    };
+};
+export type DevServerRecord = {
+    server_id: string;
+    pid: number;
+    host: string;
+    port: number;
+    cwd: string;
+    started_at: string;
+};
+export declare class LocalCapabilityExecutor {
+    #private;
+    constructor(engine: LocalCapabilityEngine, auditLogger?: AuditLogger);
+    readFile(context: LocalCapabilityExecutionContext, path: string, options?: FilesystemReadOptions): Promise<LocalActionResult<FilesystemReadResult>>;
+    listDirectory(context: LocalCapabilityExecutionContext, path: string, options?: FilesystemListOptions): Promise<LocalActionResult<FilesystemListResult>>;
+    writeFile(context: LocalCapabilityExecutionContext, path: string, content: string, options?: FilesystemWriteOptions): Promise<LocalActionResult<FilesystemWriteResult>>;
+    patchFile(context: LocalCapabilityExecutionContext, path: string, options: FilesystemPatchOptions): Promise<LocalActionResult<FilesystemPatchResult>>;
+    deletePath(context: LocalCapabilityExecutionContext, path: string): Promise<LocalActionResult<{
+        path: string;
+    }>>;
+    git(context: LocalCapabilityExecutionContext, operation: LocalGitAction, options?: GitCommandOptions): Promise<LocalActionResult<GitCommandResult>>;
+    shell(context: LocalCapabilityExecutionContext, request: ShellCommandRequest): Promise<LocalActionResult<ShellCommandResult>>;
+    startDevServer(context: LocalCapabilityExecutionContext, request: DevServerStartRequest): Promise<LocalActionResult<DevServerRecord>>;
+    stopDevServer(context: LocalCapabilityExecutionContext, serverId: string, signal?: NodeJS.Signals, timeoutMs?: number): Promise<LocalActionResult<{
+        server_id: string;
+    }>>;
+    listDevServers(): DevServerRecord[];
+    stopDevServersForSession(sessionId: string, timeoutMs?: number): Promise<void>;
+}
+export declare class LocalCapabilityExecutionError extends Error {
+    readonly events: LocalCapabilityExecutionEvent[];
+    readonly cause: unknown;
+    constructor(events: LocalCapabilityExecutionEvent[], cause: unknown);
+}
+//# sourceMappingURL=executors.d.ts.map