@ggui-ai/mcp-server-handlers 0.1.0-rc.1

package/dist/threads/append-message.d.ts

@@ -0,0 +1,26 @@
+/**
+ * `appendMessage` — persist a message idempotently on (threadId, key).
+ *
+ * Thin over {@link ThreadStore.appendMessage}. The store owns:
+ *   - idempotency (first-write-wins on (threadId, key))
+ *   - seq assignment (monotonic, gap-free, from 1)
+ *   - unread counter (bumps only on non-user authors)
+ *   - ownership enforcement
+ *
+ * Handlers MUST NOT re-implement any of the above. A retry that
+ * returns the originally stored message (with stable seq/at) is the
+ * contract — transports surface it as a normal 200/201, not a
+ * conflict.
+ *
+ * Failure modes:
+ *   - {@link InvalidThreadRequestError} — malformed body.
+ *   - {@link ThreadNotFoundError} — thread missing or wrong owner.
+ */
+import type { ThreadStore } from '@ggui-ai/mcp-server-core';
+import type { ThreadMessage } from '@ggui-ai/protocol';
+import type { ThreadHandlerContext } from './context.js';
+export interface AppendMessageDeps {
+    readonly threads: ThreadStore;
+}
+export declare function appendMessage(deps: AppendMessageDeps, input: unknown, ctx: ThreadHandlerContext): Promise<ThreadMessage>;
+//# sourceMappingURL=append-message.d.ts.map

package/dist/threads/append-message.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"append-message.d.ts","sourceRoot":"","sources":["../../src/threads/append-message.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AACH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,0BAA0B,CAAC;AAC5D,OAAO,KAAK,EAEV,aAAa,EACd,MAAM,mBAAmB,CAAC;AAC3B,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,cAAc,CAAC;AAMzD,MAAM,WAAW,iBAAiB;IAChC,QAAQ,CAAC,OAAO,EAAE,WAAW,CAAC;CAC/B;AAED,wBAAsB,aAAa,CACjC,IAAI,EAAE,iBAAiB,EACvB,KAAK,EAAE,OAAO,EACd,GAAG,EAAE,oBAAoB,GACxB,OAAO,CAAC,aAAa,CAAC,CAOxB"}

package/dist/threads/append-message.js

@@ -0,0 +1,5 @@
+import { appendThreadMessageInputSchema, parseWithSchema, } from './schemas.js';
+export async function appendMessage(deps, input, ctx) {
+    const parsed = parseWithSchema(appendThreadMessageInputSchema, input, 'append-message request');
+    return deps.threads.appendMessage(ctx.ownerId, parsed);
+}

package/dist/threads/apply-thread-action.d.ts

@@ -0,0 +1,36 @@
+/**
+ * `applyThreadAction` — mutate thread-level state (pin/archive/…).
+ *
+ * Thin over {@link ThreadStore.applyAction}. The store owns the full
+ * action state-machine:
+ *   - 9-action vocabulary (pin/unpin/mute/unmute/archive/unarchive/
+ *     mark_read/request_delete/restore)
+ *   - `restore` requires `status === 'pending_delete'`
+ *   - `archive`/`unarchive` reject on `pending_delete`
+ *   - idempotent no-ops leave `updatedAt` stable
+ *
+ * Handlers MUST NOT re-implement any of those checks — duplicating
+ * state-machine rules is how they drift.
+ *
+ * Failure modes:
+ *   - {@link InvalidThreadRequestError} — malformed body OR unknown
+ *     action value (the request-shape rejection path).
+ *   - {@link InvalidThreadActionError} — reachable only when the
+ *     store's own validator catches a bypass; normally the request
+ *     shape parser rejects first.
+ *   - {@link ThreadActionInvalidStateError} — action valid but
+ *     not permitted from the current status.
+ *   - {@link ThreadNotFoundError} — thread missing or wrong owner.
+ */
+import type { ThreadStore } from '@ggui-ai/mcp-server-core';
+import type { Thread } from '@ggui-ai/protocol';
+import type { ThreadHandlerContext } from './context.js';
+export interface ApplyThreadActionDeps {
+    readonly threads: ThreadStore;
+}
+export interface ApplyThreadActionInput {
+    readonly threadId: string;
+    readonly body: unknown;
+}
+export declare function applyThreadAction(deps: ApplyThreadActionDeps, input: ApplyThreadActionInput, ctx: ThreadHandlerContext): Promise<Thread>;
+//# sourceMappingURL=apply-thread-action.d.ts.map

