@borgee/agents-host 0.2.101 → 0.2.110

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

@@ -0,0 +1,26 @@
+import { type Static } from '@sinclair/typebox';
+export declare const AgentToolResultJson: import("@sinclair/typebox").TRecursive<import("@sinclair/typebox").TUnion<[import("@sinclair/typebox").TNull, import("@sinclair/typebox").TBoolean, import("@sinclair/typebox").TNumber, import("@sinclair/typebox").TString, import("@sinclair/typebox").TArray<import("@sinclair/typebox").TThis>, import("@sinclair/typebox").TRecord<import("@sinclair/typebox").TString, import("@sinclair/typebox").TThis>]>>;
+export type AgentToolResultJson = Static<typeof AgentToolResultJson>;
+export declare const AgentToolResultContent: import("@sinclair/typebox").TUnion<[import("@sinclair/typebox").TObject<{
+    type: import("@sinclair/typebox").TLiteral<"text">;
+    text: import("@sinclair/typebox").TString;
+    stream: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TUnion<[import("@sinclair/typebox").TLiteral<"stdout">, import("@sinclair/typebox").TLiteral<"stderr">, import("@sinclair/typebox").TLiteral<"combined">]>>;
+}>, import("@sinclair/typebox").TObject<{
+    type: import("@sinclair/typebox").TLiteral<"json">;
+    value: import("@sinclair/typebox").TRecursive<import("@sinclair/typebox").TUnion<[import("@sinclair/typebox").TNull, import("@sinclair/typebox").TBoolean, import("@sinclair/typebox").TNumber, import("@sinclair/typebox").TString, import("@sinclair/typebox").TArray<import("@sinclair/typebox").TThis>, import("@sinclair/typebox").TRecord<import("@sinclair/typebox").TString, import("@sinclair/typebox").TThis>]>>;
+}>]>;
+export type AgentToolResultContent = Static<typeof AgentToolResultContent>;
+export declare const AgentToolResult: import("@sinclair/typebox").TObject<{
+    content: import("@sinclair/typebox").TArray<import("@sinclair/typebox").TUnion<[import("@sinclair/typebox").TObject<{
+        type: import("@sinclair/typebox").TLiteral<"text">;
+        text: import("@sinclair/typebox").TString;
+        stream: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TUnion<[import("@sinclair/typebox").TLiteral<"stdout">, import("@sinclair/typebox").TLiteral<"stderr">, import("@sinclair/typebox").TLiteral<"combined">]>>;
+    }>, import("@sinclair/typebox").TObject<{
+        type: import("@sinclair/typebox").TLiteral<"json">;
+        value: import("@sinclair/typebox").TRecursive<import("@sinclair/typebox").TUnion<[import("@sinclair/typebox").TNull, import("@sinclair/typebox").TBoolean, import("@sinclair/typebox").TNumber, import("@sinclair/typebox").TString, import("@sinclair/typebox").TArray<import("@sinclair/typebox").TThis>, import("@sinclair/typebox").TRecord<import("@sinclair/typebox").TString, import("@sinclair/typebox").TThis>]>>;
+    }>]>>;
+    exitCode: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TInteger>;
+    durationMs: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TNumber>;
+    truncated: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TBoolean>;
+}>;
+export type AgentToolResult = Static<typeof AgentToolResult>;

package/dist/native-protocol-types/uplink.d.ts

