@borgee/agents-host 0.2.44 → 0.2.56

package/dist/progress-to-activity.d.ts

@@ -0,0 +1,16 @@
+import type { AgentActivity } from './plugin-sdk.js';
+import type { ProviderProgressUpdate } from './types.js';
+/** Everything a provider reports. The turn boundary is the reporter's own and never arrives here. */
+export type ReportedActivity = Exclude<AgentActivity, {
+    shape: 'turn';
+}>;
+/**
+ * Restates one progress update in the rail's own vocabulary.
+ *
+ * This is the one part of reporting that belongs to this host rather than to the
+ * SDK: `ProviderProgressUpdate` is the seam the provider adapters speak, and
+ * nothing outside this package has it. What happens to a report afterwards —
+ * how often it may travel, what supersedes it, where a turn begins and ends —
+ * is the rail's and lives with the client.
+ */
+export declare function toReportedActivity(update: ProviderProgressUpdate): ReportedActivity | null;

package/dist/progress-to-activity.js

@@ -0,0 +1,24 @@
+/**
+ * Restates one progress update in the rail's own vocabulary.
+ *
+ * This is the one part of reporting that belongs to this host rather than to the
+ * SDK: `ProviderProgressUpdate` is the seam the provider adapters speak, and
+ * nothing outside this package has it. What happens to a report afterwards —
+ * how often it may travel, what supersedes it, where a turn begins and ends —
+ * is the rail's and lives with the client.
+ */
+export function toReportedActivity(update) {
+    switch (update.type) {
+        case 'text':
+            return { shape: 'output', stream: update.stream, text: update.text };
+        case 'plan':
+            return {
+                shape: 'plan',
+                entries: update.items.map((item) => ({ label: item.label, status: item.status })),
+            };
+        case 'activity':
+            return { shape: 'activity', ...update.activity };
+        case 'compaction':
+            return null;
+    }
+}

package/dist/projection-strategy-values.d.ts

@@ -0,0 +1,4 @@
+import type { ProjectionStrategy } from './types.js';
+export declare const DEFAULT_PROJECTION_STRATEGY: ProjectionStrategy;
+export declare function normalizeProjectionStrategy(value: string | undefined | null): ProjectionStrategy | undefined;
+export declare function isProjectionStrategy(value: string | undefined | null): value is ProjectionStrategy;

package/dist/projection-strategy-values.js

@@ -0,0 +1,28 @@
+export const DEFAULT_PROJECTION_STRATEGY = 'turn-thin';
+export function normalizeProjectionStrategy(value) {
+    switch (value?.trim()) {
+        case 'session-brief':
+        case 'session-augmented':
+        case 'sessionized':
+            return 'session-brief';
+        case 'turn-full':
+        case 'inline-full':
+        case 'legacy':
+            return 'turn-full';
+        case 'message-only':
+        case 'zero-turn':
+            return 'message-only';
+        case 'turn-thin':
+        case 'grounded-thin':
+        case 'minimal-turn':
+            return 'turn-thin';
+        case 'projected-brief':
+        case 'file-brief':
+            return 'file-brief';
+        default:
+            return undefined;
+    }
+}
+export function isProjectionStrategy(value) {
+    return normalizeProjectionStrategy(value) !== undefined;
+}

package/dist/providers/acp-progress-collector.d.ts

