@pinecall/agents 0.9.20

package/dist/client/index.d.ts

@@ -0,0 +1,18 @@
+export { Agent } from "./agent.js";
+export type { AgentGateway, AgentOptions, DevHandler, Tool } from "./agent.js";
+export { Call, CallBook } from "./calls.js";
+export type { CallGateway, CallStatus } from "./calls.js";
+export { Pinecall } from "./client.js";
+export type { DrainOptions, Drained, Found, PinecallOptions } from "./client.js";
+export { Connection } from "./connection.js";
+export type { Backoff, ConnectionHandlers, ConnectionOptions } from "./connection.js";
+export { agentLogUrl, appsUrl, callLogUrl, lookupUrl } from "./endpoints.js";
+export { DevRefused, PinecallError, Refused, frame, nextId } from "./frames.js";
+export { Listeners, camelEvent } from "./listeners.js";
+export type { AnyListener, CamelEvent, Listener, Payload } from "./listeners.js";
+export { aLostSocket } from "./lost.js";
+export { history, observe } from "./observe.js";
+export type { LogTarget, Observation, Page, ReadOptions } from "./observe.js";
+export { signed } from "./signed.js";
+export type { World } from "./signed.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/client/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/client/index.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,KAAK,EAAE,MAAM,YAAY,CAAC;AACnC,YAAY,EAAE,YAAY,EAAE,YAAY,EAAE,UAAU,EAAE,IAAI,EAAE,MAAM,YAAY,CAAC;AAC/E,OAAO,EAAE,IAAI,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AAC5C,YAAY,EAAE,WAAW,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAC1D,OAAO,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAC;AACvC,YAAY,EAAE,YAAY,EAAE,OAAO,EAAE,KAAK,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AACjF,OAAO,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAC;AAC7C,YAAY,EAAE,OAAO,EAAE,kBAAkB,EAAE,iBAAiB,EAAE,MAAM,iBAAiB,CAAC;AACtF,OAAO,EAAE,WAAW,EAAE,OAAO,EAAE,UAAU,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAC;AAC7E,OAAO,EAAE,UAAU,EAAE,aAAa,EAAE,OAAO,EAAE,KAAK,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AAChF,OAAO,EAAE,SAAS,EAAE,UAAU,EAAE,MAAM,gBAAgB,CAAC;AACvD,YAAY,EAAE,WAAW,EAAE,UAAU,EAAE,QAAQ,EAAE,OAAO,EAAE,MAAM,gBAAgB,CAAC;AACjF,OAAO,EAAE,WAAW,EAAE,MAAM,WAAW,CAAC;AACxC,OAAO,EAAE,OAAO,EAAE,OAAO,EAAE,MAAM,cAAc,CAAC;AAChD,YAAY,EAAE,SAAS,EAAE,WAAW,EAAE,IAAI,EAAE,WAAW,EAAE,MAAM,cAAc,CAAC;AAC9E,OAAO,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AACrC,YAAY,EAAE,KAAK,EAAE,MAAM,aAAa,CAAC"}

package/dist/client/index.js

@@ -0,0 +1,13 @@
+// @pinecall/agents/client: register agents over the gateway socket, answer tool calls, and read logs.
+// Socket layer only, with no dependency on the Agent framework, views or CLI.
+export { Agent } from "./agent.js";
+export { Call, CallBook } from "./calls.js";
+export { Pinecall } from "./client.js";
+export { Connection } from "./connection.js";
+export { agentLogUrl, appsUrl, callLogUrl, lookupUrl } from "./endpoints.js";
+export { DevRefused, PinecallError, Refused, frame, nextId } from "./frames.js";
+export { Listeners, camelEvent } from "./listeners.js";
+export { aLostSocket } from "./lost.js";
+export { history, observe } from "./observe.js";
+export { signed } from "./signed.js";
+//# sourceMappingURL=index.js.map

package/dist/client/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/client/index.ts"],"names":[],"mappings":"AAAA,sGAAsG;AACtG,8EAA8E;AAE9E,OAAO,EAAE,KAAK,EAAE,MAAM,YAAY,CAAC;AAEnC,OAAO,EAAE,IAAI,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AAE5C,OAAO,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAC;AAEvC,OAAO,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAC;AAE7C,OAAO,EAAE,WAAW,EAAE,OAAO,EAAE,UAAU,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAC;AAC7E,OAAO,EAAE,UAAU,EAAE,aAAa,EAAE,OAAO,EAAE,KAAK,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AAChF,OAAO,EAAE,SAAS,EAAE,UAAU,EAAE,MAAM,gBAAgB,CAAC;AAEvD,OAAO,EAAE,WAAW,EAAE,MAAM,WAAW,CAAC;AACxC,OAAO,EAAE,OAAO,EAAE,OAAO,EAAE,MAAM,cAAc,CAAC;AAEhD,OAAO,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC"}

package/dist/client/listeners.d.ts