@@ -0,0 +1,56 @@
+import { type Static } from '@sinclair/typebox';
+import type { WireDecodeResult, WireEncodeResult } from './codec.js';
+export declare const UPLINK_VERSION = 1;
+export declare const UPLINK_MAX_FRAME_BYTES: number;
+export declare const UPLINK_MAX_PUBLIC_REQUEST_BYTES: number;
+export declare const UplinkMessage: import("@sinclair/typebox").TUnion<[import("@sinclair/typebox").TObject<{
+    uplinkVersion: import("@sinclair/typebox").TLiteral<1>;
+    type: import("@sinclair/typebox").TLiteral<"register">;
+    agentId: import("@sinclair/typebox").TString;
+}>, import("@sinclair/typebox").TObject<{
+    uplinkVersion: import("@sinclair/typebox").TLiteral<1>;
+    type: import("@sinclair/typebox").TLiteral<"registered">;
+    agentId: import("@sinclair/typebox").TString;
+}>, import("@sinclair/typebox").TObject<{
+    type: import("@sinclair/typebox").TLiteral<"rpc_request">;
+    method: import("@sinclair/typebox").TUnion<[import("@sinclair/typebox").TLiteral<"GET">, import("@sinclair/typebox").TLiteral<"POST">]>;
+    path: import("@sinclair/typebox").TString;
+    body: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
+    uplinkVersion: import("@sinclair/typebox").TLiteral<1>;
+    requestId: import("@sinclair/typebox").TString;
+}>, import("@sinclair/typebox").TObject<{
+    type: import("@sinclair/typebox").TLiteral<"rpc_response">;
+    status: import("@sinclair/typebox").TInteger;
+    body: import("@sinclair/typebox").TString;
+    uplinkVersion: import("@sinclair/typebox").TLiteral<1>;
+    requestId: import("@sinclair/typebox").TString;
+}>, import("@sinclair/typebox").TObject<{
+    type: import("@sinclair/typebox").TLiteral<"rpc_cancel">;
+    uplinkVersion: import("@sinclair/typebox").TLiteral<1>;
+    requestId: import("@sinclair/typebox").TString;
+}>, import("@sinclair/typebox").TObject<{
+    type: import("@sinclair/typebox").TLiteral<"stream_open">;
+    uplinkVersion: import("@sinclair/typebox").TLiteral<1>;
+    streamId: import("@sinclair/typebox").TString;
+}>, import("@sinclair/typebox").TObject<{
+    type: import("@sinclair/typebox").TLiteral<"stream_opened">;
+    uplinkVersion: import("@sinclair/typebox").TLiteral<1>;
+    streamId: import("@sinclair/typebox").TString;
+}>, import("@sinclair/typebox").TObject<{
+    type: import("@sinclair/typebox").TLiteral<"stream_message">;
+    message: import("@sinclair/typebox").TString;
+    uplinkVersion: import("@sinclair/typebox").TLiteral<1>;
+    streamId: import("@sinclair/typebox").TString;
+}>, import("@sinclair/typebox").TObject<{
+    type: import("@sinclair/typebox").TLiteral<"stream_close">;
+    code: import("@sinclair/typebox").TUnion<[...import("@sinclair/typebox").TLiteral<number>[], import("@sinclair/typebox").TInteger]>;
+    reason: import("@sinclair/typebox").TString;
+    uplinkVersion: import("@sinclair/typebox").TLiteral<1>;
+    streamId: import("@sinclair/typebox").TString;
+}>]>;
+export type UplinkMessage = Static<typeof UplinkMessage>;
+export type UplinkBrokerMessage = Extract<UplinkMessage, {
+    type: 'registered' | 'rpc_request' | 'rpc_cancel' | 'stream_open' | 'stream_message' | 'stream_close';
+}>;
+export declare function decodeUplinkMessage(json: string): WireDecodeResult<UplinkMessage>;
+export declare function encodeUplinkMessage(value: UplinkMessage): WireEncodeResult;

package/dist/native-protocol-types/version.d.ts

@@ -0,0 +1,5 @@
+import { type Static } from '@sinclair/typebox';
+export declare const BORGEE_AGENT_REMOTE_PROTOCOL_VERSION = "1.7.0";
+export declare const PROTOCOL_VERSION = "1.7.0";
+export declare const ProtocolVersionSchema: import("@sinclair/typebox").TLiteral<"1.7.0">;
+export type ProtocolVersionSchema = Static<typeof ProtocolVersionSchema>;

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

