@guuey/threads

中文文档
0.36.0发布于 2026/11/15MITTypeScriptES Module构建来源已验证近 30 天下载 5014

Universal session/thread persistence for AgJSON agents — the ThreadStore contract (append-fold, history, snapshots), the fold↔row mapping, and an in-memory binding. Guuey's hosted runtime is one binding; implement the port against your own store and run t

原始使用文档
文档目录4 节
  1. Hosted binding — keep your memory after ejecting
  2. Row size limits
  3. Sealed messages
  4. Support

@guuey/threads

Universal session/thread persistence for AgJSON agents.

Hosted guuey agents get thread rehydration ("my agent remembers this conversation") from the platform. This package is that same session model as a public contract, so ejected and self-hosted agents — and integration harnesses — share it:

  • ThreadStore — the storage-agnostic logic: thread resolution and ownership, atomic gap-free sequencing, clientMessageId idempotency, turn-level fold persistence (messages + generative-UI card rows + the latest-replace snapshot), and the prompt-lane history projection.
  • ThreadPersistencePort — the narrow surface a binding implements. InMemoryThreadPersistence ships in the box (dev, tests, CI); guuey's hosted runtime binds DynamoDB; HttpThreadPersistence points a self-hosted agent at guuey's hosted thread API ("eject the code, keep your memory"); or implement the port against your own store.
  • fold ↔ row mapping — agMessageToRow, reassembleFold, uiCardArtifactsFromMessages and friends: byte-identity persistence of an @silverprotocol/core AgReduceResult, including the projection that persists MCP-App cards carried on tool-result blocks.
  • @guuey/threads/testing — the port contract suite. Run it against your binding and "works in-memory" and "works on the real thing" mean the same set of guarantees.
import { InMemoryThreadPersistence, ThreadStore } from "@guuey/threads";

const store = new ThreadStore(new InMemoryThreadPersistence());
const threadId = await store.ensureThread({
  userId: "g_dev",
  appId: "my-agent",
  region: "local",
});
await store.appendMessage({
  threadId,
  userId: "g_dev",
  role: "user",
  content: "hello",
  text: "hello",
  clientMessageId: "m1",
});
const history = await store.loadHistory(threadId);
// your-binding.test.ts
import { runThreadPersistenceContractSuite } from "@guuey/threads/testing";
runThreadPersistenceContractSuite("MyBinding", async () => ({ port: makeMyPort() }));

Hosted binding — keep your memory after ejecting

HttpThreadPersistence implements the same port over guuey's thread API, so an agent you run yourself reads and writes the SAME conversation rows the hosted runtime does. It is scoped to one app and one end-user: pass the end-user's bearer token — one your 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 end-user id the hosted runtime uses, and confines every op to (app, user).

import { HttpThreadPersistence, ThreadStore } from "@guuey/threads";

const appId = process.env.GUUEY_APP_ID!;
const port = new HttpThreadPersistence({
  baseUrl: "https://api.us-east-1.guuey.com",
  appId,
  token: endUserToken, // per request — the end-user's own token
});
const { userId, region } = await port.scope(); // what the token resolves to
const store = new ThreadStore(port);
const threadId = await store.ensureThread({ threadId: clientThreadId, userId, appId, region });

Requires the app to run identified end-users (userAuthMode: "byo"); guests and Cognito sessions are served on-platform only. Errors surface as HttpThreadStoreError (status, code). Reads retry once on a network failure or 5xx; writes never do.

Row size limits

A store with an item-size limit declares it as the port's optional rowBudget ({ maxBytes, bytesOf(row), numberFits?(n) }). The DynamoDB-backed bindings, HttpThreadPersistence included, declare DYNAMODB_ROW_BUDGET: 380,000 bytes measured by dynamoItemBytes, an upper bound under DynamoDB's own item-size rules, and dynamoNumberFits, which refuses a number DynamoDB cannot hold as written (outside the safe-integer range, NaN or an infinity, or a non-zero magnitude below 1e-130). A port without a budget stores rows exactly as mapped.

appendFold checks every row of a turn against the budget before it writes any:

  • A value is stored as a marker in its place, { "com.guuey/elided": { "bytes": <UTF-8 length of its JSON> } }. A tool-call value is, when it carries a number the store cannot hold (reason: "number"). An oversized row leaves values out until it fits (reason: "size"), the largest first within each step: first a tool-result's uiData that is an inline UI resource with text ({ uri, text }) when a card row of the same turn carries the same value for the same call (field: "uiData"; the card row holds the resource, and the thread's readers draw the card from it), then each providerMetadata.wireInput copy, then each input. Text blocks are never elided. The result lists each one in elidedToolInputs.
  • A turn that still cannot be stored is never written in part. With unstorableNotice: { text } the turn is stored as ONE agent row carrying that text and content.error.code "stored_turn_too_large" or "stored_turn_unstorable_number" (classifyStoredRow reads either as a failure), and the result carries unstorable. Without it, appendFold throws StoredRowTooLargeError or StoredRowUnstorableNumberError and writes nothing.

