@skein-js/core 0.3.0 → 0.5.0

package/dist/index.d.ts

@@ -1,8 +1,71 @@
-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"]>;
+
+/**
+ * The authenticated caller, normalized to the shape LangGraph's `Auth` produces: a required
+ * `identity`, `display_name`, `is_authenticated`, and `permissions` scopes, plus open extra keys a
+ * handler may attach (e.g. `email`, `org_id`). Structurally identical to the SDK's internal
+ * `BaseUser`, so a graph written for LangGraph Platform reads the same `langgraph_auth_user`.
+ */
+interface AuthUser {
+    identity: string;
+    display_name: string;
+    is_authenticated: boolean;
+    permissions: string[];
+    [key: string]: unknown;
+}
+/** The result of authenticating a request: the caller plus their permission scopes. */
+interface AuthContext {
+    user: AuthUser;
+    scopes: string[];
+}
+/** A protocol resource an `@auth.on.*` handler can guard. Runs authorize through their thread. */
+type AuthResource = "threads" | "assistants" | "store";
+/** An action on a resource, mirroring LangGraph's `resource:action` event names. */
+type AuthAction = "create" | "read" | "update" | "delete" | "search" | "create_run" | "put" | "get" | "list_namespaces";
+/** A single metadata filter clause — an exact value or an `$eq`/`$contains` operator object. */
+type AuthFilterValue = string | {
+    $eq?: string;
+    $contains?: string | string[];
+};
+/**
+ * Ownership filters returned by an `@auth.on.*` handler. Keys are metadata fields; a returned filter
+ * both scopes reads (a resource is visible only if its metadata satisfies every clause) and stamps
+ * writes (the clause values are merged into new resources' metadata). Shape-compatible with
+ * `@langchain/langgraph-api`'s `isAuthMatching`.
+ */
+type AuthFilters = Record<string, AuthFilterValue>;
+/**
+ * The injectable auth engine — one per runtime, no module-global state (unlike langgraph-api's
+ * `registerAuth`). Absent from `ProtocolDeps` means no auth is configured and every request is
+ * allowed (the default, so `skein dev` stays frictionless).
+ */
+interface AuthEngine {
+    /** True when a `langgraph.json` `auth.path` was loaded; false disables the whole gate. */
+    readonly enabled: boolean;
+    /** When true, studio traffic must present real credentials like any other client. */
+    readonly studioAuthDisabled: boolean;
+    /** Run the user's authenticate handler over a request; throws 401 on rejection/missing identity. */
+    authenticate(request: Request): Promise<AuthContext | undefined>;
+    /** Consult the `@auth.on.*` handlers for a resource+action; throws 403 on deny, else returns filters. */
+    authorize(input: {
+        resource: AuthResource;
+        action: AuthAction;
+        value: unknown;
+        context: AuthContext | undefined;
+    }): Promise<{
+        filters?: AuthFilters;
+        value: unknown;
+    }>;
+    /** Whether a resource's metadata satisfies the ownership filters (`$eq`/`$contains` semantics). */
+    matchesFilters(metadata: Record<string, unknown> | undefined, filters?: AuthFilters): boolean;
+}
 
 /** Fields accepted when registering an assistant (from a langgraph.json graph or the API). */
 interface AssistantCreate {
@@ -37,13 +100,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
@@ -64,6 +156,18 @@ interface RunKwargs {
     stream_mode?: StreamMode | StreamMode[];
     interrupt_before?: string[] | "*";
     interrupt_after?: string[] | "*";
+    /**
+     * The authenticated caller, stamped by the server (never accepted from the client). Persisted
+     * opaquely with the run so a background/crash-recovered run on another instance reconstructs the
+     * principal via `getKwargs` and injects it into the graph's `configurable.langgraph_auth_user`.
+     */
+    auth_user?: AuthUser;
+    /**
+     * The caller's authenticated permission scopes (the `AuthContext.scopes`), stamped alongside
+     * {@link auth_user}. Injected as `configurable.langgraph_auth_permissions`, matching LangGraph
+     * (which sources permissions from the auth scopes, not from the user object's `permissions`).
+     */
+    auth_scopes?: string[];
 }
 interface RunCreate {
     thread_id: string;
@@ -109,12 +213,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 {
@@ -241,62 +365,4 @@ declare class SkeinHttpError extends Error {
 /** Narrow an unknown thrown value to a {@link SkeinHttpError}. */
 declare function isSkeinHttpError(value: unknown): value is SkeinHttpError;
 
-/**
- * The authenticated caller, normalized to the shape LangGraph produces: a required `identity`,
- * `permissions` scopes, and open extra keys a handler may attach (e.g. `email`, `org_id`).
- */
-interface AuthUser {
-    identity: string;
-    display_name: string;
-    is_authenticated: boolean;
-    permissions: string[];
-    [key: string]: unknown;
-}
-/** The result of authenticating a request: the caller plus their permission scopes. */
-interface AuthContext {
-    user: AuthUser;
-    scopes: string[];
-}
-/** A protocol resource an `@auth.on.*` handler can guard. Runs authorize through their thread. */
-type AuthResource = "threads" | "assistants" | "store";
-/** An action on a resource, mirroring LangGraph's `resource:action` event names. */
-type AuthAction = "create" | "read" | "update" | "delete" | "search" | "create_run" | "put" | "get" | "list_namespaces";
-/** A single metadata filter clause — an exact value or an `$eq`/`$contains` operator object. */
-type AuthFilterValue = string | {
-    $eq?: string;
-    $contains?: string | string[];
-};
-/**
- * Ownership filters returned by an `@auth.on.*` handler. Keys are metadata fields; a returned filter
- * both scopes reads (a resource is visible only if its metadata satisfies every clause) and stamps
- * writes (the clause values are merged into new resources' metadata). Shape-compatible with
- * `@langchain/langgraph-api`'s `isAuthMatching`.
- */
-type AuthFilters = Record<string, AuthFilterValue>;
-/**
- * The injectable auth engine — one per runtime, no module-global state (unlike langgraph-api's
- * `registerAuth`). Absent from `ProtocolDeps` means no auth is configured and every request is
- * allowed (the default, so `skein dev` stays frictionless).
- */
-interface AuthEngine {
-    /** True when a `langgraph.json` `auth.path` was loaded; false disables the whole gate. */
-    readonly enabled: boolean;
-    /** When true, studio traffic must present real credentials like any other client. */
-    readonly studioAuthDisabled: boolean;
-    /** Run the user's authenticate handler over a request; throws 401 on rejection/missing identity. */
-    authenticate(request: Request): Promise<AuthContext | undefined>;
-    /** Consult the `@auth.on.*` handlers for a resource+action; throws 403 on deny, else returns filters. */
-    authorize(input: {
-        resource: AuthResource;
-        action: AuthAction;
-        value: unknown;
-        context: AuthContext | undefined;
-    }): Promise<{
-        filters?: AuthFilters;
-        value: unknown;
-    }>;
-    /** Whether a resource's metadata satisfies the ownership filters (`$eq`/`$contains` semantics). */
-    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 SkeinStoreSnapshot, 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.3.0",
+  "version": "0.5.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>",