@buoy-gg/agent-core 7.0.33

package/lib/typescript/policy/redact.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Scrub tool results before they leave the device.
+ *
+ * Two separate reasons, and the second is the one people forget:
+ *
+ * 1. EGRESS. Tool results go to the customer's own model endpoint. That is
+ *    their data boundary, not ours — but a response body carrying an
+ *    `Authorization` header or a Buoy `licenseKey` is a credential, and
+ *    credentials do not belong in a chat transcript that may be retained for
+ *    30 days for abuse monitoring.
+ * 2. SELF-INJECTION. Buoy's own network interceptor captures the agent's
+ *    requests to the model endpoint. Without exclusion, the model reads back
+ *    its own request headers — including whatever the host app's `headers()`
+ *    returned — out of `network.getRequests`. That is a credential leak and a
+ *    prompt-injection channel in one call.
+ */
+/**
+ * Deep-redact by key name AND by value shape. Depth-limited because tool
+ * results can be deeply nested state trees and a runaway walk on a megabyte
+ * payload is a frame drop on the JS thread the app is also using.
+ */
+export declare function redact(value: unknown, depth?: number): unknown;
+export declare function registerSelfEndpoint(endpoint: string): void;
+export declare function isSelfTraffic(url: unknown): boolean;
+/**
+ * Drop the agent's own requests out of a network-shaped result before the
+ * model sees them.
+ *
+ * WALKS INTO OBJECTS, not just top-level arrays. A network reader returns
+ * `{ totalCaptured, requests: [...] }`, not a bare array, and a version of
+ * this that only handled the bare array quietly did nothing — the agent's own
+ * POST to the model endpoint, headers and all, came straight back to it out
+ * of the network read. Depth-limited for the same reason `redact` is: this
+ * runs on the JS thread the app is drawing on.
+ */
+export declare function stripSelfTraffic(value: unknown, depth?: number): unknown;
+//# sourceMappingURL=redact.d.ts.map

package/lib/typescript/policy/redact.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"redact.d.ts","sourceRoot":"","sources":["../../../src/policy/redact.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAqDH;;;;GAIG;AACH,wBAAgB,MAAM,CAAC,KAAK,EAAE,OAAO,EAAE,KAAK,SAAI,GAAG,OAAO,CAazD;AAQD,wBAAgB,oBAAoB,CAAC,QAAQ,EAAE,MAAM,GAAG,IAAI,CAQ3D;AAED,wBAAgB,aAAa,CAAC,GAAG,EAAE,OAAO,GAAG,OAAO,CAOnD;AAQD;;;;;;;;;;GAUG;AACH,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,OAAO,EAAE,KAAK,SAAI,GAAG,OAAO,CAYnE"}

package/lib/typescript/providers/anthropic.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Anthropic Messages protocol.
+ *
+ * Four things here are not obvious and each one is a silent failure if missed:
+ *
+ * 1. `content_block_start` for a `tool_use` carries `"input": {}` — an EMPTY
+ *    object, never the real arguments. The arguments only exist after
+ *    concatenating every `input_json_delta.partial_json` and parsing at
+ *    `content_block_stop`. Reading `.input` at start yields a tool call with no
+ *    arguments and no error.
+ * 2. There is NO `data: [DONE]` sentinel (removed in the 2023-06-01 version).
+ *    The stream ends at `message_stop`.
+ * 3. `error` events arrive MID-STREAM on an already-committed HTTP 200 —
+ *    `overloaded_error` being the common one. A 200 is not success.
+ * 4. Ordering is 400-level strict: `tool_result` blocks must come FIRST in the
+ *    user content array with any text after, and that user message must
+ *    immediately follow the assistant turn. "Here are the results:" placed
+ *    before the blocks is an instant 400.
+ */
+import type { Provider, ProviderConfig } from "./types";
+export declare function createAnthropicProvider(config: ProviderConfig): Provider;
+//# sourceMappingURL=anthropic.d.ts.map

