@skein-js/core 0.2.1 → 0.4.0

package/dist/index.d.ts

@@ -1,8 +1,11 @@
-import { Run, Config, Metadata, Assistant, StreamMode, Thread, ThreadStatus, DefaultValues, Interrupt, Item, SearchItem } from '@langchain/langgraph-sdk';
-export { Assistant, AssistantBase, AssistantGraph, Checkpoint, Config, DefaultValues, GraphSchema, Interrupt, Item, Metadata, Run, SearchItem, StreamMode, Thread, ThreadState, ThreadStatus, ThreadTask } from '@langchain/langgraph-sdk';
+import { Run as Run$1, Config, Metadata, Assistant, StreamMode, Thread, DefaultValues, ThreadStatus, Interrupt, Item, SearchItem } from '@langchain/langgraph-sdk';
+export { Assistant, AssistantBase, AssistantGraph, Checkpoint, Config, DefaultValues, GraphSchema, Interrupt, Item, Metadata, SearchItem, StreamMode, Thread, ThreadState, ThreadStatus, ThreadTask } from '@langchain/langgraph-sdk';
 
-type RunStatus = Run["status"];
-type MultitaskStrategy = NonNullable<Run["multitask_strategy"]>;
+type RunStatus = Run$1["status"] | "cancelled";
+type Run = Omit<Run$1, "status"> & {
+    status: RunStatus;
+};
+type MultitaskStrategy = NonNullable<Run$1["multitask_strategy"]>;
 
 /** Fields accepted when registering an assistant (from a langgraph.json graph or the API). */
 interface AssistantCreate {
@@ -37,13 +40,42 @@ interface ThreadUpdate {
     /** Pending human-in-the-loop interrupts, mirrored from the graph state onto the thread row. */
     interrupts?: Record<string, Interrupt[]>;
 }
+/** Filter + pagination for `POST /threads/search`. Omitted fields don't constrain the result. */
+interface ThreadSearchQuery {
+    /** Match threads whose metadata contains every one of these key/value pairs (subset match). */
+    metadata?: Metadata;
+    /** Match threads whose mirrored graph values contain every one of these key/value pairs. */
+    values?: DefaultValues;
+    /** Restrict to threads in this status. */
+    status?: ThreadStatus;
+    /** Restrict to these thread ids. */
+    ids?: string[];
+    limit?: number;
+    offset?: number;
+    /** Sort key; defaults to `created_at`. */
+    sortBy?: "thread_id" | "status" | "created_at" | "updated_at";
+    /** Sort direction; defaults to `desc`. */
+    sortOrder?: "asc" | "desc";
+}
 interface ThreadRepo {
     list(): Promise<Thread[]>;
+    /** Filtered + paginated listing backing `POST /threads/search`. */
+    search(query: ThreadSearchQuery): Promise<Thread[]>;
     get(threadId: string): Promise<Thread | null>;
     create(input?: ThreadCreate): Promise<Thread>;
     update(threadId: string, patch: ThreadUpdate): Promise<Thread>;
+    /** Duplicate a thread's row (new id, fresh timestamps); checkpoint history is copied at the service layer. */
+    copy(threadId: string): Promise<Thread>;
     delete(threadId: string): Promise<void>;
 }
+/**
+ * True if `subject` contains `filter`, mirroring Postgres' JSONB `@>` operator so the memory driver,
+ * the conformance suite, and the Postgres driver all agree on metadata/values matching. Containment is
+ * recursive: an object matches on a *subset* of its keys (nested objects included), an array matches as
+ * a set (every filter element is contained in some subject element), and scalars match by equality. An
+ * empty (or absent) filter matches everything.
+ */
+declare function isMetadataSubset(subject: unknown, filter: unknown): boolean;
 /**
  * The execution payload of a run — everything the run engine needs to (re)start a graph. Stored
  * *opaquely* alongside the run (it is NOT part of the wire {@link Run}), so a background run picked
@@ -109,12 +141,32 @@ interface StoreSearchQuery {
     limit?: number;
     offset?: number;
 }
+/**
+ * Expiry policy for long-term store items (from `langgraph.json` `store.ttl`). All durations are in
+ * minutes. A driver applies `defaultTtl` when a `put` gives no explicit `ttl`, refreshes an item's
+ * expiry on read when `refreshOnRead` is set, and a background sweeper (interval `sweepIntervalMinutes`)
+ * deletes expired rows via {@link StoreRepo.sweepExpired}.
+ */
+interface StoreTtlConfig {
+    /** Default item lifetime in minutes when `put` doesn't pass its own `ttl`. */
+    defaultTtl?: number;
+    /** Extend an item's expiry when it is read. Defaults to true. */
+    refreshOnRead?: boolean;
+    /** Sweeper cadence in minutes. Defaults to 60. */
+    sweepIntervalMinutes?: number;
+}
+/** Per-`put` options. `ttl` (minutes) overrides the configured `defaultTtl` for this item. */
+interface StorePutOptions {
+    ttl?: number;
+}
 interface StoreRepo {
     get(namespace: string[], key: string): Promise<Item | null>;
-    put(namespace: string[], key: string, value: Record<string, unknown>): Promise<Item>;
+    put(namespace: string[], key: string, value: Record<string, unknown>, options?: StorePutOptions): Promise<Item>;
     delete(namespace: string[], key: string): Promise<void>;
     search(query: StoreSearchQuery): Promise<SearchItem[]>;
     listNamespaces(prefix?: string[]): Promise<string[][]>;
+    /** Delete every expired item; returns how many were removed. No-op when TTL is unconfigured. */
+    sweepExpired(): Promise<number>;
 }
 /** The single persistence seam for Agent Protocol resources. One implementation per driver. */
 interface SkeinStore {
@@ -123,6 +175,24 @@ interface SkeinStore {
     runs: RunRepo;
     store: StoreRepo;
 }
+/**
+ * A driver-agnostic, JSON-serializable snapshot of every resource row — the unit of bulk
+ * transfer for persistence and migration tooling (e.g. `skein dev`'s cross-restart snapshot, and
+ * importing an existing LangGraph in-memory dev state). Each entry is an `[id, row]` tuple: the id
+ * is the entity's own id, except `items` (keyed by `JSON.stringify([namespace, key])`) and
+ * `runKwargs` (keyed by `run_id`, since {@link RunKwargs} has no id of its own).
+ *
+ * A driver MAY expose `restore(snapshot)` to bulk-load one of these verbatim — ids and timestamps
+ * preserved — which is what makes an import lossless. It is intentionally not part of
+ * {@link SkeinStore}: only migration tooling needs it, and consumers feature-detect it.
+ */
+interface SkeinStoreSnapshot {
+    assistants: [string, Assistant][];
+    threads: [string, Thread][];
+    runs: [string, Run][];
+    runKwargs: [string, RunKwargs][];
+    items: [string, Item][];
+}
 
 /**
  * A normalized stream frame produced during a run. Adapters map these onto SSE
@@ -281,4 +351,4 @@ interface AuthEngine {
     matchesFilters(metadata: Record<string, unknown> | undefined, filters?: AuthFilters): boolean;
 }
 
-export { type AssistantCreate, type AssistantRepo, type AuthAction, type AuthContext, type AuthEngine, type AuthFilterValue, type AuthFilters, type AuthResource, type AuthUser, type MultitaskStrategy, type QueuedRun, type RunConsumer, type RunConsumerOptions, type RunCreate, type RunEventBus, type RunFrame, type RunKwargs, type RunProcessor, type RunQueue, type RunRepo, type RunStatus, SkeinHttpError, type SkeinHttpErrorOptions, type SkeinStore, type StoreRepo, type StoreSearchQuery, TERMINAL_RUN_STATUSES, type ThreadCreate, type ThreadRepo, type ThreadUpdate, isSkeinHttpError, isTerminalRunStatus, serializeWireJson };
+export { type AssistantCreate, type AssistantRepo, type AuthAction, type AuthContext, type AuthEngine, type AuthFilterValue, type AuthFilters, type AuthResource, type AuthUser, type MultitaskStrategy, type QueuedRun, type Run, type RunConsumer, type RunConsumerOptions, type RunCreate, type RunEventBus, type RunFrame, type RunKwargs, type RunProcessor, type RunQueue, type RunRepo, type RunStatus, SkeinHttpError, type SkeinHttpErrorOptions, type SkeinStore, type SkeinStoreSnapshot, type StorePutOptions, type StoreRepo, type StoreSearchQuery, type StoreTtlConfig, TERMINAL_RUN_STATUSES, type ThreadCreate, type ThreadRepo, type ThreadSearchQuery, type ThreadUpdate, isMetadataSubset, isSkeinHttpError, isTerminalRunStatus, serializeWireJson };

package/dist/index.js

@@ -1,9 +1,26 @@
 // src/store/skein-store.ts
+function isMetadataSubset(subject, filter) {
+  if (filter === void 0 || filter === null) return true;
+  return jsonbContains(subject, filter);
+}
+function jsonbContains(subject, filter) {
+  if (filter === null || typeof filter !== "object") return subject === filter;
+  if (Array.isArray(filter)) {
+    if (!Array.isArray(subject)) return false;
+    return filter.every((wanted) => subject.some((candidate) => jsonbContains(candidate, wanted)));
+  }
+  const entries = Object.entries(filter);
+  if (entries.length === 0) return true;
+  if (subject === null || typeof subject !== "object" || Array.isArray(subject)) return false;
+  const row = subject;
+  return entries.every(([key, value]) => key in row && jsonbContains(row[key], value));
+}
 var TERMINAL_RUN_STATUSES = [
   "success",
   "error",
   "timeout",
-  "interrupted"
+  "interrupted",
+  "cancelled"
 ];
 function isTerminalRunStatus(status) {
   return TERMINAL_RUN_STATUSES.includes(status);
@@ -66,6 +83,7 @@ function isSkeinHttpError(value) {
 export {
   SkeinHttpError,
   TERMINAL_RUN_STATUSES,
+  isMetadataSubset,
   isSkeinHttpError,
   isTerminalRunStatus,
   serializeWireJson

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@skein-js/core",
-  "version": "0.2.1",
+  "version": "0.4.0",
   "description": "Framework-agnostic Agent Protocol engine for LangGraph.js — the heart of skein-js.",
   "license": "Apache-2.0",
   "author": "Maina Wycliffe <wmmaina7@gmail.com>",