@borgee/agents-host 0.2.2 → 0.2.28

package/dist/policy/authorization-audit.d.ts

@@ -0,0 +1,63 @@
+import type { DebugLogger } from '../debug.js';
+import type { InternalPolicyMode } from '../compatibility-gates.js';
+export type AuthorizationAuditSurface = 'copilot-acp-permission' | 'localhost-gateway';
+export interface AuthorizationAuditRecord {
+    timestamp: string;
+    surface: AuthorizationAuditSurface;
+    policyMode: InternalPolicyMode;
+    effectiveOutcome: string;
+    reason: string;
+    agentId?: string;
+    channelId?: string;
+    selectedOptionKind?: string;
+    policyOutcome?: string;
+    policySelectedOptionKind?: string;
+    toolKind?: string;
+    method?: string;
+    path?: string;
+    status?: number;
+}
+interface AuthorizationAuditFileSystem {
+    mkdir(path: string, options: {
+        recursive: boolean;
+        mode: number;
+    }): Promise<void>;
+    stat(path: string): Promise<{
+        size: number;
+    }>;
+    rm(path: string, options: {
+        force: boolean;
+    }): Promise<void>;
+    rename(from: string, to: string): Promise<void>;
+    appendFile(path: string, data: string, options: {
+        encoding: BufferEncoding;
+        mode: number;
+    }): Promise<void>;
+    chmod(path: string, mode: number): Promise<void>;
+}
+export interface AuthorizationAuditSinkOptions {
+    stateRootDir: string;
+    logger?: DebugLogger;
+    maxFileBytes?: number;
+    fileSystem?: AuthorizationAuditFileSystem;
+}
+export interface AuthorizationAuditSinkLike {
+    append(record: AuthorizationAuditRecord): void;
+    drain(): Promise<void>;
+}
+export declare class AuthorizationAuditSink implements AuthorizationAuditSinkLike {
+    private readonly logger;
+    private readonly fileSystem;
+    private readonly currentPath;
+    private readonly previousPath;
+    private readonly maxFileBytes;
+    private writeQueue;
+    private lastWriteError;
+    constructor(options: AuthorizationAuditSinkOptions);
+    append(record: AuthorizationAuditRecord): void;
+    drain(): Promise<void>;
+    private writePayload;
+    private rotateIfNeeded;
+    private readFileSize;
+}
+export {};

package/dist/policy/authorization-audit.js

