@harness-control/runner 0.1.0

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

@@ -0,0 +1,74 @@
+import type { HcpSessionStartPayload, LocalCapabilityGrant, LocalCapabilityLease } from "@harness-control/protocol";
+import type { ProviderInstanceConfig, RunnerConfig } from "../config/index.js";
+export type LocalCapabilityActionRequest = {
+    session_id: string;
+    turn_id: string;
+    workspace_id: string;
+    provider_instance_id: string;
+    capability_id: string;
+    scope: string;
+    action: string;
+};
+export type LocalFilesystemAction = "read" | "list" | "write" | "create" | "delete" | "patch";
+export type LocalFilesystemAuthorizationRequest = {
+    session_id: string;
+    turn_id: string;
+    workspace_id: string;
+    provider_instance_id: string;
+    action: LocalFilesystemAction;
+};
+export type LocalGitAction = "status" | "diff" | "branch" | "commit_metadata" | "commit" | "checkout" | "push";
+export type LocalGitAuthorizationRequest = {
+    session_id: string;
+    turn_id: string;
+    workspace_id: string;
+    provider_instance_id: string;
+    action: LocalGitAction;
+};
+export type LocalShellAuthorizationRequest = {
+    session_id: string;
+    turn_id: string;
+    workspace_id: string;
+    provider_instance_id: string;
+    executable: string;
+    argv: string[];
+    cwd: string;
+    workspace_root: string;
+    use_shell: boolean;
+    timeout_seconds: number;
+    env?: Record<string, string>;
+};
+export type LocalDevServerAuthorizationRequest = {
+    session_id: string;
+    turn_id: string;
+    workspace_id: string;
+    provider_instance_id: string;
+    action: "start" | "stop" | "inspect";
+    executable?: string;
+    argv?: string[];
+    cwd?: string;
+    workspace_root?: string;
+    use_shell?: boolean;
+    timeout_seconds?: number;
+    env?: Record<string, string>;
+};
+export declare class LocalCapabilityPolicyError extends Error {
+    readonly code: string;
+    constructor(code: string, message: string);
+}
+export declare class LocalCapabilityLeaseManager {
+    #private;
+    constructor(config: RunnerConfig, hostId: string, now?: () => Date);
+    validateSessionLease(payload: HcpSessionStartPayload, provider: ProviderInstanceConfig): LocalCapabilityLease | undefined;
+    revokeLease(leaseId: string): void;
+    assertActionAllowed(lease: LocalCapabilityLease, request: LocalCapabilityActionRequest): LocalCapabilityGrant;
+}
+export declare class LocalCapabilityEngine {
+    readonly leaseManager: LocalCapabilityLeaseManager;
+    constructor(leaseManager: LocalCapabilityLeaseManager);
+    authorizeFilesystemAction(lease: LocalCapabilityLease, request: LocalFilesystemAuthorizationRequest): LocalCapabilityGrant;
+    authorizeGitAction(lease: LocalCapabilityLease, request: LocalGitAuthorizationRequest): LocalCapabilityGrant;
+    authorizeShellCommand(lease: LocalCapabilityLease, request: LocalShellAuthorizationRequest): Promise<LocalCapabilityGrant>;
+    authorizeDevServerAction(lease: LocalCapabilityLease, request: LocalDevServerAuthorizationRequest): Promise<LocalCapabilityGrant>;
+}
+//# sourceMappingURL=index.d.ts.map

package/dist/local-actions/index.js