package/dist/threads/apply-thread-action.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"apply-thread-action.d.ts","sourceRoot":"","sources":["../../src/threads/apply-thread-action.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,0BAA0B,CAAC;AAC5D,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,mBAAmB,CAAC;AAChD,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,cAAc,CAAC;AAGzD,MAAM,WAAW,qBAAqB;IACpC,QAAQ,CAAC,OAAO,EAAE,WAAW,CAAC;CAC/B;AAED,MAAM,WAAW,sBAAsB;IACrC,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAC;CACxB;AAED,wBAAsB,iBAAiB,CACrC,IAAI,EAAE,qBAAqB,EAC3B,KAAK,EAAE,sBAAsB,EAC7B,GAAG,EAAE,oBAAoB,GACxB,OAAO,CAAC,MAAM,CAAC,CAOjB"}

package/dist/threads/apply-thread-action.js

@@ -0,0 +1,5 @@
+import { applyThreadActionInputSchema, parseWithSchema } from './schemas.js';
+export async function applyThreadAction(deps, input, ctx) {
+    const parsed = parseWithSchema(applyThreadActionInputSchema, input.body, 'apply-thread-action request');
+    return deps.threads.applyAction(ctx.ownerId, input.threadId, parsed.action);
+}

package/dist/threads/context.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Per-request context threaded through every thread handler.
+ *
+ * Narrower than the tool-shaped {@link HandlerContext} in this package's
+ * root: thread handlers are partition-scoped by `ownerId` (the identity
+ * the auth layer resolved upstream), not by `appId`. `appId` is still
+ * present on individual `Thread` rows but it's carried as data through
+ * request shapes (e.g. {@link CreateThreadInput}), not through handler
+ * context.
+ */
+import type { ThreadOwnerId } from '@ggui-ai/protocol';
+export interface ThreadHandlerContext {
+    /**
+     * Resolved owner id — the thread-partition key. Upstream auth proves
+     * this; handlers forward it verbatim to {@link ThreadStore}. Tests
+     * that bypass auth inject it directly.
+     *
+     * Wrong-owner + missing-thread both surface as
+     * {@link ThreadNotFoundError}; handlers never distinguish them.
+     */
+    readonly ownerId: ThreadOwnerId;
+    /** Per-request correlation id. Used for log lines; transport-owned. */
+    readonly requestId: string;
+}
+//# sourceMappingURL=context.d.ts.map

package/dist/threads/context.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"context.d.ts","sourceRoot":"","sources":["../../src/threads/context.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AACH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,mBAAmB,CAAC;AAEvD,MAAM,WAAW,oBAAoB;IACnC;;;;;;;OAOG;IACH,QAAQ,CAAC,OAAO,EAAE,aAAa,CAAC;IAChC,uEAAuE;IACvE,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;CAC5B"}

package/dist/threads/context.js

@@ -0,0 +1 @@
+export {};

package/dist/threads/create-thread.d.ts

@@ -0,0 +1,19 @@
+/**
+ * `createThread` — open a new persistent chat.
+ *
+ * Thin over {@link ThreadStore.createThread}. The store owns id
+ * generation, initial field seeding (lastSeq=0, unreadCount=0,
+ * status='active'), title-hint truncation, and metadata cloning.
+ *
+ * Failure modes:
+ *   - {@link InvalidThreadRequestError} — malformed body (missing
+ *     appId, extra unknown fields, wrong type).
+ */
+import type { ThreadStore } from '@ggui-ai/mcp-server-core';
+import type { Thread } from '@ggui-ai/protocol';
+import type { ThreadHandlerContext } from './context.js';
+export interface CreateThreadDeps {
+    readonly threads: ThreadStore;
+}
+export declare function createThread(deps: CreateThreadDeps, input: unknown, ctx: ThreadHandlerContext): Promise<Thread>;
+//# sourceMappingURL=create-thread.d.ts.map

package/dist/threads/create-thread.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"create-thread.d.ts","sourceRoot":"","sources":["../../src/threads/create-thread.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AACH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,0BAA0B,CAAC;AAC5D,OAAO,KAAK,EAAqB,MAAM,EAAE,MAAM,mBAAmB,CAAC;AACnE,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,cAAc,CAAC;AAGzD,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,OAAO,EAAE,WAAW,CAAC;CAC/B;AAED,wBAAsB,YAAY,CAChC,IAAI,EAAE,gBAAgB,EACtB,KAAK,EAAE,OAAO,EACd,GAAG,EAAE,oBAAoB,GACxB,OAAO,CAAC,MAAM,CAAC,CAOjB"}

package/dist/threads/create-thread.js

@@ -0,0 +1,5 @@
+import { createThreadInputSchema, parseWithSchema } from './schemas.js';
+export async function createThread(deps, input, ctx) {
+    const parsed = parseWithSchema(createThreadInputSchema, input, 'create-thread request');
+    return deps.threads.createThread(ctx.ownerId, parsed);
+}