@@ -0,0 +1,35 @@
+import { type Camel, type Event, type EventData } from "../wire/codec.js";
+import { type EventType } from "../wire/registry.js";
+/** An event's data in camelCase. */
+export type Payload<K extends EventType> = Camel<EventData<K>>;
+/** A camelCase event, discriminated by `type`. */
+export type CamelEvent = {
+    [K in EventType]: {
+        type: K;
+        data: Payload<K>;
+    };
+}[EventType];
+/** Listener for one event type. */
+export type Listener<K extends EventType, Context> = (data: Payload<K>, context: Context) => unknown;
+/** Listener for every event. */
+export type AnyListener<Context> = (event: CamelEvent, context: Context) => unknown;
+/** Convert a decoded event's data keys to camelCase. */
+export declare function camelEvent(event: Event): CamelEvent;
+/**
+ * The listeners of one agent or call. A throwing listener (sync or async) is reported to `onError`
+ * and the others still run.
+ */
+export declare class Listeners<Context> {
+    #private;
+    private readonly onError;
+    constructor(onError: (error: Error) => void);
+    /** Listen for one event type. The returned function stops listening. */
+    on<K extends EventType>(type: K, listener: Listener<K, Context>): () => void;
+    /** Listen for every event. The returned function stops listening. */
+    onAny(listener: AnyListener<Context>): () => void;
+    /** Dispatch to the type's listeners, then to the catch-all ones. */
+    emit(event: CamelEvent, context: Context): void;
+}
+/** Coerce any thrown value to an Error. */
+export declare function asError(thrown: unknown): Error;
+//# sourceMappingURL=listeners.d.ts.map

package/dist/client/listeners.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"listeners.d.ts","sourceRoot":"","sources":["../../src/client/listeners.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,KAAK,KAAK,EAAE,KAAK,KAAK,EAAE,KAAK,SAAS,EAAW,MAAM,kBAAkB,CAAC;AACnF,OAAO,EAAE,KAAK,SAAS,EAAE,MAAM,qBAAqB,CAAC;AAErD,oCAAoC;AACpC,MAAM,MAAM,OAAO,CAAC,CAAC,SAAS,SAAS,IAAI,KAAK,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC,CAAC;AAE/D,kDAAkD;AAClD,MAAM,MAAM,UAAU,GAAG;KAAG,CAAC,IAAI,SAAS,GAAG;QAAE,IAAI,EAAE,CAAC,CAAC;QAAC,IAAI,EAAE,OAAO,CAAC,CAAC,CAAC,CAAA;KAAE;CAAE,CAAC,SAAS,CAAC,CAAC;AAExF,mCAAmC;AACnC,MAAM,MAAM,QAAQ,CAAC,CAAC,SAAS,SAAS,EAAE,OAAO,IAAI,CAAC,IAAI,EAAE,OAAO,CAAC,CAAC,CAAC,EAAE,OAAO,EAAE,OAAO,KAAK,OAAO,CAAC;AAErG,gCAAgC;AAChC,MAAM,MAAM,WAAW,CAAC,OAAO,IAAI,CAAC,KAAK,EAAE,UAAU,EAAE,OAAO,EAAE,OAAO,KAAK,OAAO,CAAC;AAIpF,wDAAwD;AACxD,wBAAgB,UAAU,CAAC,KAAK,EAAE,KAAK,GAAG,UAAU,CAEnD;AAED;;;GAGG;AACH,qBAAa,SAAS,CAAC,OAAO;;IAIhB,OAAO,CAAC,QAAQ,CAAC,OAAO;IAApC,YAA6B,OAAO,EAAE,CAAC,KAAK,EAAE,KAAK,KAAK,IAAI,EAAI;IAEhE,wEAAwE;IACxE,EAAE,CAAC,CAAC,SAAS,SAAS,EAAE,IAAI,EAAE,CAAC,EAAE,QAAQ,EAAE,QAAQ,CAAC,CAAC,EAAE,OAAO,CAAC,GAAG,MAAM,IAAI,CAO3E;IAED,qEAAqE;IACrE,KAAK,CAAC,QAAQ,EAAE,WAAW,CAAC,OAAO,CAAC,GAAG,MAAM,IAAI,CAKhD;IAED,oEAAoE;IACpE,IAAI,CAAC,KAAK,EAAE,UAAU,EAAE,OAAO,EAAE,OAAO,GAAG,IAAI,CAO9C;CAYF;AAED,2CAA2C;AAC3C,wBAAgB,OAAO,CAAC,MAAM,EAAE,OAAO,GAAG,KAAK,CAE9C"}

package/dist/client/listeners.js

@@ -0,0 +1,60 @@
+// Event listener registry, shared by agents and calls.
+import { toCamel } from "../wire/codec.js";
+import {} from "../wire/registry.js";
+/** Convert a decoded event's data keys to camelCase. */
+export function camelEvent(event) {
+    return { type: event.type, data: toCamel(event.data) };
+}
+/**
+ * The listeners of one agent or call. A throwing listener (sync or async) is reported to `onError`
+ * and the others still run.
+ */
+export class Listeners {
+    onError;
+    #byType = new Map();
+    #any = new Set();
+    constructor(onError) {
+        this.onError = onError;
+    }
+    /** Listen for one event type. The returned function stops listening. */
+    on(type, listener) {
+        const listeners = this.#byType.get(type) ?? new Set();
+        this.#byType.set(type, listeners);
+        listeners.add(listener);
+        return () => {
+            listeners.delete(listener);
+        };
+    }
+    /** Listen for every event. The returned function stops listening. */
+    onAny(listener) {
+        this.#any.add(listener);
+        return () => {
+            this.#any.delete(listener);
+        };
+    }
+    /** Dispatch to the type's listeners, then to the catch-all ones. */
+    emit(event, context) {
+        for (const listener of this.#byType.get(event.type) ?? []) {
+            this.#run(() => listener(event.data, context));
+        }
+        for (const listener of this.#any) {
+            this.#run(() => listener(event, context));
+        }
+    }
+    #run(listener) {
+        try {
+            const running = listener();
+            if (running instanceof Promise) {
+                running.catch((failed) => this.onError(asError(failed)));
+            }
+        }
+        catch (failed) {
+            this.onError(asError(failed));
+        }
+    }
+}
+/** Coerce any thrown value to an Error. */
+export function asError(thrown) {
+    return thrown instanceof Error ? thrown : new Error(String(thrown));
+}
+//# sourceMappingURL=listeners.js.map