package/lib/typescript/providers/anthropic.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"anthropic.d.ts","sourceRoot":"","sources":["../../../src/providers/anthropic.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AACH,OAAO,KAAK,EAEV,QAAQ,EACR,cAAc,EAKf,MAAM,SAAS,CAAC;AAsCjB,wBAAgB,uBAAuB,CAAC,MAAM,EAAE,cAAc,GAAG,QAAQ,CAkLxE"}

package/lib/typescript/providers/openai.d.ts

@@ -0,0 +1,19 @@
+/**
+ * OpenAI chat-completions protocol.
+ *
+ * The differences from Anthropic that actually matter to the code:
+ * - Tool results are their own `{role:"tool", tool_call_id, content}` MESSAGE,
+ *   not blocks inside a user message.
+ * - Tool arguments arrive as a JSON STRING, streamed in fragments, and are
+ *   keyed by an `index` that is stable across deltas while `id`/`name` only
+ *   appear on the first fragment.
+ * - The stream DOES have a `data: [DONE]` sentinel, unlike Anthropic's.
+ *
+ * This adapter also serves Azure and any OpenAI-compatible org gateway, which
+ * is the common shape for an internal LLM proxy. Note Anthropic's own
+ * OpenAI-compatibility endpoint is explicitly not production-ready and silently
+ * ignores several fields — use the native Anthropic adapter for Anthropic.
+ */
+import type { Provider, ProviderConfig } from "./types";
+export declare function createOpenAIProvider(config: ProviderConfig): Provider;
+//# sourceMappingURL=openai.d.ts.map

package/lib/typescript/providers/openai.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"openai.d.ts","sourceRoot":"","sources":["../../../src/providers/openai.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AACH,OAAO,KAAK,EAEV,QAAQ,EACR,cAAc,EAGf,MAAM,SAAS,CAAC;AA2CjB,wBAAgB,oBAAoB,CAAC,MAAM,EAAE,cAAc,GAAG,QAAQ,CA+GrE"}

package/lib/typescript/providers/sse.d.ts

@@ -0,0 +1,18 @@
+/**
+ * SSE reading, with the React Native reality baked in.
+ *
+ * RN's built-in `fetch` does not implement `response.body`. Under Expo you get
+ * a real `ReadableStream` because `expo/fetch` is the global — but
+ * `EXPO_PUBLIC_USE_RN_FETCH=1` reverts that, and the bare-RN, NativeScript and
+ * TV-CLI lanes never had it. So `readSse` degrades to reading the whole body
+ * and replaying it as events rather than failing: a non-streaming answer is a
+ * slower chat, while a hard failure is no chat at all.
+ */
+export interface SseEvent {
+    event?: string;
+    data: string;
+}
+export declare function readSse(response: Response): AsyncGenerator<SseEvent, void, void>;
+/** Body text for a failed response, trimmed to something a user can read. */
+export declare function errorBody(response: Response): Promise<string>;
+//# sourceMappingURL=sse.d.ts.map

package/lib/typescript/providers/sse.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sse.d.ts","sourceRoot":"","sources":["../../../src/providers/sse.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,MAAM,WAAW,QAAQ;IACvB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,IAAI,EAAE,MAAM,CAAC;CACd;AAsBD,wBAAuB,OAAO,CAC5B,QAAQ,EAAE,QAAQ,GACjB,cAAc,CAAC,QAAQ,EAAE,IAAI,EAAE,IAAI,CAAC,CAkDtC;AAED,6EAA6E;AAC7E,wBAAsB,SAAS,CAAC,QAAQ,EAAE,QAAQ,GAAG,OAAO,CAAC,MAAM,CAAC,CAQnE"}

package/lib/typescript/providers/types.d.ts