package/dist/threads/errors.d.ts

@@ -0,0 +1,38 @@
+/**
+ * Handler-level error classes for the threads/ family.
+ *
+ * The two error tiers kept deliberately separate:
+ *
+ *   - **Request-shape errors** ({@link InvalidThreadRequestError}).
+ *     Raised by the handlers themselves when input fails schema
+ *     validation — transport returns 400 Bad Request.
+ *
+ *   - **Store errors** — re-exported from `@ggui-ai/mcp-server-core`
+ *     and surfaced verbatim by the handlers. Transport maps them to
+ *     HTTP status codes (`ThreadNotFoundError` → 404,
+ *     `InvalidThreadActionError` → 400,
+ *     `ThreadActionInvalidStateError` → 409).
+ *
+ * Handlers MUST NOT invent new semantic error classes. Every new
+ * failure case either maps back to one of the three store errors or
+ * is a request-shape error. Anything else implies the store boundary
+ * is leaking concerns it shouldn't own — fix there, not here.
+ */
+export { InvalidThreadActionError, ThreadActionInvalidStateError, ThreadNotFoundError, } from '@ggui-ai/mcp-server-core';
+/**
+ * Raised when a thread handler receives malformed input — unknown
+ * fields are fine (the schemas use `.strict()` only where ambiguity
+ * would be dangerous; otherwise we pass extras through for forward-
+ * compatibility), but missing/wrong-typed required fields fail here.
+ *
+ * `issues` is a machine-readable snapshot of the zod error's
+ * `issues[]`. Transports that want to return structured 400s use it;
+ * transports that return a flat `{ error: string }` just read
+ * `message`.
+ */
+export declare class InvalidThreadRequestError extends Error {
+    readonly code = "INVALID_THREAD_REQUEST";
+    readonly issues: readonly unknown[];
+    constructor(message: string, issues?: readonly unknown[]);
+}
+//# sourceMappingURL=errors.d.ts.map

package/dist/threads/errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../../src/threads/errors.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AACH,OAAO,EACL,wBAAwB,EACxB,6BAA6B,EAC7B,mBAAmB,GACpB,MAAM,0BAA0B,CAAC;AAElC;;;;;;;;;;GAUG;AACH,qBAAa,yBAA0B,SAAQ,KAAK;IAClD,QAAQ,CAAC,IAAI,4BAA4B;IACzC,QAAQ,CAAC,MAAM,EAAE,SAAS,OAAO,EAAE,CAAC;gBAExB,OAAO,EAAE,MAAM,EAAE,MAAM,GAAE,SAAS,OAAO,EAAO;CAK7D"}

package/dist/threads/errors.js

@@ -0,0 +1,41 @@
+/**
+ * Handler-level error classes for the threads/ family.
+ *
+ * The two error tiers kept deliberately separate:
+ *
+ *   - **Request-shape errors** ({@link InvalidThreadRequestError}).
+ *     Raised by the handlers themselves when input fails schema
+ *     validation — transport returns 400 Bad Request.
+ *
+ *   - **Store errors** — re-exported from `@ggui-ai/mcp-server-core`
+ *     and surfaced verbatim by the handlers. Transport maps them to
+ *     HTTP status codes (`ThreadNotFoundError` → 404,
+ *     `InvalidThreadActionError` → 400,
+ *     `ThreadActionInvalidStateError` → 409).
+ *
+ * Handlers MUST NOT invent new semantic error classes. Every new
+ * failure case either maps back to one of the three store errors or
+ * is a request-shape error. Anything else implies the store boundary
+ * is leaking concerns it shouldn't own — fix there, not here.
+ */
+export { InvalidThreadActionError, ThreadActionInvalidStateError, ThreadNotFoundError, } from '@ggui-ai/mcp-server-core';
+/**
+ * Raised when a thread handler receives malformed input — unknown
+ * fields are fine (the schemas use `.strict()` only where ambiguity
+ * would be dangerous; otherwise we pass extras through for forward-
+ * compatibility), but missing/wrong-typed required fields fail here.
+ *
+ * `issues` is a machine-readable snapshot of the zod error's
+ * `issues[]`. Transports that want to return structured 400s use it;
+ * transports that return a flat `{ error: string }` just read
+ * `message`.
+ */
+export class InvalidThreadRequestError extends Error {
+    code = 'INVALID_THREAD_REQUEST';
+    issues;
+    constructor(message, issues = []) {
+        super(message);
+        this.name = 'InvalidThreadRequestError';
+        this.issues = issues;
+    }
+}

package/dist/threads/get-thread.d.ts