package/dist/client/listeners.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"listeners.js","sourceRoot":"","sources":["../../src/client/listeners.ts"],"names":[],"mappings":"AAAA,uDAAuD;AAEvD,OAAO,EAA0C,OAAO,EAAE,MAAM,kBAAkB,CAAC;AACnF,OAAO,EAAkB,MAAM,qBAAqB,CAAC;AAgBrD,wDAAwD;AACxD,MAAM,UAAU,UAAU,CAAC,KAAY;IACrC,OAAO,EAAE,IAAI,EAAE,KAAK,CAAC,IAAI,EAAE,IAAI,EAAE,OAAO,CAAC,KAAK,CAAC,IAAI,CAAC,EAAgB,CAAC;AACvE,CAAC;AAED;;;GAGG;AACH,MAAM,OAAO,SAAS;IAIS,OAAO;IAH3B,OAAO,GAAG,IAAI,GAAG,EAAgC,CAAC;IAClD,IAAI,GAAG,IAAI,GAAG,EAAwB,CAAC;IAEhD,YAA6B,OAA+B;uBAA/B,OAAO;IAA2B,CAAC;IAEhE,wEAAwE;IACxE,EAAE,CAAsB,IAAO,EAAE,QAA8B;QAC7D,MAAM,SAAS,GAAG,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,IAAI,CAAC,IAAI,IAAI,GAAG,EAAmB,CAAC;QACvE,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,IAAI,EAAE,SAAS,CAAC,CAAC;QAClC,SAAS,CAAC,GAAG,CAAC,QAA2B,CAAC,CAAC;QAC3C,OAAO,GAAG,EAAE;YACV,SAAS,CAAC,MAAM,CAAC,QAA2B,CAAC,CAAC;QAChD,CAAC,CAAC;IACJ,CAAC;IAED,qEAAqE;IACrE,KAAK,CAAC,QAA8B;QAClC,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAC;QACxB,OAAO,GAAG,EAAE;YACV,IAAI,CAAC,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC;QAC7B,CAAC,CAAC;IACJ,CAAC;IAED,oEAAoE;IACpE,IAAI,CAAC,KAAiB,EAAE,OAAgB;QACtC,KAAK,MAAM,QAAQ,IAAI,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,KAAK,CAAC,IAAI,CAAC,IAAI,EAAE,EAAE,CAAC;YAC1D,IAAI,CAAC,IAAI,CAAC,GAAG,EAAE,CAAE,QAAyD,CAAC,KAAK,CAAC,IAAI,EAAE,OAAO,CAAC,CAAC,CAAC;QACnG,CAAC;QACD,KAAK,MAAM,QAAQ,IAAI,IAAI,CAAC,IAAI,EAAE,CAAC;YACjC,IAAI,CAAC,IAAI,CAAC,GAAG,EAAE,CAAC,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAC,CAAC,CAAC;QAC5C,CAAC;IACH,CAAC;IAED,IAAI,CAAC,QAAuB;QAC1B,IAAI,CAAC;YACH,MAAM,OAAO,GAAG,QAAQ,EAAE,CAAC;YAC3B,IAAI,OAAO,YAAY,OAAO,EAAE,CAAC;gBAC/B,OAAO,CAAC,KAAK,CAAC,CAAC,MAAe,EAAE,EAAE,CAAC,IAAI,CAAC,OAAO,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC;YACpE,CAAC;QACH,CAAC;QAAC,OAAO,MAAM,EAAE,CAAC;YAChB,IAAI,CAAC,OAAO,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC;QAChC,CAAC;IACH,CAAC;CACF;AAED,2CAA2C;AAC3C,MAAM,UAAU,OAAO,CAAC,MAAe;IACrC,OAAO,MAAM,YAAY,KAAK,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,IAAI,KAAK,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC,CAAC;AACtE,CAAC"}

package/dist/client/lost.d.ts

@@ -0,0 +1,4 @@
+/** Whether an error is the gateway being out of reach, which the client redials on its own. */
+/** Whether the error is an unreachable gateway (the client reconnects) rather than an app's own. */
+export declare function aLostSocket(failed: Error): boolean;
+//# sourceMappingURL=lost.d.ts.map

package/dist/client/lost.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"lost.d.ts","sourceRoot":"","sources":["../../src/client/lost.ts"],"names":[],"mappings":"AAAA,+FAA+F;AAK/F,oGAAoG;AACpG,wBAAgB,WAAW,CAAC,MAAM,EAAE,KAAK,GAAG,OAAO,CAElD"}

package/dist/client/lost.js