@@ -0,0 +1,94 @@
+import { dirname } from 'node:path';
+import { promises as fs } from 'node:fs';
+import { HostLogger, summarizeError } from '../debug.js';
+import { resolveAuthorizationAuditPath, resolvePreviousAuthorizationAuditPath } from '../state-paths.js';
+const PRIVATE_AUDIT_FILE_MODE = 0o600;
+const PRIVATE_AUDIT_DIRECTORY_MODE = 0o700;
+const DEFAULT_MAX_AUDIT_FILE_BYTES = 32 * 1024;
+const DEFAULT_FILE_SYSTEM = {
+    async mkdir(path, options) {
+        await fs.mkdir(path, options);
+    },
+    async stat(path) {
+        return fs.stat(path);
+    },
+    async rm(path, options) {
+        await fs.rm(path, options);
+    },
+    async rename(from, to) {
+        await fs.rename(from, to);
+    },
+    async appendFile(path, data, options) {
+        await fs.appendFile(path, data, options);
+    },
+    async chmod(path, mode) {
+        await fs.chmod(path, mode);
+    },
+};
+export class AuthorizationAuditSink {
+    logger;
+    fileSystem;
+    currentPath;
+    previousPath;
+    maxFileBytes;
+    writeQueue = Promise.resolve();
+    lastWriteError = null;
+    constructor(options) {
+        this.logger = options.logger ?? new HostLogger();
+        this.fileSystem = options.fileSystem ?? DEFAULT_FILE_SYSTEM;
+        this.currentPath = resolveAuthorizationAuditPath(options.stateRootDir);
+        this.previousPath = resolvePreviousAuthorizationAuditPath(options.stateRootDir);
+        this.maxFileBytes = options.maxFileBytes ?? DEFAULT_MAX_AUDIT_FILE_BYTES;
+    }
+    append(record) {
+        const payload = `${JSON.stringify(record)}\n`;
+        const operation = this.writeQueue.then(() => this.writePayload(payload), () => this.writePayload(payload));
+        this.writeQueue = operation.catch((error) => {
+            this.lastWriteError = error instanceof Error ? error : new Error(String(error));
+            this.logger.error('failed to persist authorization audit record', {
+                auditPath: this.currentPath,
+                error: summarizeError(this.lastWriteError),
+            });
+        });
+    }
+    async drain() {
+        await this.writeQueue;
+        if (this.lastWriteError) {
+            throw this.lastWriteError;
+        }
+    }
+    async writePayload(payload) {
+        await this.fileSystem.mkdir(dirname(this.currentPath), {
+            recursive: true,
+            mode: PRIVATE_AUDIT_DIRECTORY_MODE,
+        });
+        await this.rotateIfNeeded(Buffer.byteLength(payload, 'utf8'));
+        await this.fileSystem.appendFile(this.currentPath, payload, {
+            encoding: 'utf8',
+            mode: PRIVATE_AUDIT_FILE_MODE,
+        });
+        await this.fileSystem.chmod(this.currentPath, PRIVATE_AUDIT_FILE_MODE);
+    }
+    async rotateIfNeeded(nextPayloadBytes) {
+        const currentSize = await this.readFileSize(this.currentPath);
+        if (currentSize === 0 || currentSize + nextPayloadBytes <= this.maxFileBytes) {
+            return;
+        }
+        await this.fileSystem.rm(this.previousPath, { force: true }).catch(() => { });
+        await this.fileSystem.rename(this.currentPath, this.previousPath);
+        await this.fileSystem.chmod(this.previousPath, PRIVATE_AUDIT_FILE_MODE).catch(() => { });
+    }
+    async readFileSize(path) {
+        try {
+            const stats = await this.fileSystem.stat(path);
+            return stats.size;
+        }
+        catch (error) {
+            const code = error instanceof Error && 'code' in error ? error.code : undefined;
+            if (code === 'ENOENT') {
+                return 0;
+            }
+            throw error;
+        }
+    }
+}

package/dist/policy/copilot-permission.d.ts

@@ -0,0 +1,15 @@
+import type { RequestPermissionRequest, RequestPermissionResponse } from '@agentclientprotocol/sdk';
+import type { DebugLogger } from '../debug.js';
+import type { InternalPolicyMode } from '../compatibility-gates.js';
+import type { AuthorizationAuditSinkLike } from './authorization-audit.js';
+export interface CopilotPermissionPolicyContext {
+    gateEnabled: boolean;
+    policyMode: InternalPolicyMode;
+    params: RequestPermissionRequest;
+    logger: DebugLogger;
+    auditSink?: AuthorizationAuditSinkLike;
+    agentId?: string;
+    channelId?: string;
+}
+export declare function resolveCopilotPermissionResponse(context: CopilotPermissionPolicyContext): RequestPermissionResponse;
+export declare function createLegacyMissingAllowOptionError(): Error;

package/dist/policy/copilot-permission.js

