@guuey/threads 0.31.1 → 0.32.0

package/dist/http-read.js

@@ -0,0 +1,274 @@
+/**
+ * Readers for what the hosted thread API answers ({@link HttpThreadPersistence}
+ * in `http.ts`). A response body is parsed to `unknown` and read here member by
+ * member; nothing is taken as a port type until these readers have proven it.
+ *
+ * Each reader returns the typed value, or `undefined` when the payload is not
+ * one; the binding turns `undefined` into an `HttpThreadStoreError` with code
+ * `BAD_RESPONSE`, the error every caller of the binding already handles.
+ *
+ * What a reader checks follows the port types in `rows.ts`, read across a
+ * rolling release, and reads a stored row the way the DynamoDB binding hands
+ * the same row to its readers (the two bindings must agree):
+ * - a member that IDENTIFIES the row (a thread's own members; a message's
+ *   `threadId`, integer `seq`, `clientMessageId`, `at`, which the schema
+ *   requires on every row) is proven by type, and a row without it is refused;
+ * - a message's closed vocabularies are read the way every reader of the row
+ *   reads them: a `kind` this release does not know (a newer writer's, or none
+ *   on a legacy row) is a `text` row (it is not a card, the one kind a reader
+ *   branches on), and an `authorRole` it does not know is `agent` (not the
+ *   user's words: `rowToAgMessage` reads it as the assistant, the managed read
+ *   plane as `agent`), so one such row never refuses the thread's history;
+ * - a message's `userId` (no reader on this path reads it) is left absent when
+ *   a legacy row has none, and the binding fills in the token's user, the only
+ *   user whose threads the server answers (`http.ts`);
+ * - an OPTIONAL member is kept when it reads as its type and is absent
+ *   otherwise, the way each one's own reader treats it at use (`readThreadInputKind`,
+ *   `readTapLabels`, `threadClosure`), so a field an older server omits reads
+ *   as absent and a value a newer one adds that this release does not know is
+ *   left out;
+ * - a thread's `sealIntervals` is carried as stored, never normalised or
+ *   dropped: `readSealState` reads it at use, and reads one it cannot read as
+ *   wholly sealed (fail closed), exactly as over the DynamoDB binding;
+ * - a message's `untrustedOrigin` that is not a boolean would read as trusted
+ *   if it were dropped, so that row is refused instead;
+ * - opaque members (`content`, `cardSnapshot`, `aiContext`) are carried as
+ *   they came, as the port types them (`unknown`).
+ */
+import { JsonValue } from "@silverprotocol/core";
+import { readTapLabels } from "@guuey/mcp-apps-host/narrowing";
+import { splitStoredThreadMemory } from "./fold-rows.js";
+import { readThreadInputKind, } from "./rows.js";
+/** Whether `value` is a JSON object: not `null`, not an array, not a scalar. */
+export function isWireObject(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function isSeqNumber(value) {
+    return typeof value === "number" && Number.isInteger(value);
+}
+/** The member when it is a string, else undefined (absent, null or another type). */
+function optString(obj, key) {
+    const value = obj[key];
+    return typeof value === "string" ? value : undefined;
+}
+const MESSAGE_KINDS = ["text", "card", "event"];
+const MESSAGE_ROLES = ["user", "agent", "system"];
+/** What a message `kind` this release does not know reads as (see the module doc). */
+const UNKNOWN_KIND_READS_AS = "text";
+/** What a message `authorRole` this release does not know reads as (see the module doc). */
+const UNKNOWN_ROLE_READS_AS = "agent";
+const TURN_ORIGINS = ["card_action", "chip", "typed"];
+const CLIENT_CLASSES = ["operator", "bot", "browser"];
+/** `value` when it is one of `allowed`, else undefined. */
+function oneOf(allowed, value) {
+    return allowed.find((member) => member === value);
+}
+/** `scope`'s result: the three strings the server binds the token to. */
+export function readThreadScope(value) {
+    if (!isWireObject(value))
+        return undefined;
+    const { appId, userId, region } = value;
+    if (typeof appId !== "string" || typeof userId !== "string" || typeof region !== "string")
+        return undefined;
+    return { appId, userId, region };
+}
+/** `incrementSeq`'s result: the integer seq the server allocated. */
+export function readAllocatedSeq(value) {
+    return isSeqNumber(value) ? value : undefined;
+}
+/** A `getThread` row. */
+export function readThreadRow(value) {
+    if (!isWireObject(value))
+        return undefined;
+    const { id, userId, appId, servingRegion, title, status, pinned, lastSeq } = value;
+    const { lastMessageAt, lastMessagePreview, threadMode, createdAt, updatedAt } = value;
+    if (typeof id !== "string" ||
+        typeof userId !== "string" ||
+        typeof appId !== "string" ||
+        typeof servingRegion !== "string" ||
+        typeof title !== "string" ||
+        typeof status !== "string" ||
+        typeof pinned !== "boolean" ||
+        !isSeqNumber(lastSeq) ||
+        typeof lastMessageAt !== "string" ||
+        typeof lastMessagePreview !== "string" ||
+        typeof threadMode !== "string" ||
+        typeof createdAt !== "string" ||
+        typeof updatedAt !== "string") {
+        return undefined;
+    }
+    // Carried as stored (`null` is no seal, as `readSealState` reads it): a seal
+    // this release cannot read still reaches `readSealState`, which reads it as
+    // wholly sealed, so the thread stays usable and closed.
+    const sealIntervals = value.sealIntervals;
+    const previewSeq = value.lastMessagePreviewSeq;
+    const previewDigest = optString(value, "lastMessagePreviewDigest");
+    const closedCode = optString(value, "closedCode");
+    const closedMessage = optString(value, "closedMessage");
+    const closedAt = optString(value, "closedAt");
+    return {
+        id,
+        userId,
+        appId,
+        servingRegion,
+        title,
+        status,
+        pinned,
+        lastSeq,
+        lastMessageAt,
+        lastMessagePreview,
+        ...(isSeqNumber(previewSeq) ? { lastMessagePreviewSeq: previewSeq } : {}),
+        ...(previewDigest !== undefined ? { lastMessagePreviewDigest: previewDigest } : {}),
+        ...(sealIntervals !== undefined && sealIntervals !== null ? { sealIntervals } : {}),
+        ...(closedCode !== undefined ? { closedCode: closedCode } : {}),
+        ...(closedMessage !== undefined ? { closedMessage: closedMessage } : {}),
+        ...(closedAt !== undefined ? { closedAt: closedAt } : {}),
+        threadMode,
+        createdAt,
+        updatedAt,
+    };
+}
+/** A stored `event` this release reads; another `type`, or a malformed one, is not one ("not mine"). */
+function readThreadMessageEvent(value) {
+    if (!isWireObject(value))
+        return undefined;
+    if (value.type === "handoff") {
+        const question = value.question;
+        if (typeof question !== "string")
+            return undefined;
+        const contactEmail = optString(value, "contactEmail");
+        const contactName = optString(value, "contactName");
+        const summary = optString(value, "summary");
+        const event = {
+            type: "handoff",
+            question,
+            ...(contactEmail !== undefined ? { contactEmail } : {}),
+            ...(contactName !== undefined ? { contactName } : {}),
+            ...(summary !== undefined ? { summary } : {}),
+        };
+        return event;
+    }
+    if (value.type === "report") {
+        const { summary, reportedBy, wantedHuman } = value;
+        if (typeof summary !== "string" || typeof reportedBy !== "string")
+            return undefined;
+        const contactEmail = optString(value, "contactEmail");
+        const contactName = optString(value, "contactName");
+        const event = {
+            type: "report",
+            summary,
+            ...(typeof wantedHuman === "boolean" ? { wantedHuman } : {}),
+            ...(contactEmail !== undefined ? { contactEmail } : {}),
+            ...(contactName !== undefined ? { contactName } : {}),
+            reportedBy,
+        };
+        return event;
+    }
+    return undefined;
+}
+/** A message row (`listRecentMessages`, `findByClientMessageId`). */
+export function readThreadMessageRow(value) {
+    if (!isWireObject(value))
+        return undefined;
+    const { threadId, seq, clientMessageId, at } = value;
+    if (typeof threadId !== "string" || !isSeqNumber(seq) || typeof clientMessageId !== "string" || typeof at !== "string") {
+        return undefined;
+    }
+    const userId = optString(value, "userId");
+    const kind = oneOf(MESSAGE_KINDS, value.kind) ?? UNKNOWN_KIND_READS_AS;
+    const authorRole = oneOf(MESSAGE_ROLES, value.authorRole) ?? UNKNOWN_ROLE_READS_AS;
+    // `untrustedOrigin` marks page-derived content; a stored value that is not a
+    // boolean must not read as trusted, so the row is refused.
+    const untrustedOrigin = value.untrustedOrigin;
+    if (untrustedOrigin !== undefined && typeof untrustedOrigin !== "boolean")
+        return undefined;
+    const event = readThreadMessageEvent(value.event);
+    const turnOrigin = oneOf(TURN_ORIGINS, value.turnOrigin);
+    const clientClass = oneOf(CLIENT_CLASSES, value.clientClass);
+    const inputKind = readThreadInputKind(value.inputKind);
+    const tapLabels = readTapLabels(value.tapLabels);
+    const text = optString(value, "text");
+    const toolName = optString(value, "toolName");
+    const answeredCardSessionId = optString(value, "answeredCardSessionId");
+    return {
+        threadId,
+        seq,
+        ...(userId !== undefined ? { userId } : {}),
+        clientMessageId,
+        at,
+        kind,
+        authorRole,
+        ...(text !== undefined ? { text } : {}),
+        ...(value.content !== undefined ? { content: value.content } : {}),
+        ...(value.cardSnapshot !== undefined ? { cardSnapshot: value.cardSnapshot } : {}),
+        ...(toolName !== undefined ? { toolName } : {}),
+        ...(value.aiContext !== undefined ? { aiContext: value.aiContext } : {}),
+        ...(untrustedOrigin !== undefined ? { untrustedOrigin } : {}),
+        ...(event !== undefined ? { event } : {}),
+        ...(turnOrigin !== undefined ? { turnOrigin } : {}),
+        ...(inputKind !== undefined ? { inputKind } : {}),
+        ...(answeredCardSessionId !== undefined ? { answeredCardSessionId } : {}),
+        ...(clientClass !== undefined ? { clientClass } : {}),
+        ...(tapLabels !== undefined ? { tapLabels } : {}),
+    };
+}
+/**
+ * `listRecentMessages`' result: every row must read, or the list is refused. A
+ * row reads unless it lacks a member that identifies it or carries a malformed
+ * `untrustedOrigin` (see the module doc); a vocabulary value or a `userId` this
+ * release does not know never refuses it.
+ */
+export function readThreadMessageRows(value) {
+    if (!Array.isArray(value))
+        return undefined;
+    const rows = [];
+    for (const entry of value) {
+        const row = readThreadMessageRow(entry);
+        if (row === undefined)
+            return undefined;
+        rows.push(row);
+    }
+    return rows;
+}
+/**
+ * A `getSnapshot` row. Its memory arrays are JSON (checked, never assumed); the
+ * thread records are re-read through the one stored-memory reader
+ * (`splitStoredThreadMemory`), and any element this release cannot read as a
+ * thread record joins the carried elements, so it is kept, never dropped.
+ */
+export function readThreadSnapshotRow(value) {
+    if (!isWireObject(value))
+        return undefined;
+    const { threadId, userId, updatedAt } = value;
+    if (typeof threadId !== "string" || typeof userId !== "string" || typeof updatedAt !== "string")
+        return undefined;
+    const memory = JsonValue.array().safeParse(value.threadMemory);
+    if (!memory.success)
+        return undefined;
+    let carried = [];
+    if (value.carriedThreadMemory !== undefined) {
+        const parsed = JsonValue.array().safeParse(value.carriedThreadMemory);
+        if (!parsed.success)
+            return undefined;
+        carried = parsed.data;
+    }
+    let workingState;
+    if (value.workingState !== undefined) {
+        const parsed = JsonValue.safeParse(value.workingState);
+        if (!parsed.success)
+            return undefined;
+        workingState = parsed.data;
+    }
+    const split = splitStoredThreadMemory(memory.data);
+    const carriedThreadMemory = [...carried, ...split.carriedThreadMemory];
+    const lastTurnId = optString(value, "lastTurnId");
+    return {
+        threadId,
+        userId,
+        ...(workingState !== undefined ? { workingState } : {}),
+        threadMemory: split.threadMemory,
+        ...(value.carriedThreadMemory !== undefined || carriedThreadMemory.length > 0 ? { carriedThreadMemory } : {}),
+        ...(lastTurnId !== undefined ? { lastTurnId } : {}),
+        updatedAt,
+    };
+}

package/dist/http.d.ts

@@ -1,33 +1,4 @@
-/**
- * Hosted HTTP binding — {@link ThreadPersistencePort} over guuey's thread
- * API, `POST <base>/v1/thread-store/<op>` (guuey#208). The "eject the code,
- * keep your memory" leg of the ejected ladder: point a `ThreadStore` at
- * this binding with an end-user token and your self-hosted agent reads and
- * writes the SAME conversation rows guuey's hosted runtime does.
- *
- * Wire protocol (the `@guuey/state` `HttpKv` shape):
- * - Request: JSON body `{ context: { appId }, args: {...} }`, header
- *   `Authorization: Bearer <token>`.
- * - Success: `200 { result }`.
- * - Failure: `4xx/5xx { code, message }` → {@link HttpThreadStoreError}.
- *
- * Auth + tenancy: the token is an END-USER token for the app — one the
- * app's configured identity issuer minted (your own IdP, or guuey's per-app
- * widget issuer via `@guuey/widget-auth`). The server verifies it against
- * that issuer, derives the same `byo_…` userId the hosted runtime would, and
- * scopes every op to `(appId, userId)`: rows you write must carry that
- * userId, threads you touch must belong to it. `context` on the wire is
- * advisory — the token is authoritative. Call {@link scope} to learn the
- * derived userId (and the API's region) before `ensureThread`.
- *
- * Retry policy: reads (`getThread`/`listRecentMessages`/
- * `findByClientMessageId`/`getSnapshot`/`scope`) are idempotent and retried
- * once on a network failure or a 5xx. Writes (`createThread`/`incrementSeq`/
- * `putMessage`/`putSnapshot`) are NEVER retried automatically —
- * `incrementSeq` is not idempotent, and a blind retry after a server-side
- * apply would double-allocate a seq.
- */
-import type { ThreadMessageRow, ThreadPersistencePort, ThreadRow, ThreadSnapshotRow } from "./rows.js";
+import type { RowBudget, ThreadMessageRow, ThreadPersistencePort, ThreadRow, ThreadSnapshotRow } from "./rows.js";
 /** What the token resolves to server-side — the scope every op is bound to. */
 export interface ThreadScope {
     appId: string;
@@ -50,7 +21,9 @@ export interface HttpThreadPersistenceOptions {
  * Thrown for every non-2xx response and every exhausted network failure.
  * `code` is the server's flat error code (`UNAUTHORIZED`, `FORBIDDEN`,
  * `INVALID_ARGUMENT`, `INVALID_CONTEXT`, `THREAD_NOT_FOUND`, `CONFLICT`,
- * `NOT_FOUND`, `TRANSPORT`); `status` is the HTTP status (`0` for a network
+ * `NOT_FOUND`, `TRANSPORT`, and the client's own `BAD_RESPONSE` for a 2xx body
+ * it cannot read; `incrementSeq`'s `THREAD_CLOSED` is thrown as
+ * `ThreadClosedError` instead); `status` is the HTTP status (`0` for a network
  * failure that never produced a response).
  */
 export declare class HttpThreadStoreError extends Error {
@@ -61,10 +34,17 @@ export declare class HttpThreadStoreError extends Error {
     });
 }
 export declare class HttpThreadPersistence implements ThreadPersistencePort {
+    /**
+     * guuey#1794: the server stores the rows this binding sends in DynamoDB, so
+     * the store sizes them by DynamoDB's own item rules before it sends any.
+     */
+    readonly rowBudget: RowBudget;
     private readonly baseUrl;
     private readonly appId;
     private readonly token;
     private readonly fetchImpl;
+    /** The token's user, read from `scope` the first time a row lacks its `userId`. */
+    private ownerRead;
     constructor(opts: HttpThreadPersistenceOptions);
     /** The `(appId, userId, region)` the server bound this token to. */
     scope(): Promise<ThreadScope>;
@@ -77,10 +57,33 @@ export declare class HttpThreadPersistence implements ThreadPersistencePort {
     getSnapshot(threadId: string): Promise<ThreadSnapshotRow | undefined>;
     putSnapshot(row: ThreadSnapshotRow): Promise<void>;
     /**
-     * One shared retry budget (`retried`) covers BOTH retry triggers — a
-     * network failure and a 5xx response — so a retryable op makes at most
-     * 2 total requests, never 3.
+     * A write: never retried, and its body (the server's `{ result: null }`) is
+     * never read: a 2xx means it committed, whatever the body holds. The body is
+     * cancelled, not left open, so the connection is released.
+     *
+     * Releasing is best effort and never awaited: a body stream that errors
+     * after the 2xx headers (a connection reset) rejects `cancel()`, and that
+     * rejection must not turn a committed write into a thrown one, which a
+     * caller would retry into `CONFLICT`. The failure is reported on
+     * `console.warn` instead: the write stands, and the stream is already dead.
+     */
+    private write;
+    /** `row` with its `userId`: the stored one, or the token's user for a legacy row without one. */
+    private owned;
+    /** The token's user, read once; a failed read is not kept, so the next row asks again. */
+    private owner;
+    /** A point read: `null` (the port's `undefined`) or the row `read` proves. */
+    private pointRead;
+    /**
+     * The op's `{ result }` envelope, its `result` read by `read`. `undefined`
+     * from `read` (the result is not this op's answer) is `BAD_RESPONSE`.
      */
     private call;
+    /**
+     * One op on the wire: the 2xx response (its body unread), or the typed error. One shared retry budget (`retried`) covers BOTH retry
+     * triggers — a network failure and a 5xx response — so a retryable op makes
+     * at most 2 total requests, never 3.
+     */
+    private send;
 }
 //# sourceMappingURL=http.d.ts.map

package/dist/http.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"http.d.ts","sourceRoot":"","sources":["../src/http.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,OAAO,KAAK,EACV,gBAAgB,EAChB,qBAAqB,EACrB,SAAS,EACT,iBAAiB,EAClB,MAAM,WAAW,CAAC;AAEnB,+EAA+E;AAC/E,MAAM,WAAW,WAAW;IAC1B,KAAK,EAAE,MAAM,CAAC;IACd,2EAA2E;IAC3E,MAAM,EAAE,MAAM,CAAC;IACf,0EAA0E;IAC1E,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,4BAA4B;IAC3C,qEAAqE;IACrE,OAAO,EAAE,MAAM,CAAC;IAChB,mDAAmD;IACnD,KAAK,EAAE,MAAM,CAAC;IACd,wDAAwD;IACxD,KAAK,EAAE,MAAM,CAAC;IACd,gFAAgF;IAChF,SAAS,CAAC,EAAE,OAAO,KAAK,CAAC;CAC1B;AAaD;;;;;;GAMG;AACH,qBAAa,oBAAqB,SAAQ,KAAK;IAE3C,QAAQ,CAAC,MAAM,EAAE,MAAM;IACvB,QAAQ,CAAC,IAAI,EAAE,MAAM;gBADZ,MAAM,EAAE,MAAM,EACd,IAAI,EAAE,MAAM,EACrB,OAAO,EAAE,MAAM,EACf,OAAO,CAAC,EAAE;QAAE,KAAK,CAAC,EAAE,OAAO,CAAA;KAAE;CAKhC;AAgBD,qBAAa,qBAAsB,YAAW,qBAAqB;IACjE,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAS;IACjC,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAS;IAC/B,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAS;IAC/B,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAe;gBAE7B,IAAI,EAAE,4BAA4B;IAO9C,oEAAoE;IAC9D,KAAK,IAAI,OAAO,CAAC,WAAW,CAAC;IAI7B,SAAS,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,SAAS,GAAG,SAAS,CAAC;IAI3D,YAAY,CAAC,GAAG,EAAE,SAAS,GAAG,OAAO,CAAC,IAAI,CAAC;IAI3C,YAAY,CAAC,QAAQ,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,IAAI,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IAItF,UAAU,CAAC,GAAG,EAAE,gBAAgB,GAAG,OAAO,CAAC,IAAI,CAAC;IAIhD,kBAAkB,CAAC,QAAQ,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,gBAAgB,EAAE,CAAC;IAIhF,qBAAqB,CACzB,QAAQ,EAAE,MAAM,EAChB,eAAe,EAAE,MAAM,GACtB,OAAO,CAAC,gBAAgB,GAAG,SAAS,CAAC;IAUlC,WAAW,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,iBAAiB,GAAG,SAAS,CAAC;IAIrE,WAAW,CAAC,GAAG,EAAE,iBAAiB,GAAG,OAAO,CAAC,IAAI,CAAC;IAMxD;;;;OAIG;YACW,IAAI;CAqCnB"}
+{"version":3,"file":"http.d.ts","sourceRoot":"","sources":["../src/http.ts"],"names":[],"mappings":"AAmDA,OAAO,KAAK,EACV,SAAS,EACT,gBAAgB,EAChB,qBAAqB,EACrB,SAAS,EACT,iBAAiB,EAClB,MAAM,WAAW,CAAC;AAEnB,+EAA+E;AAC/E,MAAM,WAAW,WAAW;IAC1B,KAAK,EAAE,MAAM,CAAC;IACd,2EAA2E;IAC3E,MAAM,EAAE,MAAM,CAAC;IACf,0EAA0E;IAC1E,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,4BAA4B;IAC3C,qEAAqE;IACrE,OAAO,EAAE,MAAM,CAAC;IAChB,mDAAmD;IACnD,KAAK,EAAE,MAAM,CAAC;IACd,wDAAwD;IACxD,KAAK,EAAE,MAAM,CAAC;IACd,gFAAgF;IAChF,SAAS,CAAC,EAAE,OAAO,KAAK,CAAC;CAC1B;AAED;;;;;;;;GAQG;AACH,qBAAa,oBAAqB,SAAQ,KAAK;IAE3C,QAAQ,CAAC,MAAM,EAAE,MAAM;IACvB,QAAQ,CAAC,IAAI,EAAE,MAAM;gBADZ,MAAM,EAAE,MAAM,EACd,IAAI,EAAE,MAAM,EACrB,OAAO,EAAE,MAAM,EACf,OAAO,CAAC,EAAE;QAAE,KAAK,CAAC,EAAE,OAAO,CAAA;KAAE;CAKhC;AAqCD,qBAAa,qBAAsB,YAAW,qBAAqB;IACjE;;;OAGG;IACH,QAAQ,CAAC,SAAS,EAAE,SAAS,CAAuB;IAEpD,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAS;IACjC,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAS;IAC/B,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAS;IAC/B,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAe;IACzC,mFAAmF;IACnF,OAAO,CAAC,SAAS,CAA8B;gBAEnC,IAAI,EAAE,4BAA4B;IAO9C,oEAAoE;IAC9D,KAAK,IAAI,OAAO,CAAC,WAAW,CAAC;IAI7B,SAAS,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,SAAS,GAAG,SAAS,CAAC;IAI3D,YAAY,CAAC,GAAG,EAAE,SAAS,GAAG,OAAO,CAAC,IAAI,CAAC;IAI3C,YAAY,CAAC,QAAQ,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,IAAI,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IAatF,UAAU,CAAC,GAAG,EAAE,gBAAgB,GAAG,OAAO,CAAC,IAAI,CAAC;IAIhD,kBAAkB,CAAC,QAAQ,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,gBAAgB,EAAE,CAAC;IAKhF,qBAAqB,CACzB,QAAQ,EAAE,MAAM,EAChB,eAAe,EAAE,MAAM,GACtB,OAAO,CAAC,gBAAgB,GAAG,SAAS,CAAC;IAKlC,WAAW,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,iBAAiB,GAAG,SAAS,CAAC;IAIrE,WAAW,CAAC,GAAG,EAAE,iBAAiB,GAAG,OAAO,CAAC,IAAI,CAAC;IAMxD;;;;;;;;;;OAUG;YACW,KAAK;IAOnB,iGAAiG;YACnF,KAAK;IAInB,0FAA0F;IAC1F,OAAO,CAAC,KAAK;IAWb,8EAA8E;YAChE,SAAS;IAKvB;;;OAGG;YACW,IAAI;IAgBlB;;;;OAIG;YACW,IAAI;CAoCnB"}

package/dist/http.js

@@ -1,8 +1,52 @@
+/**
+ * Hosted HTTP binding — {@link ThreadPersistencePort} over guuey's thread
+ * API, `POST <base>/v1/thread-store/<op>` (guuey#208). The "eject the code,
+ * keep your memory" leg of the ejected ladder: point a `ThreadStore` at
+ * this binding with an end-user token and your self-hosted agent reads and
+ * writes the SAME conversation rows guuey's hosted runtime does.
+ *
+ * Wire protocol (the `@guuey/state` `HttpKv` shape):
+ * - Request: JSON body `{ context: { appId }, args: {...} }`, header
+ *   `Authorization: Bearer <token>`.
+ * - Success: `200 { result }`.
+ * - Failure: `4xx/5xx { code, message }` → {@link HttpThreadStoreError}.
+ * - Every read's body is parsed to `unknown` and read through `http-read.ts`;
+ *   a 2xx whose body is not an envelope, or whose `result` is not what the op
+ *   answers, is an {@link HttpThreadStoreError} with code `BAD_RESPONSE`. A
+ *   write's 2xx body is never read: the write has committed, and a body that
+ *   does not parse must not turn it into a failure a caller would retry (into
+ *   `CONFLICT`, since `createThread` and `putMessage` are conditional).
+ * - A message row an older writer stored without a `userId` gets the token's
+ *   user (read once from {@link HttpThreadPersistence.scope}): the server
+ *   answers only threads that user owns, and every row the port writes there
+ *   carries that user.
+ *
+ * Auth + tenancy: the token is an END-USER token for the app — one the
+ * app's configured identity issuer minted (your own IdP, or guuey's per-app
+ * widget issuer via `@guuey/widget-auth`). The server verifies it against
+ * that issuer, derives the same `byo_…` userId the hosted runtime would, and
+ * scopes every op to `(appId, userId)`: rows you write must carry that
+ * userId, threads you touch must belong to it. `context` on the wire is
+ * advisory — the token is authoritative. Call {@link scope} to learn the
+ * derived userId (and the API's region) before `ensureThread`.
+ *
+ * Retry policy: reads (`getThread`/`listRecentMessages`/
+ * `findByClientMessageId`/`getSnapshot`/`scope`) are idempotent and retried
+ * once on a network failure or a 5xx. Writes (`createThread`/`incrementSeq`/
+ * `putMessage`/`putSnapshot`) are NEVER retried automatically —
+ * `incrementSeq` is not idempotent, and a blind retry after a server-side
+ * apply would double-allocate a seq.
+ */
+import { DYNAMODB_ROW_BUDGET } from "./item-size.js";
+import { ThreadClosedError } from "./closed.js";
+import { isWireObject, readAllocatedSeq, readThreadMessageRow, readThreadMessageRows, readThreadRow, readThreadScope, readThreadSnapshotRow, } from "./http-read.js";
 /**
  * Thrown for every non-2xx response and every exhausted network failure.
  * `code` is the server's flat error code (`UNAUTHORIZED`, `FORBIDDEN`,
  * `INVALID_ARGUMENT`, `INVALID_CONTEXT`, `THREAD_NOT_FOUND`, `CONFLICT`,
- * `NOT_FOUND`, `TRANSPORT`); `status` is the HTTP status (`0` for a network
+ * `NOT_FOUND`, `TRANSPORT`, and the client's own `BAD_RESPONSE` for a 2xx body
+ * it cannot read; `incrementSeq`'s `THREAD_CLOSED` is thrown as
+ * `ThreadClosedError` instead); `status` is the HTTP status (`0` for a network
  * failure that never produced a response).
  */
 export class HttpThreadStoreError extends Error {
@@ -15,21 +59,38 @@ export class HttpThreadStoreError extends Error {
         this.name = "HttpThreadStoreError";
     }
 }
-async function toError(res) {
-    let body;
+async function parsedBody(res) {
     try {
-        body = (await res.json());
+        const value = await res.json();
+        return { parsed: true, value };
     }
-    catch {
-        body = {};
+    catch (cause) {
+        return { parsed: false, cause };
     }
-    return new HttpThreadStoreError(res.status, body.code ?? "TRANSPORT", body.message ?? `guuey thread API error (HTTP ${res.status})`);
+}
+async function toError(res) {
+    // `{ code, message }`, each read only when it is a string: a body that is
+    // not one (not JSON, a gateway's HTML page) keeps the transport defaults.
+    const body = await parsedBody(res);
+    const env = body.parsed && isWireObject(body.value) ? body.value : undefined;
+    return new HttpThreadStoreError(res.status, typeof env?.code === "string" ? env.code : "TRANSPORT", typeof env?.message === "string" ? env.message : `guuey thread API error (HTTP ${res.status})`, body.parsed ? undefined : { cause: body.cause });
+}
+/** The refusal for a 2xx whose body the op cannot read. */
+function badResponse(res, op, what, cause) {
+    return new HttpThreadStoreError(res.status, "BAD_RESPONSE", `guuey thread API ${op}: ${what} (HTTP ${res.status})`, cause !== undefined ? { cause } : undefined);
 }
 export class HttpThreadPersistence {
+    /**
+     * guuey#1794: the server stores the rows this binding sends in DynamoDB, so
+     * the store sizes them by DynamoDB's own item rules before it sends any.
+     */
+    rowBudget = DYNAMODB_ROW_BUDGET;
     baseUrl;
     appId;
     token;
     fetchImpl;
+    /** The token's user, read from `scope` the first time a row lacks its `userId`. */
+    ownerRead;
     constructor(opts) {
         this.baseUrl = opts.baseUrl.replace(/\/+$/, "");
         this.appId = opts.appId;
@@ -38,39 +99,102 @@ export class HttpThreadPersistence {
     }
     /** The `(appId, userId, region)` the server bound this token to. */
     async scope() {
-        return this.call("scope", {}, true);
+        return this.call("scope", {}, true, readThreadScope);
     }
     async getThread(threadId) {
-        return (await this.call("getThread", { threadId }, true)) ?? undefined;
+        return this.pointRead("getThread", { threadId }, readThreadRow);
     }
     async createThread(row) {
-        await this.call("createThread", { row }, false);
+        await this.write("createThread", { row });
     }
     async incrementSeq(threadId, preview, atIso) {
-        return this.call("incrementSeq", { threadId, preview, atIso }, false);
+        try {
+            return await this.call("incrementSeq", { threadId, preview, atIso }, false, readAllocatedSeq);
+        }
+        catch (err) {
+            // The server's word for a closed thread (guuey#2355) becomes the typed
+            // refusal every binding gives, so a ThreadStore reads it the same way.
+            if (err instanceof HttpThreadStoreError && err.code === "THREAD_CLOSED") {
+                throw new ThreadClosedError(threadId);
+            }
+            throw err;
+        }
     }
     async putMessage(row) {
-        await this.call("putMessage", { row }, false);
+        await this.write("putMessage", { row });
     }
     async listRecentMessages(threadId, limit) {
-        return this.call("listRecentMessages", { threadId, limit }, true);
+        const rows = await this.call("listRecentMessages", { threadId, limit }, true, readThreadMessageRows);
+        return Promise.all(rows.map((row) => this.owned(row)));
     }
     async findByClientMessageId(threadId, clientMessageId) {
-        return ((await this.call("findByClientMessageId", { threadId, clientMessageId }, true)) ?? undefined);
+        const row = await this.pointRead("findByClientMessageId", { threadId, clientMessageId }, readThreadMessageRow);
+        return row === undefined ? undefined : this.owned(row);
     }
     async getSnapshot(threadId) {
-        return (await this.call("getSnapshot", { threadId }, true)) ?? undefined;
+        return this.pointRead("getSnapshot", { threadId }, readThreadSnapshotRow);
     }
     async putSnapshot(row) {
-        await this.call("putSnapshot", { row }, false);
+        await this.write("putSnapshot", { row });
     }
     // ── internals ──────────────────────────────────────────────────────
     /**
-     * One shared retry budget (`retried`) covers BOTH retry triggers — a
-     * network failure and a 5xx response — so a retryable op makes at most
-     * 2 total requests, never 3.
+     * A write: never retried, and its body (the server's `{ result: null }`) is
+     * never read: a 2xx means it committed, whatever the body holds. The body is
+     * cancelled, not left open, so the connection is released.
+     *
+     * Releasing is best effort and never awaited: a body stream that errors
+     * after the 2xx headers (a connection reset) rejects `cancel()`, and that
+     * rejection must not turn a committed write into a thrown one, which a
+     * caller would retry into `CONFLICT`. The failure is reported on
+     * `console.warn` instead: the write stands, and the stream is already dead.
+     */
+    async write(op, args) {
+        const res = await this.send(op, args, false);
+        void res.body?.cancel().catch((err) => {
+            console.warn(`@guuey/threads: ${op} committed, but releasing its response body failed`, err);
+        });
+    }
+    /** `row` with its `userId`: the stored one, or the token's user for a legacy row without one. */
+    async owned(row) {
+        return { ...row, userId: row.userId ?? (await this.owner()) };
+    }
+    /** The token's user, read once; a failed read is not kept, so the next row asks again. */
+    owner() {
+        this.ownerRead ??= this.scope().then((scope) => scope.userId, (err) => {
+            this.ownerRead = undefined;
+            throw err;
+        });
+        return this.ownerRead;
+    }
+    /** A point read: `null` (the port's `undefined`) or the row `read` proves. */
+    async pointRead(op, args, read) {
+        const row = await this.call(op, args, true, (value) => (value === null ? null : read(value)));
+        return row ?? undefined;
+    }
+    /**
+     * The op's `{ result }` envelope, its `result` read by `read`. `undefined`
+     * from `read` (the result is not this op's answer) is `BAD_RESPONSE`.
+     */
+    async call(op, args, retryable, read) {
+        const res = await this.send(op, args, retryable);
+        const parsed = await parsedBody(res);
+        if (!parsed.parsed)
+            throw badResponse(res, op, "the body is not JSON", parsed.cause);
+        const body = parsed.value;
+        if (!isWireObject(body) || !("result" in body))
+            throw badResponse(res, op, "the body is not a { result } envelope");
+        const value = read(body.result);
+        if (value === undefined)
+            throw badResponse(res, op, "the result does not read as this op's answer");
+        return value;
+    }
+    /**
+     * One op on the wire: the 2xx response (its body unread), or the typed error. One shared retry budget (`retried`) covers BOTH retry
+     * triggers — a network failure and a 5xx response — so a retryable op makes
+     * at most 2 total requests, never 3.
      */
-    async call(op, args, retryable) {
+    async send(op, args, retryable) {
         const doOnce = async () => this.fetchImpl(`${this.baseUrl}/v1/thread-store/${op}`, {
             method: "POST",
             headers: {
@@ -100,7 +224,6 @@ export class HttpThreadPersistence {
         }
         if (!res.ok)
             throw await toError(res);
-        const body = (await res.json());
-        return body.result;
+        return res;
     }
 }

package/dist/in-memory.d.ts

@@ -1,10 +1,4 @@
-/**
- * InMemoryThreadPersistence — the dev/test binding of
- * {@link ThreadPersistencePort}. Same contract as any real binding (run
- * the suite in `@guuey/threads/testing` to prove yours), including the
- * two conditional-write guards and the null-preview no-touch semantics.
- */
-import type { ThreadMessageRow, ThreadPersistencePort, ThreadRow, ThreadSnapshotRow } from "./rows.js";
+import type { ThreadClosure, ThreadMessageRow, ThreadPersistencePort, ThreadRow, ThreadSnapshotRow } from "./rows.js";
 export declare class InMemoryThreadPersistence implements ThreadPersistencePort {
     readonly threads: Map<string, ThreadRow>;
     readonly messages: ThreadMessageRow[];
@@ -12,6 +6,7 @@ export declare class InMemoryThreadPersistence implements ThreadPersistencePort
     getThread(threadId: string): Promise<ThreadRow | undefined>;
     createThread(row: ThreadRow): Promise<void>;
     incrementSeq(threadId: string, preview: string | null, atIso: string): Promise<number>;
+    closeThread(threadId: string, closure: ThreadClosure): Promise<"closed" | "already_closed">;
     putMessage(row: ThreadMessageRow): Promise<void>;
     listRecentMessages(threadId: string, limit: number): Promise<ThreadMessageRow[]>;
     findByClientMessageId(threadId: string, clientMessageId: string): Promise<ThreadMessageRow | undefined>;

package/dist/in-memory.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"in-memory.d.ts","sourceRoot":"","sources":["../src/in-memory.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,OAAO,KAAK,EACV,gBAAgB,EAChB,qBAAqB,EACrB,SAAS,EACT,iBAAiB,EAClB,MAAM,WAAW,CAAC;AAEnB,qBAAa,yBAA0B,YAAW,qBAAqB;IACrE,QAAQ,CAAC,OAAO,yBAAgC;IAChD,QAAQ,CAAC,QAAQ,EAAE,gBAAgB,EAAE,CAAM;IAC3C,QAAQ,CAAC,SAAS,iCAAwC;IAEpD,SAAS,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,SAAS,GAAG,SAAS,CAAC;IAI3D,YAAY,CAAC,GAAG,EAAE,SAAS,GAAG,OAAO,CAAC,IAAI,CAAC;IAO3C,YAAY,CAAC,QAAQ,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,IAAI,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IAYtF,UAAU,CAAC,GAAG,EAAE,gBAAgB,GAAG,OAAO,CAAC,IAAI,CAAC;IAOhD,kBAAkB,CAAC,QAAQ,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,gBAAgB,EAAE,CAAC;IAQhF,qBAAqB,CACzB,QAAQ,EAAE,MAAM,EAChB,eAAe,EAAE,MAAM,GACtB,OAAO,CAAC,gBAAgB,GAAG,SAAS,CAAC;IAMlC,WAAW,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,iBAAiB,GAAG,SAAS,CAAC;IAIrE,WAAW,CAAC,GAAG,EAAE,iBAAiB,GAAG,OAAO,CAAC,IAAI,CAAC;CAGzD"}
+{"version":3,"file":"in-memory.d.ts","sourceRoot":"","sources":["../src/in-memory.ts"],"names":[],"mappings":"AAQA,OAAO,KAAK,EACV,aAAa,EACb,gBAAgB,EAChB,qBAAqB,EACrB,SAAS,EACT,iBAAiB,EAClB,MAAM,WAAW,CAAC;AAEnB,qBAAa,yBAA0B,YAAW,qBAAqB;IACrE,QAAQ,CAAC,OAAO,yBAAgC;IAChD,QAAQ,CAAC,QAAQ,EAAE,gBAAgB,EAAE,CAAM;IAC3C,QAAQ,CAAC,SAAS,iCAAwC;IAEpD,SAAS,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,SAAS,GAAG,SAAS,CAAC;IAI3D,YAAY,CAAC,GAAG,EAAE,SAAS,GAAG,OAAO,CAAC,IAAI,CAAC;IAO3C,YAAY,CAAC,QAAQ,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,IAAI,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IAmBtF,WAAW,CAAC,QAAQ,EAAE,MAAM,EAAE,OAAO,EAAE,aAAa,GAAG,OAAO,CAAC,QAAQ,GAAG,gBAAgB,CAAC;IAU3F,UAAU,CAAC,GAAG,EAAE,gBAAgB,GAAG,OAAO,CAAC,IAAI,CAAC;IAOhD,kBAAkB,CAAC,QAAQ,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,gBAAgB,EAAE,CAAC;IAQhF,qBAAqB,CACzB,QAAQ,EAAE,MAAM,EAChB,eAAe,EAAE,MAAM,GACtB,OAAO,CAAC,gBAAgB,GAAG,SAAS,CAAC;IAMlC,WAAW,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,iBAAiB,GAAG,SAAS,CAAC;IAIrE,WAAW,CAAC,GAAG,EAAE,iBAAiB,GAAG,OAAO,CAAC,IAAI,CAAC;CAGzD"}