@@ -0,0 +1,129 @@
+/**
+ * The provider boundary.
+ *
+ * Anthropic and OpenAI look similar and are not. Anthropic puts tool results in
+ * `tool_result` content blocks inside a USER message and delivers arguments as
+ * a parsed object; OpenAI uses a separate `{role:"tool"}` MESSAGE and delivers
+ * arguments as a JSON STRING. A single shared "message" type leaks that
+ * difference into every caller, so the normalisation happens here: the engine
+ * speaks only {@link AgentMessage}, and each adapter owns the reshaping.
+ */
+import type { ProviderTool } from "../catalog/toProviderTools";
+/** A tool call the model asked for, normalised across providers. */
+export interface ToolCall {
+    /** Provider-assigned id; must be echoed back on the result. */
+    id: string;
+    /** Provider tool name, e.g. `buoy_storage`. */
+    name: string;
+    /** Parsed arguments. OpenAI's JSON string is parsed by the adapter. */
+    input: Record<string, unknown>;
+}
+export interface ToolResult {
+    toolCallId: string;
+    /** Already JSON-encoded and truncated by the engine. */
+    content: string;
+    isError?: boolean;
+}
+export type AgentMessage = {
+    role: "user";
+    text: string;
+} | {
+    role: "assistant";
+    text: string;
+    toolCalls?: ToolCall[];
+} | {
+    role: "tool-results";
+    results: ToolResult[];
+};
+/** Incremental output from a streaming turn. */
+export type StreamEvent = {
+    type: "text";
+    delta: string;
+} | {
+    type: "tool-call";
+    call: ToolCall;
+}
+/** Mid-stream provider error. Anthropic can emit these on a committed 200. */
+ | {
+    type: "error";
+    message: string;
+} | {
+    type: "done";
+    stopReason?: string;
+    usage?: TokenUsage;
+};
+export interface TokenUsage {
+    input: number;
+    output: number;
+    /**
+     * Anthropic's prompt-cache counters, when the provider reports them.
+     * `cacheRead` is the prefix that was served from cache at 0.1x — the whole
+     * point of caching — and `cacheWrite` is the prefix stored at 1.25x on the
+     * request that populated it. Both are reported SEPARATELY from `input` by
+     * the API, so a cached request shows a tiny `input` and a large `cacheRead`
+     * rather than a smaller `input`; adding them is what gives the real total.
+     */
+    cacheRead?: number;
+    cacheWrite?: number;
+}
+export interface ProviderRequest {
+    messages: AgentMessage[];
+    system: string;
+    tools: ProviderTool[];
+    model: string;
+    maxTokens: number;
+    signal?: AbortSignal;
+}
+export interface ProviderConfig {
+    /** The org's gateway, or the provider's own URL for the dev-only direct mode. */
+    endpoint: string;
+    /**
+     * Fresh headers per request, so short-lived tokens from the host app's own
+     * session work. This is why Buoy stores no credential of its own.
+     */
+    headers?: () => Record<string, string> | Promise<Record<string, string>>;
+    /** Dev-only direct mode. Never for a distributed build. */
+    apiKey?: string;
+    model: string;
+    maxTokens?: number;
+    /** Anthropic API version header. Ignored by the OpenAI adapter. */
+    anthropicVersion?: string;
+    /**
+     * Ask Anthropic to cache the unchanging prefix of every request — the tool
+     * definitions and the system prompt. Default true; ignored by the OpenAI
+     * adapter, which caches automatically with no annotation.
+     *
+     * WHY IT IS ON BY DEFAULT. That prefix is ~20k tokens (24 tools, 192
+     * actions) and is byte-identical on every request of every turn, and a turn
+     * re-sends it once per tool round-trip: a four-tool answer paid for it five
+     * times. A cache write costs 1.25x and a read costs 0.1x, so anything past
+     * the first request is a ~90% saving on the largest part of the bill.
+     *
+     * The one case where this LOSES is a turn that calls no tools and is never
+     * followed by another within the cache's 5-minute window — one request that
+     * pays the write multiplier and never reads. That is not what a devtools
+     * chat session looks like, which is why the default is on rather than off.
+     *
+     * Set false for a gateway that rejects unknown `cache_control` fields.
+     */
+    cache?: boolean;
+    /**
+     * Extra fields merged into every request BODY, last — `temperature`, a
+     * gateway's routing hints, whatever the endpoint demands that this config
+     * doesn't model. The escape hatch that keeps one config type honest across
+     * every OpenAI-compatible gateway; core fields (model, messages, tools,
+     * stream) win only if you don't override them, so use with care.
+     */
+    requestOverrides?: Record<string, unknown>;
+}
+export interface Provider {
+    readonly protocol: "anthropic" | "openai";
+    /**
+     * Run one request. Yields incrementally when the platform supports it and
+     * falls back to a single buffered chunk when it does not — React Native's
+     * built-in fetch has no `response.body`, so streaming only exists where
+     * `expo/fetch` is the global.
+     */
+    send(req: ProviderRequest): AsyncGenerator<StreamEvent, void, void>;
+}
+//# sourceMappingURL=types.d.ts.map