@@ -0,0 +1,51 @@
+import type { AgentInteractionRequest, AgentInteractionResponse } from './control.js';
+import type { AgentStreamEvent } from './observation.js';
+export interface AgentCommand {
+    id: string;
+    name: string;
+    description: string;
+    kind: 'command' | 'skill' | 'prompt';
+    inputHint?: string;
+    shortDescription?: string;
+    /** Provider-owned resource locator for read-only command documentation. */
+    documentation?: string;
+}
+export interface AgentCommandResult {
+    text?: string;
+    /** This invocation admitted native turn work; completion remains on observe(). */
+    execution?: 'turn';
+    /** Turn identity returned by the native transport. */
+    turnId?: string;
+    /** Actual native input protocol identity, including caller-assigned message IDs. */
+    messageId?: string;
+}
+/** The invocation was rejected before any native side effect or turn admission. */
+export declare class AgentCommandRejectedError extends Error {
+    constructor(message: string);
+}
+export declare function validateCommandDirectory(commands: AgentCommand[]): AgentCommand[];
+type CommandRequest = Omit<Extract<AgentInteractionRequest, {
+    kind: 'question';
+}>, 'requestId'> | Omit<Extract<AgentInteractionRequest, {
+    kind: 'form';
+}>, 'requestId'>;
+interface PendingCommandInteraction {
+    request: AgentInteractionRequest;
+    handler(response: AgentInteractionResponse): Promise<void>;
+    submitting: boolean;
+}
+/** Command menus share the same response validation and events as native interactions. */
+export declare class CommandInteractions {
+    private readonly provider;
+    private readonly emit;
+    private readonly requests;
+    private readonly prefix;
+    private sequence;
+    constructor(provider: string, emit: (event: AgentStreamEvent) => void);
+    get pending(): boolean;
+    pendingInteractions(): AgentInteractionRequest[];
+    open(request: CommandRequest, handler: PendingCommandInteraction['handler']): string;
+    respond(requestId: string, response: AgentInteractionResponse): Promise<boolean>;
+    clear(): void;
+}
+export {};

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

