@borgee/agents-host 0.2.101 → 0.2.110

package/dist/native-provider-types/provider.d.ts

@@ -0,0 +1,124 @@
+import type { AgentInteractionResponse } from './control.js';
+import type { AgentRuntimeInfo, ProviderStreamItem } from './observation.js';
+export interface AgentCapabilities {
+    history: boolean;
+    sendMessage: boolean;
+    queueMessage?: boolean;
+    steer: boolean;
+    cancel: boolean;
+    /** The session can return content for supported resource locators; this does not imply arbitrary URI access or inline rendering. */
+    readResource: boolean;
+    sessionSettings?: boolean;
+    commands?: boolean;
+    planning?: boolean;
+    interactions: {
+        question: boolean;
+        planApproval: boolean;
+        toolApproval: boolean;
+        form?: boolean;
+        permissionApproval?: boolean;
+        externalAction?: boolean;
+    };
+}
+export interface AgentProviderDescriptor {
+    providerId: string;
+    displayName: string;
+    /** Emits a complete session_restored state after the history boundary, before admitting live observation or input. */
+    sessionObservation?: 'complete-state';
+    /** Explicit input operations with receipt and expected-turn semantics. */
+    sessionInputOperations?: readonly ('start_turn' | 'steer' | 'next_turn')[];
+}
+export interface AgentPersistenceHandle {
+    providerId: string;
+    sessionId: string;
+    opaque: string;
+}
+/** An adapter-confirmed ownership conflict, with a message safe for remote clients. */
+export declare class AgentSessionInUseError extends Error {
+    constructor(message: string);
+}
+export interface AgentSessionConfig {
+    sessionId: string;
+    cwd?: string;
+    /** Extra native working-directory roots, still subject to native tool permissions. Unsupported providers reject this option. */
+    additionalDirectories?: string[];
+    model?: string;
+    reasoningEffort?: string;
+    systemPrompt?: string;
+    planning?: boolean;
+}
+export interface AgentSessionResumeOptions {
+    /** Replaces saved directory roots; an empty array clears them and undefined preserves them. Unsupported providers reject a supplied value. */
+    additionalDirectories?: string[];
+}
+export interface AgentProviderAdapter {
+    readonly descriptor: AgentProviderDescriptor;
+    createSession(config: AgentSessionConfig): Promise<AgentSession>;
+    resumeSession(handle: AgentPersistenceHandle, options?: AgentSessionResumeOptions): Promise<AgentSession>;
+    /** Opens an observed direct child of a loaded parent; never discovers or resumes arbitrary sessions. */
+    openChildSession?(parentNativeSessionId: string, childNativeSessionId: string): Promise<AgentSession>;
+    /** Releases provider resources after every owned session has been disposed. */
+    dispose?(): Promise<void>;
+}
+export interface AgentMessageOptions {
+    /** Native context fragments, separate from user content and admitted only with a new idle turn. Never implicitly steers; unsupported providers reject a supplied value. */
+    additionalContext?: Record<string, {
+        kind: 'application' | 'untrusted';
+        value: string;
+    }>;
+    /** Opaque caller input identity echoed by a supporting native transport. */
+    clientMessageId?: string;
+    /** Immediate input joins active work; next_turn uses the native follow-up queue. */
+    delivery?: 'immediate' | 'next_turn';
+    /** Refuses input unless the provider can admit a new native turn without steering active work. */
+    requireIdle?: boolean;
+}
+export type AgentMessageReceipt = {
+    /** Native message identity shared with the normalized user_message item. */
+    messageId?: string;
+    /** Native accepted turn identity; distinct from the input message identity. */
+    turnId?: string;
+} & ({
+    messageId: string;
+} | {
+    turnId: string;
+});
+export interface AgentSteerOptions {
+    /** Opaque caller input identity echoed by a supporting native transport. */
+    clientMessageId?: string;
+    /** Captured normalized turn identity; a mismatch must not start another turn. */
+    expectedTurnId?: string;
+}
+/** Native input was refused before admission; retry is a caller decision. */
+export declare class AgentInputRejectedError extends Error {
+    readonly reason?: "context_unavailable" | undefined;
+    constructor(message: string, reason?: "context_unavailable" | undefined);
+}
+export interface AgentSession {
+    readonly capabilities: AgentCapabilities;
+    /** A session observation may span turn completion and saved/live descriptor transitions; iterator termination means this observer ended. */
+    observe(): AsyncIterable<ProviderStreamItem>;
+    sendMessage(text: string, options?: AgentMessageOptions): Promise<void | AgentMessageReceipt>;
+    /** Native pending input message identities; unavailable or ambiguous snapshots reject. */
+    listPendingInputs?(): Promise<string[]>;
+    respondToInteraction(requestId: string, response: AgentInteractionResponse): Promise<void>;
+    steer?(text: string, options?: AgentSteerOptions): Promise<void | AgentMessageReceipt>;
+    cancel?(): Promise<void>;
+    setPlanning?(active: boolean): Promise<void>;
+    setSessionSetting?(id: string, value: string): Promise<void>;
+    listCommands?(): Promise<import('./commands.js').AgentCommand[]>;
+    executeCommand?(id: string, args: string): Promise<import('./commands.js').AgentCommandResult>;
+    /** Reads within this session's supported resource scope; unavailable resources return an unavailable result. */
+    readResource?(locator: string): Promise<AgentResourceReadResult>;
+    runtimeInfo(): Promise<AgentRuntimeInfo>;
+    /** Releases this observer's resources without implying cancellation of separately owned native execution. */
+    dispose(): Promise<void>;
+}
+export type AgentResourceReadResult = {
+    status: 'available';
+    bytes: Uint8Array;
+    mediaType: string;
+} | {
+    status: 'unavailable';
+    reason: string;
+};

