@botcord/daemon 0.2.4 → 0.2.6

package/dist/gateway/gateway.d.ts

@@ -1,7 +1,8 @@
 import { type ChannelBackoffOptions } from "./channel-manager.js";
 import { type RuntimeFactory } from "./dispatcher.js";
 import { type GatewayLogger } from "./log.js";
-import type { ChannelAdapter, GatewayChannelConfig, GatewayConfig, GatewayRoute, GatewayRuntimeSnapshot, InboundObserver, OutboundObserver, SystemContextBuilder, UserTurnBuilder } from "./types.js";
+import { type TranscriptWriter } from "./transcript.js";
+import type { ChannelAdapter, GatewayChannelConfig, GatewayConfig, GatewayInboundMessage, GatewayRoute, GatewayRuntimeSnapshot, InboundObserver, OutboundObserver, SystemContextBuilder, UserTurnBuilder } from "./types.js";
 /** Constructor options for `Gateway`. */
 export interface GatewayBootOptions {
     config: GatewayConfig;
@@ -35,6 +36,33 @@ export interface GatewayBootOptions {
      * bookkeeping like loop-risk tracking.
      */
     onOutbound?: OutboundObserver;
+    /**
+     * Optional attention gate (PR3, design §4.2). Forwarded to the dispatcher
+     * verbatim — see {@link Dispatcher} for semantics. Returning `false` skips
+     * the runtime turn while preserving ack + onInbound side effects.
+     */
+    attentionGate?: (message: GatewayInboundMessage) => Promise<boolean> | boolean;
+    /**
+     * Resolve the per-agent hub URL for an inbound message. Forwarded to the
+     * dispatcher as `RuntimeRunOptions.hubUrl` so spawned CLI subprocesses
+     * (`BOTCORD_HUB`) target the correct hub for the owning agent.
+     */
+    resolveHubUrl?: (accountId: string) => string | undefined;
+    /**
+     * Persistent NDJSON transcript writer (design §3 / §6). Optional — when
+     * omitted the dispatcher uses a noop writer. Pass `transcriptEnabled` plus
+     * `transcriptRootDir` to let the gateway construct one for you.
+     */
+    transcript?: TranscriptWriter;
+    /**
+     * Tri-state convenience: if `transcript` is not provided, the gateway
+     * constructs a writer using this flag plus `transcriptRootDir`. Use
+     * {@link resolveTranscriptEnabled} to combine `BOTCORD_TRANSCRIPT` env with
+     * the persistent daemon-config flag.
+     */
+    transcriptEnabled?: boolean;
+    /** Root directory for transcript files. Defaults to `~/.botcord/agents`. */
+    transcriptRootDir?: string;
 }
 /**
  * Top-level gateway bootstrap. Wires `ChannelManager` → `Dispatcher` →

package/dist/gateway/gateway.js

@@ -3,6 +3,7 @@ import { Dispatcher } from "./dispatcher.js";
 import { consoleLogger } from "./log.js";
 import { createRuntime } from "./runtimes/registry.js";
 import { DEFAULT_SESSION_STORE_MAX_ENTRY_AGE_MS, SessionStore } from "./session-store.js";
+import { createTranscriptWriter, } from "./transcript.js";
 /** Default runtime factory: delegates to the built-in registry; ignores extraArgs at construction. */
 const defaultRuntimeFactory = (runtimeId) => createRuntime(runtimeId);
 /**
@@ -53,6 +54,12 @@ export class Gateway {
             maxEntryAgeMs: opts.sessionStoreMaxEntryAgeMs ?? DEFAULT_SESSION_STORE_MAX_ENTRY_AGE_MS,
         });
         const runtimeFactory = opts.createRuntime ?? defaultRuntimeFactory;
+        const transcript = opts.transcript
+            ?? createTranscriptWriter({
+                log: this.log,
+                enabled: opts.transcriptEnabled === true,
+                rootDir: opts.transcriptRootDir,
+            });
         this.dispatcher = new Dispatcher({
             config: this.config,
             channels: this.channelMap,
@@ -65,6 +72,9 @@ export class Gateway {
             composeUserTurn: opts.composeUserTurn,
             onOutbound: opts.onOutbound,
             managedRoutes: this.managedRoutes,
+            attentionGate: opts.attentionGate,
+            resolveHubUrl: opts.resolveHubUrl,
+            transcript,
         });
         this.channelManager = new ChannelManager({
             config: this.config,

package/dist/gateway/index.d.ts

@@ -8,6 +8,8 @@ export { resolveRoute, matchesRoute } from "./router.js";
 export { ChannelManager, type ChannelManagerOptions, type ChannelBackoffOptions } from "./channel-manager.js";
 export { Dispatcher, type DispatcherOptions, type RuntimeFactory } from "./dispatcher.js";
 export { Gateway, type GatewayBootOptions } from "./gateway.js";
+export { createTranscriptWriter, resolveTranscriptEnabled, defaultTranscriptRoot, truncateTextField, TRANSCRIPT_TEXT_LIMIT, TRANSCRIPT_FILE_LIMIT, type TranscriptWriter, type TranscriptRecord, type InboundTranscriptRecord, type DispatchedTranscriptRecord, type ComposeFailedTranscriptRecord, type OutboundTranscriptRecord, type TurnErrorTranscriptRecord, type AttentionSkippedTranscriptRecord, type DroppedTranscriptRecord, type DeliveryStatus, type DroppedReason, } from "./transcript.js";
+export { safePathSegment, transcriptFilePath, transcriptRoomDir, transcriptAgentRoot, } from "./transcript-paths.js";
 export { ClaudeCodeAdapter, probeClaude, resolveClaudeCommand, } from "./runtimes/claude-code.js";
 export { CodexAdapter, probeCodex, resolveCodexCommand } from "./runtimes/codex.js";
 export { GeminiAdapter, probeGemini, resolveGeminiCommand } from "./runtimes/gemini.js";

package/dist/gateway/index.js

@@ -8,6 +8,8 @@ export { resolveRoute, matchesRoute } from "./router.js";
 export { ChannelManager } from "./channel-manager.js";
 export { Dispatcher } from "./dispatcher.js";
 export { Gateway } from "./gateway.js";
+export { createTranscriptWriter, resolveTranscriptEnabled, defaultTranscriptRoot, truncateTextField, TRANSCRIPT_TEXT_LIMIT, TRANSCRIPT_FILE_LIMIT, } from "./transcript.js";
+export { safePathSegment, transcriptFilePath, transcriptRoomDir, transcriptAgentRoot, } from "./transcript-paths.js";
 export { ClaudeCodeAdapter, probeClaude, resolveClaudeCommand, } from "./runtimes/claude-code.js";
 export { CodexAdapter, probeCodex, resolveCodexCommand } from "./runtimes/codex.js";
 export { GeminiAdapter, probeGemini, resolveGeminiCommand } from "./runtimes/gemini.js";

package/dist/gateway/policy-resolver.d.ts

@@ -0,0 +1,57 @@
+/**
+ * Daemon-side per-agent attention-policy cache (PR3, design §5).
+ *
+ * The dispatcher consults this resolver after `onInbound` fires and before
+ * the runtime turn enqueues. Cache layout:
+ *
+ *   - `agent_id`              → global default policy (seeded by
+ *                                `provision_agent` + `policy_updated{agent}`).
+ *   - `agent_id:room_id`      → genuine per-room override only — installed
+ *                                exclusively via `put` from a per-room
+ *                                `policy_updated` frame. Inheritance reads
+ *                                never write here.
+ *
+ * `resolve(agent, room)` checks the room key first, then falls back to the
+ * global key. This means a per-room override always wins, and the global
+ * propagates to every room without explicit fan-out (a global update only
+ * needs to refresh the agent_id entry).
+ *
+ * `invalidate(agent_id, room_id)` drops the matching room entry; the next
+ * resolve falls through to the global. `invalidate(agent_id)` drops every
+ * entry for that agent — both global and any room overrides — used when
+ * the agent is revoked or the cache must rebuild from scratch.
+ */
+import type { AttentionPolicy } from "@botcord/protocol-core";
+/** Public surface — kept narrow so the dispatcher can mock easily in tests. */
+export interface PolicyResolverLike {
+    resolve(agentId: string, roomId: string | null): Promise<AttentionPolicy>;
+    invalidate(agentId: string, roomId?: string): void;
+    /**
+     * Install (or replace) the cached policy entry for an agent / room. Used
+     * by the `policy_updated` control-frame handler to apply embedded policy
+     * payloads without forcing a refetch.
+     */
+    put(agentId: string, roomId: string | null, policy: AttentionPolicy): void;
+}
+export interface PolicyResolverOptions {
+    /** Fetcher for the per-agent default. Returning `undefined` means "no policy known"; the resolver falls back to `mode=always`. */
+    fetchGlobal: (agentId: string) => Promise<AttentionPolicy | undefined>;
+    /**
+     * Optional per-room fetcher. PR2 supplies this; PR3 leaves it
+     * unimplemented and the resolver collapses to the global policy.
+     */
+    fetchEffective?: (agentId: string, roomId: string) => Promise<AttentionPolicy | undefined>;
+    /** Cache TTL in milliseconds. Defaults to 5 minutes. */
+    ttlMs?: number;
+}
+export declare class PolicyResolver implements PolicyResolverLike {
+    private readonly fetchGlobal;
+    private readonly fetchEffective?;
+    private readonly ttlMs;
+    private readonly cache;
+    constructor(opts: PolicyResolverOptions);
+    resolve(agentId: string, roomId: string | null): Promise<AttentionPolicy>;
+    private safeFetch;
+    invalidate(agentId: string, roomId?: string): void;
+    put(agentId: string, roomId: string | null, policy: AttentionPolicy): void;
+}

package/dist/gateway/policy-resolver.js

@@ -0,0 +1,123 @@
+/**
+ * Daemon-side per-agent attention-policy cache (PR3, design §5).
+ *
+ * The dispatcher consults this resolver after `onInbound` fires and before
+ * the runtime turn enqueues. Cache layout:
+ *
+ *   - `agent_id`              → global default policy (seeded by
+ *                                `provision_agent` + `policy_updated{agent}`).
+ *   - `agent_id:room_id`      → genuine per-room override only — installed
+ *                                exclusively via `put` from a per-room
+ *                                `policy_updated` frame. Inheritance reads
+ *                                never write here.
+ *
+ * `resolve(agent, room)` checks the room key first, then falls back to the
+ * global key. This means a per-room override always wins, and the global
+ * propagates to every room without explicit fan-out (a global update only
+ * needs to refresh the agent_id entry).
+ *
+ * `invalidate(agent_id, room_id)` drops the matching room entry; the next
+ * resolve falls through to the global. `invalidate(agent_id)` drops every
+ * entry for that agent — both global and any room overrides — used when
+ * the agent is revoked or the cache must rebuild from scratch.
+ */
+const DEFAULT_TTL_MS = 5 * 60 * 1000;
+const FETCH_FAILED = Symbol("fetch_failed");
+/**
+ * Force DM rooms (`rm_dm_*`) to `mode: "always"` per design §4.2 — UI never
+ * lets the user mute a DM, but a stale cache from before a UX bug is cheap
+ * to defend against here.
+ */
+function maybeForceDm(roomId, policy) {
+    if (roomId && roomId.startsWith("rm_dm_") && policy.mode !== "always") {
+        return { ...policy, mode: "always" };
+    }
+    return policy;
+}
+function defaultPolicy() {
+    return { mode: "always", keywords: [] };
+}
+export class PolicyResolver {
+    fetchGlobal;
+    fetchEffective;
+    ttlMs;
+    cache = new Map();
+    constructor(opts) {
+        this.fetchGlobal = opts.fetchGlobal;
+        this.fetchEffective = opts.fetchEffective;
+        this.ttlMs = opts.ttlMs ?? DEFAULT_TTL_MS;
+    }
+    async resolve(agentId, roomId) {
+        const now = Date.now();
+        // 1. Per-room cache — populated either by a `policy_updated{room_id}`
+        //    push (genuine override) or by a prior `fetchEffective` cold-start.
+        if (roomId) {
+            const roomHit = this.cache.get(cacheKey(agentId, roomId));
+            if (roomHit && roomHit.expiresAt > now)
+                return roomHit.policy;
+        }
+        // 2. If a per-room fetcher is wired, treat it as authoritative for cold
+        //    rooms — it returns the override-merged effective policy and so must
+        //    not be skipped just because the global cache is warm.
+        if (roomId && this.fetchEffective) {
+            const fetched = await this.safeFetch(() => this.fetchEffective(agentId, roomId));
+            if (fetched === FETCH_FAILED)
+                return defaultPolicy();
+            const policy = fetched ?? defaultPolicy();
+            this.cache.set(cacheKey(agentId, roomId), {
+                policy: maybeForceDm(roomId, policy),
+                expiresAt: now + this.ttlMs,
+            });
+            return maybeForceDm(roomId, policy);
+        }
+        // 3. No room override known — inherit from the cached agent-wide global.
+        //    Without this layer, group messages collapsed to mode=always whenever
+        //    the daemon ran without a per-room fetcher (the current production
+        //    state), silently breaking global mention_only/muted.
+        const globalKey = cacheKey(agentId, null);
+        const globalHit = this.cache.get(globalKey);
+        if (globalHit && globalHit.expiresAt > now) {
+            return maybeForceDm(roomId, globalHit.policy);
+        }
+        // 4. Cold start for global.
+        const fetched = await this.safeFetch(() => this.fetchGlobal(agentId));
+        if (fetched === FETCH_FAILED)
+            return defaultPolicy();
+        const policy = fetched ?? defaultPolicy();
+        this.cache.set(globalKey, { policy, expiresAt: now + this.ttlMs });
+        return maybeForceDm(roomId, policy);
+    }
+    async safeFetch(fn) {
+        try {
+            return await fn();
+        }
+        catch {
+            // Fail-open: a fetch error must not silence the agent. The caller
+            // returns the default policy without caching so the next resolve retries.
+            return FETCH_FAILED;
+        }
+    }
+    invalidate(agentId, roomId) {
+        if (roomId !== undefined) {
+            this.cache.delete(cacheKey(agentId, roomId));
+            return;
+        }
+        // Drop every entry for this agent.
+        const prefix = agentId + ":";
+        for (const key of Array.from(this.cache.keys())) {
+            if (key === agentId || key.startsWith(prefix)) {
+                this.cache.delete(key);
+            }
+        }
+    }
+    put(agentId, roomId, policy) {
+        const key = cacheKey(agentId, roomId);
+        this.cache.set(key, {
+            policy: maybeForceDm(roomId, policy),
+            expiresAt: Date.now() + this.ttlMs,
+        });
+    }
+}
+function cacheKey(agentId, roomId) {
+    return roomId ? `${agentId}:${roomId}` : agentId;
+}

package/dist/gateway/runtimes/acp-stream.d.ts

@@ -0,0 +1,99 @@
+import type { RuntimeAdapter, RuntimeProbeResult, RuntimeRunOptions, RuntimeRunResult, StreamBlock } from "../types.js";
+/** ACP protocol version this client targets. */
+export declare const ACP_PROTOCOL_VERSION = 1;
+export interface AcpInitializeResult {
+    protocolVersion?: number;
+    agentInfo?: {
+        name?: string;
+        version?: string;
+    };
+    agentCapabilities?: Record<string, unknown>;
+    authMethods?: Array<{
+        id?: string;
+        name?: string;
+        description?: string;
+    }>;
+    [k: string]: unknown;
+}
+export interface AcpPermissionOption {
+    optionId: string;
+    name?: string;
+    /**
+     * ACP option kind. Common values: `allow_once`, `allow_always`,
+     * `reject_once`, `reject_always`. Treated as opaque by the base class —
+     * subclasses inspect `.kind` to pick the right outcome.
+     */
+    kind?: string;
+    [k: string]: unknown;
+}
+export interface AcpPermissionRequest {
+    sessionId: string;
+    toolCall?: {
+        name?: string;
+        rawInput?: unknown;
+        [k: string]: unknown;
+    };
+    options: AcpPermissionOption[];
+    [k: string]: unknown;
+}
+export type AcpPermissionResponse = {
+    outcome: {
+        outcome: "selected";
+        optionId: string;
+    };
+} | {
+    outcome: {
+        outcome: "cancelled";
+    };
+};
+export interface AcpUpdateParams {
+    sessionId: string;
+    update: {
+        sessionUpdate?: string;
+        [k: string]: unknown;
+    };
+    [k: string]: unknown;
+}
+/** Hooks exposed to subclasses to react to inbound traffic during a turn. */
+export interface AcpTurnHooks {
+    /** Called for each `session/update` notification. */
+    onUpdate(params: AcpUpdateParams, ctx: AcpUpdateCtx): void;
+    /** Called for `session/request_permission` requests. Must resolve to an outcome. */
+    onPermissionRequest(req: AcpPermissionRequest): Promise<AcpPermissionResponse>;
+}
+export interface AcpUpdateCtx {
+    /** Append to the turn's running assistant text. */
+    appendAssistantText(text: string): void;
+    /** Forward a normalized StreamBlock to `opts.onBlock`. */
+    emitBlock(block: StreamBlock): void;
+    /** 1-based sequence within this turn. */
+    seq: number;
+}
+export declare abstract class AcpRuntimeAdapter implements RuntimeAdapter {
+    abstract readonly id: string;
+    probe?(): RuntimeProbeResult;
+    protected abstract resolveBinary(opts: RuntimeRunOptions): string;
+    /** Argv tail (excluding the binary). ACP servers usually take none. */
+    protected buildArgs(_opts: RuntimeRunOptions): string[];
+    protected abstract spawnEnv(opts: RuntimeRunOptions): NodeJS.ProcessEnv;
+    /** Subclass hook: react to one `session/update` notification. */
+    protected abstract onUpdate(params: AcpUpdateParams, ctx: AcpUpdateCtx): void;
+    /** Subclass hook: respond to a `session/request_permission` request. */
+    protected abstract onPermissionRequest(req: AcpPermissionRequest, opts: RuntimeRunOptions): Promise<AcpPermissionResponse>;
+    /** Runtime-specific clientCapabilities sent on initialize. */
+    protected clientCapabilities(): Record<string, unknown>;
+    /** Runtime-specific clientInfo sent on initialize. */
+    protected clientInfo(): {
+        name: string;
+        version: string;
+    };
+    /**
+     * Hook invoked synchronously before spawn. Subclasses use this to write
+     * systemContext to disk (e.g. `<cwd>/AGENTS.md`).
+     */
+    protected prepareTurn(_opts: RuntimeRunOptions): void;
+    /** cwd passed to ACP `session/new` / `session/load`. Typically `opts.cwd`. */
+    protected sessionCwd(opts: RuntimeRunOptions): string;
+    run(opts: RuntimeRunOptions): Promise<RuntimeRunResult>;
+    private withTimeout;
+}