package/lib/typescript/providers/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../src/providers/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AACH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,4BAA4B,CAAC;AAE/D,oEAAoE;AACpE,MAAM,WAAW,QAAQ;IACvB,+DAA+D;IAC/D,EAAE,EAAE,MAAM,CAAC;IACX,+CAA+C;IAC/C,IAAI,EAAE,MAAM,CAAC;IACb,uEAAuE;IACvE,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CAChC;AAED,MAAM,WAAW,UAAU;IACzB,UAAU,EAAE,MAAM,CAAC;IACnB,wDAAwD;IACxD,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,CAAC,EAAE,OAAO,CAAC;CACnB;AAED,MAAM,MAAM,YAAY,GACpB;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,GAC9B;IAAE,IAAI,EAAE,WAAW,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,SAAS,CAAC,EAAE,QAAQ,EAAE,CAAA;CAAE,GAC3D;IAAE,IAAI,EAAE,cAAc,CAAC;IAAC,OAAO,EAAE,UAAU,EAAE,CAAA;CAAE,CAAC;AAEpD,gDAAgD;AAChD,MAAM,MAAM,WAAW,GACnB;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,GAC/B;IAAE,IAAI,EAAE,WAAW,CAAC;IAAC,IAAI,EAAE,QAAQ,CAAA;CAAE;AACvC,8EAA8E;GAC5E;IAAE,IAAI,EAAE,OAAO,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,GAClC;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,UAAU,CAAC,EAAE,MAAM,CAAC;IAAC,KAAK,CAAC,EAAE,UAAU,CAAA;CAAE,CAAC;AAE9D,MAAM,WAAW,UAAU;IACzB,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,CAAC;IACf;;;;;;;OAOG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED,MAAM,WAAW,eAAe;IAC9B,QAAQ,EAAE,YAAY,EAAE,CAAC;IACzB,MAAM,EAAE,MAAM,CAAC;IACf,KAAK,EAAE,YAAY,EAAE,CAAC;IACtB,KAAK,EAAE,MAAM,CAAC;IACd,SAAS,EAAE,MAAM,CAAC;IAClB,MAAM,CAAC,EAAE,WAAW,CAAC;CACtB;AAED,MAAM,WAAW,cAAc;IAC7B,iFAAiF;IACjF,QAAQ,EAAE,MAAM,CAAC;IACjB;;;OAGG;IACH,OAAO,CAAC,EAAE,MAAM,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;IACzE,2DAA2D;IAC3D,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,KAAK,EAAE,MAAM,CAAC;IACd,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,mEAAmE;IACnE,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B;;;;;;;;;;;;;;;;;OAiBG;IACH,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB;;;;;;OAMG;IACH,gBAAgB,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CAC5C;AAED,MAAM,WAAW,QAAQ;IACvB,QAAQ,CAAC,QAAQ,EAAE,WAAW,GAAG,QAAQ,CAAC;IAC1C;;;;;OAKG;IACH,IAAI,CAAC,GAAG,EAAE,eAAe,GAAG,cAAc,CAAC,WAAW,EAAE,IAAI,EAAE,IAAI,CAAC,CAAC;CACrE"}

package/lib/typescript/session.d.ts

