@alfe.ai/claude-code-host 0.1.6 → 0.1.8

package/dist/index.cjs

@@ -1,11 +1,13 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
 const require_host_config = require("./host-config.cjs");
 exports.BRIDGE_ENV_VAR = require_host_config.BRIDGE_ENV_VAR;
+exports.CLAUDE_PERMISSION_MODES = require_host_config.CLAUDE_PERMISSION_MODES;
 exports.ClaudeCodeHost = require_host_config.ClaudeCodeHost;
 exports.DEFAULT_ALLOWED_TOOLS = require_host_config.DEFAULT_ALLOWED_TOOLS;
 exports.DEFAULT_PERMISSION_MODE = require_host_config.DEFAULT_PERMISSION_MODE;
 exports.SCRUBBED_ANTHROPIC_ENV_VARS = require_host_config.SCRUBBED_ANTHROPIC_ENV_VARS;
 exports.SessionDriver = require_host_config.SessionDriver;
+exports.TERMINATION_GRACE_MS = require_host_config.TERMINATION_GRACE_MS;
 exports.TURN_TIMEOUT_MS = require_host_config.TURN_TIMEOUT_MS;
 exports.WARM_STREAMING_SUPPORTED = require_host_config.WARM_STREAMING_SUPPORTED;
 exports.addMessage = require_host_config.addMessage;

package/dist/index.d.cts