@@ -0,0 +1,23 @@
+/**
+ * `getThread` — fetch a single thread by id, owner-scoped.
+ *
+ * Thin over {@link ThreadStore.getThread}. The store already partitions
+ * by ownerId (wrong-owner → null, same surface as missing). This
+ * handler promotes `null` to a typed {@link ThreadNotFoundError} so
+ * transports have exactly one "thread not found" mapping to 404 —
+ * no optional-return logic branches at the HTTP layer.
+ *
+ * Failure modes:
+ *   - {@link ThreadNotFoundError} — thread missing or wrong owner.
+ */
+import type { ThreadStore } from '@ggui-ai/mcp-server-core';
+import type { Thread } from '@ggui-ai/protocol';
+import type { ThreadHandlerContext } from './context.js';
+export interface GetThreadDeps {
+    readonly threads: ThreadStore;
+}
+export interface GetThreadInput {
+    readonly threadId: string;
+}
+export declare function getThread(deps: GetThreadDeps, input: GetThreadInput, ctx: ThreadHandlerContext): Promise<Thread>;
+//# sourceMappingURL=get-thread.d.ts.map

package/dist/threads/get-thread.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"get-thread.d.ts","sourceRoot":"","sources":["../../src/threads/get-thread.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AACH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,0BAA0B,CAAC;AAC5D,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,mBAAmB,CAAC;AAChD,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,cAAc,CAAC;AAGzD,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,OAAO,EAAE,WAAW,CAAC;CAC/B;AAED,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;CAC3B;AAED,wBAAsB,SAAS,CAC7B,IAAI,EAAE,aAAa,EACnB,KAAK,EAAE,cAAc,EACrB,GAAG,EAAE,oBAAoB,GACxB,OAAO,CAAC,MAAM,CAAC,CAIjB"}

package/dist/threads/get-thread.js

@@ -0,0 +1,7 @@
+import { ThreadNotFoundError } from './errors.js';
+export async function getThread(deps, input, ctx) {
+    const thread = await deps.threads.getThread(ctx.ownerId, input.threadId);
+    if (!thread)
+        throw new ThreadNotFoundError(input.threadId);
+    return thread;
+}

package/dist/threads/index.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Persistent-chat handler family (`@ggui-ai/mcp-server-handlers/threads`).
+ *
+ * Thin functional layer over {@link ThreadStore}. Every handler:
+ *   - takes `(deps, input, ctx)` where `deps.threads` is a store impl.
+ *   - parses request shape and throws
+ *     {@link InvalidThreadRequestError} on failure.
+ *   - delegates the load-bearing work to the store, which enforces
+ *     ownership, idempotency, sequencing, and state-machine rules.
+ *   - surfaces the store's typed errors ({@link ThreadNotFoundError},
+ *     {@link InvalidThreadActionError},
+ *     {@link ThreadActionInvalidStateError}) without re-wrapping.
+ *
+ * Pure functions, no transport coupling. HTTP routing (Step 4) and SSE
+ * (Step 5) mount these directly; non-HTTP transports (e.g. a future
+ * MCP resource) can reuse them identically.
+ */
+export { createThread } from './create-thread.js';
+export type { CreateThreadDeps } from './create-thread.js';
+export { getThread } from './get-thread.js';
+export type { GetThreadDeps, GetThreadInput } from './get-thread.js';
+export { listThreads } from './list-threads.js';
+export type { ListThreadsDeps } from './list-threads.js';
+export { appendMessage } from './append-message.js';
+export type { AppendMessageDeps } from './append-message.js';
+export { listMessages } from './list-messages.js';
+export type { ListMessagesDeps, ListMessagesInput, } from './list-messages.js';
+export { applyThreadAction } from './apply-thread-action.js';
+export type { ApplyThreadActionDeps, ApplyThreadActionInput, } from './apply-thread-action.js';
+export { observeMessages } from './observe-messages.js';
+export type { ObserveMessagesDeps, ObserveMessagesInput, } from './observe-messages.js';
+export type { ThreadHandlerContext } from './context.js';
+export { InvalidThreadActionError, InvalidThreadRequestError, ThreadActionInvalidStateError, ThreadNotFoundError, } from './errors.js';
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/threads/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAEH,OAAO,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAClD,YAAY,EAAE,gBAAgB,EAAE,MAAM,oBAAoB,CAAC;AAE3D,OAAO,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC;AAC5C,YAAY,EAAE,aAAa,EAAE,cAAc,EAAE,MAAM,iBAAiB,CAAC;AAErE,OAAO,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAChD,YAAY,EAAE,eAAe,EAAE,MAAM,mBAAmB,CAAC;AAEzD,OAAO,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AACpD,YAAY,EAAE,iBAAiB,EAAE,MAAM,qBAAqB,CAAC;AAE7D,OAAO,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAClD,YAAY,EACV,gBAAgB,EAChB,iBAAiB,GAClB,MAAM,oBAAoB,CAAC;AAE5B,OAAO,EAAE,iBAAiB,EAAE,MAAM,0BAA0B,CAAC;AAC7D,YAAY,EACV,qBAAqB,EACrB,sBAAsB,GACvB,MAAM,0BAA0B,CAAC;AAElC,OAAO,EAAE,eAAe,EAAE,MAAM,uBAAuB,CAAC;AACxD,YAAY,EACV,mBAAmB,EACnB,oBAAoB,GACrB,MAAM,uBAAuB,CAAC;AAE/B,YAAY,EAAE,oBAAoB,EAAE,MAAM,cAAc,CAAC;AACzD,OAAO,EACL,wBAAwB,EACxB,yBAAyB,EACzB,6BAA6B,EAC7B,mBAAmB,GACpB,MAAM,aAAa,CAAC"}