@@ -0,0 +1,275 @@
+import { realpath } from "node:fs/promises";
+import { isAbsolute, relative } from "node:path";
+export class LocalCapabilityPolicyError extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.code = code;
+        this.name = "LocalCapabilityPolicyError";
+    }
+}
+export class LocalCapabilityLeaseManager {
+    #config;
+    #hostId;
+    #now;
+    #revokedLeaseIds = new Set();
+    #callCounts = new Map();
+    constructor(config, hostId, now = () => new Date()) {
+        this.#config = config;
+        this.#hostId = hostId;
+        this.#now = now;
+    }
+    validateSessionLease(payload, provider) {
+        const lease = payload.local_capability_lease;
+        if (!lease) {
+            return undefined;
+        }
+        this.#assertLeaseBinding(lease, payload);
+        this.#assertLeaseUsable(lease);
+        for (const grant of lease.capabilities) {
+            const configuredCapability = this.#requireConfiguredCapability(grant.id);
+            this.#assertGrantScopesAllowed(configuredCapability, grant);
+            this.#assertProviderSupportsCapability(provider, grant.id);
+        }
+        return lease;
+    }
+    revokeLease(leaseId) {
+        this.#revokedLeaseIds.add(leaseId);
+    }
+    assertActionAllowed(lease, request) {
+        this.#assertLeaseUsable(lease);
+        if (request.session_id !== lease.hcp_session_id) {
+            throw new LocalCapabilityPolicyError("local_capability_session_mismatch", "Local capability action session does not match the lease.");
+        }
+        if (request.workspace_id !== lease.workspace_id) {
+            throw new LocalCapabilityPolicyError("local_capability_workspace_mismatch", "Local capability action workspace does not match the lease.");
+        }
+        if (request.provider_instance_id !== lease.provider_instance_id) {
+            throw new LocalCapabilityPolicyError("local_capability_provider_mismatch", "Local capability action provider does not match the lease.");
+        }
+        const grant = lease.capabilities.find((candidate) => candidate.id === request.capability_id);
+        if (!grant) {
+            throw new LocalCapabilityPolicyError("local_capability_not_granted", `Capability '${request.capability_id}' is not granted by lease '${lease.lease_id}'.`);
+        }
+        if (!grant.scopes.includes(request.scope)) {
+            throw new LocalCapabilityPolicyError("local_capability_scope_not_granted", `Scope '${request.scope}' is not granted for capability '${request.capability_id}'.`);
+        }
+        const configuredCapability = this.#requireConfiguredCapability(request.capability_id);
+        if (!configuredCapability.scopes.includes(request.scope)) {
+            throw new LocalCapabilityPolicyError("local_capability_scope_unavailable", `Scope '${request.scope}' is not available for capability '${request.capability_id}' on this runner.`);
+        }
+        const countKey = `${lease.lease_id}:${grant.id}`;
+        const existingCallCount = this.#callCounts.get(countKey) ?? 0;
+        if (grant.max_calls !== undefined && existingCallCount >= grant.max_calls) {
+            throw new LocalCapabilityPolicyError("local_capability_max_calls_exceeded", `Capability '${request.capability_id}' exceeded its max call count.`);
+        }
+        this.#callCounts.set(countKey, existingCallCount + 1);
+        return grant;
+    }
+    #assertLeaseBinding(lease, payload) {
+        if (lease.hcp_session_id !== payload.session_id) {
+            throw new LocalCapabilityPolicyError("local_capability_session_mismatch", "Local capability lease session does not match the HCP session.");
+        }
+        if (lease.execution_host_id !== this.#hostId) {
+            throw new LocalCapabilityPolicyError("local_capability_host_mismatch", "Local capability lease host does not match this runner.");
+        }
+        if (lease.provider_instance_id !== payload.provider_instance_id) {
+            throw new LocalCapabilityPolicyError("local_capability_provider_mismatch", "Local capability lease provider does not match the selected provider.");
+        }
+        if (lease.workspace_id !== payload.workspace_id) {
+            throw new LocalCapabilityPolicyError("local_capability_workspace_mismatch", "Local capability lease workspace does not match the selected workspace.");
+        }
+    }
+    #assertLeaseUsable(lease) {
+        if (this.#revokedLeaseIds.has(lease.lease_id)) {
+            throw new LocalCapabilityPolicyError("local_capability_lease_revoked", `Local capability lease '${lease.lease_id}' has been revoked.`);
+        }
+        const expiresAt = Date.parse(lease.expires_at);
+        if (Number.isNaN(expiresAt) || expiresAt <= this.#now().getTime()) {
+            throw new LocalCapabilityPolicyError("local_capability_lease_expired", `Local capability lease '${lease.lease_id}' has expired.`);
+        }
+    }
+    #requireConfiguredCapability(capabilityId) {
+        const capability = this.#config.local_capabilities.find((candidate) => candidate.id === capabilityId);
+        if (!capability) {
+            throw new LocalCapabilityPolicyError("local_capability_unavailable", `Capability '${capabilityId}' is not configured by this runner.`);
+        }
+        if (capability.status !== "available") {
+            throw new LocalCapabilityPolicyError("local_capability_unavailable", `Capability '${capabilityId}' is ${capability.status}.`);
+        }
+        return capability;
+    }
+    #assertProviderSupportsCapability(provider, capabilityId) {
+        if (!provider.local_capabilities.includes(capabilityId)) {
+            throw new LocalCapabilityPolicyError("local_capability_provider_unsupported", `Provider '${provider.id}' does not support capability '${capabilityId}'.`);
+        }
+    }
+    #assertGrantScopesAllowed(configuredCapability, grant) {
+        const unavailableScopes = grant.scopes.filter((scope) => !configuredCapability.scopes.includes(scope));
+        if (unavailableScopes.length > 0) {
+            throw new LocalCapabilityPolicyError("local_capability_scope_unavailable", `Capability '${grant.id}' requested unavailable scopes: ${unavailableScopes.join(", ")}.`);
+        }
+    }
+}
+export class LocalCapabilityEngine {
+    leaseManager;
+    constructor(leaseManager) {
+        this.leaseManager = leaseManager;
+    }
+    authorizeFilesystemAction(lease, request) {
+        return this.leaseManager.assertActionAllowed(lease, {
+            session_id: request.session_id,
+            turn_id: request.turn_id,
+            workspace_id: request.workspace_id,
+            provider_instance_id: request.provider_instance_id,
+            capability_id: "filesystem",
+            scope: filesystemScopeForAction(request.action),
+            action: request.action,
+        });
+    }
+    authorizeGitAction(lease, request) {
+        return this.leaseManager.assertActionAllowed(lease, {
+            session_id: request.session_id,
+            turn_id: request.turn_id,
+            workspace_id: request.workspace_id,
+            provider_instance_id: request.provider_instance_id,
+            capability_id: "git",
+            scope: gitScopeForAction(request.action),
+            action: request.action,
+        });
+    }
+    async authorizeShellCommand(lease, request) {
+        const grant = this.leaseManager.assertActionAllowed(lease, {
+            session_id: request.session_id,
+            turn_id: request.turn_id,
+            workspace_id: request.workspace_id,
+            provider_instance_id: request.provider_instance_id,
+            capability_id: "shell",
+            scope: "workspace",
+            action: "run_command",
+        });
+        await assertExecutableGrantAllowed(grant, "Shell actions");
+        await assertCommandPolicyAllows(grant.command_policy, {
+            executable: request.executable,
+            argv: request.argv,
+            cwd: request.cwd,
+            workspace_root: request.workspace_root,
+            use_shell: request.use_shell,
+            timeout_seconds: request.timeout_seconds,
+            env: request.env ?? {},
+        });
+        return grant;
+    }
+    async authorizeDevServerAction(lease, request) {
+        const grant = this.leaseManager.assertActionAllowed(lease, {
+            session_id: request.session_id,
+            turn_id: request.turn_id,
+            workspace_id: request.workspace_id,
+            provider_instance_id: request.provider_instance_id,
+            capability_id: "dev_server",
+            scope: "workspace",
+            action: request.action,
+        });
+        if (request.action === "start") {
+            await assertExecutableGrantAllowed(grant, "Dev server start actions");
+            if (!request.executable ||
+                !request.argv ||
+                !request.cwd ||
+                !request.workspace_root ||
+                request.use_shell === undefined ||
+                request.timeout_seconds === undefined) {
+                throw new LocalCapabilityPolicyError("local_capability_command_policy_required", "Dev server start actions require executable, argv, cwd, workspace root, shell mode, and timeout.");
+            }
+            await assertCommandPolicyAllows(grant.command_policy, {
+                executable: request.executable,
+                argv: request.argv,
+                cwd: request.cwd,
+                workspace_root: request.workspace_root,
+                use_shell: request.use_shell,
+                timeout_seconds: request.timeout_seconds,
+                env: request.env ?? {},
+            });
+        }
+        return grant;
+    }
+}
+async function assertExecutableGrantAllowed(grant, actionLabel) {
+    if (grant.approval_policy !== "full_access") {
+        throw new LocalCapabilityPolicyError("local_capability_approval_required", `${actionLabel} require a local capability lease grant with approval_policy 'full_access'.`);
+    }
+    if (!grant.command_policy) {
+        throw new LocalCapabilityPolicyError("local_capability_command_policy_required", `${actionLabel} require a structured command policy.`);
+    }
+}
+async function assertCommandPolicyAllows(policy, request) {
+    if (!policy) {
+        throw new LocalCapabilityPolicyError("local_capability_command_policy_required", "Executable local capability actions require a structured command policy.");
+    }
+    if (!policy.allow_shell && request.use_shell) {
+        throw new LocalCapabilityPolicyError("local_capability_shell_denied", "Shell wrappers are not allowed by policy.");
+    }
+    if (request.timeout_seconds > policy.timeout_seconds) {
+        throw new LocalCapabilityPolicyError("local_capability_timeout_exceeded", `Requested timeout ${request.timeout_seconds}s exceeds policy timeout ${policy.timeout_seconds}s.`);
+    }
+    if (policy.network_policy !== "inherit") {
+        throw new LocalCapabilityPolicyError("local_capability_network_policy_unsupported", `Network policy '${policy.network_policy}' cannot be enforced by this runner.`);
+    }
+    if (policy.env_policy === "minimal" && Object.keys(request.env).length > 0) {
+        throw new LocalCapabilityPolicyError("local_capability_env_denied", "Custom environment variables are not allowed by minimal environment policy.");
+    }
+    if (policy.denied_executables?.includes(request.executable)) {
+        throw new LocalCapabilityPolicyError("local_capability_executable_denied", `Executable '${request.executable}' is denied by policy.`);
+    }
+    if (policy.allowed_executables && !policy.allowed_executables.includes(request.executable)) {
+        throw new LocalCapabilityPolicyError("local_capability_executable_not_allowed", `Executable '${request.executable}' is not allowed by policy.`);
+    }
+    if (policy.argv_patterns && !argvMatchesPolicy(request.argv, policy.argv_patterns)) {
+        throw new LocalCapabilityPolicyError("local_capability_argv_denied", `Command arguments do not match policy.`);
+    }
+    if (policy.cwd_policy === "selected_workspace_only") {
+        await assertPathInsideWorkspace(request.cwd, request.workspace_root);
+    }
+}
+function filesystemScopeForAction(action) {
+    return action === "read" || action === "list" ? "workspace_read" : "workspace_write";
+}
+function gitScopeForAction(action) {
+    return action === "status" || action === "diff" || action === "branch" || action === "commit_metadata"
+        ? "workspace_read"
+        : "workspace_write";
+}
+function argvMatchesPolicy(argv, patterns) {
+    const commandLine = argv.join(" ");
+    return patterns.some((pattern) => {
+        try {
+            return new RegExp(pattern).test(commandLine);
+        }
+        catch (error) {
+            if (error instanceof SyntaxError) {
+                throw new LocalCapabilityPolicyError("local_capability_command_policy_invalid", `Command policy argv pattern '${pattern}' is invalid: ${error.message}`);
+            }
+            throw error;
+        }
+    });
+}
+async function assertPathInsideWorkspace(path, workspaceRoot) {
+    const resolvedPath = await realpathForPolicy(path);
+    const resolvedWorkspace = await realpathForPolicy(workspaceRoot);
+    const pathFromWorkspace = relative(resolvedWorkspace, resolvedPath);
+    if (pathFromWorkspace === "" || (!pathFromWorkspace.startsWith("..") && !isAbsolute(pathFromWorkspace))) {
+        return;
+    }
+    throw new LocalCapabilityPolicyError("local_capability_cwd_denied", `Path '${path}' is outside the selected workspace.`);
+}
+async function realpathForPolicy(path) {
+    try {
+        return await realpath(path);
+    }
+    catch (error) {
+        if (error instanceof Error) {
+            throw new LocalCapabilityPolicyError("local_capability_path_unresolved", `Path '${path}' could not be resolved: ${error.message}`);
+        }
+        throw error;
+    }
+}
+//# sourceMappingURL=index.js.map