package/dist/native-provider-types/session-settings.d.ts

@@ -0,0 +1,17 @@
+export interface AgentSessionSettingOption {
+    value: string;
+    label: string;
+    description?: string;
+}
+/** A native selection; values are opaque outside the declaring Provider. */
+export interface AgentSessionSetting {
+    id: string;
+    category: 'model' | 'permissions';
+    label: string;
+    value: string | null;
+    options: AgentSessionSettingOption[];
+    mutable: boolean;
+    scope: 'session' | 'session_and_default';
+    description?: string;
+}
+export declare function validateSessionSetting(settings: readonly AgentSessionSetting[] | undefined, id: string, value: string): AgentSessionSetting;

package/dist/native-provider-types/testing.d.ts

@@ -0,0 +1,27 @@
+import type { AgentSession, ProviderObservation, ProviderStreamItem } from './index.js';
+import type { AgentProviderAdapter, AgentSessionConfig } from './index.js';
+export interface CollectedProviderStream {
+    history: ProviderObservation[];
+    live: ProviderObservation[];
+    boundary: Extract<ProviderStreamItem, {
+        type: 'history_boundary';
+    }>;
+    replacements: Extract<ProviderStreamItem, {
+        type: 'timeline_replacement';
+    }>[];
+    initialState?: Extract<ProviderStreamItem, {
+        type: 'session_restored';
+    }>;
+}
+export declare function collectProviderStream(session: AgentSession, liveCount: number, observationContract?: 'complete-state'): Promise<CollectedProviderStream>;
+export declare function validateAgentSessionCapabilities(session: AgentSession): void;
+export interface AgentProviderContractFixture {
+    adapter: AgentProviderAdapter;
+    createConfig: AgentSessionConfig;
+    expected: {
+        providerId: string;
+        historyCount: number;
+        liveCount: number;
+    };
+}
+export declare function runAgentProviderContractTests(name: string, factory: () => Promise<AgentProviderContractFixture>): void;

package/dist/native-provider-types/tool-result.d.ts

@@ -0,0 +1,21 @@
+export type AgentToolResultJson = null | boolean | number | string | AgentToolResultJson[] | {
+    [key: string]: AgentToolResultJson;
+};
+export type AgentToolResultContent = {
+    type: 'text';
+    text: string;
+    stream?: 'stdout' | 'stderr' | 'combined';
+} | {
+    type: 'json';
+    value: AgentToolResultJson;
+};
+export interface AgentToolResult {
+    content: AgentToolResultContent[];
+    exitCode?: number;
+    durationMs?: number;
+    truncated?: boolean;
+}
+export declare const TOOL_RESULT_MAX_CHARS: number;
+export declare const TOOL_RESULT_MAX_BLOCKS = 128;
+/** Result bodies are bounded snapshots; consumers replace them instead of appending. */
+export declare function boundToolResult(result: AgentToolResult): AgentToolResult;

package/dist/native-providers.d.ts

@@ -0,0 +1,21 @@
+import type { AgentInteractionResponse, AgentProviderAdapter, AgentSession } from "./native-provider-types/index.js";
+export { AgentCommandRejectedError, AgentInputRejectedError, AgentSessionInUseError, redactInteractionRequest, redactInteractionResponse, validateInteractionResponse as validateNativeInteractionResponse } from "./native-provider-types/index.js";
+export type { AgentTimelineItem, AgentQuestionnaireResponse, AgentCapabilities, AgentInteractionRequest, AgentInteractionResponse, AgentMessageReceipt, AgentPersistenceHandle, AgentProviderAdapter, AgentRuntimeInfo, AgentSession, AgentStreamEvent, ProviderObservation, ProviderStreamItem, ProviderSessionRestored } from "./native-provider-types/index.js";
+export { decodeAgentSnapshot } from "./native-protocol-types/index.js";
+export type { AgentSnapshot } from "./native-protocol-types/index.js";
+export declare function createHostedNativeProvider(provider: 'claude' | 'codex' | 'copilot', executable?: string, codex?: {
+    codexConnectionMode?: 'shared' | 'stdio';
+    codexSharedSocketPath?: string;
+    codexTrustShared?: boolean;
+}): AgentProviderAdapter;
+export declare function configureHostedNativeSession(session: AgentSession, provider: string): Promise<void>;
+export declare const PROTOCOL_VERSION = "1.7.0";
+export declare function isInteractionResponseMessage(value: unknown): value is {
+    protocolVersion: string;
+    type: 'interaction_response';
+    payload: {
+        agentId: string;
+        requestId: string;
+        response: AgentInteractionResponse;
+    };
+};