package/dist/threads/index.js

@@ -0,0 +1,25 @@
+/**
+ * Persistent-chat handler family (`@ggui-ai/mcp-server-handlers/threads`).
+ *
+ * Thin functional layer over {@link ThreadStore}. Every handler:
+ *   - takes `(deps, input, ctx)` where `deps.threads` is a store impl.
+ *   - parses request shape and throws
+ *     {@link InvalidThreadRequestError} on failure.
+ *   - delegates the load-bearing work to the store, which enforces
+ *     ownership, idempotency, sequencing, and state-machine rules.
+ *   - surfaces the store's typed errors ({@link ThreadNotFoundError},
+ *     {@link InvalidThreadActionError},
+ *     {@link ThreadActionInvalidStateError}) without re-wrapping.
+ *
+ * Pure functions, no transport coupling. HTTP routing (Step 4) and SSE
+ * (Step 5) mount these directly; non-HTTP transports (e.g. a future
+ * MCP resource) can reuse them identically.
+ */
+export { createThread } from './create-thread.js';
+export { getThread } from './get-thread.js';
+export { listThreads } from './list-threads.js';
+export { appendMessage } from './append-message.js';
+export { listMessages } from './list-messages.js';
+export { applyThreadAction } from './apply-thread-action.js';
+export { observeMessages } from './observe-messages.js';
+export { InvalidThreadActionError, InvalidThreadRequestError, ThreadActionInvalidStateError, ThreadNotFoundError, } from './errors.js';

package/dist/threads/list-messages.d.ts

@@ -0,0 +1,25 @@
+/**
+ * `listMessages` — read a thread's messages in seq-ASC order.
+ *
+ * Thin over {@link ThreadStore.listMessages}. The store enforces
+ * ordering, ownership, and fromSeq/cursor paging. This handler splits
+ * the `threadId` path parameter from the query-string-shaped options
+ * so transports (Step 4) can wire them directly from URL segments +
+ * query params without bespoke parsing.
+ *
+ * Failure modes:
+ *   - {@link InvalidThreadRequestError} — malformed options.
+ *   - {@link ThreadNotFoundError} — thread missing or wrong owner.
+ */
+import type { ThreadStore } from '@ggui-ai/mcp-server-core';
+import type { ListMessagesResult } from '@ggui-ai/protocol';
+import type { ThreadHandlerContext } from './context.js';
+export interface ListMessagesDeps {
+    readonly threads: ThreadStore;
+}
+export interface ListMessagesInput {
+    readonly threadId: string;
+    readonly options?: unknown;
+}
+export declare function listMessages(deps: ListMessagesDeps, input: ListMessagesInput, ctx: ThreadHandlerContext): Promise<ListMessagesResult>;
+//# sourceMappingURL=list-messages.d.ts.map

package/dist/threads/list-messages.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"list-messages.d.ts","sourceRoot":"","sources":["../../src/threads/list-messages.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AACH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,0BAA0B,CAAC;AAC5D,OAAO,KAAK,EAEV,kBAAkB,EACnB,MAAM,mBAAmB,CAAC;AAC3B,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,cAAc,CAAC;AAGzD,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,OAAO,EAAE,WAAW,CAAC;CAC/B;AAED,MAAM,WAAW,iBAAiB;IAChC,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,OAAO,CAAC,EAAE,OAAO,CAAC;CAC5B;AAED,wBAAsB,YAAY,CAChC,IAAI,EAAE,gBAAgB,EACtB,KAAK,EAAE,iBAAiB,EACxB,GAAG,EAAE,oBAAoB,GACxB,OAAO,CAAC,kBAAkB,CAAC,CAO7B"}

package/dist/threads/list-messages.js