@@ -0,0 +1,8 @@
+/** Whether an error is the gateway being out of reach, which the client redials on its own. */
+// `ws` and network errors for an unreachable gateway, including a proxy answering during a restart.
+const LOST = /^(Unexpected server response|WebSocket|socket hang up|connect |getaddrinfo |read ECONN|write E)/;
+/** Whether the error is an unreachable gateway (the client reconnects) rather than an app's own. */
+export function aLostSocket(failed) {
+    return typeof failed.code === "string" || LOST.test(failed.message);
+}
+//# sourceMappingURL=lost.js.map

package/dist/client/lost.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"lost.js","sourceRoot":"","sources":["../../src/client/lost.ts"],"names":[],"mappings":"AAAA,+FAA+F;AAE/F,oGAAoG;AACpG,MAAM,IAAI,GAAG,iGAAiG,CAAC;AAE/G,oGAAoG;AACpG,MAAM,UAAU,WAAW,CAAC,MAAa;IACvC,OAAO,OAAQ,MAAgC,CAAC,IAAI,KAAK,QAAQ,IAAI,IAAI,CAAC,IAAI,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC;AACjG,CAAC"}

package/dist/client/observe.d.ts

@@ -0,0 +1,50 @@
+import { type Entry } from "../wire/envelope.js";
+import { type State } from "../wire/state.js";
+import { type CamelEvent } from "./listeners.js";
+import { type World } from "./signed.js";
+/** A call's log or an agent's own log. */
+export type LogTarget = {
+    call: string;
+    agent?: never;
+} | {
+    agent: string;
+    call?: never;
+};
+/** Connection and cursor options for reading a log. */
+export interface ReadOptions {
+    url: string;
+    apiKey: string;
+    /** The world to read from; omitted means sandbox. */
+    env?: World;
+    after?: number;
+    signal?: AbortSignal;
+}
+/** One page of a log: entries after the cursor, their folded state, and the next cursor. */
+export interface Page {
+    entries: Entry[];
+    state: State;
+    /** True while the log is still open and more entries will follow. */
+    live: boolean;
+    /** The cursor for the next page, or null when nothing follows. */
+    next: number | null;
+}
+/** One entry, its decoded event, and the folded state including it. */
+export interface Observation {
+    entry: Entry;
+    event: CamelEvent;
+    state: State;
+}
+/**
+ * Stream a log from the cursor onward, until aborted.
+ *
+ * A dropped stream reconnects with `Last-Event-ID`; a reader that fell behind receives `log.gap`
+ * (with a snapshot when available) and then `log.caught_up`. Throws only if the first connection
+ * fails.
+ */
+export declare function observe(target: LogTarget, options: ReadOptions): AsyncGenerator<Observation>;
+/**
+ * Read one page of a log after the cursor. Use `next` rather than the last entry's seq: an empty
+ * page of a live log still has one.
+ */
+export declare function history(target: LogTarget, options: ReadOptions): Promise<Page>;
+//# sourceMappingURL=observe.d.ts.map

package/dist/client/observe.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"observe.d.ts","sourceRoot":"","sources":["../../src/client/observe.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,KAAK,KAAK,EAAE,MAAM,qBAAqB,CAAC;AAEjD,OAAO,EAAE,KAAK,KAAK,EAAE,MAAM,kBAAkB,CAAC;AAG9C,OAAO,EAAc,KAAK,UAAU,EAAE,MAAM,gBAAgB,CAAC;AAC7D,OAAO,EAAU,KAAK,KAAK,EAAE,MAAM,aAAa,CAAC;AAEjD,0CAA0C;AAC1C,MAAM,MAAM,SAAS,GAAG;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,KAAK,CAAC,EAAE,KAAK,CAAA;CAAE,GAAG;IAAE,KAAK,EAAE,MAAM,CAAC;IAAC,IAAI,CAAC,EAAE,KAAK,CAAA;CAAE,CAAC;AAE1F,uDAAuD;AACvD,MAAM,WAAW,WAAW;IAC1B,GAAG,EAAE,MAAM,CAAC;IACZ,MAAM,EAAE,MAAM,CAAC;IACf,qDAAqD;IACrD,GAAG,CAAC,EAAE,KAAK,CAAC;IACZ,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,MAAM,CAAC,EAAE,WAAW,CAAC;CACtB;AAED,4FAA4F;AAC5F,MAAM,WAAW,IAAI;IACnB,OAAO,EAAE,KAAK,EAAE,CAAC;IACjB,KAAK,EAAE,KAAK,CAAC;IACb,qEAAqE;IACrE,IAAI,EAAE,OAAO,CAAC;IACd,kEAAkE;IAClE,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;CACrB;AAED,uEAAuE;AACvE,MAAM,WAAW,WAAW;IAC1B,KAAK,EAAE,KAAK,CAAC;IACb,KAAK,EAAE,UAAU,CAAC;IAClB,KAAK,EAAE,KAAK,CAAC;CACd;AAKD;;;;;;GAMG;AACH,wBAAuB,OAAO,CAAC,MAAM,EAAE,SAAS,EAAE,OAAO,EAAE,WAAW,GAAG,cAAc,CAAC,WAAW,CAAC,CA0BnG;AAED;;;GAGG;AACH,wBAAsB,OAAO,CAAC,MAAM,EAAE,SAAS,EAAE,OAAO,EAAE,WAAW,GAAG,OAAO,CAAC,IAAI,CAAC,CAcpF"}