@@ -29,26 +29,32 @@ declare class AgentApiTransport {
    * `Content-Type: application/json` and parses a `{ data: T }` envelope,
    * neither of which fits a raw-audio flow (voice TTS/STT), so those go
    * through this instead. Auth (Bearer), the request budget, and the single
-   * retry on transient 5xx / network errors are kept in sync with
-   * `request()`. Retries fire only on statuses produced BEFORE the route
-   * handler runs (authorizer-timeout 500 + LB 502/503/504), so re-issuing a
-   * POST does not risk a duplicate side effect.
+   * retry policy on transient 5xx / network errors is kept in sync with
+   * `request()`. Safe read methods retry once by default; mutation methods do
+   * not, because a response can be lost after a handler or provider call has
+   * already succeeded.
    */
   rawRequest(path: string, init: {
     method: string;
     headers: Headers;
     body?: BodyInit | Uint8Array;
+  }, extra?: {
+    retry?: boolean;
   }): Promise<Response>;
   /**
    * @param extra.timeoutMs Per-request abort timeout (default REQUEST_TIMEOUT_MS).
    *   Long endpoints (image generation) pass a larger value so the gateway's
    *   own timeout wins with a readable status instead of a client-side abort.
-   * @param extra.retry Whether to retry once on transient failures (default
-   *   true). Expensive/non-idempotent endpoints pass false.
+   * @param extra.retry Whether to retry once on transient failures. Safe reads
+   *   (GET/HEAD/OPTIONS) default to true; mutations default to false. Set true
+   *   only when the endpoint's server-side contract is explicitly idempotent.
+   * @param extra.signal Optional caller cancellation combined with the client's
+   *   own timeout budget. Aborting either signal cancels the request.
    */
   request<T>(path: string, options?: RequestInit, extra?: {
     timeoutMs?: number;
     retry?: boolean;
+    signal?: AbortSignal;
   }): Promise<T>;
 }
 /**
@@ -64,7 +70,7 @@ declare class ApiBase {
 //# sourceMappingURL=transport.d.ts.map
 //#endregion
 //#region src/domains/workspace.d.ts
-/** Response of GET /agents/me/workspace (services/agents). */
+/** Response of GET /agent/workspace (services/agents). */
 interface AgentWorkspaceInfo {
   templateKey?: string;
   defaultModel?: string;
@@ -92,7 +98,7 @@ interface AgentWorkspaceInfo {
 }
 declare class WorkspaceApi extends ApiBase {
   /**
-   * GET /agents/me/workspace — workspace config for the authenticated agent
+   * GET /agent/workspace — workspace config for the authenticated agent
    * (template assignment, default model, org roster).
    */
   getWorkspace(): Promise<AgentWorkspaceInfo>;
@@ -235,6 +241,8 @@ declare class SyncApi extends ApiBase {
   sharedListFiles(args: {
     scope: "org" | "team" | "project";
     scopeId: string;
+    limit?: number;
+    cursor?: string;
   }): Promise<{
     files: SharedFileEntry[];
     nextCursor: string | null;
@@ -394,7 +402,9 @@ declare class KnowledgeApi extends ApiBase {
    * from `services/org`, then fetches the bytes directly from S3 (the one
    * legitimate raw fetch in a plugin — same pattern as sync).
    */
-  readScopeDoc(scopeType: KnowledgeScopeType, scopeId: string, filePath: string): Promise<{
+  readScopeDoc(scopeType: KnowledgeScopeType, scopeId: string, filePath: string, opts?: {
+    maxBytes?: number;
+  }): Promise<{
     filePath: string;
     text: string;
   }>;
@@ -433,15 +443,11 @@ interface MobileAvailableNumber {
 }
 /** Approved WhatsApp content template from GET /mobile/whatsapp/templates. */
 interface WhatsAppTemplate {
-  sid: string;
-  friendlyName: string;
+  contentSid: string;
+  name: string;
   language: string;
   body: string;
   variables: Record<string, string>;
-  dateCreated: string;
-  dateUpdated: string;
-  approvalStatus?: string;
-  rejectionReason?: string;
   category?: string;
 }
 declare class MobileApi extends ApiBase {
@@ -689,15 +695,22 @@ declare class SearchApi extends ApiBase {
     offset?: number;
     country?: string;
     freshness?: string;
+  }, options?: {
+    signal?: AbortSignal;
   }): Promise<unknown>;
   searchImages(params: {
     query: string;
     count?: number;
+  }, options?: {
+    signal?: AbortSignal;
   }): Promise<unknown>;
   searchNews(params: {
     query: string;
     count?: number;
+    offset?: number;
     freshness?: string;
+  }, options?: {
+    signal?: AbortSignal;
   }): Promise<unknown>;
   /** Search news across the selected provider's corpus. → POST /agent/news/search */
   newsSearch(params: {
@@ -721,6 +734,48 @@ declare class SearchApi extends ApiBase {
 }
 //# sourceMappingURL=search.d.ts.map
 //#endregion
+//#region src/domains/webhooks.d.ts
+interface AgentWebhook {
+  webhookId: string;
+  tenantId: string;
+  agentId: string;
+  name: string;
+  provider: string;
+  active: boolean;
+  createdBy: string;
+  createdAt: string;
+  updatedAt: string;
+}
+interface CreatedAgentWebhook extends AgentWebhook {
+  url: string;
+  signingSecret: string;
+}
+interface AgentWebhookDelivery {
+  deliveryId: string;
+  webhookId: string;
+  status: string;
+  attempts: number;
+  createdAt: string;
+  deliveredAt?: string;
+}
+declare class WebhooksApi extends ApiBase {
+  createWebhook(args: {
+    name: string;
+    provider?: "generic" | "github" | "stripe" | "slack";
+  }): Promise<CreatedAgentWebhook>;
+  listWebhooks(): Promise<AgentWebhook[]>;
+  deleteWebhook(webhookId: string): Promise<{
+    webhookId: string;
+    active: false;
+  }>;
+  rotateWebhookSecret(webhookId: string): Promise<{
+    webhookId: string;
+    signingSecret: string;
+  }>;
+  listWebhookDeliveries(webhookId: string): Promise<AgentWebhookDelivery[]>;
+}
+//# sourceMappingURL=webhooks.d.ts.map
+//#endregion
 //#region src/domains/chat.d.ts
 declare class ChatApi extends ApiBase {
   presignAttachments(files: {
@@ -857,8 +912,9 @@ declare class ConnectCredentialsApi extends ApiBase {
    * selector arg (e.g. `xeroTenantId`) on every credential-touching tool
    * and look up the matching account by that selector at dispatch time.
    *
-   * Returned `accounts[i].accountIdentifier` is the Xero tenantId — the
-   * stable cross-session identifier the LLM should pass.
+   * `xeroTenantId` is the model-facing organisation selector. The separate
+   * `accountIdentifier` is the Connect persistence key used for refresh and
+   * may be an email; never substitute one for the other.
    */
   getXeroAccounts(): Promise<{
     accounts: {
@@ -876,12 +932,12 @@ declare class ConnectCredentialsApi extends ApiBase {
     expiresAt: string;
   }>;
   /**
-   * Pattern A: refresh a specific Xero connection by its `accountIdentifier`
-   * (the Xero `tenantId`). The legacy `refreshXeroToken()` only refreshes
-   * the *primary* connection, which is wrong for multi-tenant Xero where
-   * each tenant has its own non-interchangeable access token.
+   * Refresh a specific Xero Connection by its exact `accountIdentifier` from
+   * `getXeroAccounts()`. Do not substitute `xeroTenantId`: current Xero OAuth
+   * rows may use the account email as their persistence key even when a sole
+   * organisation tenant ID is available in provider metadata.
    */
-  refreshXeroAccountToken(xeroTenantId: string): Promise<{
+  refreshXeroAccountToken(accountIdentifier: string): Promise<{
     accessToken: string;
     accessTokenExpiresAt: string;
     expiresAt: string;
@@ -1036,6 +1092,21 @@ declare class ConnectCredentialsApi extends ApiBase {
     accessToken: string;
     expiresAt: string;
   }>;
+  /**
+   * Pattern A: refresh one MYOB Connection by its stable
+   * `accountIdentifier` (the MYOB business id returned by
+   * `getMYOBAccounts()`).
+   *
+   * MYOB refresh tokens belong to individual Connection rows. A
+   * multi-business client must use this method instead of refreshing the
+   * primary Connection and copying that access token into every cached
+   * business client.
+   */
+  refreshMYOBAccountToken(accountIdentifier: string): Promise<{
+    accessToken: string;
+    accessTokenExpiresAt: string;
+    expiresAt: string;
+  }>;
   /**
    * @deprecated Returns a single primary credential blob. Use
    * `getSalesforceAccounts()` for the multi-account shape required by
@@ -1098,9 +1169,6 @@ declare class ConnectCredentialsApi extends ApiBase {
       connectedAt: string;
       accessToken: string;
       accessTokenExpiresAt: string;
-      refreshToken: string;
-      clientId: string;
-      clientSecret: string;
       email: string;
       microsoftTenantId: string;
       workspaceDomain: string;
@@ -1206,10 +1274,41 @@ declare class ConnectCredentialsApi extends ApiBase {
       brokerName?: string;
       accountNumber?: string;
       accessToken: string;
+      /**
+       * The stable per-grant Connection key (`ctid:<userId>`) this account
+       * belongs to. Every trading account under one cTrader login shares one
+       * grant (one OAuth token), so this is the identifier the MCP server
+       * passes to `refreshCTraderAccount()` to rotate the token for the whole
+       * grant on a `CH_ACCESS_TOKEN_INVALID` expiry. Empty string when the
+       * server did not supply one (legacy rows) — such an account can still
+       * trade with its current token but cannot self-refresh.
+       */
+      accountIdentifier: string;
     }[];
     clientId: string;
     clientSecret: string;
   }>;
+  /**
+   * Pattern A: refresh a specific cTrader grant by its stable
+   * `accountIdentifier` (`ctid:<userId>` from `getCTraderAccounts()`).
+   *
+   * cTrader access tokens live ~30 days; the `getCTraderAccounts()` /
+   * credentials reads serve the STORED token without refreshing, so refresh is
+   * the consumer's job. `@alfe.ai/ctrader-mcp` calls this when the cTrader Open
+   * API rejects an account-auth with `CH_ACCESS_TOKEN_INVALID`, then re-runs
+   * the socket handshake with the returned `accessToken`.
+   *
+   * Refreshing one grant rotates the single OAuth token that covers EVERY
+   * trading account under that login. cTrader's refresh token itself does not
+   * expire but may rotate on refresh (`rotatesRefreshToken: true`); connect
+   * persists the rotated refresh token server-side, so the caller only needs
+   * the new `accessToken`. Mirrors `refreshXeroAccountToken`.
+   */
+  refreshCTraderAccount(accountIdentifier: string): Promise<{
+    accessToken: string;
+    accessTokenExpiresAt: string;
+    expiresAt: string;
+  }>;
   /**
    * @deprecated Returns a single primary credential blob. Use
    * `getShopifyAccounts()` for the multi-account shape required by Pattern A
@@ -1374,59 +1473,35 @@ declare class IdentityApi extends ApiBase {
   }>;
   mergeIdentities(survivorId: string, args: {
     mergedId: string;
-    changedBy: {
-      type: string;
-      id: string;
-      name?: string;
-    };
   }): Promise<{
     ok: boolean;
     error?: string;
   }>;
-  unmergeIdentity(identityId: string, args: {
-    changedBy: {
-      type: string;
-      id: string;
-      name?: string;
-    };
-  }): Promise<{
+  unmergeIdentity(identityId: string): Promise<{
     ok: boolean;
     error?: string;
   }>;
   addIdentityNote(identityId: string, args: {
     content: string;
     category?: string;
-    changedBy: {
-      type: string;
-      id: string;
-      name?: string;
-    };
   }): Promise<{
     noteId: string | null;
   }>;
   tagIdentity(identityId: string, args: {
     tag: string;
     action: "add" | "remove";
-    changedBy: {
-      type: string;
-      id: string;
-      name?: string;
-    };
   }): Promise<{
     ok: boolean;
   }>;
   getIdentityChangelog(identityId: string, args?: {
     limit?: number;
+    cursor?: string;
   }): Promise<{
     entries: unknown[];
+    cursor: string | null;
   }>;
   rollbackIdentity(identityId: string, args: {
     targetVersion: number;
-    changedBy: {
-      type: string;
-      id: string;
-      name?: string;
-    };
   }): Promise<{
     ok: boolean;
     entry?: unknown;
@@ -1465,7 +1540,7 @@ declare class IdentityApi extends ApiBase {
     verified: boolean;
     identityId?: string;
     /** Phase 2: how the confirm resolved — Scenario A vs B. */
-    action?: "merged" | "contact_verified";
+    action?: "merged" | "contact_verified" | "already_confirmed";
     error?: string;
   }>;
   /**
@@ -1597,8 +1672,21 @@ declare class MemoryApi extends ApiBase {
     messageCount: number;
   }>;
   memoryLoadContext(tier?: number, topicHint?: string): Promise<{
+    tier: number;
+    facts: {
+      subject: string;
+      predicate: string;
+      object: string;
+      since: string;
+    }[];
+    memories: {
+      text: string;
+      topic: string;
+      subtopic: string;
+      score: number;
+    }[];
+    tokenEstimate: number;
     formatted: string;
-    [key: string]: unknown;
   }>;
   memoryLookupEntity(subject: string): Promise<{
     subject: string;
@@ -1830,7 +1918,7 @@ declare class TeamsApi extends ApiBase {
 
 //#endregion
 //#region src/index.d.ts
-interface AgentApiClient extends SyncApi, IntegrationsApi, WorkspaceApi, ConnectCredentialsApi, TeamsApi, ChatApi, SecretsApi, IdentityApi, MemoryApi, SearchApi, KnowledgeApi, DatabaseApi, MobileApi, RemoteApi, SelfApi, VoiceApi, ImagesApi {}
+interface AgentApiClient extends SyncApi, IntegrationsApi, WorkspaceApi, ConnectCredentialsApi, TeamsApi, ChatApi, SecretsApi, IdentityApi, MemoryApi, SearchApi, KnowledgeApi, DatabaseApi, MobileApi, RemoteApi, SelfApi, VoiceApi, ImagesApi, WebhooksApi {}
 declare class AgentApiClient extends ApiBase {
   constructor(config: AgentApiClientConfig);
 }
@@ -1850,7 +1938,7 @@ interface ChatServiceClientOptions {
   /** Agent API key for Bearer auth */
   apiKey: string;
   /** Called when the chat service sends an RPC request */
-  onRequest: (request: RpcRequest) => void;
+  onRequest: (request: RpcRequest) => void | Promise<void>;
   /** Called when connection state changes */
   onConnectionChange?: (connected: boolean) => void;
   /** Optional logger (defaults to console) */
@@ -1872,12 +1960,12 @@ interface Logger {
 }
 //#endregion
 //#region src/client.d.ts
-
 declare class ChatServiceClient {
   private readonly options;
   private ws;
   private stopped;
   private connected;
+  private connectionGeneration;
   private retryCount;
   private retryTimer;
   private heartbeatTimer;
@@ -1886,7 +1974,7 @@ declare class ChatServiceClient {
   private pendingRequests;
   private requestCounter;
   private messageQueue;
-  private readonly MAX_QUEUE_SIZE;
+  private queuedBytes;
   constructor(options: ChatServiceClientOptions);
   get isConnected(): boolean;
   /** Start connecting to the chat service. */
@@ -1907,8 +1995,13 @@ declare class ChatServiceClient {
    */
   sendRequest(method: string, params: Record<string, unknown>, timeoutMs?: number): Promise<Record<string, unknown>>;
   private flushMessageQueue;
+  private enqueueMessage;
   private flushPendingRequests;
+  private rejectPendingRequest;
   private doConnect;
+  private isCurrentSocket;
+  private setConnected;
+  private notifyConnectionChange;
   private handleMessage;
   private scheduleReconnect;
   /**
@@ -2080,14 +2173,20 @@ declare const WARM_STREAMING_SUPPORTED = false;
  * posture). An inbound chat message could try to induce a destructive shell
  * command, and these turns run unattended on the user's machine. We therefore
  * pass an explicit allow-list of read/analysis/edit tools and DENY Bash by
- * default, and use `--permission-mode default` (NEVER `bypassPermissions` /
+ * default, and use `--permission-mode dontAsk` (NEVER `bypassPermissions` /
  * `--dangerously-skip-permissions`). See DEVELOPING.md → "Tool-permission
  * posture". Bash is intentionally absent — a bridged turn cannot run arbitrary
  * shell. Callers that want a wider set pass `allowedTools` explicitly.
  */
 declare const DEFAULT_ALLOWED_TOOLS: readonly ["Read", "Grep", "Glob", "LS", "Edit", "Write", "WebFetch", "WebSearch", "Task", "TodoWrite"];
-/** Sane default permission posture. NEVER `bypassPermissions`. */
-declare const DEFAULT_PERMISSION_MODE = "default";
+declare const CLAUDE_PERMISSION_MODES: readonly ["acceptEdits", "auto", "manual", "dontAsk", "plan"];
+type ClaudePermissionMode = (typeof CLAUDE_PERMISSION_MODES)[number];
+/**
+ * Headless-safe permission posture supported by current Claude CLI releases.
+ * Allow-listed tools run; any permission prompt the bridge cannot answer is
+ * denied. `bypassPermissions` is deliberately not representable.
+ */
+declare const DEFAULT_PERMISSION_MODE: ClaudePermissionMode;
 /** How a turn ended, surfaced to the host so it can settle / persist. */
 interface DriverTurnResult {
   /** The claude session id observed on the `system:init` event (for --resume). */
@@ -2119,7 +2218,7 @@ interface RunTurnParams {
   /** Tool allow-list (defaults to DEFAULT_ALLOWED_TOOLS). */
   allowedTools?: readonly string[];
   /** Permission mode (defaults to DEFAULT_PERMISSION_MODE — never bypass). */
-  permissionMode?: string;
+  permissionMode?: ClaudePermissionMode;
   /** Per-emission callback so the host can stream deltas/activity live. */
   onEmission: (emission: MapperEmission) => void;
   /** Wall-clock override for the mapper (tests). Defaults to Date.now. */
@@ -2134,6 +2233,8 @@ interface RunTurnParams {
  * cap, but the late settle is harmlessly no-op'd by the chat service.
  */
 declare const TURN_TIMEOUT_MS = 300000;
+/** Grace after SIGINT before SIGKILL + local settlement. Keeps E2 under 305s. */
+declare const TERMINATION_GRACE_MS = 2000;
 /**
  * Spawns and drives `claude` subprocesses. Tracks a SINGLE in-flight child, so
  * the host creates ONE driver PER TURN (`ClaudeCodeHost.makeDriver`) — a driver
@@ -2142,6 +2243,7 @@ declare const TURN_TIMEOUT_MS = 300000;
  */
 declare class SessionDriver {
   private child;
+  private abortCurrent;
   private readonly bin;
   private readonly baseEnv;
   private readonly log;
@@ -2215,6 +2317,9 @@ declare class ClaudeCodeHost {
   private readonly seenIdempotencyKeys;
   /** RPC sessionKey → resolved SessionDriver so chat.abort can SIGINT the child. */
   private activeDriverBySession;
+  private claudeSessionSave;
+  private stopping;
+  private stopPromise;
   constructor(cfg: ClaudeCodeHostConfig, deps?: {
     /** Per-turn driver factory (test seam). Called once per turn. */
     makeDriver?: () => SessionDriver;
@@ -2223,8 +2328,8 @@ declare class ClaudeCodeHost {
   });
   /** Start the chat WS. Non-blocking — the client reconnects internally. */
   start(): Promise<void>;
-  /** Stop the chat WS (SIGTERM path). */
-  stop(): void;
+  /** Stop admission, abort owned children, and give active turns time to settle. */
+  stop(): Promise<void>;
   /**
    * Inbound RPC dispatch. Invoked by the chat client's `onRequest` in
    * production; also the test seam (drive `agent`/`chat.abort`/… directly).
@@ -2246,6 +2351,7 @@ declare class ClaudeCodeHost {
   private ensureSession;
   private loadClaudeSessionIds;
   private saveClaudeSessionIds;
+  private rememberClaudeSessionId;
   private pruneIdempotency;
 }
 /** Strip the `agent:{agentId}:` prefix from a full server session key. */
@@ -2404,4 +2510,4 @@ declare function listSessions(filters?: {
  */
 declare function resolveHostConfig(): ClaudeCodeHostConfig;
 //#endregion
-export { type ActivityEmission, BRIDGE_ENV_VAR, type ChatActivityRecord, type ChatMessage, ClaudeCodeHost, type ClaudeCodeHostConfig, DEFAULT_ALLOWED_TOOLS, DEFAULT_PERMISSION_MODE, type DriverTurnResult, type EndEmission, type MapperEmission, type MapperState, type RunTurnParams, SCRUBBED_ANTHROPIC_ENV_VARS, type SessionData, SessionDriver, type SessionSummary, TURN_TIMEOUT_MS, type TextEmission, type ThinkingActivity, type ToolActivity, WARM_STREAMING_SUPPORTED, addMessage, appendActivity, buildChildEnv, collectTurnActivityRecords, createMapperState, createSession, getSession, listSessions, mapStreamEvent, mapStreamEvents, resolveHostConfig, saveSession, stripAgentPrefix };
+export { type ActivityEmission, BRIDGE_ENV_VAR, CLAUDE_PERMISSION_MODES, type ChatActivityRecord, type ChatMessage, ClaudeCodeHost, type ClaudeCodeHostConfig, type ClaudePermissionMode, DEFAULT_ALLOWED_TOOLS, DEFAULT_PERMISSION_MODE, type DriverTurnResult, type EndEmission, type MapperEmission, type MapperState, type RunTurnParams, SCRUBBED_ANTHROPIC_ENV_VARS, type SessionData, SessionDriver, type SessionSummary, TERMINATION_GRACE_MS, TURN_TIMEOUT_MS, type TextEmission, type ThinkingActivity, type ToolActivity, WARM_STREAMING_SUPPORTED, addMessage, appendActivity, buildChildEnv, collectTurnActivityRecords, createMapperState, createSession, getSession, listSessions, mapStreamEvent, mapStreamEvents, resolveHostConfig, saveSession, stripAgentPrefix };