@@ -0,0 +1,5 @@
+import { listMessagesOptionsSchema, parseWithSchema } from './schemas.js';
+export async function listMessages(deps, input, ctx) {
+    const options = parseWithSchema(listMessagesOptionsSchema, input.options ?? {}, 'list-messages options');
+    return deps.threads.listMessages(ctx.ownerId, input.threadId, options);
+}

package/dist/threads/list-threads.d.ts

@@ -0,0 +1,18 @@
+/**
+ * `listThreads` — enumerate the caller's threads, owner-scoped.
+ *
+ * Thin over {@link ThreadStore.listThreads}. The store enforces
+ * partitioning by ownerId, ordering (most-recent-first), and
+ * limit/cursor semantics. This handler only validates request shape.
+ *
+ * Failure modes:
+ *   - {@link InvalidThreadRequestError} — malformed filter.
+ */
+import type { ThreadStore } from '@ggui-ai/mcp-server-core';
+import type { ListThreadsResult } from '@ggui-ai/protocol';
+import type { ThreadHandlerContext } from './context.js';
+export interface ListThreadsDeps {
+    readonly threads: ThreadStore;
+}
+export declare function listThreads(deps: ListThreadsDeps, input: unknown, ctx: ThreadHandlerContext): Promise<ListThreadsResult>;
+//# sourceMappingURL=list-threads.d.ts.map

package/dist/threads/list-threads.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"list-threads.d.ts","sourceRoot":"","sources":["../../src/threads/list-threads.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AACH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,0BAA0B,CAAC;AAC5D,OAAO,KAAK,EAEV,iBAAiB,EAClB,MAAM,mBAAmB,CAAC;AAC3B,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,cAAc,CAAC;AAGzD,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,OAAO,EAAE,WAAW,CAAC;CAC/B;AAED,wBAAsB,WAAW,CAC/B,IAAI,EAAE,eAAe,EACrB,KAAK,EAAE,OAAO,EACd,GAAG,EAAE,oBAAoB,GACxB,OAAO,CAAC,iBAAiB,CAAC,CAO5B"}

package/dist/threads/list-threads.js

@@ -0,0 +1,5 @@
+import { listThreadsFilterSchema, parseWithSchema } from './schemas.js';
+export async function listThreads(deps, input, ctx) {
+    const filter = parseWithSchema(listThreadsFilterSchema, input ?? {}, 'list-threads filter');
+    return deps.threads.listThreads(ctx.ownerId, filter);
+}

package/dist/threads/observe-messages.d.ts

@@ -0,0 +1,31 @@
+/**
+ * `observeMessages` — subscribe to appended messages on a thread.
+ *
+ * Thin over {@link ThreadStore.observeMessages}. The store owns
+ * snapshot+tail semantics, ordering, fromSeq skip, and
+ * throw-on-wrong-owner (from the iterator's first pull). This
+ * handler only parses options + forwards.
+ *
+ * Returns an `AsyncIterable<ThreadMessage>` — the SSE transport
+ * (Step 5) iterates it and serializes each message as a
+ * {@link ThreadStreamEvent}. Non-SSE consumers (tests, future
+ * WebSocket transports) iterate it the same way.
+ *
+ * Failure modes:
+ *   - {@link InvalidThreadRequestError} — malformed options.
+ *   - {@link ThreadNotFoundError} — thrown from the iterator's
+ *     first `next()`, NOT from this function synchronously. Callers
+ *     MUST handle the rejection on the first pull.
+ */
+import type { ThreadStore } from '@ggui-ai/mcp-server-core';
+import type { ThreadMessage } from '@ggui-ai/protocol';
+import type { ThreadHandlerContext } from './context.js';
+export interface ObserveMessagesDeps {
+    readonly threads: ThreadStore;
+}
+export interface ObserveMessagesInput {
+    readonly threadId: string;
+    readonly options?: unknown;
+}
+export declare function observeMessages(deps: ObserveMessagesDeps, input: ObserveMessagesInput, ctx: ThreadHandlerContext): AsyncIterable<ThreadMessage>;
+//# sourceMappingURL=observe-messages.d.ts.map

package/dist/threads/observe-messages.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"observe-messages.d.ts","sourceRoot":"","sources":["../../src/threads/observe-messages.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AACH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,0BAA0B,CAAC;AAC5D,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,mBAAmB,CAAC;AAEvD,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,cAAc,CAAC;AAMzD,MAAM,WAAW,mBAAmB;IAClC,QAAQ,CAAC,OAAO,EAAE,WAAW,CAAC;CAC/B;AAED,MAAM,WAAW,oBAAoB;IACnC,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,OAAO,CAAC,EAAE,OAAO,CAAC;CAC5B;AAED,wBAAgB,eAAe,CAC7B,IAAI,EAAE,mBAAmB,EACzB,KAAK,EAAE,oBAAoB,EAC3B,GAAG,EAAE,oBAAoB,GACxB,aAAa,CAAC,aAAa,CAAC,CAO9B"}