@@ -0,0 +1,58 @@
+import { type TurnEvent } from "./engine/runAgentTurn";
+import { type ContextPack } from "./engine/systemPrompt";
+import { EffectLedger } from "./effects/ledger";
+import type { AgentMessage, ProviderConfig } from "./providers/types";
+import { type AskBuoyPolicy } from "./policy/policy";
+import type { DispatchFn, SnapshotFn, ToolDescriptor } from "./types";
+export interface AskBuoySessionConfig extends ProviderConfig {
+    protocol: "anthropic" | "openai";
+    dispatch: DispatchFn;
+    /**
+     * Reads a tool's `getSnapshot`. Without it the console, network, route and
+     * env reads are unavailable — they are snapshot-only, not actions.
+     */
+    readSnapshot?: SnapshotFn;
+    /**
+     * From `listToolActions()` — the live truth about this device, with
+     * `getSnapshot` appended for tools whose adapter publishes one.
+     */
+    availableActions: Record<string, string[]>;
+    policy?: AskBuoyPolicy;
+    context?: ContextPack;
+    /** `__DEV__ === false` for this bundle. */
+    isRelease: boolean;
+    appName?: string;
+    platform?: string;
+    /** Override the built-in catalog. Tests and the desktop port use this. */
+    catalog?: ToolDescriptor[];
+    requestApproval?: RunApproval;
+}
+type RunApproval = (input: {
+    id: string;
+    toolId: string;
+    action: string;
+    label: string;
+    description: string;
+    reason: string;
+}) => Promise<boolean>;
+export interface AskBuoySession {
+    readonly ledger: EffectLedger;
+    readonly messages: AgentMessage[];
+    /** Probe the app for grounding. Safe to call more than once. */
+    prime(): Promise<void>;
+    /**
+     * Re-point the session at the tools this device currently exposes.
+     *
+     * The live tool list is NOT session identity: packages register a frame or
+     * two apart, so it legitimately changes right after open. Rebuilding the
+     * session when it does threw away the conversation, the model's memory and
+     * the undo ledger mid-chat — silently, because the transcript lives in a
+     * separate store and kept rendering. Update in place instead.
+     */
+    setAvailableActions(actions: Record<string, string[]>): void;
+    send(text: string, signal?: AbortSignal): AsyncGenerator<TurnEvent, void, void>;
+    reset(): void;
+}
+export declare function createAskBuoySession(config: AskBuoySessionConfig): AskBuoySession;
+export {};
+//# sourceMappingURL=session.d.ts.map

package/lib/typescript/session.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"session.d.ts","sourceRoot":"","sources":["../../src/session.ts"],"names":[],"mappings":"AAWA,OAAO,EAAgB,KAAK,SAAS,EAAE,MAAM,uBAAuB,CAAC;AACrE,OAAO,EAAqB,KAAK,WAAW,EAAE,MAAM,uBAAuB,CAAC;AAC5E,OAAO,EAAE,YAAY,EAAE,MAAM,kBAAkB,CAAC;AAGhD,OAAO,KAAK,EAAE,YAAY,EAAY,cAAc,EAAE,MAAM,mBAAmB,CAAC;AAChF,OAAO,EAA0B,KAAK,aAAa,EAAE,MAAM,iBAAiB,CAAC;AAE7E,OAAO,KAAK,EAAE,UAAU,EAAE,UAAU,EAAE,cAAc,EAAE,MAAM,SAAS,CAAC;AAEtE,MAAM,WAAW,oBAAqB,SAAQ,cAAc;IAC1D,QAAQ,EAAE,WAAW,GAAG,QAAQ,CAAC;IACjC,QAAQ,EAAE,UAAU,CAAC;IACrB;;;OAGG;IACH,YAAY,CAAC,EAAE,UAAU,CAAC;IAC1B;;;OAGG;IACH,gBAAgB,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,EAAE,CAAC,CAAC;IAC3C,MAAM,CAAC,EAAE,aAAa,CAAC;IACvB,OAAO,CAAC,EAAE,WAAW,CAAC;IACtB,2CAA2C;IAC3C,SAAS,EAAE,OAAO,CAAC;IACnB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,0EAA0E;IAC1E,OAAO,CAAC,EAAE,cAAc,EAAE,CAAC;IAC3B,eAAe,CAAC,EAAE,WAAW,CAAC;CAC/B;AAED,KAAK,WAAW,GAAG,CAAC,KAAK,EAAE;IACzB,EAAE,EAAE,MAAM,CAAC;IACX,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,MAAM,CAAC;IACf,KAAK,EAAE,MAAM,CAAC;IACd,WAAW,EAAE,MAAM,CAAC;IACpB,MAAM,EAAE,MAAM,CAAC;CAChB,KAAK,OAAO,CAAC,OAAO,CAAC,CAAC;AAEvB,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,MAAM,EAAE,YAAY,CAAC;IAC9B,QAAQ,CAAC,QAAQ,EAAE,YAAY,EAAE,CAAC;IAClC,gEAAgE;IAChE,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IACvB;;;;;;;;OAQG;IACH,mBAAmB,CAAC,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,EAAE,CAAC,GAAG,IAAI,CAAC;IAC7D,IAAI,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,WAAW,GAAG,cAAc,CAAC,SAAS,EAAE,IAAI,EAAE,IAAI,CAAC,CAAC;IAChF,KAAK,IAAI,IAAI,CAAC;CACf;AAsCD,wBAAgB,oBAAoB,CAAC,MAAM,EAAE,oBAAoB,GAAG,cAAc,CAqHjF"}