package/dist/client/observe.js

@@ -0,0 +1,125 @@
+// Log reading: one URL served as a JSON page or SSE, folded by the protocol's reducer.
+import { decodeEntry, eventOf } from "../wire/codec.js";
+import {} from "../wire/envelope.js";
+import { apply, initialState } from "../wire/reduce.js";
+import {} from "../wire/state.js";
+import { agentLogUrl, callLogUrl } from "./endpoints.js";
+import { PinecallError } from "./frames.js";
+import { camelEvent } from "./listeners.js";
+import { signed } from "./signed.js";
+const RETRY_MS = 1_000;
+const RETRY_CAP_MS = 30_000;
+/**
+ * Stream a log from the cursor onward, until aborted.
+ *
+ * A dropped stream reconnects with `Last-Event-ID`; a reader that fell behind receives `log.gap`
+ * (with a snapshot when available) and then `log.caught_up`. Throws only if the first connection
+ * fails.
+ */
+export async function* observe(target, options) {
+    let state = initialState();
+    let after = options.after ?? 0;
+    let attempt = 0;
+    let opened = false;
+    while (!aborted(options.signal)) {
+        try {
+            for await (const entry of stream(target, { ...options, after })) {
+                attempt = 0;
+                opened = true;
+                after = entry.seq;
+                state = apply(state, entry);
+                yield { entry, event: camelEvent(eventOf(entry)), state };
+            }
+        }
+        catch (failed) {
+            if (aborted(options.signal)) {
+                return;
+            }
+            // Never opened means misconfiguration (bad key, unknown call): surface it. Later drops retry.
+            if (!opened) {
+                throw failed;
+            }
+        }
+        attempt += 1;
+        await pause(Math.min(RETRY_CAP_MS, RETRY_MS * 2 ** (attempt - 1)) * Math.random(), options.signal);
+    }
+}
+/**
+ * Read one page of a log after the cursor. Use `next` rather than the last entry's seq: an empty
+ * page of a live log still has one.
+ */
+export async function history(target, options) {
+    const response = await read(target, options, "application/json");
+    const page = await response.json();
+    if (page === null || typeof page !== "object" || !Array.isArray(page.entries)) {
+        throw new PinecallError("the log page is not { entries, live, next }");
+    }
+    const { entries: raw, live, next } = page;
+    const entries = raw.map((one) => decodeEntry(one));
+    return {
+        entries,
+        state: entries.reduce(apply, initialState()),
+        live: live === true,
+        next: typeof next === "number" ? next : null,
+    };
+}
+/** One SSE connection, yielding entries until it closes or is aborted. */
+async function* stream(target, options) {
+    const response = await read(target, options, "text/event-stream");
+    if (response.body === null) {
+        throw new PinecallError("the event stream came back with no body");
+    }
+    let buffered = "";
+    const decoder = new TextDecoder();
+    for await (const chunk of response.body) {
+        buffered += decoder.decode(chunk, { stream: true });
+        let cut = buffered.indexOf("\n\n");
+        while (cut !== -1) {
+            const entry = entryIn(buffered.slice(0, cut));
+            buffered = buffered.slice(cut + 2);
+            cut = buffered.indexOf("\n\n");
+            if (entry !== null) {
+                yield entry;
+            }
+        }
+    }
+}
+/** Parse one SSE block, or null for a comment or keep-alive. */
+function entryIn(block) {
+    const data = block
+        .split("\n")
+        .filter((line) => line.startsWith("data:"))
+        .map((line) => line.slice("data:".length).trimStart())
+        .join("\n");
+    return data === "" ? null : decodeEntry(JSON.parse(data));
+}
+async function read(target, options, accept) {
+    const url = new URL(target.call === undefined ? agentLogUrl(options.url, target.agent) : callLogUrl(options.url, target.call));
+    const after = options.after ?? 0;
+    if (after > 0) {
+        url.searchParams.set("after", String(after));
+    }
+    const headers = { accept, ...signed(options.apiKey, options.env) };
+    if (after > 0) {
+        headers["last-event-id"] = String(after);
+    }
+    const response = await fetch(url, { headers, ...(options.signal === undefined ? {} : { signal: options.signal }) });
+    if (!response.ok) {
+        throw new PinecallError(`${url.pathname}: the gateway answered ${response.status}`);
+    }
+    return response;
+}
+// A function so TypeScript doesn't narrow `signal.aborted` across the loop.
+function aborted(signal) {
+    return signal?.aborted === true;
+}
+async function pause(ms, signal) {
+    await new Promise((resolve) => {
+        const timer = setTimeout(resolve, ms);
+        signal?.addEventListener("abort", () => {
+            clearTimeout(timer);
+            resolve();
+        });
+    });
+}
+//# sourceMappingURL=observe.js.map

package/dist/client/observe.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"observe.js","sourceRoot":"","sources":["../../src/client/observe.ts"],"names":[],"mappings":"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"}

package/dist/client/signed.d.ts

