@borgee/agents-host 0.2.2 → 0.2.28

package/dist/context/turn-preparation.d.ts

@@ -0,0 +1,9 @@
+import { type DebugLogger } from '../debug.js';
+import type { PreparedProviderTurnInput, ProviderInput } from '../types.js';
+import { type ChannelContextStore } from './injection.js';
+export declare class ProviderTurnPreparer {
+    private readonly channelContextStore?;
+    private readonly logger;
+    constructor(channelContextStore?: ChannelContextStore | undefined, logger?: DebugLogger);
+    prepare(input: ProviderInput): Promise<PreparedProviderTurnInput>;
+}

package/dist/context/turn-preparation.js

@@ -0,0 +1,135 @@
+import { HostLogger, summarizeError } from '../debug.js';
+import { ChannelContextPreparationError, } from './injection.js';
+import { buildPrompt } from './prompt.js';
+function providerLabel(provider) {
+    if (provider === 'copilot') {
+        return 'Copilot';
+    }
+    if (provider === 'codex') {
+        return 'Codex';
+    }
+    return 'Claude';
+}
+function toPromptContext(channelContext, input) {
+    if (!channelContext
+        && !input.collaboration
+        && !input.collaborationOutcome
+        && !input.attentionSnapshot
+        && !input.collaborationCapabilities
+        && !input.missedCollaborationDiagnostic
+        && !input.taskThreadCollaborationContract) {
+        return undefined;
+    }
+    return {
+        ...(channelContext
+            ? {
+                channelContextPayloadPath: channelContext.payloadPath,
+                gatewayAuthPath: channelContext.gatewayAuthPath,
+                skillRuntime: channelContext.skillRuntime,
+                localhostGateway: channelContext.localhostGateway,
+                taskAssignmentContext: channelContext.payload.taskAssignmentContext,
+                taskWorkspace: channelContext.taskWorkspace,
+            }
+            : {}),
+        collaborationTurnExecutionId: input.collaboration?.turnExecutionId,
+        collaborationTurnMode: input.collaboration?.turnMode,
+        collaborationOutcome: input.collaborationOutcome ?? channelContext?.payload.collaborationOutcome,
+        attentionSnapshot: input.attentionSnapshot ?? channelContext?.payload.attentionSnapshot,
+        ...(() => {
+            const collaborationCapabilities = input.collaborationCapabilities ?? channelContext?.payload.collaborationCapabilities;
+            return collaborationCapabilities ? { collaborationCapabilities } : {};
+        })(),
+        ...(() => {
+            const missedCollaborationDiagnostic = input.missedCollaborationDiagnostic ?? channelContext?.payload.missedCollaborationDiagnostic;
+            return missedCollaborationDiagnostic ? { missedCollaborationDiagnostic } : {};
+        })(),
+        ...(input.taskThreadCollaborationContract || channelContext?.payload.taskThreadCollaborationContract
+            ? {
+                taskThreadCollaborationContract: input.taskThreadCollaborationContract
+                    ?? channelContext?.payload.taskThreadCollaborationContract,
+            }
+            : {}),
+        kickoff: input.collaboration?.kickoff,
+        protocol: input.collaboration?.protocol,
+        grounding: input.collaboration?.grounding,
+    };
+}
+function resolveProviderSessionRouting(input) {
+    const kickoff = input.collaboration?.kickoff;
+    if (input.collaboration?.turnMode === 'silent-kickoff' && kickoff) {
+        return {
+            key: `${input.channelId}::kickoff::${kickoff.anchorMessageId}`,
+            persistence: 'ephemeral',
+        };
+    }
+    return {
+        key: input.channelId,
+        persistence: 'persistent',
+    };
+}
+export class ProviderTurnPreparer {
+    channelContextStore;
+    logger;
+    constructor(channelContextStore, logger = new HostLogger()) {
+        this.channelContextStore = channelContextStore;
+        this.logger = logger;
+    }
+    async prepare(input) {
+        let channelContext;
+        if (this.channelContextStore) {
+            try {
+                const prepareInput = {
+                    channelId: input.channelId,
+                    collaboration: input.collaboration
+                        ? {
+                            ...input.collaboration,
+                            sendRoutesAllowed: input.collaboration.turnMode !== 'protocol-managed'
+                                && input.collaboration.turnMode !== 'silent-kickoff',
+                        }
+                        : undefined,
+                    collaborationOutcome: input.collaborationOutcome,
+                    attentionSnapshot: input.attentionSnapshot,
+                    collaborationCapabilities: input.collaborationCapabilities,
+                    missedCollaborationDiagnostic: input.missedCollaborationDiagnostic,
+                    ...(input.taskThreadCollaborationContract
+                        ? { taskThreadCollaborationContract: input.taskThreadCollaborationContract }
+                        : {}),
+                    ...(input.incomingMessageType !== undefined
+                        ? { incomingMessageType: input.incomingMessageType }
+                        : {}),
+                    ...(input.incomingMessageType !== undefined && input.incomingContent !== undefined
+                        ? { incomingContent: input.incomingContent }
+                        : {}),
+                };
+                channelContext = await this.channelContextStore.prepare(prepareInput);
+            }
+            catch (error) {
+                if (error instanceof ChannelContextPreparationError) {
+                    channelContext = error.partialContext;
+                }
+                this.logger.error(`failed to materialize ${providerLabel(input.provider)} channel context payload; keeping prompt delivery`, {
+                    channelId: input.channelId,
+                    error: summarizeError(error),
+                });
+            }
+        }
+        const promptContext = toPromptContext(channelContext, input);
+        return {
+            channelId: input.channelId,
+            incomingEventKind: input.incomingEventKind,
+            incomingMessageType: input.incomingMessageType,
+            prompt: buildPrompt({
+                agentName: input.agentName,
+                provider: input.provider,
+                channelId: input.channelId,
+                incomingAuthorId: input.incomingAuthorId,
+                incomingContent: input.incomingContent,
+                incomingEventKind: input.incomingEventKind,
+                incomingMessageType: input.incomingMessageType,
+                promptContext,
+            }),
+            promptContext,
+            providerSessionRouting: resolveProviderSessionRouting(input),
+        };
+    }
+}