@@ -0,0 +1,192 @@
+export type AgentPlanAction = 'approve' | 'approve_and_resume' | 'reject';
+export type AgentToolDecision = 'allow' | 'deny' | 'cancel';
+export type AgentToolApprovalScope = 'once' | 'session' | 'policy';
+export type AgentToolDetail = {
+    type: 'shell';
+    command: string;
+    cwd?: string;
+} | {
+    type: 'read';
+    filePath: string;
+} | {
+    type: 'edit';
+    filePath: string;
+} | {
+    type: 'write';
+    filePath: string;
+} | {
+    type: 'search';
+    query: string;
+} | {
+    type: 'fetch';
+    url: string;
+} | {
+    type: 'other';
+    description: string;
+};
+export interface AgentQuestionOption {
+    value: string;
+    label: string;
+    description?: string;
+}
+export interface AgentQuestion {
+    questionId: string;
+    header: string;
+    prompt: string;
+    description?: string;
+    required: boolean;
+    selection: 'single' | 'multiple';
+    options: AgentQuestionOption[];
+    allowCustomText: boolean;
+    allowDismiss: boolean;
+    sensitive?: boolean;
+}
+export interface AgentFormOption {
+    value: string;
+    label: string;
+}
+interface AgentFormFieldBase {
+    fieldId: string;
+    label: string;
+    required: boolean;
+    description?: string;
+    sensitive?: boolean;
+}
+export type AgentFormField = AgentFormFieldBase & ({
+    type: 'text';
+    minLength?: number;
+    maxLength?: number;
+    format?: 'email' | 'uri' | 'date' | 'date-time';
+    defaultValue?: string;
+} | {
+    type: 'number';
+    integer?: boolean;
+    minimum?: number;
+    maximum?: number;
+    defaultValue?: number;
+} | {
+    type: 'boolean';
+    defaultValue?: boolean;
+} | {
+    type: 'select';
+    options: AgentFormOption[];
+    defaultValue?: string;
+} | {
+    type: 'multiselect';
+    options: AgentFormOption[];
+    minItems?: number;
+    maxItems?: number;
+    defaultValue?: string[];
+});
+export type AgentFormValue = string | number | boolean | string[];
+export type AgentFormValues = Record<string, AgentFormValue>;
+export type AgentPermissionScope = 'turn' | 'session';
+export interface AgentPermission {
+    resource: 'filesystem' | 'network';
+    access: 'read' | 'write' | 'deny' | 'connect';
+    target: string;
+}
+export type AgentInteractionRequest = {
+    kind: 'question';
+    requestId: string;
+    questions: AgentQuestion[];
+} | {
+    kind: 'plan_approval';
+    requestId: string;
+    plan: string;
+    allowedActions: AgentPlanAction[];
+} | {
+    kind: 'tool_approval';
+    requestId: string;
+    toolCallId: string;
+    toolName: string;
+    summary: string;
+    detail: AgentToolDetail;
+    allowedDecisions: AgentToolDecision[];
+    allowScopes: AgentToolApprovalScope[];
+    policies?: {
+        policyId: string;
+        description: string;
+    }[];
+    context?: {
+        label: string;
+        value: string;
+    }[];
+} | {
+    kind: 'form';
+    requestId: string;
+    title: string;
+    message: string;
+    fields: AgentFormField[];
+} | {
+    kind: 'permission_approval';
+    requestId: string;
+    summary: string;
+    permissions: AgentPermission[];
+    allowScopes: AgentPermissionScope[];
+} | {
+    kind: 'external_action';
+    requestId: string;
+    title: string;
+    message: string;
+    url: string;
+};
+export interface AgentQuestionAnswer {
+    questionId: string;
+    selectedValues: string[];
+    customText?: string;
+    redacted?: boolean;
+}
+/** Answers are ordinary visible user input, not a pending tool response. */
+export interface AgentQuestionnaireResponse {
+    messageId: string;
+    answers: AgentQuestionAnswer[];
+}
+/** Asynchronous questionnaires do not provide sensitive-input handling. */
+export type AgentQuestionnaireQuestion = Omit<AgentQuestion, 'sensitive'> & {
+    sensitive?: false;
+};
+export type AgentInteractionResponse = {
+    kind: 'question';
+    answers: AgentQuestionAnswer[];
+    dismissed?: boolean;
+} | {
+    kind: 'plan_approval';
+    action: 'approve' | 'approve_and_resume';
+} | {
+    kind: 'plan_approval';
+    action: 'reject';
+    feedback?: string;
+} | {
+    kind: 'tool_approval';
+    decision: 'allow';
+    scope: 'once' | 'session';
+} | {
+    kind: 'tool_approval';
+    decision: 'allow';
+    scope: 'policy';
+    policyId: string;
+} | {
+    kind: 'tool_approval';
+    decision: 'deny' | 'cancel';
+    message?: string;
+} | {
+    kind: 'form';
+    action: 'submit';
+    values: AgentFormValues;
+    redactedFields?: string[];
+} | {
+    kind: 'form';
+    action: 'decline' | 'cancel';
+} | {
+    kind: 'permission_approval';
+    decision: 'allow';
+    scope: AgentPermissionScope;
+} | {
+    kind: 'permission_approval';
+    decision: 'deny';
+} | {
+    kind: 'external_action';
+    action: 'completed' | 'decline' | 'cancel';
+};
+export {};

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

@@ -0,0 +1,9 @@
+import { type AgentToolResult } from './tool-result.js';
+export interface AgentFileChange {
+    path: string;
+    kind: 'added' | 'modified' | 'deleted' | 'renamed' | 'unknown';
+    previousPath?: string;
+    diff: string;
+}
+/** A versioned presentation format within the existing JSON result channel. */
+export declare function fileChangesResult(files: AgentFileChange[]): AgentToolResult;

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