@@ -0,0 +1,14 @@
+/** One of the gateway's two worlds. */
+export type World = "sandbox" | "production";
+/**
+ * Header naming the world the request acts in. A person's key opens both worlds and this picks
+ * one (absent, the sandbox); a server token's world is fixed by its prefix, and the header may
+ * only agree.
+ */
+export declare const ENV_HEADER = "pinecall-env";
+/**
+ * Headers for one request or socket upgrade: the key as a Bearer (never in a URL, which lands in
+ * access logs) and the world if given. An empty key sends no authorization header.
+ */
+export declare function signed(apiKey: string, world?: World): Record<string, string>;
+//# sourceMappingURL=signed.d.ts.map

package/dist/client/signed.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"signed.d.ts","sourceRoot":"","sources":["../../src/client/signed.ts"],"names":[],"mappings":"AAEA,uCAAuC;AACvC,MAAM,MAAM,KAAK,GAAG,SAAS,GAAG,YAAY,CAAC;AAE7C;;;;GAIG;AACH,eAAO,MAAM,UAAU,iBAAiB,CAAC;AAEzC;;;GAGG;AACH,wBAAgB,MAAM,CAAC,MAAM,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,KAAK,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAI5E"}

package/dist/client/signed.js

@@ -0,0 +1,18 @@
+// Request headers for the gateway: the API key and the world the request acts in.
+/**
+ * Header naming the world the request acts in. A person's key opens both worlds and this picks
+ * one (absent, the sandbox); a server token's world is fixed by its prefix, and the header may
+ * only agree.
+ */
+export const ENV_HEADER = "pinecall-env";
+/**
+ * Headers for one request or socket upgrade: the key as a Bearer (never in a URL, which lands in
+ * access logs) and the world if given. An empty key sends no authorization header.
+ */
+export function signed(apiKey, world) {
+    const headers = apiKey === "" ? {} : { authorization: `Bearer ${apiKey}` };
+    if (world !== undefined)
+        headers[ENV_HEADER] = world;
+    return headers;
+}
+//# sourceMappingURL=signed.js.map

package/dist/client/signed.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"signed.js","sourceRoot":"","sources":["../../src/client/signed.ts"],"names":[],"mappings":"AAAA,kFAAkF;AAKlF;;;;GAIG;AACH,MAAM,CAAC,MAAM,UAAU,GAAG,cAAc,CAAC;AAEzC;;;GAGG;AACH,MAAM,UAAU,MAAM,CAAC,MAAc,EAAE,KAAa;IAClD,MAAM,OAAO,GAA2B,MAAM,KAAK,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,aAAa,EAAE,UAAU,MAAM,EAAE,EAAE,CAAC;IACnG,IAAI,KAAK,KAAK,SAAS;QAAE,OAAO,CAAC,UAAU,CAAC,GAAG,KAAK,CAAC;IACrD,OAAO,OAAO,CAAC;AACjB,CAAC"}

package/dist/client/testing/gateway.d.ts

@@ -0,0 +1,58 @@
+import { type Command, type Entry } from "../../wire/envelope.js";
+import { type EventType } from "../../wire/registry.js";
+/** Options for `FakeGateway.start()`. */
+export interface FakeGatewayOptions {
+    /** The only accepted key; any other fails the handshake with 403. */
+    apiKey?: string;
+    /** Slugs whose registration is refused, as when another agent or fleet holds them. */
+    taken?: string[];
+    /** Close every socket with 1008 and this reason, as for a key without the needed scope. */
+    refusesWith?: string;
+    /** Never answer `agent.drain`, like an older or hung gateway. */
+    holdsDrain?: boolean;
+}
+/** A command the fake gateway received. */
+export type Received = Command;
+/** A scripted search result chunk. */
+export interface Scripted {
+    path: string;
+    heading: string | null;
+    text: string;
+}
+/** A search request recorded by the fake gateway. */
+export interface Searched {
+    call: string;
+    query: string;
+    k: number | undefined;
+}
+/**
+ * A fake gateway with no sessions, store or model. It numbers entries, answers the commands the
+ * app socket handles itself, and lets a test push any entry to connected apps.
+ */
+export declare class FakeGateway {
+    #private;
+    private readonly options;
+    readonly received: Received[];
+    /** Every search made through this gateway, in order. */
+    readonly searched: Searched[];
+    private constructor();
+    /** Start on a random port. Close it when the test is over. */
+    static start(options?: FakeGatewayOptions): Promise<FakeGateway>;
+    /** The URL to give a client as PINECALL_URL. */
+    get url(): string;
+    /** How many apps are connected right now. */
+    get connections(): number;
+    /** Received commands of one type, in arrival order. */
+    commandsOf(type: string): Received[];
+    /** Push one numbered entry to every connected app. */
+    emit(agent: string, call: string | null, type: EventType, data: Record<string, unknown>): Entry;
+    /** Set the chunks (best first) that subsequent searches return. */
+    finds(chunks: Scripted[]): void;
+    /** Drop every open socket while still listening, simulating a gateway restart. */
+    cut(): void;
+    /** Stop every connected app as `POST /v1/apps/{app}/stop` does: an `error` coded `stopped`, then close. */
+    stop(why: string): void;
+    /** Stop listening and close all connections. */
+    close(): Promise<void>;
+}
+//# sourceMappingURL=gateway.d.ts.map

