@openape/ape-agent 2.9.2 → 2.11.0

package/dist/index.d.ts

@@ -0,0 +1,356 @@
+import { DecisionResult } from '@openape/prompt-injection-detector';
+import { RuntimeConfig } from '@openape/apes';
+
+declare const REASONING_EFFORTS: readonly ["minimal", "low", "medium", "high"];
+type ReasoningEffort = typeof REASONING_EFFORTS[number];
+/**
+ * Telegram chat-adapter config. Present only when the owner has bound a bot
+ * token to this agent (delivered as a sealed secret → bridge env). Its mere
+ * presence activates the Telegram channel — no separate toggle.
+ */
+interface TelegramConfig {
+    botToken: string;
+    /**
+     * The one Telegram user id allowed to drive the bot. Optional: when unset,
+     * the channel pins the first user who messages it as the owner (trust on
+     * first use) and persists that — so the owner only has to supply the token.
+     * Set it explicitly to hard-lock without the first-contact step.
+     */
+    ownerUserId?: number;
+}
+interface BridgeConfig {
+    endpoint: string;
+    apesBin: string;
+    model: string;
+    /**
+     * Reasoning/thinking depth for gpt-5.x. Lets the PM tier compute by task
+     * difficulty without changing the model. Omitted = proxy/model default.
+     */
+    reasoningEffort?: ReasoningEffort;
+    systemPrompt: string;
+    tools: string[];
+    maxSteps: number;
+    roomFilter?: string;
+    /** Optional Telegram adapter — set when TELEGRAM_BOT_TOKEN is in the env. */
+    telegram?: TelegramConfig;
+}
+/**
+ * Resolve the bridge config from an env map. Defaults to `process.env` so the
+ * bin entrypoint is unchanged; the env is injectable so the nest's in-process
+ * SessionHost can resolve one config per agent (per-agent model merged into the
+ * map) without depending on or mutating the daemon's global `process.env`.
+ */
+declare function readConfig(env?: NodeJS.ProcessEnv): BridgeConfig;
+
+/**
+ * A decoded inbound troop chat frame worth acting on: the chat it belongs to
+ * plus the raw payload (`{id, chatId, role, body, ...}`). Produced by
+ * {@link AgentSession.parseChatFrame} after the protocol envelope is stripped.
+ */
+interface TroopChatFrame {
+    chatId: string;
+    payload: Record<string, unknown>;
+}
+/**
+ * A troop chat message in the chat.openape.ai-style shape the agent loop
+ * consumes — the input `runLoop` runs on. Produced by {@link AgentSession.toMessage}
+ * from a {@link TroopChatFrame}.
+ */
+interface TroopMessage {
+    id: string;
+    roomId: string;
+    threadId: string;
+    senderEmail: string;
+    senderAct: 'human' | 'agent';
+    body: string;
+    replyTo: string | null;
+    createdAt: number;
+    editedAt: number | null;
+}
+declare class AgentSession {
+    readonly email: string;
+    readonly ownerEmail: string;
+    readonly config: BridgeConfig;
+    /**
+     * Lazily-created prompt-injection detector, shared across this session's
+     * messages. Matches the per-agent bridge, which holds one
+     * `createHeuristicDetector()` for its lifetime.
+     */
+    private injectionDetector;
+    constructor(email: string, ownerEmail: string, config: BridgeConfig);
+    describe(): string;
+    /**
+     * Build this agent's troop chat WebSocket URL from its resolved endpoint and
+     * a bearer token. Ports the exact derivation the per-agent bridge uses in
+     * `pumpOnce` (http→ws, token carried as a query param, a leading `Bearer `
+     * prefix stripped, the value URL-encoded) so the nest's in-process WS-open
+     * increment connects to the same socket the bridge process opens today — with
+     * no second copy of the URL rule once the nest drives the connection.
+     */
+    chatSocketUrl(bearer: string): string;
+    /**
+     * Decode one raw troop chat-socket frame into a {@link TroopChatFrame}, or
+     * `null` for frames the agent ignores. Ports the exact decode + filter the
+     * per-agent bridge applies in `pumpOnce`: tolerate string or `Buffer` data,
+     * skip anything that is not valid JSON, and keep only `{type:'message'}`
+     * frames that carry a payload. This is the canonical home for the framing
+     * rule once the nest drives the connection — the WS-message increment routes
+     * accepted frames into the agent loop with no second copy of the rule.
+     */
+    parseChatFrame(data: unknown): TroopChatFrame | null;
+    /**
+     * Translate an accepted {@link TroopChatFrame} into the {@link TroopMessage}
+     * the agent loop runs on. Ports the bridge's `translateTroopPayload`: troop's
+     * payload carries `role` (human|agent) but no sender email, so the email is
+     * synthesized from role (agent → this session's own email, human → the owner)
+     * — the bridge skips its own echoes via `senderEmail === selfEmail`, so this
+     * mapping must match. `threadId` is the synthetic `'main'` because troop has
+     * no threads. This is the canonical home for the payload→message rule once the
+     * nest drives the connection: the runLoop-dispatch increment feeds this
+     * message straight into the loop with no second copy of the translation.
+     */
+    toMessage(frame: TroopChatFrame): TroopMessage;
+    /**
+     * Whether a translated {@link TroopMessage} is this agent's own echo. troop
+     * fans every chat message back to the socket that sent it, so the agent sees
+     * its own replies; feeding those into the loop would be an infinite feedback
+     * cycle. Ports the bridge's `handleInbound` guard (`senderEmail === selfEmail`)
+     * — the canonical home for the self-echo rule once the nest drives the
+     * connection: the runLoop-dispatch increment skips own echoes before it runs
+     * the loop, with no second copy of the comparison.
+     */
+    isOwnEcho(message: TroopMessage): boolean;
+    /**
+     * Whether a translated, non-echo {@link TroopMessage} should reach the agent
+     * loop. Ports the bridge's remaining pre-loop guards in `handleInbound`: an
+     * empty or whitespace-only body carries nothing to act on, and a configured
+     * `roomFilter` scopes the agent to a single chat. (The bridge's `threadId`
+     * guard is moot here — {@link toMessage} always synthesizes `'main'`.) The
+     * own-echo guard stays {@link isOwnEcho}, applied first by the caller. This is
+     * the canonical home for the dispatch-filter rule once the nest drives the
+     * connection: the runLoop-dispatch increment runs the loop only for messages
+     * this accepts, with no second copy of the guards.
+     */
+    shouldDispatch(message: TroopMessage): boolean;
+    /**
+     * Screen an accepted, non-echo {@link TroopMessage} for prompt injection
+     * before it reaches the agent loop. Ports the bridge's `handleInbound`
+     * choke-point: the bridge runs every inbound message through a heuristic
+     * detector and refuses to forward it when the score crosses the threshold,
+     * because once the text is in the loop's history a refusal is harder and
+     * inconsistent. The owner gets a higher bar (legitimate "run shell, do X"
+     * instructions aren't refused) — handled by `decide` keying the threshold off
+     * `sender.isOwner`. This is the canonical home for the screening rule once the
+     * nest drives the connection: the runLoop-dispatch increment refuses blocked
+     * messages with no second copy of the detector setup or the sender mapping.
+     */
+    screenInjection(message: TroopMessage): Promise<DecisionResult>;
+    /**
+     * The short, neutral refusal the agent posts back when {@link screenInjection}
+     * blocks a message. Ports the bridge's `refusalText`: the matched reason is
+     * appended so the owner sees in their chat history + audit log why a specific
+     * message was blocked, but the phrasing deliberately avoids language an
+     * attacker could copy back ("ignore previous instructions and …") to
+     * re-trigger the detector. This is the canonical home for the refusal-message
+     * rule once the nest drives the connection: the runLoop-dispatch increment
+     * posts this text on a block with no second copy of the wording.
+     */
+    refusalText(reason: string | undefined): string;
+}
+
+interface AgentIdentity {
+    email: string;
+    ownerEmail: string;
+    idp: string;
+}
+/**
+ * Read the agent's identity from auth.json. Throws if the file is
+ * missing or has no `email` — both indicate a botched spawn.
+ *
+ * `owner_email` is written by `apes agents spawn`. If it's missing we
+ * fall back to `OPENAPE_OWNER_EMAIL` from the container environment
+ * (compose `environment:` block) so an old auth.json that pre-dates
+ * Phase A doesn't strand the bridge in a crash loop. If both are
+ * missing we throw — the bridge requires it for the contact handshake.
+ *
+ * `home` defaults to the running process's home, which is the bin path's
+ * behaviour (each per-agent bridge ran as its own OS user). The nest's
+ * in-process SessionHost passes the registry entry's `home` so one daemon
+ * can read each hosted agent's identity from that agent's own home.
+ */
+declare function readAgentIdentity(home?: string): AgentIdentity;
+
+interface PostedMessage {
+    id: string;
+    roomId: string;
+    threadId: string;
+    body: string;
+    createdAt: number;
+}
+/**
+ * One row from chat history. Used by the bridge to backfill
+ * ThreadSession message history after a process restart.
+ */
+interface HistoryMessage {
+    id: string;
+    roomId: string;
+    threadId: string;
+    senderEmail: string;
+    senderAct: 'human' | 'agent';
+    body: string;
+    replyTo: string | null;
+    createdAt: number;
+}
+interface ContactView {
+    peerEmail: string;
+    myStatus: 'accepted' | 'pending' | 'blocked';
+    theirStatus: 'accepted' | 'pending' | 'blocked';
+    connected: boolean;
+    roomId: string | null;
+}
+/**
+ * Structural interface both the cron-runner and thread-session use
+ * so their call sites stay backend-agnostic.
+ */
+interface ChatBackend {
+    postMessage: (roomId: string, body: string, opts?: {
+        replyTo?: string;
+        threadId?: string;
+        streaming?: boolean;
+    }) => Promise<PostedMessage>;
+    listMessages: (roomId: string, threadId: string, limit?: number) => Promise<HistoryMessage[]>;
+    patchMessage: (messageId: string, opts?: {
+        body?: string;
+        streaming?: boolean;
+        streamingStatus?: string | null;
+    }) => Promise<void>;
+    listContacts: () => Promise<ContactView[]>;
+    requestContact: (peerEmail: string) => Promise<ContactView>;
+    acceptContact: (peerEmail: string) => Promise<ContactView>;
+    createThread: (roomId: string, name: string) => Promise<{
+        id: string;
+        name: string;
+    }>;
+}
+declare class TroopChatApi {
+    private endpoint;
+    private bearer;
+    private bootstrap;
+    constructor(endpoint: string, bearer: () => Promise<string>);
+    /** Resolve + cache the agent's chat row (lazy fetch on first use). */
+    private getBootstrap;
+    /** chat.id + (lazy-fetched) ownerEmail for the bridge's frame-translation path. */
+    getChatContext(): Promise<{
+        chatId: string;
+        ownerEmail: string;
+        agentEmail: string;
+    }>;
+    postMessage(roomId: string, body: string, opts?: {
+        replyTo?: string;
+        threadId?: string;
+        streaming?: boolean;
+    }): Promise<PostedMessage>;
+    listMessages(roomId: string, threadId: string, limit?: number): Promise<HistoryMessage[]>;
+    patchMessage(messageId: string, opts?: {
+        body?: string;
+        streaming?: boolean;
+        streamingStatus?: string | null;
+    }): Promise<void>;
+    /**
+     * Troop's chat doesn't have contacts — synthesize a single
+     *  always-connected entry pointing at the owner so the bridge's
+     *  initial-contact + allowlist flows are no-ops.
+     */
+    listContacts(): Promise<ContactView[]>;
+    requestContact(peerEmail: string): Promise<ContactView>;
+    acceptContact(peerEmail: string): Promise<ContactView>;
+    /**
+     * Troop has no threads — return a synthetic one. The bridge's
+     *  cron-runner falls back to the main thread on createThread
+     *  failure already, so a stable "main" stand-in is the right shape.
+     */
+    createThread(roomId: string, name: string): Promise<{
+        id: string;
+        name: string;
+    }>;
+}
+
+interface ThreadSessionDeps {
+    roomId: string;
+    threadId: string;
+    chat: ChatBackend;
+    /** LiteLLM proxy + model — the bridge resolves these from its env. */
+    runtimeConfig: RuntimeConfig;
+    /**
+     * Resolve the runtimeConfig fresh at the start of every turn. The gateway
+     * bearer is a short-lived (1h) DDISA-exchanged token; a long-lived thread
+     * that froze it at construction would present an expired token and get a
+     * 401. When provided, this is awaited per turn so the token stays fresh;
+     * falls back to the static `runtimeConfig` when absent (tests).
+     */
+    refreshRuntimeConfig?: () => Promise<RuntimeConfig>;
+    /**
+     * Resolve systemPrompt + tools at the start of every turn rather
+     * than freezing them at construction. Lets owner edits in the
+     * troop UI (which sync to `~/.openape/agent/agent.json` via
+     * `apes agents sync`) take effect on the next message in an
+     * existing thread — not just on freshly-opened threads.
+     * `tools` is the string list that `taskTools()` resolves to the
+     * concrete `ToolDefinition[]`.
+     */
+    resolveConfig: () => {
+        systemPrompt: string;
+        tools: string[];
+    };
+    /**
+     * Agent's own DDISA email — used to classify backfilled messages:
+     * `senderEmail === selfEmail` → role='assistant', else → 'user'.
+     */
+    selfEmail: string;
+    maxSteps: number;
+    /** Logger sink — bridge typically forwards to stderr. */
+    log: (line: string) => void;
+}
+declare class ThreadSession {
+    private deps;
+    private active;
+    private queue;
+    private history;
+    /**
+     * Whether we've already backfilled history from the chat server.
+     * Done lazily on the first turn so a freshly-created ThreadSession
+     * (e.g. after a bridge restart) sees the full conversation context,
+     * not just the message that woke it up. We skip the message that
+     * triggered the turn — runLoop adds it via `userMessage`.
+     */
+    private backfilled;
+    constructor(deps: ThreadSessionDeps);
+    /**
+     * No-op placeholder kept for API compatibility with the previous
+     *  RPC-listener model where dispose() detached the listener.
+     */
+    dispose(): void;
+    /** Forward an inbound chat message to the runtime. Queues if a turn is in flight. */
+    enqueue(body: string, replyToMessageId: string): void;
+    private startTurn;
+    /**
+     * Fetch recent chat history for this thread and seed `this.history`.
+     * Idempotent — only runs once per ThreadSession instance. Skips the
+     * placeholder we just posted plus the inbound message that triggered
+     * this turn (runLoop's `userMessage` handles that one).
+     *
+     * Failures are non-fatal: we log and continue with empty history.
+     * That preserves the pre-backfill behaviour rather than failing the
+     * turn over a transient chat-server hiccup.
+     */
+    private backfillHistoryOnce;
+    /**
+     * Stream-end: flush any pending throttled body PATCH, then mark the
+     * message as no-longer-streaming. The combined call also triggers
+     * the user-facing push (the placeholder POST suppressed it).
+     */
+    private endTurn;
+    private failTurn;
+}
+
+export { type AgentIdentity, AgentSession, type BridgeConfig, ThreadSession, type ThreadSessionDeps, TroopChatApi, type TroopChatFrame, type TroopMessage, readAgentIdentity, readConfig };