@borgee/agents-host 0.2.2 → 0.2.28

package/dist/types.d.ts

@@ -1,7 +1,9 @@
-export type ProviderKind = 'claude' | 'copilot';
+export type ProviderKind = 'claude' | 'codex' | 'copilot';
 export interface ProviderCommandConfig {
     claudeCommand: string;
     claudeArgs: string[];
+    codexCommand: string;
+    codexArgs: string[];
     copilotCommand: string;
     copilotArgs: string[];
     copilotSessionTtlMinutes: number;
@@ -83,6 +85,7 @@ export interface LocalConfigGenerateResult {
 }
 export interface ChannelMessageEvent {
     type?: string;
+    message_type?: string;
     channel_id: string;
     channel_type?: string;
     message_id?: string;
@@ -99,19 +102,282 @@ export interface MeResponseUser {
     display_name?: string;
     role?: string;
 }
+export interface DirectoryUser {
+    id: string;
+    display_name?: string;
+    kind: 'user' | 'agent';
+}
+export interface ChannelHistoryEntry {
+    id: string;
+    channelId: string;
+    authorId: string;
+    body: string;
+    contentType?: string;
+    type?: string;
+    replyToId?: string;
+    createdAt: number;
+    editedAt?: number;
+}
+export interface ReadChannelHistoryInput {
+    channelId: string;
+    before?: number;
+    after?: number;
+    limit: number;
+}
+export interface ChannelSummary {
+    id: string;
+    name: string;
+    kind?: string;
+}
+export interface CollaborationDraftSnapshot {
+    draftId: string;
+    channelId: string;
+    turnExecutionId: string;
+    replyToId?: string;
+    body: string;
+    status: 'streaming' | 'finalized';
+    updatedAt: number;
+    finalMessageId?: string;
+}
+export type ProviderCollaborationTurnMode = 'ordinary' | 'silent-kickoff' | 'protocol-managed';
+export type CollaborationOutcomeResponseState = 'responded' | 'blocked' | 'superseded' | 'failed';
+export type CollaborationOutcomeDeliveryState = 'posted' | 'draft-finalized' | 'not-delivered' | 'delivery-failed';
+export type CollaborationOutcomeWakeState = 'waiting' | 'suppressed-agent' | 'resumed-human';
+export interface CollaborationOutcomeBlockedDetails {
+    question: string;
+    reason?: string;
+}
+/**
+ * Shared host-side projection only. This is the latest host-observed snapshot
+ * that adapters may surface back to providers; it is not provider-authoritative
+ * truth about collaboration state or recovery.
+ */
+export interface CollaborationOutcomeSnapshot {
+    source: 'host-observed';
+    responseState: CollaborationOutcomeResponseState;
+    deliveryState: CollaborationOutcomeDeliveryState;
+    wakeState?: CollaborationOutcomeWakeState;
+    blockedDetails?: CollaborationOutcomeBlockedDetails;
+    observedAt: number;
+    turnExecutionId?: string;
+}
+export type AttentionDeliveryMode = 'default' | 'follow' | 'muted';
+export type AttentionClaimState = 'unclaimed' | 'claimed';
+export type AttentionClaimActivation = 'inactive' | 'active' | 'dormant';
+export type AttentionWakeMode = 'current-policy' | 'follow-visible-human' | 'mute-non-mention';
+export type ProviderAttentionUpdate = 'follow-channel' | 'unfollow-channel' | 'mute-channel' | 'claim-channel' | 'claim-task-thread' | 'unclaim-channel' | 'unclaim-task-thread';
+export interface AttentionClaimContext {
+    scope: 'channel' | 'task-thread';
+    taskId: string;
+}
+/**
+ * Shared host-side projection only. This is the latest host-observed snapshot
+ * that adapters may surface back to providers; it is not server-authoritative
+ * truth about delivery policy, fanout, or ownership.
+ */
+export interface AttentionSnapshot {
+    source: 'host-observed';
+    deliveryMode: AttentionDeliveryMode;
+    claimState: AttentionClaimState;
+    claimActivation: AttentionClaimActivation;
+    wakeMode: AttentionWakeMode;
+    observedAt: number;
+    turnExecutionId?: string;
+    claimContext?: AttentionClaimContext;
+}
+export type TaskThreadCollaborationTurnRole = 'assignment' | 'continuation';
+export type TaskThreadMainResultContract = 'ordinary-final-reply-in-thread';
+export type TaskThreadAuxiliaryRouteContract = 'optional-auxiliary-send-or-escalation-only';
+export type TaskThreadCheckInContract = 'status-update-intent-only';
+export type TaskThreadBlockedWorkContract = 'in-thread-disclosure-only';
+/**
+ * Shared host-side projection only. This is a narrow adapter-facing summary of
+ * task-thread collaboration meaning; it is not runtime-authoritative truth
+ * about task ownership, task routes, heartbeat execution, or blocked state.
+ */
+export interface TaskThreadCollaborationContract {
+    source: 'host-projected';
+    turnRole: TaskThreadCollaborationTurnRole;
+    taskThreadContextActive: true;
+    mainResult: TaskThreadMainResultContract;
+    auxiliaryRoute: TaskThreadAuxiliaryRouteContract;
+    checkIn: TaskThreadCheckInContract;
+    blockedWork: TaskThreadBlockedWorkContract;
+}
+export interface CollaborationCapabilityDeclaration {
+    collaborationOutcome?: true;
+    attentionSnapshot?: true;
+    taskThreadCollaborationContract?: true;
+    missedCollaborationDiagnostic?: true;
+    recoveryExplanation?: 'runtime-local-only';
+}
+export type MissedCollaborationDiagnosticStage = 'delivery' | 'wake' | 'response';
+export type MissedCollaborationDiagnosticReason = 'delivery-failed' | 'not-delivered' | 'wake-suppressed-attention-policy' | 'blocked-awaiting-user';
+export interface MissedCollaborationDiagnostic {
+    stage: MissedCollaborationDiagnosticStage;
+    reason: MissedCollaborationDiagnosticReason;
+}
+export interface ProviderCollaborationContext {
+    enabled: boolean;
+    turnExecutionId?: string;
+    sendRoutesAllowed?: boolean;
+    turnMode?: ProviderCollaborationTurnMode;
+    kickoff?: ProviderProtocolKickoffContext;
+    protocol?: ProviderProtocolContext;
+    grounding?: ProviderTurnGroundingContext;
+}
 export interface ProviderInput {
     agentName: string;
     provider: ProviderKind;
     channelId: string;
     incomingAuthorId: string;
     incomingContent: string;
+    incomingEventKind?: string;
+    incomingMessageType?: string;
+    collaboration?: ProviderCollaborationContext;
+    collaborationOutcome?: CollaborationOutcomeSnapshot;
+    attentionSnapshot?: AttentionSnapshot;
+    taskThreadCollaborationContract?: TaskThreadCollaborationContract;
+    collaborationCapabilities?: CollaborationCapabilityDeclaration;
+    missedCollaborationDiagnostic?: MissedCollaborationDiagnostic;
+}
+export interface ProviderProtocolContext {
+    anchorMessageId: string;
+    anchorSummary: string;
+    issuerId: string;
+    role: 'issuer' | 'intermediate' | 'final';
+    targetPeerId: string;
+    turnIndex: number;
+    maxTurnCount: number;
 }
+export interface ProviderProtocolKickoffContext {
+    anchorMessageId: string;
+    participantIds: [string, string];
+    issuerId: string;
+}
+export interface ProviderTurnIdentity {
+    id: string;
+    displayName?: string;
+    kind: 'human' | 'agent' | 'unknown';
+}
+export interface ProviderTurnGroundingContext {
+    self: ProviderTurnIdentity;
+    incomingAuthor: ProviderTurnIdentity;
+    peer?: ProviderTurnIdentity;
+    participants?: ProviderTurnIdentity[];
+    hostRecognizedKickoffCandidate?: boolean;
+}
+export interface SkillRuntimeBootstrapMetadata {
+    skillDirectoryPath: string;
+    skillMarkdownPath: string;
+    nodeCliPath: string;
+    pythonCliPath: string;
+}
+export interface LocalhostGatewayBootstrapMetadata {
+    baseUrl: string;
+    collaboration?: {
+        enabled: true;
+    };
+}
+export interface TaskAssignmentThreadContext {
+    active: true;
+    currentTaskId?: string;
+}
+export interface TaskWorkspaceContext {
+    currentTaskId: string;
+    rootPath: string;
+}
+export interface PreparedPromptContext {
+    channelContextPayloadPath?: string;
+    gatewayAuthPath?: string;
+    collaborationTurnExecutionId?: string;
+    collaborationTurnMode?: ProviderCollaborationTurnMode;
+    collaborationOutcome?: CollaborationOutcomeSnapshot;
+    attentionSnapshot?: AttentionSnapshot;
+    taskThreadCollaborationContract?: TaskThreadCollaborationContract;
+    collaborationCapabilities?: CollaborationCapabilityDeclaration;
+    missedCollaborationDiagnostic?: MissedCollaborationDiagnostic;
+    kickoff?: ProviderProtocolKickoffContext;
+    protocol?: ProviderProtocolContext;
+    grounding?: ProviderTurnGroundingContext;
+    skillRuntime?: SkillRuntimeBootstrapMetadata;
+    localhostGateway?: LocalhostGatewayBootstrapMetadata;
+    taskAssignmentContext?: TaskAssignmentThreadContext;
+    taskWorkspace?: TaskWorkspaceContext;
+}
+export interface PreparedProviderSessionRouting {
+    key: string;
+    persistence: 'persistent' | 'ephemeral';
+}
+export interface PreparedProviderTurnInput {
+    channelId: string;
+    incomingEventKind?: string;
+    incomingMessageType?: string;
+    prompt: string;
+    promptContext?: PreparedPromptContext;
+    providerSessionRouting?: PreparedProviderSessionRouting;
+}
+export interface ProviderAwaitingUser {
+    question: string;
+    reason?: string;
+}
+export interface ProviderTurnControlBase {
+    attentionUpdate?: ProviderAttentionUpdate;
+}
+export type ProviderTurnControl = ({
+    kind: 'continue-to-peer';
+} & ProviderTurnControlBase) | ({
+    kind: 'conclude-locally';
+} & ProviderTurnControlBase) | {
+    kind: 'start-protocol';
+    rounds: number;
+} | ({
+    kind: 'awaiting-user';
+} & ProviderAwaitingUser & ProviderTurnControlBase) | ({
+    kind: 'attention-only';
+    attentionUpdate: ProviderAttentionUpdate;
+} & ProviderTurnControlBase);
 export interface ProviderReply {
     text: string;
+    awaitingUser?: ProviderAwaitingUser;
+    control?: ProviderTurnControl;
+    controlMalformed?: boolean;
 }
 export interface PostedMessage {
     messageId: string;
 }
+export interface PostMessageInput {
+    channelId: string;
+    body: string;
+    replyToId?: string;
+}
+export interface Task {
+    id: string;
+    channelId: string;
+    guildId: string;
+    seq?: number;
+    title: string;
+    description: string;
+    status: string;
+    assigneeId: string | null;
+    createdBy: string;
+    messageId: string | null;
+    threadId: string | null;
+    createdAt: number;
+    updatedAt: number;
+}
+export interface CreateTaskInput {
+    channelId: string;
+    title: string;
+    description?: string;
+    assigneeId?: string;
+}
+export interface UpdateTaskInput {
+    taskId: string;
+    status?: string;
+    assigneeId?: string;
+    title?: string;
+}
 export interface ProviderProgressUpdate {
     text: string;
 }

package/dist/visible-mentions.d.ts

@@ -0,0 +1,3 @@
+export declare function extractVisibleMentionIds(content: string): string[];
+export declare function hasVisibleMention(content: string, participantId: string): boolean;
+export declare function appendVisibleMention(content: string, participantId: string): string;

package/dist/visible-mentions.js

@@ -0,0 +1,15 @@
+export function extractVisibleMentionIds(content) {
+    return [...content.matchAll(/<@([^>\s]+)>/gu)]
+        .map((match) => match[1]?.trim())
+        .filter((value) => Boolean(value));
+}
+export function hasVisibleMention(content, participantId) {
+    return extractVisibleMentionIds(content).includes(participantId);
+}
+export function appendVisibleMention(content, participantId) {
+    if (hasVisibleMention(content, participantId)) {
+        return content;
+    }
+    const separator = /\s$/u.test(content) ? '' : ' ';
+    return `${content}${separator}<@${participantId}>`;
+}

package/package.json

@@ -1,17 +1,18 @@
 {
   "name": "@borgee/agents-host",
-  "version": "0.2.2",
+  "version": "0.2.28",
   "private": false,
   "publishConfig": {
     "access": "public"
   },
   "type": "module",
-  "description": "Minimal local agents host: connects a local Claude/Copilot CLI to a Borgee agent over @borgee/plugin-sdk",
+  "description": "Minimal local agents host: connects local Claude/Codex/Copilot runtimes to a Borgee agent over @borgee/plugin-sdk",
   "bin": {
-    "agents-host": "dist/cli.js"
+    "agents-host": "./dist/cli.js"
   },
   "files": [
     "dist",
+    "skills",
     "README.md"
   ],
   "repository": {
@@ -20,6 +21,20 @@
     "directory": "packages/agents-host"
   },
   "license": "MIT",
+  "dependencies": {
+    "@agentclientprotocol/codex-acp": "1.1.7",
+    "@agentclientprotocol/sdk": "1.3.0",
+    "cross-spawn": "^7.0.6",
+    "yaml": "^2.8.1",
+    "@borgee/plugin-sdk": "0.2.4"
+  },
+  "devDependencies": {
+    "@types/cross-spawn": "^6.0.6",
+    "@types/node": "^24.3.0",
+    "tsx": "^4.20.5",
+    "typescript": "^5.9.3",
+    "vitest": "^4.1.5"
+  },
   "scripts": {
     "predev": "pnpm --filter @borgee/plugin-sdk build",
     "dev": "tsx src/index.ts",
@@ -33,18 +48,5 @@
     "pretest": "pnpm --filter @borgee/plugin-sdk build",
     "test": "vitest run --testTimeout=10000",
     "pretypecheck": "pnpm --filter @borgee/plugin-sdk build"
-  },
-  "dependencies": {
-    "@agentclientprotocol/sdk": "^1.2.1",
-    "@borgee/plugin-sdk": "0.1.5",
-    "cross-spawn": "^7.0.6",
-    "yaml": "^2.8.1"
-  },
-  "devDependencies": {
-    "@types/cross-spawn": "^6.0.6",
-    "@types/node": "^24.3.0",
-    "tsx": "^4.20.5",
-    "typescript": "^5.9.3",
-    "vitest": "^4.1.5"
   }
-}
+}

package/skills/borgee-agent/SKILL.md

@@ -0,0 +1,33 @@
+# Borgee Agent Skill Bootstrap
+
+This skill runtime surface stays read-only for final visible replies in this slice.
+
+Use one of the packaged local CLIs to inspect the current channel bootstrap payload. When `localhost-gateway` is enabled together with `context-injection` and `skill-runtime`, the same CLIs can also call the loopback gateway using the persisted context payload.
+
+- Node: `node ./borgee-agent.mjs --context /absolute/path/to/context.json --print-bootstrap`
+- Python: `python3 ./borgee-agent.py --context /absolute/path/to/context.json --print-bootstrap`
+- Node health: `node ./borgee-agent.mjs --context /absolute/path/to/context.json --auth-path /absolute/path/to/.localhost-gateway-auth.json --health`
+- Node bootstrap: `node ./borgee-agent.mjs --context /absolute/path/to/context.json --auth-path /absolute/path/to/.localhost-gateway-auth.json --read-bootstrap`
+- Node identity: `node ./borgee-agent.mjs --context /absolute/path/to/context.json --auth-path /absolute/path/to/.localhost-gateway-auth.json --get-me`
+- Node history: `node ./borgee-agent.mjs --context /absolute/path/to/context.json --auth-path /absolute/path/to/.localhost-gateway-auth.json --read-history --limit 20`
+- Node private draft snapshot: `node ./borgee-agent.mjs --context /absolute/path/to/context.json --auth-path /absolute/path/to/.localhost-gateway-auth.json --turn-execution-id turn-id --read-draft`
+- Node users: `node ./borgee-agent.mjs --context /absolute/path/to/context.json --auth-path /absolute/path/to/.localhost-gateway-auth.json --list-users`
+- Node auxiliary mention: `node ./borgee-agent.mjs --context /absolute/path/to/context.json --auth-path /absolute/path/to/.localhost-gateway-auth.json --turn-execution-id turn-id --send-mention user-id --body "Need review from <@user-id>"`
+- Node auxiliary reply: `node ./borgee-agent.mjs --context /absolute/path/to/context.json --auth-path /absolute/path/to/.localhost-gateway-auth.json --turn-execution-id turn-id --send-message --body "Following up here" --reply-to message-id`
+- Python health: `python3 ./borgee-agent.py --context /absolute/path/to/context.json --auth-path /absolute/path/to/.localhost-gateway-auth.json --health`
+- Python bootstrap: `python3 ./borgee-agent.py --context /absolute/path/to/context.json --auth-path /absolute/path/to/.localhost-gateway-auth.json --read-bootstrap`
+- Python identity: `python3 ./borgee-agent.py --context /absolute/path/to/context.json --auth-path /absolute/path/to/.localhost-gateway-auth.json --get-me`
+- Python history: `python3 ./borgee-agent.py --context /absolute/path/to/context.json --auth-path /absolute/path/to/.localhost-gateway-auth.json --read-history --limit 20`
+- Python private draft snapshot: `python3 ./borgee-agent.py --context /absolute/path/to/context.json --auth-path /absolute/path/to/.localhost-gateway-auth.json --turn-execution-id turn-id --read-draft`
+- Python users: `python3 ./borgee-agent.py --context /absolute/path/to/context.json --auth-path /absolute/path/to/.localhost-gateway-auth.json --list-users`
+- Python auxiliary mention: `python3 ./borgee-agent.py --context /absolute/path/to/context.json --auth-path /absolute/path/to/.localhost-gateway-auth.json --turn-execution-id turn-id --send-mention user-id --body "Need review from <@user-id>"`
+- Python auxiliary reply: `python3 ./borgee-agent.py --context /absolute/path/to/context.json --auth-path /absolute/path/to/.localhost-gateway-auth.json --turn-execution-id turn-id --send-message --body "Following up here" --reply-to message-id`
+
+When the injected `context.json` includes `taskAssignmentContext.active: true`, the same CLIs also expose the task-thread compatibility surface:
+
+- In ordinary parent channels: `--create-task`, `--list-tasks`, `--get-task --task-id ...`, `--update-task --task-id ...`
+- In task-assignment threads: `--get-task` and `--update-task` may omit `--task-id` and resolve the current thread task through the persisted `currentTaskId` or an agents-host local fallback; `--create-task` and `--list-tasks` stay disabled there and must be run from the parent channel
+
+The private draft snapshot is read-only, collaboration-scoped, and separate from ordinary public channel messages.
+Auxiliary sends are only for short targeted escalation, reply-thread nudges, or mentions. They must not be used for the main final answer body, which still belongs to AgentsHost.
+Both CLIs are local-only, may only access the loopback gateway described above, and must not mutate files.