package/dist/logs/index.d.ts

@@ -0,0 +1,6 @@
+export type RunnerLogger = {
+    info(message: string): void;
+    error(message: string): void;
+};
+export declare const consoleLogger: RunnerLogger;
+//# sourceMappingURL=index.d.ts.map

package/dist/logs/index.js

@@ -0,0 +1,9 @@
+export const consoleLogger = {
+    info(message) {
+        console.log(message);
+    },
+    error(message) {
+        console.error(message);
+    },
+};
+//# sourceMappingURL=index.js.map

package/dist/mcp/McpAttachmentClient.d.ts

@@ -0,0 +1,111 @@
+import { Client } from "@modelcontextprotocol/sdk/client";
+import type { Tool } from "@modelcontextprotocol/sdk/types.js";
+import type { HcpEventType, StreamableHttpMcpServerAttachment } from "@harness-control/protocol";
+export type McpAttachmentEvent = {
+    event_type: HcpEventType;
+    data: Record<string, unknown>;
+};
+export type McpAttachmentEventSink = (event: McpAttachmentEvent) => void | Promise<void>;
+export type McpToolCallArguments = Record<string, unknown>;
+type FetchLike = (input: Parameters<typeof fetch>[0], init?: Parameters<typeof fetch>[1]) => ReturnType<typeof fetch>;
+export type McpToolDescriptor = {
+    name: string;
+    description?: string;
+    input_schema: Record<string, unknown>;
+    output_schema?: Record<string, unknown>;
+};
+export type McpToolCallResult = {
+    content?: unknown[];
+    structured_content?: Record<string, unknown>;
+    is_error: boolean;
+};
+export declare class McpToolPolicyError extends Error {
+    readonly attachmentName: string;
+    readonly toolName: string;
+    constructor(attachmentName: string, toolName: string, message: string);
+}
+export declare class McpAttachmentExpiredError extends Error {
+    readonly attachmentName: string;
+    constructor(attachmentName: string);
+}
+export declare class McpProofBindingError extends Error {
+    readonly attachmentName: string;
+    constructor(attachmentName: string, message: string);
+}
+export type McpProofContext = {
+    session_id: string;
+    host_id: string;
+    provider_instance_id: string;
+    workspace_id: string;
+    server_id?: string;
+    turn_id?: string;
+};
+export type McpProofSigningInput = {
+    key_id: string;
+    method: string;
+    url: string;
+    body_hash: string;
+    lease_id: string;
+    session_id: string;
+    host_id: string;
+    provider_instance_id: string;
+    workspace_id: string;
+    server_id: string;
+    turn_id?: string;
+    timestamp: string;
+    nonce: string;
+};
+export type McpProofSigner = (input: McpProofSigningInput) => string;
+type SdkToolClient = {
+    connect(transport: unknown): Promise<void>;
+    listTools(): Promise<{
+        tools: Tool[];
+    }>;
+    callTool(params: {
+        name: string;
+        arguments?: McpToolCallArguments;
+    }): Promise<SdkToolCallResult>;
+    close(): Promise<void>;
+};
+type SdkToolCallResult = Awaited<ReturnType<Client["callTool"]>>;
+type McpSdkFactory = {
+    createClient(): SdkToolClient;
+    createStreamableHttpTransport(attachment: StreamableHttpMcpServerAttachment, options: {
+        fetch: FetchLike;
+    }): unknown;
+};
+export type McpAttachmentClientOptions = {
+    eventSink?: McpAttachmentEventSink;
+    sdkFactory?: McpSdkFactory;
+    now?: () => Date;
+    proofContext?: McpProofContext;
+    proofSigner?: McpProofSigner;
+};
+export declare class McpAttachmentClient {
+    private readonly attachment;
+    private readonly allowedTools;
+    private readonly deniedTools;
+    private readonly eventSink;
+    private readonly sdkFactory;
+    private readonly now;
+    private readonly proofContext;
+    private readonly proofSigner;
+    private readonly hasProofSigner;
+    private client;
+    private connected;
+    constructor(attachment: StreamableHttpMcpServerAttachment, options?: McpAttachmentClientOptions);
+    connect(): Promise<void>;
+    listTools(): Promise<McpToolDescriptor[]>;
+    callTool(name: string, arguments_?: McpToolCallArguments): Promise<McpToolCallResult>;
+    close(): Promise<void>;
+    isToolAllowed(toolName: string): boolean;
+    private assertToolAllowed;
+    private requireConnectedClient;
+    private emitEvent;
+    private assertNotExpired;
+    private assertProofBindingConfigured;
+    private createProofFetch;
+}
+export declare function createDevelopmentHmacProofSigner(secret: string): McpProofSigner;
+export {};
+//# sourceMappingURL=McpAttachmentClient.d.ts.map