@@ -0,0 +1,44 @@
+import type { ActiveSession } from '@agentclientprotocol/sdk';
+import type { ProviderGenerateOptions } from '../types.js';
+type AcpSessionUpdate = Awaited<ReturnType<ActiveSession['nextUpdate']>>;
+export type AcpProgressNotification = Extract<AcpSessionUpdate, {
+    kind: 'session_update';
+}>;
+type AcpToolCall = Extract<AcpProgressNotification['update'], {
+    sessionUpdate: 'tool_call';
+}>;
+type AcpToolCallUpdate = Extract<AcpProgressNotification['update'], {
+    sessionUpdate: 'tool_call_update';
+}>;
+/**
+ * What a provider says about a tool call beside what the protocol says. Every
+ * field here is one the protocol has no place for, which is why each provider
+ * hangs it under its own namespace and why reading it is the one thing about
+ * this stream that cannot be written once for all three.
+ */
+export interface AcpActivityMetadata {
+    description?: string;
+    parentId?: string;
+    subagent?: boolean;
+    reason?: string;
+}
+export type AcpActivityMetadataReader = (meta: AcpToolCall['_meta'] | AcpToolCallUpdate['_meta']) => AcpActivityMetadata;
+/**
+ * Turns one ACP session's notifications into progress updates and keeps the
+ * turn's answer text so the caller can resolve the reply once the turn stops.
+ * The three providers speak the same protocol version and their streams map
+ * identically; what differs between them sits in provider metadata, read here
+ * through one injected function rather than through a per-provider branch or a
+ * per-provider copy of this class.
+ */
+export declare class AcpProgressCollector {
+    private readonly onProgress?;
+    private readonly readMetadata;
+    private answerText;
+    private reasoningText;
+    constructor(onProgress?: ProviderGenerateOptions['onProgress'], readMetadata?: AcpActivityMetadataReader);
+    consume(notification: AcpProgressNotification): void;
+    getFinalText(): string;
+    private publishStream;
+}
+export {};

package/dist/providers/acp-progress-collector.js

@@ -0,0 +1,130 @@
+const ACTIVITY_KINDS = new Set([
+    'read',
+    'edit',
+    'delete',
+    'move',
+    'search',
+    'execute',
+    'think',
+    'fetch',
+    'switch_mode',
+    'other',
+]);
+/** The protocol's four. Ours adds `waiting`, which no agent can report. */
+const ACTIVITY_STATUSES = new Set([
+    'pending',
+    'in_progress',
+    'completed',
+    'failed',
+]);
+/** For a provider that hangs nothing beside the protocol, or whose namespace nobody has read yet. */
+const noProviderMetadata = () => ({});
+function hasVisibleText(value) {
+    return typeof value === 'string' && value.trim().length > 0;
+}
+/** An unknown kind is not an error: the enum is closed in this protocol version and open in the next. */
+function toActivityKind(kind) {
+    return ACTIVITY_KINDS.has(kind ?? '') ? kind : 'other';
+}
+/** A status outside the vocabulary leaves the entry where it stands rather than inventing a transition. */
+function toActivityStatus(status) {
+    return ACTIVITY_STATUSES.has(status ?? '') ? status : undefined;
+}
+function toActivityPaths(locations) {
+    return locations ? locations.map((location) => location.path) : undefined;
+}
+/** Only the id and the title are required on the wire, so the rest of a new entry defaults here. */
+function toCreatedActivity(update, metadata) {
+    const paths = toActivityPaths(update.locations);
+    return {
+        id: update.toolCallId,
+        label: update.title,
+        ...metadata,
+        kind: toActivityKind(update.kind),
+        status: toActivityStatus(update.status) ?? 'pending',
+        ...(paths ? { paths } : {}),
+    };
+}
+function toPatchedActivity(update, metadata) {
+    const paths = toActivityPaths(update.locations);
+    const status = toActivityStatus(update.status);
+    return {
+        id: update.toolCallId,
+        ...(typeof update.title === 'string' ? { label: update.title } : {}),
+        ...metadata,
+        ...(update.kind == null ? {} : { kind: toActivityKind(update.kind) }),
+        ...(status ? { status } : {}),
+        ...(paths ? { paths } : {}),
+    };
+}
+function toPlanItem(entry) {
+    return { label: entry.content, status: entry.status };
+}
+/**
+ * Turns one ACP session's notifications into progress updates and keeps the
+ * turn's answer text so the caller can resolve the reply once the turn stops.
+ * The three providers speak the same protocol version and their streams map
+ * identically; what differs between them sits in provider metadata, read here
+ * through one injected function rather than through a per-provider branch or a
+ * per-provider copy of this class.
+ */
+export class AcpProgressCollector {
+    onProgress;
+    readMetadata;
+    answerText = '';
+    reasoningText = '';
+    constructor(onProgress, readMetadata = noProviderMetadata) {
+        this.onProgress = onProgress;
+        this.readMetadata = readMetadata;
+    }
+    consume(notification) {
+        const update = notification.update;
+        switch (update.sessionUpdate) {
+            case 'agent_message_chunk':
+                if (update.content.type !== 'text') {
+                    return;
+                }
+                this.answerText += update.content.text;
+                this.publishStream('answer', this.answerText, update.messageId);
+                return;
+            case 'agent_thought_chunk':
+                if (update.content.type !== 'text') {
+                    return;
+                }
+                this.reasoningText += update.content.text;
+                this.publishStream('reasoning', this.reasoningText, update.messageId);
+                return;
+            case 'tool_call':
+                this.onProgress?.({
+                    type: 'activity',
+                    activity: toCreatedActivity(update, this.readMetadata(update._meta)),
+                });
+                return;
+            case 'tool_call_update':
+                this.onProgress?.({
+                    type: 'activity',
+                    activity: toPatchedActivity(update, this.readMetadata(update._meta)),
+                });
+                return;
+            case 'plan':
+                this.onProgress?.({ type: 'plan', items: update.entries.map(toPlanItem) });
+                return;
+            default:
+                return;
+        }
+    }
+    getFinalText() {
+        return this.answerText.trim();
+    }
+    publishStream(stream, text, messageId) {
+        if (!hasVisibleText(text)) {
+            return;
+        }
+        this.onProgress?.({
+            type: 'text',
+            stream,
+            text,
+            ...(typeof messageId === 'string' ? { messageId } : {}),
+        });
+    }
+}

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