package/lib/typescript/types.d.ts

@@ -0,0 +1,119 @@
+/**
+ * The vocabulary Ask Buoy needs and Buoy's wire protocol does not have.
+ *
+ * The device advertises `ToolCapability { toolId, version, actions: string[] }`
+ * — names only. Nothing on the wire, and nothing in `toolActionRegistry`, says
+ * what an action's params look like, whether calling it changes anything, or
+ * whether it still works once `__DEV__` is false. The MCP server papers over
+ * that with ~48 hand-written zod shapes, but those live in a Node-only package
+ * and cover a fraction of the ~179 actions.
+ *
+ * This module is that missing description, as plain data, so an agent can be
+ * told the truth about a tool before it calls one.
+ */
+/**
+ * A JSON Schema subset: object/string/number/boolean/array + enum + required.
+ * Deliberately not the whole spec — `validateParams` implements exactly this
+ * much, and a schema the validator cannot check is worse than no schema.
+ */
+export interface JsonSchema {
+    type?: "object" | "string" | "number" | "integer" | "boolean" | "array" | "null";
+    description?: string;
+    enum?: (string | number | boolean | null)[];
+    properties?: Record<string, JsonSchema>;
+    required?: string[];
+    additionalProperties?: boolean;
+    items?: JsonSchema;
+    default?: unknown;
+    /** Union of primitive shapes, for the few params that genuinely take either. */
+    anyOf?: JsonSchema[];
+    /** Tuple bounds — `storage.async.multiSet` takes [key, value] pairs. */
+    minItems?: number;
+    maxItems?: number;
+}
+/**
+ * What calling this action does to the app.
+ *
+ * `destructive` is deliberately broad: anything that wipes, clears, resets,
+ * replaces a whole store, reloads the realm, or starts impersonating a real
+ * person. When the classification is arguable, the catalog rounds UP — the
+ * cost of an over-cautious label is a confirmation the user didn't need; the
+ * cost of an under-cautious one is a tester's device state gone.
+ */
+export type ActionEffect = "read" | "write" | "destructive";
+/**
+ * What this action does in a RELEASE build (`__DEV__ === false`).
+ *
+ * This field exists because several Buoy actions REPORT SUCCESS AND DO NOTHING
+ * once `__DEV__` is false, and an agent that relays that success to a QA tester
+ * causes a bug report filed against data that was never applied. Two live
+ * examples: `network.upsertOverrideRule` persists a rule the engine will never
+ * consult (`network/overrides/engine.ts:74`), and every fiber-walking action
+ * returns empty because React Native installs `__REACT_DEVTOOLS_GLOBAL_HOOK__`
+ * only under `if (__DEV__)` — no Buoy code ever installs it, so no amount of
+ * configuration brings those back.
+ */
+export type ReleaseBehavior = 
+/** Behaves the same in dev and release. */
+"works"
+/** Returns a success result and has no effect. The dangerous one. */
+ | "noop"
+/** Succeeds but the data is always empty. */
+ | "empty"
+/** Raises an error, which at least is honest. */
+ | "throws"
+/** Not established. Treated as `noop` by the policy layer — fail closed. */
+ | "unknown";
+/** How to reverse an action, when it can be reversed at all. */
+export interface UndoSpec {
+    /** The action on the same tool that reverses this one. */
+    action: string;
+    /** How to build the undo params from the original call's params/result. */
+    note: string;
+}
+export interface ActionDescriptor {
+    /** Exact key in the adapter's `actions` object. Never a display name. */
+    action: string;
+    /** One line, written to help a model choose between sibling actions. */
+    summary: string;
+    /** Gotchas, defaults, and what the result looks like. */
+    description?: string;
+    params: JsonSchema;
+    effect: ActionEffect;
+    release: ReleaseBehavior;
+    /** For non-`works` release behaviour: the evidence and the reason. */
+    releaseNote?: string;
+    /**
+     * Host-app prerequisites this action needs beyond the package being
+     * installed — `expo-router`, `<RouteTracker/>` mounted,
+     * `createImpersonateTool({onSearchUsers})`, a TV platform. An action name
+     * appearing in `listToolActions()` does NOT mean it can do anything here.
+     */
+    requires?: string[];
+    undo?: UndoSpec;
+    /**
+     * True when the tool's store only records while something holds a
+     * subscription. A cold read then returns an empty timeline, and the honest
+     * answer is "nothing is holding capture open", never "nothing happened".
+     */
+    armsCapture?: boolean;
+}
+export interface ToolDescriptor {
+    /** The sync tool id — `query`, `route-events`, `time-machine`, … */
+    toolId: string;
+    title: string;
+    /** 1-3 sentences telling a model what this tool is for. */
+    summary: string;
+    /** When the whole tool is absent or inert on a device. */
+    unavailableWhen?: string;
+    actions: ActionDescriptor[];
+}
+/** The one function `agent-core` needs from its host to actually do anything. */
+export type DispatchFn = (toolId: string, action: string, params?: unknown) => Promise<unknown>;
+/**
+ * Read a tool's `getSnapshot` — the half of Buoy's read surface that is not an
+ * action. See `catalog/snapshotReads.ts`; without it the agent cannot see the
+ * console, network traffic, routes or env at all.
+ */
+export type SnapshotFn = (toolId: string) => Promise<unknown>;
+//# sourceMappingURL=types.d.ts.map