appendMessage refuses such a row the same way before it allocates a seq. withItemSizeLimit(port) from @guuey/threads/testing wraps any port to declare the budget and refuse what DynamoDB would (on putMessage and putSnapshot), for tests.

The turn's snapshot is planned under the same budget, also before any row is written (planSnapshot), so the snapshot write never fails after the rows landed:

  • A workingState that carries a number the store cannot hold is not stored. The snapshot keeps priorWorkingState (the state the turn was seeded with), or no state when none is given.
  • A thread-memory element that carries such a number is left out.
  • Over the budget, the turn's state is refused first, then the memory records this turn wrote are left out, the largest first. Records stored unchanged from priorThreadMemory, and carried elements, stay.
  • A snapshot that still does not fit is not written, and the prior one stands.

The result's refusedSnapshot ({ state?, memoryNumber, memorySize, notWritten }) reports what was left out, as counts.

Sealed messages

A thread row may carry sealIntervals: stretches of messages (fromSeq to toSeq, both inclusive; no toSeq = still open) that the app's operator may not read. A reader that shows conversation data to the operator checks them with the exported helpers, never by hand:

import { isSeqSealed, readableThreadPreview, readSealState } from "@guuey/threads";

const seal = readSealState(row.sealIntervals); // absent = legacy, wholly readable
if (isSeqSealed(seal, message.seq)) {
  /* withhold this message */
}
const preview = readableThreadPreview(row); // '' when its source message is sealed

A seal record that is present but malformed reads as wholly sealed. Each preview records the seq it was taken from (lastMessagePreviewSeq) and a digest of its text (lastMessagePreviewDigest, previewDigest(preview)) in the same update. On a thread with any sealed part, a preview whose seq is missing, or whose digest is missing or does not match its text, is withheld. A binding that implements the port writes both with the preview.

An event row (a hand-off, a report) leaves the preview as it was, like a card row: it is written from the whole conversation, so it never becomes the thread's preview.

Support

Questions and help: the guuey community on Discord — https://guuey.com/discord. Bugs and feature requests: https://github.com/withguuey/guuey-sdks/issues.

版本与发布记录

@guuey/threads 共发布 74 个版本,首次发布于 2026/08/07;过去 12 个月发布了 74 个版本。最新版本附带 npm provenance 构建来源证明,可追溯到公开的 CI 构建记录。

版本发布日期距今
0.36.0latest2026/11/152 天前
0.35.02026/11/116 天前
0.34.02026/11/0610 天前
0.33.02026/11/0610 天前
0.32.02026/11/0611 天前
0.31.12026/09/291 个月前

其他发布通道:next → 0.16.15。

关于 @guuey/threads 的常见问题

@guuey/threads 是什么?

Universal session/thread persistence for AgJSON agents — the ThreadStore contract (append-fold, history, snapshots), the fold↔row mapping, and an in-memory binding. Guuey's hosted runtime is one binding; implement the port against your own store and run t

如何安装 @guuey/threads?

在项目目录运行 npm install @guuey/threads,或使用 pnpm add / yarn add / bun add。

@guuey/threads 支持 TypeScript 吗?

支持。包内自带 TypeScript 类型声明(package.json 声明了 types 入口),安装后即可获得类型提示,无需再安装 @types 包。

@guuey/threads 支持 ESM 还是 CommonJS?

以 ES Module 形式发布,推荐使用 import 引入。在 CommonJS 项目中,Node.js 20.19+ / 22.12+ 可以直接 require() 不含顶层 await 的 ES Module,更早的版本需要改用动态 import()。

@guuey/threads 需要什么版本的 Node.js?

package.json 的 engines 字段要求 Node.js >=22.12.0。版本不符时 npm 默认只给出警告,开启 engine-strict 后会拒绝安装。

@guuey/threads 可以商用吗?

@guuey/threads 使用 MIT 许可。宽松许可:允许商业使用、修改和再分发,通常只需在分发时保留原版权与许可声明。以上为概括,不构成法律意见,请以许可原文为准。

@guuey/threads 的下载量有多少?

根据 npm 官方下载统计,@guuey/threads 在 2026/10/17 – 2026/11/15 这 30 天内被下载 5,014 次,日均约 167 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入,适合横向比较热度,不能直接等同于使用人数。

@guuey/threads 还在维护吗?

最新版本 0.36.0 发布于 2026/11/15(2 天前);至今共发布 74 个版本,其中过去 12 个月发布了 74 个;首次发布于 2026/08/07。发布频率只是参考信号:功能稳定的工具可能很少需要更新,建议结合源码仓库的 issue 和提交记录判断。