@@ -0,0 +1,193 @@
+import { summarizeError } from '../debug.js';
+const LEGACY_MISSING_ALLOW_OPTION_MESSAGE = 'Copilot ACP requested permission but did not offer an allow option';
+function legacySelectPermissionOption(options) {
+    const option = options.find((candidate) => candidate.kind === 'allow_always')
+        ?? options.find((candidate) => candidate.kind === 'allow_once');
+    if (!option) {
+        throw new Error(LEGACY_MISSING_ALLOW_OPTION_MESSAGE);
+    }
+    return option;
+}
+function resolveRejectOption(options) {
+    return options.find((candidate) => candidate.kind === 'reject_once')
+        ?? options.find((candidate) => candidate.kind === 'reject_always');
+}
+function normalizeToolKind(value) {
+    switch (value) {
+        case 'read':
+        case 'edit':
+        case 'delete':
+        case 'move':
+        case 'search':
+        case 'execute':
+        case 'think':
+        case 'fetch':
+        case 'switch_mode':
+        case 'other':
+            return value;
+        default:
+            return 'unknown';
+    }
+}
+function selectPreferredAllowOption(options, toolKind) {
+    const prefersAlways = toolKind === 'read' || toolKind === 'search';
+    if (prefersAlways) {
+        return options.find((candidate) => candidate.kind === 'allow_always')
+            ?? options.find((candidate) => candidate.kind === 'allow_once');
+    }
+    return options.find((candidate) => candidate.kind === 'allow_once')
+        ?? options.find((candidate) => candidate.kind === 'allow_always');
+}
+function evaluatePermissionDecision(params) {
+    const toolKind = normalizeToolKind(params.toolCall.kind);
+    const allowOption = selectPreferredAllowOption(params.options, toolKind);
+    if (!allowOption) {
+        return null;
+    }
+    return {
+        outcome: 'selected',
+        optionId: allowOption.optionId,
+        optionKind: allowOption.kind,
+        reason: toolKind === 'read' || toolKind === 'search'
+            ? 'readonly-tool-preferred'
+            : 'mutating-or-unknown-tool-preferred',
+        toolKind,
+    };
+}
+function decisionToResponse(decision) {
+    return decision.outcome === 'selected'
+        ? {
+            outcome: {
+                outcome: 'selected',
+                optionId: decision.optionId,
+            },
+        }
+        : {
+            outcome: {
+                outcome: 'cancelled',
+            },
+        };
+}
+function appendAuditRecord(context, effectiveDecision, reason, policyDecision) {
+    context.auditSink?.append({
+        timestamp: new Date().toISOString(),
+        surface: 'copilot-acp-permission',
+        policyMode: context.policyMode,
+        effectiveOutcome: effectiveDecision?.outcome ?? 'error',
+        reason,
+        agentId: context.agentId,
+        channelId: context.channelId,
+        selectedOptionKind: effectiveDecision?.outcome === 'selected' ? effectiveDecision.optionKind : undefined,
+        policyOutcome: policyDecision?.outcome,
+        policySelectedOptionKind: policyDecision?.outcome === 'selected' ? policyDecision.optionKind : undefined,
+        toolKind: effectiveDecision?.toolKind ?? policyDecision?.toolKind ?? normalizeToolKind(context.params.toolCall.kind),
+    });
+}
+export function resolveCopilotPermissionResponse(context) {
+    if (!context.gateEnabled) {
+        const legacyOption = legacySelectPermissionOption(context.params.options);
+        return {
+            outcome: {
+                outcome: 'selected',
+                optionId: legacyOption.optionId,
+            },
+        };
+    }
+    try {
+        const decision = evaluatePermissionDecision(context.params);
+        if (decision) {
+            if (context.policyMode === 'audit-only') {
+                const legacyOption = legacySelectPermissionOption(context.params.options);
+                const effectiveDecision = {
+                    outcome: 'selected',
+                    optionId: legacyOption.optionId,
+                    optionKind: legacyOption.kind,
+                    reason: decision.reason,
+                    toolKind: decision.toolKind,
+                };
+                appendAuditRecord(context, effectiveDecision, decision.reason, decision);
+                return decisionToResponse(effectiveDecision);
+            }
+            appendAuditRecord(context, decision, decision.reason, decision);
+            return decisionToResponse(decision);
+        }
+        const rejectOption = resolveRejectOption(context.params.options);
+        if (context.policyMode === 'audit-only') {
+            const hypotheticalDecision = rejectOption
+                ? {
+                    outcome: 'selected',
+                    optionId: rejectOption.optionId,
+                    optionKind: rejectOption.kind,
+                    reason: 'no-allow-option',
+                    toolKind: normalizeToolKind(context.params.toolCall.kind),
+                }
+                : {
+                    outcome: 'cancelled',
+                    reason: 'no-allow-option',
+                    toolKind: normalizeToolKind(context.params.toolCall.kind),
+                };
+            appendAuditRecord(context, null, 'no-allow-option', hypotheticalDecision);
+            throw new Error(LEGACY_MISSING_ALLOW_OPTION_MESSAGE);
+        }
+        const rejectedDecision = rejectOption
+            ? {
+                outcome: 'selected',
+                optionId: rejectOption.optionId,
+                optionKind: rejectOption.kind,
+                reason: 'no-allow-option',
+                toolKind: normalizeToolKind(context.params.toolCall.kind),
+            }
+            : {
+                outcome: 'cancelled',
+                reason: 'no-allow-option',
+                toolKind: normalizeToolKind(context.params.toolCall.kind),
+            };
+        appendAuditRecord(context, rejectedDecision, rejectedDecision.reason, rejectedDecision);
+        return decisionToResponse(rejectedDecision);
+    }
+    catch (error) {
+        if (error instanceof Error && error.message === LEGACY_MISSING_ALLOW_OPTION_MESSAGE) {
+            throw error;
+        }
+        const errorSummary = {
+            agentId: context.agentId,
+            channelId: context.channelId,
+            sessionId: context.params.sessionId,
+            toolKind: normalizeToolKind(context.params.toolCall.kind),
+            error: summarizeError(error),
+        };
+        if (context.policyMode === 'audit-only') {
+            context.logger.error('Copilot ACP policy evaluation failed; falling back to the legacy picker', errorSummary);
+            const legacyOption = legacySelectPermissionOption(context.params.options);
+            const fallbackDecision = {
+                outcome: 'selected',
+                optionId: legacyOption.optionId,
+                optionKind: legacyOption.kind,
+                reason: 'policy-evaluator-error-fallback',
+                toolKind: normalizeToolKind(context.params.toolCall.kind),
+            };
+            appendAuditRecord(context, fallbackDecision, fallbackDecision.reason);
+            return decisionToResponse(fallbackDecision);
+        }
+        context.logger.error('Copilot ACP policy evaluation failed; failing closed', errorSummary);
+        const rejectOption = resolveRejectOption(context.params.options);
+        const failedClosedDecision = rejectOption
+            ? {
+                outcome: 'selected',
+                optionId: rejectOption.optionId,
+                optionKind: rejectOption.kind,
+                reason: 'policy-evaluator-error',
+                toolKind: normalizeToolKind(context.params.toolCall.kind),
+            }
+            : {
+                outcome: 'cancelled',
+                reason: 'policy-evaluator-error',
+                toolKind: normalizeToolKind(context.params.toolCall.kind),
+            };
+        appendAuditRecord(context, failedClosedDecision, failedClosedDecision.reason, failedClosedDecision);
+        return decisionToResponse(failedClosedDecision);
+    }
+}
+export function createLegacyMissingAllowOptionError() {
+    return new Error(LEGACY_MISSING_ALLOW_OPTION_MESSAGE);
+}