package/lib/typescript/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH;;;;GAIG;AACH,MAAM,WAAW,UAAU;IACzB,IAAI,CAAC,EAAE,QAAQ,GAAG,QAAQ,GAAG,QAAQ,GAAG,SAAS,GAAG,SAAS,GAAG,OAAO,GAAG,MAAM,CAAC;IACjF,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,IAAI,CAAC,EAAE,CAAC,MAAM,GAAG,MAAM,GAAG,OAAO,GAAG,IAAI,CAAC,EAAE,CAAC;IAC5C,UAAU,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,UAAU,CAAC,CAAC;IACxC,QAAQ,CAAC,EAAE,MAAM,EAAE,CAAC;IACpB,oBAAoB,CAAC,EAAE,OAAO,CAAC;IAC/B,KAAK,CAAC,EAAE,UAAU,CAAC;IACnB,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,gFAAgF;IAChF,KAAK,CAAC,EAAE,UAAU,EAAE,CAAC;IACrB,wEAAwE;IACxE,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED;;;;;;;;GAQG;AACH,MAAM,MAAM,YAAY,GAAG,MAAM,GAAG,OAAO,GAAG,aAAa,CAAC;AAE5D;;;;;;;;;;;GAWG;AACH,MAAM,MAAM,eAAe;AACzB,2CAA2C;AACzC,OAAO;AACT,qEAAqE;GACnE,MAAM;AACR,6CAA6C;GAC3C,OAAO;AACT,iDAAiD;GAC/C,QAAQ;AACV,4EAA4E;GAC1E,SAAS,CAAC;AAEd,gEAAgE;AAChE,MAAM,WAAW,QAAQ;IACvB,0DAA0D;IAC1D,MAAM,EAAE,MAAM,CAAC;IACf,2EAA2E;IAC3E,IAAI,EAAE,MAAM,CAAC;CACd;AAED,MAAM,WAAW,gBAAgB;IAC/B,yEAAyE;IACzE,MAAM,EAAE,MAAM,CAAC;IACf,wEAAwE;IACxE,OAAO,EAAE,MAAM,CAAC;IAChB,yDAAyD;IACzD,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,MAAM,EAAE,UAAU,CAAC;IACnB,MAAM,EAAE,YAAY,CAAC;IACrB,OAAO,EAAE,eAAe,CAAC;IACzB,sEAAsE;IACtE,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB;;;;;OAKG;IACH,QAAQ,CAAC,EAAE,MAAM,EAAE,CAAC;IACpB,IAAI,CAAC,EAAE,QAAQ,CAAC;IAChB;;;;OAIG;IACH,WAAW,CAAC,EAAE,OAAO,CAAC;CACvB;AAED,MAAM,WAAW,cAAc;IAC7B,oEAAoE;IACpE,MAAM,EAAE,MAAM,CAAC;IACf,KAAK,EAAE,MAAM,CAAC;IACd,2DAA2D;IAC3D,OAAO,EAAE,MAAM,CAAC;IAChB,0DAA0D;IAC1D,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,OAAO,EAAE,gBAAgB,EAAE,CAAC;CAC7B;AAED,iFAAiF;AACjF,MAAM,MAAM,UAAU,GAAG,CACvB,MAAM,EAAE,MAAM,EACd,MAAM,EAAE,MAAM,EACd,MAAM,CAAC,EAAE,OAAO,KACb,OAAO,CAAC,OAAO,CAAC,CAAC;AAEtB;;;;GAIG;AACH,MAAM,MAAM,UAAU,GAAG,CAAC,MAAM,EAAE,MAAM,KAAK,OAAO,CAAC,OAAO,CAAC,CAAC"}