package/dist/threads/observe-messages.js

@@ -0,0 +1,5 @@
+import { observeMessagesOptionsSchema, parseWithSchema, } from './schemas.js';
+export function observeMessages(deps, input, ctx) {
+    const options = parseWithSchema(observeMessagesOptionsSchema, input.options ?? {}, 'observe-messages options');
+    return deps.threads.observeMessages(ctx.ownerId, input.threadId, options);
+}

package/dist/threads/schemas.d.ts

@@ -0,0 +1,73 @@
+/**
+ * Shared zod schemas for thread-handler request parsing.
+ *
+ * Each schema mirrors exactly one request shape from
+ * `@ggui-ai/protocol/types/thread.ts` — kept in lockstep by tests, not
+ * by shared code, because the protocol types are the source of truth.
+ * A schema that drifts from the protocol shape is a bug in THIS file,
+ * not a need for a new protocol type.
+ *
+ * Handlers import `parseWithSchema` to convert zod errors into
+ * {@link InvalidThreadRequestError} uniformly, so transports see one
+ * error class for every shape-level rejection.
+ */
+import { z, type ZodType } from 'zod';
+export declare const createThreadInputSchema: z.ZodObject<{
+    appId: z.ZodString;
+    firstMessageHint: z.ZodOptional<z.ZodString>;
+    metadata: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+}, z.core.$strict>;
+export declare const appendThreadMessageInputSchema: z.ZodObject<{
+    threadId: z.ZodString;
+    key: z.ZodString;
+    authorRole: z.ZodEnum<{
+        agent: "agent";
+        user: "user";
+        system: "system";
+    }>;
+    kind: z.ZodEnum<{
+        text: "text";
+        card: "card";
+        event: "event";
+    }>;
+    blocks: z.ZodArray<z.ZodUnknown>;
+    cardSnapshot: z.ZodOptional<z.ZodUnknown>;
+    textPreview: z.ZodString;
+    aiContext: z.ZodOptional<z.ZodUnknown>;
+}, z.core.$strict>;
+export declare const listMessagesOptionsSchema: z.ZodObject<{
+    fromSeq: z.ZodOptional<z.ZodNumber>;
+    limit: z.ZodOptional<z.ZodNumber>;
+    cursor: z.ZodOptional<z.ZodString>;
+}, z.core.$strict>;
+export declare const listThreadsFilterSchema: z.ZodObject<{
+    status: z.ZodOptional<z.ZodEnum<{
+        active: "active";
+        archived: "archived";
+        pending_delete: "pending_delete";
+    }>>;
+    appId: z.ZodOptional<z.ZodString>;
+    limit: z.ZodOptional<z.ZodNumber>;
+    cursor: z.ZodOptional<z.ZodString>;
+}, z.core.$strict>;
+/**
+ * A ThreadStateAction string. Derived from the canonical array on the
+ * protocol so any future action addition surfaces here automatically —
+ * no duplicate literal list.
+ */
+export declare const threadStateActionSchema: z.ZodCustom<"pin" | "unpin" | "mute" | "unmute" | "archive" | "unarchive" | "mark_read" | "request_delete" | "restore", "pin" | "unpin" | "mute" | "unmute" | "archive" | "unarchive" | "mark_read" | "request_delete" | "restore">;
+export declare const applyThreadActionInputSchema: z.ZodObject<{
+    action: z.ZodCustom<"pin" | "unpin" | "mute" | "unmute" | "archive" | "unarchive" | "mark_read" | "request_delete" | "restore", "pin" | "unpin" | "mute" | "unmute" | "archive" | "unarchive" | "mark_read" | "request_delete" | "restore">;
+}, z.core.$strict>;
+export declare const observeMessagesOptionsSchema: z.ZodObject<{
+    fromSeq: z.ZodOptional<z.ZodNumber>;
+    tail: z.ZodOptional<z.ZodBoolean>;
+}, z.core.$strict>;
+/**
+ * Parse `input` against `schema`; throw {@link InvalidThreadRequestError}
+ * on failure (carrying zod's `issues` verbatim for transports that want
+ * to surface them). Success returns the parsed value with full type
+ * inference — the caller doesn't need its own cast.
+ */
+export declare function parseWithSchema<T>(schema: ZodType<T>, input: unknown, contextLabel: string): T;
+//# sourceMappingURL=schemas.d.ts.map