package/dist/debug.d.ts

@@ -0,0 +1,44 @@
+export interface LoggerLike {
+    log(...args: unknown[]): void;
+    error(...args: unknown[]): void;
+}
+export interface DebugLogger {
+    readonly enabled: boolean;
+    error(message: string, details?: unknown): void;
+    debug(message: string, details?: unknown): void;
+    debugError(message: string, details?: unknown): void;
+    childStderr(label: string, summary: ChildStderrSummary): void;
+}
+export interface AgentsHostRuntimeOptions {
+    debug?: boolean;
+    logger?: LoggerLike;
+    logPrefix?: string;
+}
+export interface ChildStderrSummary {
+    bytes: number;
+    lineCount: number;
+}
+export interface SafeErrorSummary {
+    name: string;
+    messageBytes?: number;
+    messageLineCount?: number;
+    code?: number | string;
+    exitCode?: number;
+    signal?: string;
+    stderrBytes?: number;
+    stderrLineCount?: number;
+}
+export declare function resolveAgentsHostDebugMode(cliDebugFlag?: boolean, env?: NodeJS.ProcessEnv): boolean;
+export declare function summarizeChildStderr(chunk: string): ChildStderrSummary;
+export declare function summarizeError(error: unknown): SafeErrorSummary;
+export declare class HostLogger implements DebugLogger {
+    readonly enabled: boolean;
+    private readonly logger;
+    private readonly prefix;
+    constructor(options?: AgentsHostRuntimeOptions);
+    log(message: string, details?: unknown): void;
+    error(message: string, details?: unknown): void;
+    debug(message: string, details?: unknown): void;
+    debugError(message: string, details?: unknown): void;
+    childStderr(label: string, summary: ChildStderrSummary): void;
+}

package/dist/debug.js