package/dist/policy/gateway-authorization.d.ts

@@ -0,0 +1,42 @@
+import type { IncomingMessage } from 'node:http';
+export type GatewayDecisionReason = 'browser-origin-not-allowed' | 'method-not-allowed' | 'missing-or-invalid-token' | 'invalid-token' | 'channel-mismatch' | 'not-found' | 'bootstrap-unavailable' | 'authorized';
+export interface GatewayChannelRoute {
+    channelId: string;
+    resource: 'bootstrap' | 'me' | 'history' | 'draft' | 'users' | 'messages' | 'tasks' | 'current-task';
+}
+export interface GatewayTaskRoute {
+    taskId: string;
+    resource: 'task';
+}
+export interface GatewayAuthorizationBinding {
+    channelId: string;
+    agentId?: string;
+    payloadAvailable: boolean;
+}
+export interface GatewayAuthorizationDecision {
+    reason: GatewayDecisionReason;
+    statusCode: number;
+    responseBody?: {
+        error: string;
+    } | {
+        status: 'ok';
+    };
+    allowHeader?: string;
+    binding?: GatewayAuthorizationBinding;
+    route?: GatewayChannelRoute | GatewayTaskRoute | {
+        resource: 'health';
+    };
+    path: string;
+    token?: string;
+}
+export interface GatewayAuthorizationInput {
+    request: IncomingMessage;
+    baseUrl: string;
+    allowCollaborationRoutes?: boolean;
+    lookup(token: string): GatewayAuthorizationBinding | null;
+}
+export declare function hasVisibleHeader(value: string | string[] | undefined): boolean;
+export declare function parseBearerToken(value: string | string[] | undefined): string | null;
+export declare function matchChannelRoute(pathname: string, allowCollaborationRoutes?: boolean): GatewayChannelRoute | null;
+export declare function matchTaskRoute(pathname: string): GatewayTaskRoute | null;
+export declare function evaluateGatewayAuthorization(input: GatewayAuthorizationInput): GatewayAuthorizationDecision;