package/dist/client/testing/gateway.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"gateway.d.ts","sourceRoot":"","sources":["../../../src/client/testing/gateway.ts"],"names":[],"mappings":"AAIA,OAAO,EAAE,KAAK,OAAO,EAAiB,KAAK,KAAK,EAAE,MAAM,wBAAwB,CAAC;AACjF,OAAO,EAAoB,KAAK,SAAS,EAAE,MAAM,wBAAwB,CAAC;AAW1E,yCAAyC;AACzC,MAAM,WAAW,kBAAkB;IACjC,qEAAqE;IACrE,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,sFAAsF;IACtF,KAAK,CAAC,EAAE,MAAM,EAAE,CAAC;IACjB,2FAA2F;IAC3F,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,iEAAiE;IACjE,UAAU,CAAC,EAAE,OAAO,CAAC;CACtB;AAED,2CAA2C;AAC3C,MAAM,MAAM,QAAQ,GAAG,OAAO,CAAC;AAE/B,sCAAsC;AACtC,MAAM,WAAW,QAAQ;IACvB,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;IACvB,IAAI,EAAE,MAAM,CAAC;CACd;AAED,qDAAqD;AACrD,MAAM,WAAW,QAAQ;IACvB,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,MAAM,CAAC;IACd,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;CACvB;AAKD;;;GAGG;AACH,qBAAa,WAAW;;IAaqC,OAAO,CAAC,QAAQ,CAAC,OAAO;IAZnF,QAAQ,CAAC,QAAQ,EAAE,QAAQ,EAAE,CAAM;IACnC,wDAAwD;IACxD,QAAQ,CAAC,QAAQ,EAAE,QAAQ,EAAE,CAAM;IAUnC,OAAO,eAIN;IAGD,8DAA8D;IAC9D,OAAa,KAAK,CAAC,OAAO,GAAE,kBAAuB,GAAG,OAAO,CAAC,WAAW,CAAC,CAsBzE;IAED,gDAAgD;IAChD,IAAI,GAAG,IAAI,MAAM,CAEhB;IAED,6CAA6C;IAC7C,IAAI,WAAW,IAAI,MAAM,CAExB;IAED,uDAAuD;IACvD,UAAU,CAAC,IAAI,EAAE,MAAM,GAAG,QAAQ,EAAE,CAEnC;IAED,sDAAsD;IACtD,IAAI,CAAC,KAAK,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,IAAI,EAAE,IAAI,EAAE,SAAS,EAAE,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,KAAK,CAM9F;IAED,mEAAmE;IACnE,KAAK,CAAC,MAAM,EAAE,QAAQ,EAAE,GAAG,IAAI,CAE9B;IAED,kFAAkF;IAClF,GAAG,IAAI,IAAI,CAKV;IAED,2GAA2G;IAC3G,IAAI,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI,CAKtB;IAED,gDAAgD;IAC1C,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAK3B;CA0EF"}

package/dist/client/testing/gateway.js