@@ -0,0 +1,135 @@
+const DEFAULT_LOG_PREFIX = '[agents-host]';
+export function resolveAgentsHostDebugMode(cliDebugFlag = false, env = process.env) {
+    return cliDebugFlag || env.AGENTS_HOST_DEBUG?.trim() === '1';
+}
+export function summarizeChildStderr(chunk) {
+    if (chunk.length === 0) {
+        return { bytes: 0, lineCount: 0 };
+    }
+    const segments = chunk.split(/\r?\n/u);
+    return {
+        bytes: Buffer.byteLength(chunk, 'utf8'),
+        lineCount: chunk.endsWith('\n') ? segments.length - 1 : segments.length,
+    };
+}
+function asObject(value) {
+    return typeof value === 'object' && value !== null ? value : null;
+}
+function readFiniteNumber(value) {
+    return typeof value === 'number' && Number.isFinite(value) ? value : undefined;
+}
+function readNonEmptyString(value) {
+    return typeof value === 'string' && value.length > 0 ? value : undefined;
+}
+export function summarizeError(error) {
+    if (error instanceof Error) {
+        const summary = {
+            name: error.name || 'Error',
+        };
+        if (error.message.length > 0) {
+            const messageSummary = summarizeChildStderr(error.message);
+            summary.messageBytes = messageSummary.bytes;
+            summary.messageLineCount = messageSummary.lineCount;
+        }
+        const errorRecord = asObject(error);
+        const code = readFiniteNumber(errorRecord?.code) ?? readNonEmptyString(errorRecord?.code);
+        if (code !== undefined) {
+            summary.code = code;
+        }
+        const exitCode = readFiniteNumber(errorRecord?.exitCode);
+        if (exitCode !== undefined) {
+            summary.exitCode = exitCode;
+        }
+        const signal = readNonEmptyString(errorRecord?.signal);
+        if (signal !== undefined) {
+            summary.signal = signal;
+        }
+        const stderrBytes = readFiniteNumber(errorRecord?.stderrBytes);
+        if (stderrBytes !== undefined) {
+            summary.stderrBytes = stderrBytes;
+        }
+        const stderrLineCount = readFiniteNumber(errorRecord?.stderrLineCount);
+        if (stderrLineCount !== undefined) {
+            summary.stderrLineCount = stderrLineCount;
+        }
+        return summary;
+    }
+    if (typeof error === 'string') {
+        const summary = summarizeChildStderr(error);
+        return {
+            name: 'NonErrorThrow',
+            messageBytes: summary.bytes,
+            messageLineCount: summary.lineCount,
+        };
+    }
+    return {
+        name: 'NonErrorThrow',
+    };
+}
+function sanitizeDebugDetails(details, seen = new WeakSet()) {
+    if (details instanceof Error) {
+        return summarizeError(details);
+    }
+    if (Array.isArray(details)) {
+        return details.map((item) => sanitizeDebugDetails(item, seen));
+    }
+    const record = asObject(details);
+    if (record === null) {
+        return details;
+    }
+    const prototype = Object.getPrototypeOf(record);
+    if (prototype !== Object.prototype && prototype !== null) {
+        return details;
+    }
+    if (seen.has(record)) {
+        return '[Circular]';
+    }
+    seen.add(record);
+    const sanitized = {};
+    for (const [key, value] of Object.entries(record)) {
+        sanitized[key] = sanitizeDebugDetails(value, seen);
+    }
+    return sanitized;
+}
+function emit(sink, prefix, message, details) {
+    const rendered = `${prefix} ${message}`;
+    if (details === undefined) {
+        sink(rendered);
+        return;
+    }
+    sink(rendered, details);
+}
+export class HostLogger {
+    enabled;
+    logger;
+    prefix;
+    constructor(options = {}) {
+        this.enabled = options.debug === true;
+        this.logger = options.logger ?? console;
+        this.prefix = options.logPrefix?.trim() || DEFAULT_LOG_PREFIX;
+    }
+    log(message, details) {
+        emit(this.logger.log.bind(this.logger), this.prefix, message, details);
+    }
+    error(message, details) {
+        emit(this.logger.error.bind(this.logger), this.prefix, message, details);
+    }
+    debug(message, details) {
+        if (!this.enabled) {
+            return;
+        }
+        this.log(message, details);
+    }
+    debugError(message, details) {
+        if (!this.enabled) {
+            return;
+        }
+        this.error(message, details === undefined ? undefined : sanitizeDebugDetails(details));
+    }
+    childStderr(label, summary) {
+        if (!this.enabled) {
+            return;
+        }
+        this.error(`${label} summary`, summary);
+    }
+}

package/dist/gateway/localhost-gateway.d.ts

@@ -0,0 +1,52 @@
+import type { ChatControlPlane } from '../chat/chat-control-plane.js';
+import type { DebugLogger } from '../debug.js';
+import type { InternalPolicyMode } from '../compatibility-gates.js';
+import type { CollaborationDraftSnapshot } from '../types.js';
+import type { LocalhostGatewayContextPublisher } from '../context/injection.js';
+import { type ConnectionsStateStore } from '../connections-state-store.js';
+import type { AuthorizationAuditSinkLike } from '../policy/authorization-audit.js';
+export declare const LOCALHOST_GATEWAY_HISTORY_LIMIT = 20;
+export declare const LOCALHOST_GATEWAY_COLLABORATION_BODY_LIMIT_BYTES = 512;
+export declare const LOCALHOST_GATEWAY_COLLABORATION_BODY_MAX_WORDS = 12;
+export declare const LOCALHOST_GATEWAY_COLLABORATION_TARGET_COOLDOWN_MS = 5000;
+export interface GatewayCollaborationSendAuthorizationInput {
+    channelId: string;
+    turnExecutionId: string;
+    mentions: string[];
+    replyToId?: string;
+}
+export interface GatewayCollaborationSendAuthorizationResult {
+    ok: boolean;
+    statusCode: number;
+    error?: string;
+    commit?: () => void;
+    rollback?: () => void;
+}
+export interface GatewayCollaborationDraftReadInput {
+    channelId: string;
+    turnExecutionId: string;
+}
+export interface LocalhostGatewayController {
+    readonly enabled: boolean;
+    readonly contextPublisher?: LocalhostGatewayContextPublisher;
+    start(): Promise<void>;
+    stop(): Promise<void>;
+}
+interface CreateLocalhostGatewayOptions {
+    gateEnabled: boolean;
+    collaborationEnabled?: boolean;
+    tokenBindingGateEnabled?: boolean;
+    policyAuditGateEnabled?: boolean;
+    policyMode?: InternalPolicyMode;
+    controlPlane: ChatControlPlane;
+    stateRootDir?: string;
+    resolveStableAgentId?: () => string | undefined;
+    tokenBindingStore?: ConnectionsStateStore;
+    logger?: DebugLogger;
+    tokenFactory?: () => string;
+    auditSink?: AuthorizationAuditSinkLike;
+    authorizeCollaborationSend?: (input: GatewayCollaborationSendAuthorizationInput) => GatewayCollaborationSendAuthorizationResult;
+    readCollaborationDraft?: (input: GatewayCollaborationDraftReadInput) => CollaborationDraftSnapshot | null;
+}
+export declare function createLocalhostGatewayController(options: CreateLocalhostGatewayOptions): LocalhostGatewayController;
+export {};