package/dist/policy/gateway-authorization.js

@@ -0,0 +1,162 @@
+export function hasVisibleHeader(value) {
+    if (Array.isArray(value)) {
+        return value.some((entry) => entry.trim().length > 0);
+    }
+    return typeof value === 'string' && value.trim().length > 0;
+}
+export function parseBearerToken(value) {
+    if (Array.isArray(value) || typeof value !== 'string') {
+        return null;
+    }
+    const trimmed = value.trim();
+    const prefix = 'Bearer ';
+    if (!trimmed.startsWith(prefix)) {
+        return null;
+    }
+    const token = trimmed.slice(prefix.length);
+    return token.length > 0 && !/\s/.test(token) ? token : null;
+}
+export function matchChannelRoute(pathname, allowCollaborationRoutes = false) {
+    const resources = allowCollaborationRoutes
+        ? '(bootstrap|me|history|draft|users|messages|tasks|current-task)'
+        : '(bootstrap|me|history|tasks|current-task)';
+    const match = new RegExp(`^/v1/channels/([^/]+)/${resources}$`).exec(pathname);
+    if (!match) {
+        return null;
+    }
+    return {
+        channelId: decodeURIComponent(match[1] ?? ''),
+        resource: match[2],
+    };
+}
+export function matchTaskRoute(pathname) {
+    const match = /^\/v1\/tasks\/([^/]+)$/.exec(pathname);
+    if (!match) {
+        return null;
+    }
+    return {
+        taskId: decodeURIComponent(match[1] ?? ''),
+        resource: 'task',
+    };
+}
+function allowedMethodsForRoute(route, collaborationRoutesEnabled) {
+    switch (route.resource) {
+        case 'health':
+        case 'bootstrap':
+        case 'me':
+        case 'history':
+        case 'draft':
+        case 'users':
+            return ['GET'];
+        case 'messages':
+            return collaborationRoutesEnabled ? ['POST'] : [];
+        case 'tasks':
+            return ['GET', 'POST'];
+        case 'current-task':
+        case 'task':
+            return ['GET', 'PATCH'];
+    }
+}
+export function evaluateGatewayAuthorization(input) {
+    const url = new URL(input.request.url ?? '/', input.baseUrl);
+    const hiddenCollaborationRoute = !input.allowCollaborationRoutes
+        && ['draft', 'users', 'messages'].includes(matchChannelRoute(url.pathname, true)?.resource ?? '');
+    if (hasVisibleHeader(input.request.headers.origin)) {
+        return {
+            reason: 'browser-origin-not-allowed',
+            statusCode: 403,
+            responseBody: { error: 'browser_origin_not_allowed' },
+            path: url.pathname,
+        };
+    }
+    const method = input.request.method ?? 'GET';
+    const collaborationRoutesEnabled = input.allowCollaborationRoutes ?? false;
+    const route = url.pathname === '/health'
+        ? { resource: 'health' }
+        : matchChannelRoute(url.pathname, collaborationRoutesEnabled) ?? matchTaskRoute(url.pathname);
+    if (hiddenCollaborationRoute) {
+        return {
+            reason: 'not-found',
+            statusCode: 404,
+            responseBody: { error: 'not_found' },
+            path: url.pathname,
+        };
+    }
+    if (!route) {
+        return {
+            reason: 'not-found',
+            statusCode: 404,
+            responseBody: { error: 'not_found' },
+            path: url.pathname,
+        };
+    }
+    const allowedMethods = route ? allowedMethodsForRoute(route, collaborationRoutesEnabled) : [];
+    const methodAllowed = allowedMethods.includes(method);
+    if (!methodAllowed) {
+        return {
+            reason: 'method-not-allowed',
+            statusCode: 405,
+            responseBody: { error: 'method_not_allowed' },
+            allowHeader: allowedMethods.join(', '),
+            path: url.pathname,
+        };
+    }
+    if (route?.resource === 'health') {
+        return {
+            reason: 'authorized',
+            statusCode: 200,
+            responseBody: { status: 'ok' },
+            route,
+            path: url.pathname,
+        };
+    }
+    const token = parseBearerToken(input.request.headers.authorization);
+    if (!token) {
+        return {
+            reason: 'missing-or-invalid-token',
+            statusCode: 401,
+            responseBody: { error: 'missing_or_invalid_token' },
+            path: url.pathname,
+        };
+    }
+    const binding = input.lookup(token);
+    if (!binding) {
+        return {
+            reason: 'invalid-token',
+            statusCode: 401,
+            responseBody: { error: 'invalid_token' },
+            path: url.pathname,
+            token,
+        };
+    }
+    if ('channelId' in route && binding.channelId !== route.channelId) {
+        return {
+            reason: 'channel-mismatch',
+            statusCode: 403,
+            responseBody: { error: 'channel_mismatch' },
+            binding,
+            route,
+            path: url.pathname,
+            token,
+        };
+    }
+    if (route.resource === 'bootstrap' && !binding.payloadAvailable) {
+        return {
+            reason: 'bootstrap-unavailable',
+            statusCode: 404,
+            responseBody: { error: 'bootstrap_unavailable' },
+            binding,
+            route,
+            path: url.pathname,
+            token,
+        };
+    }
+    return {
+        reason: 'authorized',
+        statusCode: 200,
+        binding,
+        route,
+        path: url.pathname,
+        token,
+    };
+}

package/dist/providers/awaiting-user.d.ts

@@ -0,0 +1,12 @@
+import type { ProviderGenerateOptions, ProviderReply } from '../types.js';
+export declare const HOST_CONTROL_PREFIX = "[[BORGEE_CONTROL]] ";
+export declare const AWAITING_USER_CONTROL_PREFIX = "[[BORGEE_CONTROL]] ";
+export declare function parseProviderReply(text: string): ProviderReply;
+export declare function sanitizeAwaitingUserProgressText(text: string): string;
+export declare class AwaitingUserProgressSanitizer {
+    private readonly onProgress?;
+    private lastPublished;
+    constructor(onProgress?: ProviderGenerateOptions['onProgress']);
+    publish(text: string): void;
+}
+export declare function createAwaitingUserProgressHandler(onProgress?: ProviderGenerateOptions['onProgress']): ProviderGenerateOptions['onProgress'] | undefined;