package/dist/threads/schemas.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"schemas.d.ts","sourceRoot":"","sources":["../../src/threads/schemas.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AACH,OAAO,EAAE,CAAC,EAAE,KAAK,OAAO,EAAE,MAAM,KAAK,CAAC;AAYtC,eAAO,MAAM,uBAAuB;;;;kBAMzB,CAAC;AAEZ,eAAO,MAAM,8BAA8B;;;;;;;;;;;;;;;;;kBAWhC,CAAC;AAEZ,eAAO,MAAM,yBAAyB;;;;kBAM3B,CAAC;AAEZ,eAAO,MAAM,uBAAuB;;;;;;;;;kBAOzB,CAAC;AAEZ;;;;GAIG;AACH,eAAO,MAAM,uBAAuB,qOAOnC,CAAC;AAEF,eAAO,MAAM,4BAA4B;;kBAI9B,CAAC;AAEZ,eAAO,MAAM,4BAA4B;;;kBAK9B,CAAC;AAEZ;;;;;GAKG;AACH,wBAAgB,eAAe,CAAC,CAAC,EAC/B,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC,EAClB,KAAK,EAAE,OAAO,EACd,YAAY,EAAE,MAAM,GACnB,CAAC,CASH"}

package/dist/threads/schemas.js

@@ -0,0 +1,86 @@
+/**
+ * Shared zod schemas for thread-handler request parsing.
+ *
+ * Each schema mirrors exactly one request shape from
+ * `@ggui-ai/protocol/types/thread.ts` — kept in lockstep by tests, not
+ * by shared code, because the protocol types are the source of truth.
+ * A schema that drifts from the protocol shape is a bug in THIS file,
+ * not a need for a new protocol type.
+ *
+ * Handlers import `parseWithSchema` to convert zod errors into
+ * {@link InvalidThreadRequestError} uniformly, so transports see one
+ * error class for every shape-level rejection.
+ */
+import { z } from 'zod';
+import { isThreadStateAction, THREAD_STATE_ACTIONS, } from '@ggui-ai/protocol';
+import { InvalidThreadRequestError } from './errors.js';
+const threadStatusSchema = z.enum(['active', 'archived', 'pending_delete']);
+const authorRoleSchema = z.enum(['user', 'agent', 'system']);
+const messageKindSchema = z.enum(['text', 'card', 'event']);
+export const createThreadInputSchema = z
+    .object({
+    appId: z.string().min(1, 'appId is required'),
+    firstMessageHint: z.string().optional(),
+    metadata: z.record(z.string(), z.unknown()).optional(),
+})
+    .strict();
+export const appendThreadMessageInputSchema = z
+    .object({
+    threadId: z.string().min(1, 'threadId is required'),
+    key: z.string().min(1, 'key is required'),
+    authorRole: authorRoleSchema,
+    kind: messageKindSchema,
+    blocks: z.array(z.unknown()),
+    cardSnapshot: z.unknown().optional(),
+    textPreview: z.string(),
+    aiContext: z.unknown().optional(),
+})
+    .strict();
+export const listMessagesOptionsSchema = z
+    .object({
+    fromSeq: z.number().int().positive().optional(),
+    limit: z.number().int().positive().max(500).optional(),
+    cursor: z.string().optional(),
+})
+    .strict();
+export const listThreadsFilterSchema = z
+    .object({
+    status: threadStatusSchema.optional(),
+    appId: z.string().min(1).optional(),
+    limit: z.number().int().positive().max(500).optional(),
+    cursor: z.string().optional(),
+})
+    .strict();
+/**
+ * A ThreadStateAction string. Derived from the canonical array on the
+ * protocol so any future action addition surfaces here automatically —
+ * no duplicate literal list.
+ */
+export const threadStateActionSchema = z.custom((value) => isThreadStateAction(value), {
+    message: `must be one of: ${THREAD_STATE_ACTIONS.join(', ')}`,
+});
+export const applyThreadActionInputSchema = z
+    .object({
+    action: threadStateActionSchema,
+})
+    .strict();
+export const observeMessagesOptionsSchema = z
+    .object({
+    fromSeq: z.number().int().positive().optional(),
+    tail: z.boolean().optional(),
+})
+    .strict();
+/**
+ * Parse `input` against `schema`; throw {@link InvalidThreadRequestError}
+ * on failure (carrying zod's `issues` verbatim for transports that want
+ * to surface them). Success returns the parsed value with full type
+ * inference — the caller doesn't need its own cast.
+ */
+export function parseWithSchema(schema, input, contextLabel) {
+    const result = schema.safeParse(input);
+    if (result.success)
+        return result.data;
+    throw new InvalidThreadRequestError(`Invalid ${contextLabel}: ${result.error.issues
+        .map((i) => `${i.path.join('.') || '(root)'} — ${i.message}`)
+        .join('; ')}`, result.error.issues);
+}