@tealbrick/kit 0.2.7 → 0.3.0-rc.10

package/dist/native-buzz.d.ts

@@ -0,0 +1,161 @@
+import type { ClaudeSdk } from './native-claude.js';
+/**
+ * Buzz (block/buzz) helpers for `kit native acp`: harness-authored prompt parsing, the `buzz` CLI
+ * runner, the owner-only in-process `buzz` MCP server, and the per-thread agent↔agent loop breaker.
+ * Message content is never parsed for identity or routing; only buzz-acp's structural blocks are.
+ */
+export declare const HEX64: RegExp;
+export type BuzzRouteInfo = {
+    channel: string;
+    replyTo?: string;
+};
+/** Routing extracted from buzz-acp's authoritative <context> block (channel UUID, reply anchor). */
+export declare function buzzRoute(prompt: string): BuzzRouteInfo | undefined;
+export interface BuzzTrigger {
+    route?: BuzzRouteInfo;
+    /** `Thread root:` from the <context> block. */
+    threadRoot?: string;
+    /** Triggering (last) event id and author, only when the event block parses unambiguously. */
+    eventId?: string;
+    author?: string;
+    /** Why author/event (or the route) could not be established (logged; never echoed to the model). */
+    unknown?: 'no_context' | 'route_rejected' | 'no_event_block' | 'ambiguous_event_block' | 'channel_mismatch';
+}
+/**
+ * Parse the trigger from buzz-acp's per-section prompt blocks (crates/buzz-acp/src/queue.rs
+ * format_prompt / format_context_hints / format_event_block; pool.rs sends one ACP text block per
+ * section). Event content is verbatim (unescaped) inside its block, so identity is read only from
+ * header lines at positions the harness controls, and a batch whose header count does not match
+ * its `count` attribute is treated as ambiguous rather than guessed.
+ */
+export declare function buzzTrigger(blocks: string[]): BuzzTrigger;
+/** Owner pubkey from a NIP-OA auth tag `["auth", ownerHex, conditions, sig]` (structure only). */
+export declare function ownerFromAuthTag(tag: string | undefined): string | undefined;
+/** x-only (BIP-340 / Nostr) public key for a hex or nsec secret key; undefined when unusable. */
+export declare function pubkeyFromSecret(secret: string | undefined): string | undefined;
+export type BuzzResult = {
+    ok: boolean;
+    stdout: string;
+    error?: string;
+};
+/** Runs `buzz` with an argv array (never a shell); stdin carries message content. */
+export type BuzzRun = (args: string[], stdin?: string) => Promise<BuzzResult>;
+/** Redact nsec keys and 64-hex values from error text (hex the caller passed in argv is kept). */
+export declare function redactSecrets(text: string, keep?: string[]): string;
+export declare function buzzRunner(cli: string, { timeoutMs, env, maxOutput }?: {
+    timeoutMs?: number;
+    env?: NodeJS.ProcessEnv;
+    maxOutput?: number;
+}): BuzzRun;
+/** Binary download through the CLI (`buzz media get <input> -o -`), capped at maxBytes. */
+export type BuzzDownload = (args: string[], maxBytes: number) => Promise<{
+    ok: boolean;
+    data?: Buffer;
+    error?: string;
+}>;
+export declare function buzzDownloader(cli: string, { timeoutMs, env }?: {
+    timeoutMs?: number;
+    env?: NodeJS.ProcessEnv;
+}): BuzzDownload;
+export declare const MAX_ATTACHMENT_BYTES: number;
+/** Content-type allowlist by magic bytes (images, pdf, audio, video, text, office); returns the file extension. */
+export declare function attachmentKind(data: Buffer, claimed?: string): string | undefined;
+export interface BuzzAttachments {
+    /**
+     * Kit-owned inbox `<root>/inbox` (realpath'd root). It lies outside the workspace: the sandboxed session
+     * may read it but never write it, so it cannot swap the directory or plant links while a download runs.
+     */
+    inbox: string;
+    /** Relay base URL (BUZZ_RELAY_URL); media URLs must be on this origin. */
+    relayUrl?: string;
+    download: BuzzDownload;
+    maxBytes?: number;
+}
+/** Validate a relay media reference: `sha256[.ext]`, or an URL on the relay origin under /media/. */
+export declare function mediaInput(input: string, relayUrl?: string): {
+    input: string;
+    sha: string;
+    ext?: string;
+} | undefined;
+/** Download into the kit-owned inbox as `<sha256>.<ext>` (temp file opened `wx` in the inbox, then renamed). */
+export declare function fetchAttachment(a: BuzzAttachments, raw: string): Promise<{
+    path: string;
+    bytes: number;
+}>;
+export declare const MAX_OUTGOING_FILES = 10, MAX_OUTGOING_BYTES: number, MAX_OUTGOING_TOTAL: number;
+export interface BuzzOutbox {
+    /** Realpath of the sandboxed workspace: only regular files inside it may be sent. */
+    workspace: string;
+    /** Kit-private staging root under `<root>/.tealbrick`, which the sandbox cannot write. */
+    dir: string;
+    maxBytes?: number;
+    maxTotal?: number;
+    /** Test hook: runs after a file is validated and before its bytes are copied. */
+    beforeCopy?: (path: string) => Promise<void>;
+}
+export type StagedFile = {
+    path: string;
+    name: string;
+    bytes: number;
+};
+/** Basename safe for the relay and logs: letters, digits, `._-`; no leading dot; at most 120 chars. */
+export declare function safeFileName(name: string): string;
+/** Absolute path for a file to send: inside the workspace, no dot segments (dotfiles, .tealbrick) and no `inbox`. */
+export declare function outgoingPath(workspace: string, p: string): string | undefined;
+/**
+ * Copy files the model names into a fresh kit-private staging dir, for the unsandboxed buzz CLI to upload.
+ * Each file is opened O_NOFOLLOW|O_NONBLOCK (no final symlink, no blocking FIFO), must be a regular file with
+ * one link (no hard link to a host file), and the opened inode must be the one at its realpath inside the
+ * workspace (so a symlinked or swapped directory cannot redirect the open). Bytes are then copied from that
+ * descriptor, never re-read by path, so a swap after validation cannot change what is uploaded.
+ */
+export declare function stageOutgoing(o: BuzzOutbox, paths: string[]): Promise<{
+    dir: string;
+    files: StagedFile[];
+}>;
+export declare const buzzToolNames: string[];
+/** Present only in the sandboxed workspace mode. */
+export declare const buzzAttachmentTool = "mcp__buzz__buzz_fetch_attachment";
+export type BuzzSent = {
+    channel: string;
+    replyTo?: string;
+    mentions: string[];
+    content: string;
+    eventId?: string;
+    files?: string[];
+};
+export declare const MAX_TOOL_OUTPUT = 12000;
+/** Compact, size-bounded view of `buzz messages get|thread` JSON output. */
+export declare function compactEvents(stdout: string, max?: number): string;
+export interface BuzzToolContext {
+    run: BuzzRun;
+    self?: string;
+    onSent?: (sent: BuzzSent) => void;
+    log?: (event: Record<string, unknown>) => void;
+    attachments?: BuzzAttachments;
+    outbox?: BuzzOutbox;
+}
+/** In-process `buzz` MCP server (owner session only; never handed to expert subagents). */
+export declare function buzzMcpServer(sdk: ClaudeSdk, ctx: BuzzToolContext): unknown;
+/** Neutralize `@Name` text so the CLI's content mention resolution cannot add p-tags we did not intend. */
+export declare function neutralizeMentions(content: string): string;
+export declare const LOOP_WINDOW_MS: number, LOOP_MAX_AGENT_TURNS = 4, REQUEST_TTL_MS: number, MAX_THREADS = 500;
+/** Agent-triggered turns one peer may cause across ALL threads per LOOP_WINDOW_MS (fan-out across new threads). */
+export declare const LOOP_MAX_PEER_TURNS = 8;
+/** Per-thread and per-peer agent↔agent bookkeeping: in memory, process lifetime, LRU-bounded. */
+export declare class BuzzThreads {
+    private now;
+    private max;
+    private peerMax;
+    private threads;
+    private peers;
+    constructor(now?: () => number, max?: number, peerMax?: number);
+    private get;
+    get size(): number;
+    /** Classify a turn triggered by another agent: capped (thread cap) or peer_capped (per-peer cap across threads): do not run; else an answer to our request, or a request to us. */
+    admit(key: string, author: string): 'capped' | 'peer_capped' | 'answer' | 'request';
+    /** Record that we asked these agents something in this thread. */
+    recordRequest(key: string, pubkeys: string[]): void;
+    /** At most one auto-post mention back per agent per thread per window. */
+    mayMentionBack(key: string, pubkey: string): boolean;
+}