@@ -0,0 +1,175 @@
+// An in-process fake gateway: enough of the app socket to test an app's agents.
+import { createServer } from "node:http";
+import { CommandSchema } from "../../wire/envelope.js";
+import { EPHEMERAL_EVENTS } from "../../wire/registry.js";
+import { WebSocket, WebSocketServer } from "ws";
+import { LOOPBACK } from "./loopback.js";
+// Unknown keys are refused during the handshake, so the upgrade never happens.
+const FORBIDDEN = 403;
+// Close code for a valid key that lacks the scope for this endpoint.
+const POLICY_VIOLATION = 1008;
+// The only HTTP endpoint: knowledge search, answered with scripted chunks.
+const LOOKUP = /^\/v1\/calls\/([^/]+)\/lookup$/;
+/**
+ * A fake gateway with no sessions, store or model. It numbers entries, answers the commands the
+ * app socket handles itself, and lets a test push any entry to connected apps.
+ */
+export class FakeGateway {
+    options;
+    received = [];
+    /** Every search made through this gateway, in order. */
+    searched = [];
+    #http;
+    #server;
+    #found = [];
+    #sockets = new Set();
+    #refused;
+    #seq = 0;
+    #apps = 0;
+    #port = 0;
+    constructor(http, server, options) {
+        this.options = options;
+        this.#http = http;
+        this.#server = server;
+        this.#refused = new Set(options.taken ?? []);
+    }
+    // The key is checked during the handshake, as the real gateway does.
+    /** Start on a random port. Close it when the test is over. */
+    static async start(options = {}) {
+        // One HTTP server for both the /v1/apps upgrade and the search endpoint.
+        const http = createServer((request, response) => void gateway.#answerHttp(request, response));
+        const server = new WebSocketServer({
+            server: http,
+            path: "/v1/apps",
+            verifyClient: ({ req }, done) => done(options.apiKey === undefined || req.headers.authorization === `Bearer ${options.apiKey}`, FORBIDDEN),
+        });
+        const gateway = new FakeGateway(http, server, options);
+        // Bind to 127.0.0.1 only: the IPv6 wildcard can be granted on a port another program holds
+        // on IPv4, and the client's 127.0.0.1 connection would reach that program instead.
+        await new Promise((resolve) => http.listen(0, LOOPBACK, resolve));
+        const address = http.address();
+        gateway.#port = typeof address === "object" && address !== null ? address.port : 0;
+        server.on("connection", (socket) => {
+            if (options.refusesWith !== undefined) {
+                socket.close(POLICY_VIOLATION, options.refusesWith);
+                return;
+            }
+            gateway.#accept(socket);
+        });
+        return gateway;
+    }
+    /** The URL to give a client as PINECALL_URL. */
+    get url() {
+        return `http://${LOOPBACK}:${this.#port}`;
+    }
+    /** How many apps are connected right now. */
+    get connections() {
+        return this.#sockets.size;
+    }
+    /** Received commands of one type, in arrival order. */
+    commandsOf(type) {
+        return this.received.filter((command) => command.type === type);
+    }
+    /** Push one numbered entry to every connected app. */
+    emit(agent, call, type, data) {
+        const entry = { seq: (this.#seq += 1), ts: Date.now() / 1000, call, agent, type, ephemeral: EPHEMERAL_EVENTS.has(type), data };
+        for (const socket of this.#sockets) {
+            socket.send(JSON.stringify(entry));
+        }
+        return entry;
+    }
+    /** Set the chunks (best first) that subsequent searches return. */
+    finds(chunks) {
+        this.#found = chunks;
+    }
+    /** Drop every open socket while still listening, simulating a gateway restart. */
+    cut() {
+        for (const socket of this.#sockets) {
+            socket.terminate();
+        }
+        this.#sockets.clear();
+    }
+    /** Stop every connected app as `POST /v1/apps/{app}/stop` does: an `error` coded `stopped`, then close. */
+    stop(why) {
+        for (const socket of this.#sockets) {
+            socket.send(JSON.stringify(this.#entry("", null, "error", { code: "stopped", message: why, recoverable: false })));
+            socket.close();
+        }
+    }
+    /** Stop listening and close all connections. */
+    async close() {
+        this.cut();
+        await new Promise((resolve, reject) => this.#server.close((failed) => (failed ? reject(failed) : resolve())));
+        this.#http.closeAllConnections();
+        await new Promise((resolve, reject) => this.#http.close((failed) => (failed ? reject(failed) : resolve())));
+    }
+    async #answerHttp(request, response) {
+        const call = LOOKUP.exec(request.url ?? "")?.[1];
+        if (request.method !== "POST" || call === undefined) {
+            response.writeHead(404).end();
+            return;
+        }
+        if (this.options.apiKey !== undefined && request.headers.authorization !== `Bearer ${this.options.apiKey}`) {
+            response.writeHead(401, { "content-type": "application/json" }).end(JSON.stringify({ detail: "this door takes an API key" }));
+            return;
+        }
+        const chunks = [];
+        for await (const chunk of request)
+            chunks.push(chunk);
+        const { input } = JSON.parse(Buffer.concat(chunks).toString("utf8"));
+        this.searched.push({ call: decodeURIComponent(call), query: input.query, k: input.k });
+        const found = input.k === undefined ? this.#found : this.#found.slice(0, input.k);
+        response.writeHead(200, { "content-type": "application/json" }).end(JSON.stringify({ output: { chunks: found }, took_ms: 1 }));
+    }
+    #accept(socket) {
+        this.#sockets.add(socket);
+        // Per-connection id, returned in `agent.registered` as the real gateway does.
+        const app = `app_${(this.#apps += 1)}`;
+        socket.on("message", (raw) => this.#take(socket, app, raw));
+        socket.on("close", () => this.#sockets.delete(socket));
+        // An unhandled `error` event throws in Node; `ws` emits one for any unparseable frame, which
+        // would crash the whole test run.
+        socket.on("error", () => this.#sockets.delete(socket));
+    }
+    #take(socket, app, raw) {
+        const command = CommandSchema.parse(JSON.parse(raw.toString()));
+        this.received.push(command);
+        switch (command.type) {
+            case "agent.register":
+                return this.#register(socket, app, command);
+            case "agent.configure":
+                return this.#answer(socket, command, "agent.configured", { changed: Object.keys((command.data["config"] ?? {})) });
+            case "ping":
+                return this.#answer(socket, command, "pong", { ts: Date.now() / 1000 });
+            case "agent.drain":
+                if (this.options.holdsDrain === true)
+                    return;
+                return this.#answer(socket, command, "agent.draining", { app, env: "sandbox", handed: 0, parked: 0 });
+            default:
+                return;
+        }
+    }
+    // Several sockets may register one agent; only slugs in `taken` are refused.
+    #register(socket, app, command) {
+        if (this.#refused.has(command.agent)) {
+            this.#refuse(socket, command, "refused", `${command.agent} answers at a door somebody else has`);
+            return;
+        }
+        const { routes, sdk } = command.data;
+        this.#answer(socket, command, "agent.registered", sdk === undefined ? { routes, app } : { routes, app, sdk });
+    }
+    #answer(socket, command, type, data) {
+        socket.send(JSON.stringify(this.#entry(command.agent, null, type, data)));
+    }
+    #refuse(socket, command, code, message) {
+        const data = { code, message, recoverable: true, command: command.type };
+        if (command.id !== undefined) {
+            data["id"] = command.id;
+        }
+        socket.send(JSON.stringify(this.#entry(command.agent, null, "error", data)));
+    }
+    #entry(agent, call, type, data) {
+        return { seq: (this.#seq += 1), ts: Date.now() / 1000, call, agent, type, ephemeral: EPHEMERAL_EVENTS.has(type), data };
+    }
+}
+//# sourceMappingURL=gateway.js.map