package/package.json

@@ -0,0 +1,58 @@
+{
+  "name": "@buoy-gg/agent-core",
+  "version": "7.0.33",
+  "description": "Headless agent core for Ask Buoy - the tool catalog, BYO-model providers, turn loop and effect ledger that let an LLM drive Buoy devtools",
+  "main": "lib/commonjs/index.js",
+  "module": "lib/module/index.js",
+  "types": "lib/typescript/index.d.ts",
+  "react-native": "lib/module/index.js",
+  "source": "src/index.ts",
+  "files": [
+    "lib"
+  ],
+  "keywords": [
+    "react-native",
+    "devtools",
+    "ai",
+    "agent",
+    "llm",
+    "buoy"
+  ],
+  "devDependencies": {
+    "typescript": "~5.8.3"
+  },
+  "react-native-builder-bob": {
+    "source": "src",
+    "output": "lib",
+    "targets": [
+      "commonjs",
+      "module",
+      [
+        "typescript",
+        {
+          "project": "tsconfig.build.json"
+        }
+      ]
+    ]
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/LovesWorking/react-native-buoy.git",
+    "directory": "packages/agent-core"
+  },
+  "bugs": {
+    "url": "https://github.com/LovesWorking/react-native-buoy/issues"
+  },
+  "homepage": "https://github.com/LovesWorking/react-native-buoy/tree/main/packages/agent-core#readme",
+  "publishConfig": {
+    "access": "public",
+    "tag": "latest"
+  },
+  "scripts": {
+    "build": "bob build",
+    "typecheck": "tsc --noEmit",
+    "clean": "rimraf lib",
+    "test": "pnpm run typecheck",
+    "postinstall": "echo \"Run pnpm build to compile this package\""
+  }
+}