@@ -1,12 +1,11 @@
-import type { ProviderGenerateOptions, ProviderReply } from '../types.js';
+import type { ProviderGenerateOptions, ProviderProgressUpdate, 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;
+    publishStructured(update: ProviderProgressUpdate): void;
 }
 export declare function createAwaitingUserProgressHandler(onProgress?: ProviderGenerateOptions['onProgress']): ProviderGenerateOptions['onProgress'] | undefined;

package/dist/providers/awaiting-user.js

@@ -165,20 +165,18 @@ export function sanitizeAwaitingUserProgressText(text) {
 }
 export class AwaitingUserProgressSanitizer {
     onProgress;
-    lastPublished = null;
     constructor(onProgress) {
         this.onProgress = onProgress;
     }
-    publish(text) {
+    publishStructured(update) {
         if (!this.onProgress) {
             return;
         }
-        const sanitizedText = sanitizeAwaitingUserProgressText(text);
-        if (!hasVisibleText(sanitizedText) || sanitizedText === this.lastPublished) {
+        if (update.type === 'text') {
+            this.onProgress({ ...update, text: sanitizeAwaitingUserProgressText(update.text) });
             return;
         }
-        this.lastPublished = sanitizedText;
-        this.onProgress({ text: sanitizedText });
+        this.onProgress(update);
     }
 }
 export function createAwaitingUserProgressHandler(onProgress) {
@@ -187,6 +185,6 @@ export function createAwaitingUserProgressHandler(onProgress) {
     }
     const sanitizer = new AwaitingUserProgressSanitizer(onProgress);
     return (update) => {
-        sanitizer.publish(update.text);
+        sanitizer.publishStructured(update);
     };
 }

package/dist/providers/claude/activity-metadata.d.ts

@@ -0,0 +1,14 @@
+import type { AcpActivityMetadataReader } from '../acp-progress-collector.js';
+/**
+ * Reads what Claude says about a tool call beside what the protocol says.
+ *
+ * The description is the phrasing the adapter would show a user, which for a
+ * shell tool is not the title: the protocol reserves the title for the raw
+ * command line so a client can render a shell preview.
+ *
+ * The container flag is only ever set, never cleared, so it is read as a fact
+ * about the call rather than as a value that could arrive false. It is stamped
+ * on the call that spawns a sub-agent; the calls that sub-agent then makes point
+ * back at it through the parent id.
+ */
+export declare const readClaudeActivityMetadata: AcpActivityMetadataReader;

package/dist/providers/claude/activity-metadata.js

@@ -0,0 +1,81 @@
+/**
+ * Where Claude's adapter hangs its own account of a tool call. The protocol
+ * fields carry what the protocol defines; everything the adapter knows in
+ * addition — the phrasing it would show a user, the call that spawned this one,
+ * why a call never ran — lives here under its own key.
+ */
+const NAMESPACE = 'claudeCode';
+function readString(source, key) {
+    const value = source[key];
+    return typeof value === 'string' && value.trim().length > 0 ? value : undefined;
+}
+function readObject(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value)
+        ? value
+        : undefined;
+}
+/**
+ * Why a call ended as it did, from the two places the adapter reports it.
+ *
+ * A permission denial and an ordinary failure are different shapes, not two
+ * spellings of one: a denial is a nested object naming the rule or the mode that
+ * refused, and everything else is a flat token drawn from an open set the
+ * adapter itself declines to validate. They arrive on different upstream events
+ * and rarely meet, so the rule is fixed here rather than left to whichever is
+ * read first: the denial wins, because it accounts for the same refusal at a
+ * finer grain than the token, which collapses a human's rejection and a rule's
+ * into one value on the permission wire this host answers over.
+ *
+ * `toolResponse` is a general slot the adapter also fills with a running call's
+ * elapsed time and with hook output, so a denial is recognised by the field that
+ * only a denial has, never by the slot being occupied.
+ */
+function readReason(provider) {
+    const response = readObject(provider.toolResponse);
+    if (response && readString(response, 'decisionReasonType')) {
+        return (readString(response, 'decisionReason')
+            ?? readString(response, 'message')
+            ?? readString(response, 'decisionReasonType'));
+    }
+    const nonExecutionKind = readString(provider, 'nonExecutionKind');
+    if (!nonExecutionKind) {
+        return undefined;
+    }
+    const feedback = readString(provider, 'userFeedback');
+    return feedback ? `${nonExecutionKind}: ${feedback}` : nonExecutionKind;
+}
+/**
+ * Reads what Claude says about a tool call beside what the protocol says.
+ *
+ * The description is the phrasing the adapter would show a user, which for a
+ * shell tool is not the title: the protocol reserves the title for the raw
+ * command line so a client can render a shell preview.
+ *
+ * The container flag is only ever set, never cleared, so it is read as a fact
+ * about the call rather than as a value that could arrive false. It is stamped
+ * on the call that spawns a sub-agent; the calls that sub-agent then makes point
+ * back at it through the parent id.
+ */
+export const readClaudeActivityMetadata = (meta) => {
+    const provider = readObject(meta?.[NAMESPACE]);
+    if (!provider) {
+        return {};
+    }
+    const metadata = {};
+    const description = readString(provider, 'title');
+    if (description) {
+        metadata.description = description;
+    }
+    const parentId = readString(provider, 'parentToolUseId');
+    if (parentId) {
+        metadata.parentId = parentId;
+    }
+    if (provider.subagent === true) {
+        metadata.subagent = true;
+    }
+    const reason = readReason(provider);
+    if (reason) {
+        metadata.reason = reason;
+    }
+    return metadata;
+};

package/dist/providers/claude/cli-client.d.ts

@@ -1,7 +1,7 @@
 import spawn from 'cross-spawn';
 import { PROTOCOL_VERSION, client, methods, ndJsonStream } from '@agentclientprotocol/sdk';
 import { type DebugLogger } from '../../debug.js';
-import type { PreparedPromptContext, PreparedProviderTurnInput, ProviderGenerateOptions } from '../../types.js';
+import type { PreparedProviderTurnInput, ProviderGenerateOptions } from '../../types.js';
 import type { ClaudeChannelSessionStore } from './session-store.js';
 interface ClaudeAcpRuntime {
     spawn: typeof spawn;
@@ -20,7 +20,6 @@ interface ClaudeHostedImageInputConfig {
     borgeeBaseUrl?: string;
     agentApiKey?: string;
 }
-export declare function buildClaudeSessionSystemPrompt(promptContext?: PreparedPromptContext): string | undefined;
 /**
  * Persistent ACP-backed client for the Claude ACP adapter.
  *