@@ -0,0 +1,8 @@
+export * from './control.js';
+export * from './interactions.js';
+export * from './observation.js';
+export * from './provider.js';
+export * from './tool-result.js';
+export * from './file-changes.js';
+export * from './session-settings.js';
+export * from './commands.js';

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

@@ -0,0 +1,7 @@
+import type { AgentInteractionRequest, AgentInteractionResponse } from './control.js';
+/** Validates a command against exactly the choices displayed by its pending request. */
+export declare function validateInteractionResponse(request: AgentInteractionRequest, response: AgentInteractionResponse): void;
+/** Produces a detached public request without publishing sensitive field defaults. */
+export declare function redactInteractionRequest(request: AgentInteractionRequest): AgentInteractionRequest;
+/** Produces a detached historical receipt; sensitive values belong only in the provider command. */
+export declare function redactInteractionResponse(request: AgentInteractionRequest, response: AgentInteractionResponse): AgentInteractionResponse;

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

@@ -0,0 +1,209 @@
+import type { AgentToolResult } from './tool-result.js';
+import type { AgentInteractionRequest, AgentInteractionResponse, AgentQuestionnaireQuestion, AgentQuestionnaireResponse, AgentToolDetail } from './control.js';
+export interface AgentTaskItem {
+    text: string;
+    completed: boolean;
+    id?: string;
+    status?: 'pending' | 'in_progress' | 'completed';
+    activeForm?: string;
+}
+interface AgentToolCallBase {
+    type: 'tool_call';
+    callId: string;
+    name: string;
+    detail: AgentToolDetail;
+    result?: AgentToolResult;
+}
+export type AgentToolCallTimelineItem = AgentToolCallBase & ({
+    status: 'running';
+    error: null;
+} | {
+    status: 'completed';
+    error: null;
+} | {
+    status: 'failed';
+    error: string;
+} | {
+    status: 'canceled';
+    error: null;
+});
+export type AgentTimelineItem = {
+    type: 'user_message';
+    text: string;
+    messageId?: string;
+    clientMessageId?: string;
+    origin?: {
+        kind: 'borgee' | 'native' | 'agent' | 'unknown';
+    };
+    questionnaireResponse?: AgentQuestionnaireResponse;
+} | {
+    type: 'assistant_message';
+    text: string;
+    messageId?: string;
+} | {
+    type: 'questionnaire';
+    messageId: string;
+    text: string;
+    questions: AgentQuestionnaireQuestion[];
+} | {
+    type: 'reasoning';
+    text: string;
+} | AgentToolCallTimelineItem | {
+    type: 'todo';
+    items: AgentTaskItem[];
+} | {
+    type: 'interaction';
+    request: AgentInteractionRequest;
+    response: AgentInteractionResponse;
+} | {
+    type: 'error';
+    message: string;
+} | {
+    type: 'compaction';
+    status: 'loading' | 'completed';
+    trigger?: 'auto' | 'manual';
+    preTokens?: number;
+};
+/** An immutable, settled delta. Token buckets are disjoint; input excludes cache. */
+export interface AgentUsageAccounting {
+    measurementId: string;
+    scope: 'turn' | 'llm_call';
+    provider: string;
+    model: string;
+    inputTokens: number;
+    outputTokens: number;
+    cacheReadTokens: number;
+    cacheWriteTokens: number;
+}
+export interface AgentUsage {
+    /** Absent when turn attribution or required counters cannot be proven; unknown API routes use provider "unknown". */
+    accounting?: AgentUsageAccounting[];
+    inputTokens?: number;
+    cachedInputTokens?: number;
+    outputTokens?: number;
+    totalCostUsd?: number;
+    contextWindowMaxTokens?: number;
+    contextWindowUsedTokens?: number;
+}
+export interface AgentPlanningState {
+    active: boolean;
+    requested?: boolean;
+}
+/** A direct native child, with stable creation provenance when the runtime provides it. */
+export interface AgentChildSession {
+    nativeSessionId: string;
+    title: string;
+    role?: string;
+    description?: string;
+    createdAt: string;
+    parentTurnId?: string;
+    parentCallId?: string;
+    status: 'starting' | 'idle' | 'running' | 'waiting' | 'failed' | 'closed';
+    observation: 'live' | 'saved_history';
+}
+export interface AgentRuntimeInfo {
+    providerId: string;
+    sessionId: string | null;
+    status: 'starting' | 'idle' | 'running' | 'waiting' | 'failed' | 'closed';
+    cwd?: string;
+    model?: string | null;
+    mode?: string | null;
+    planning?: AgentPlanningState;
+    settings?: import('./session-settings.js').AgentSessionSetting[];
+    childSessions?: AgentChildSession[];
+    persistence?: import('./provider.js').AgentPersistenceHandle;
+}
+export type AgentStreamEvent = {
+    type: 'thread_started';
+    sessionId: string;
+    provider: string;
+} | {
+    type: 'turn_started';
+    provider: string;
+    turnId?: string;
+} | {
+    type: 'turn_completed';
+    provider: string;
+    usage?: AgentUsage;
+    turnId?: string;
+} | {
+    type: 'turn_failed';
+    provider: string;
+    error: string;
+    code?: string;
+    diagnostic?: string;
+    turnId?: string;
+} | {
+    type: 'turn_canceled';
+    provider: string;
+    reason: string;
+    turnId?: string;
+} | {
+    type: 'timeline';
+    provider: string;
+    item: AgentTimelineItem;
+    turnId?: string;
+} | {
+    type: 'usage_updated';
+    provider: string;
+    usage: AgentUsage;
+    turnId?: string;
+} | {
+    type: 'runtime_updated';
+    provider: string;
+    runtimeInfo: AgentRuntimeInfo;
+} | {
+    type: 'interaction_requested';
+    provider: string;
+    request: AgentInteractionRequest;
+    turnId?: string;
+} | {
+    type: 'interaction_resolved';
+    provider: string;
+    requestId: string;
+    response: AgentInteractionResponse;
+    turnId?: string;
+};
+export interface ProviderResourceReference {
+    locator: string;
+    readLocator: string;
+}
+export interface ProviderObservation {
+    type: 'observation';
+    sourceKey: string;
+    occurredAt: number;
+    nativeRevision?: number;
+    delivery: 'history' | 'live';
+    event: AgentStreamEvent;
+    resourceReferences?: ProviderResourceReference[];
+}
+/** Ends historical delivery; complete-state providers establish authority with a following session_restored. */
+export interface ProviderHistoryBoundary {
+    type: 'history_boundary';
+}
+/** Complete, ordered Timeline correction after readiness. Runtime state is unaffected. */
+export interface ProviderTimelineReplacement {
+    type: 'timeline_replacement';
+    observations: ProviderObservation[];
+}
+/** Retires connection-owned interactions without changing native execution or capabilities. */
+export interface ProviderSessionInvalidated {
+    type: 'session_invalidated';
+    recovery: 'retrying' | 'stopped';
+    /** Bounded provider reason code, never a raw native diagnostic. */
+    reason: string;
+}
+/** Atomic complete native state and ordered history evidence on initial attachment or restoration of the same Session. */
+export interface ProviderSessionRestored {
+    type: 'session_restored';
+    runtimeInfo: AgentRuntimeInfo;
+    capabilities: import('./provider.js').AgentCapabilities;
+    activeTurn: {
+        turnId: string;
+        startedAt?: string;
+    } | null;
+    pendingInteractions: AgentInteractionRequest[];
+    observations: ProviderObservation[];
+}
+export type ProviderStreamItem = ProviderObservation | ProviderHistoryBoundary | ProviderTimelineReplacement | ProviderSessionInvalidated | ProviderSessionRestored;
+export {};