@skein-js/core 0.4.0 → 0.6.3

package/README.md

@@ -79,8 +79,8 @@ throw SkeinHttpError.notFound(`Thread "${id}" not found.`);
   `RunConsumerOptions`.
 - **`interface AuthEngine`** — `authenticate(request)` (→ `AuthContext`, throws 401) + `authorize({ resource, action, value, context })` (→ `{ filters?, value }`, throws 403) + `matchesFilters(...)`. Plus `AuthContext`, `AuthUser`, `AuthResource`, `AuthAction`, `AuthFilters`, `AuthFilterValue`.
 - **`class SkeinHttpError`** — `new SkeinHttpError(status, message, options?)` and the static helpers
-  `badRequest` (400) / `unauthorized` (401) / `forbidden` (403) / `notFound` (404) / `conflict` (409);
-  `isSkeinHttpError(value)` narrows it.
+  `badRequest` (400) / `unauthorized` (401) / `forbidden` (403) / `notFound` (404) / `conflict` (409) /
+  `unprocessable` (422); `isSkeinHttpError(value)` narrows it.
 - **`serializeWireJson(value): string`** — `JSON.stringify` replacement that flattens LangChain
   `BaseMessage`s to the wire shape the SDK / `useStream` / Agent Chat UI expect.
 

package/dist/index.d.ts

@@ -1,5 +1,5 @@
-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';
+import { Run as Run$1, Config, Metadata, Assistant, AssistantVersion, StreamMode, Thread, DefaultValues, ThreadStatus, Interrupt, Item, SearchItem } from '@langchain/langgraph-sdk';
+export { Assistant, AssistantBase, AssistantGraph, AssistantVersion, Checkpoint, Config, DefaultValues, GraphSchema, Interrupt, Item, Metadata, SearchItem, StreamMode, Thread, ThreadState, ThreadStatus, ThreadTask } from '@langchain/langgraph-sdk';
 
 type RunStatus = Run$1["status"] | "cancelled";
 type Run = Omit<Run$1, "status"> & {
@@ -7,6 +7,66 @@ type Run = Omit<Run$1, "status"> & {
 };
 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 {
     graph_id: string;
@@ -18,11 +78,67 @@ interface AssistantCreate {
     context?: unknown;
     metadata?: Metadata;
 }
+/**
+ * Partial update; omitted fields keep the current version's value. Every update mints a NEW
+ * immutable version (see {@link AssistantRepo.update}) — there is no in-place field mutation.
+ */
+interface AssistantUpdate {
+    graph_id?: string;
+    name?: string;
+    description?: string;
+    config?: Config;
+    context?: unknown;
+    metadata?: Metadata;
+}
+/** Filter + pagination for `POST /assistants/search`. Omitted fields don't constrain the result. */
+interface AssistantSearchQuery {
+    /** Restrict to assistants of this graph. */
+    graph_id?: string;
+    /** Restrict to assistants with this exact name. */
+    name?: string;
+    /** Match assistants whose metadata contains every one of these key/value pairs (subset match). */
+    metadata?: Metadata;
+    limit?: number;
+    offset?: number;
+    /** Sort key; defaults to `created_at`. */
+    sortBy?: "assistant_id" | "graph_id" | "name" | "created_at" | "updated_at";
+    /** Sort direction; defaults to `desc`. */
+    sortOrder?: "asc" | "desc";
+}
+/** Filter + pagination for `POST /assistants/{id}/versions`. */
+interface AssistantVersionsQuery {
+    /** Match versions whose metadata contains every one of these key/value pairs (subset match). */
+    metadata?: Metadata;
+    limit?: number;
+    offset?: number;
+}
 interface AssistantRepo {
     list(): Promise<Assistant[]>;
+    /** Filtered + paginated listing backing `POST /assistants/search`. */
+    search(query: AssistantSearchQuery): Promise<Assistant[]>;
+    /** Number of assistants matching `query` (ignores limit/offset), backing `POST /assistants/count`. */
+    count(query: AssistantSearchQuery): Promise<number>;
     get(assistantId: string): Promise<Assistant | null>;
-    /** Create (or, for a graph-derived assistant, register) an assistant. */
+    /**
+     * Create an assistant, seeding version 1 (the live row and its first {@link AssistantVersion}
+     * snapshot are written together). Throws `SkeinHttpError.conflict` (409) when `assistant_id` is
+     * already taken — the service layer turns that into `if_exists` handling, and callers that want
+     * idempotent registration (e.g. graph auto-registration) get-before-create and tolerate the 409.
+     */
     create(input: AssistantCreate): Promise<Assistant>;
+    /**
+     * Apply a partial patch by minting a NEW version: snapshot the current fields with `patch` applied,
+     * bump the live row to those fields + the new version number. Throws `SkeinHttpError.notFound` when
+     * the assistant is unknown. Returns the (now-active) assistant.
+     */
+    update(assistantId: string, patch: AssistantUpdate): Promise<Assistant>;
+    /** Version history, newest-first, filtered + paginated. Empty when the assistant is unknown. */
+    listVersions(assistantId: string, query?: AssistantVersionsQuery): Promise<AssistantVersion[]>;
+    /**
+     * Roll the live row back to an existing version's snapshot (no new version is minted). Throws
+     * `SkeinHttpError.notFound` when the assistant or the target version is unknown.
+     */
+    setLatest(assistantId: string, version: number): Promise<Assistant>;
     delete(assistantId: string): Promise<void>;
 }
 interface ThreadCreate {
@@ -96,6 +212,24 @@ interface RunKwargs {
     stream_mode?: StreamMode | StreamMode[];
     interrupt_before?: string[] | "*";
     interrupt_after?: string[] | "*";
+    /**
+     * Optional run-completion webhook URL (absolute `http(s)`). When set, the run engine POSTs the
+     * settled run (status + final values) to it once the run reaches a terminal status — matching
+     * `@langchain/langgraph-api`. Persisted opaquely so a background/crash-recovered run still fires.
+     */
+    webhook?: 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;
@@ -124,6 +258,13 @@ interface RunRepo {
      * as a fresh run. The run engine uses this to reject/queue concurrent runs.
      */
     hasActiveRun(threadId: string): Promise<boolean>;
+    /**
+     * The thread's *inflight* runs — those still `pending` or `running` (non-terminal per
+     * {@link isTerminalRunStatus}), the same set {@link hasActiveRun} counts. The multitask engine
+     * reads these to `interrupt`/`rollback` them when a second run arrives mid-run. Order is
+     * unspecified.
+     */
+    listActiveRuns(threadId: string): Promise<Run[]>;
 }
 /**
  * Run statuses from which a run never transitions again. `"interrupted"` is terminal: resuming an
@@ -179,8 +320,9 @@ interface SkeinStore {
  * 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).
+ * is the entity's own id, except `items` (keyed by `JSON.stringify([namespace, key])`),
+ * `runKwargs` (keyed by `run_id`, since {@link RunKwargs} has no id of its own), and
+ * `assistantVersions` (keyed by `JSON.stringify([assistant_id, version])`).
  *
  * 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
@@ -188,6 +330,7 @@ interface SkeinStore {
  */
 interface SkeinStoreSnapshot {
     assistants: [string, Assistant][];
+    assistantVersions: [string, AssistantVersion][];
     threads: [string, Thread][];
     runs: [string, Run][];
     runKwargs: [string, RunKwargs][];
@@ -289,66 +432,13 @@ declare class SkeinHttpError extends Error {
     static notFound(message: string, options?: SkeinHttpErrorOptions): SkeinHttpError;
     /** 409 — the request conflicts with current state (e.g. a thread already has an active run). */
     static conflict(message: string, options?: SkeinHttpErrorOptions): SkeinHttpError;
+    /**
+     * 422 — the request was well-formed but can't be processed in the current state. Used for a
+     * `reject` multitask strategy hitting a busy thread, matching `@langchain/langgraph-api`.
+     */
+    static unprocessable(message: string, options?: SkeinHttpErrorOptions): SkeinHttpError;
 }
 /** 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 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 };
+export { type AssistantCreate, type AssistantRepo, type AssistantSearchQuery, type AssistantUpdate, type AssistantVersionsQuery, 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

@@ -76,6 +76,13 @@ var SkeinHttpError = class _SkeinHttpError extends Error {
   static conflict(message, options) {
     return new _SkeinHttpError(409, message, options);
   }
+  /**
+   * 422 — the request was well-formed but can't be processed in the current state. Used for a
+   * `reject` multitask strategy hitting a busy thread, matching `@langchain/langgraph-api`.
+   */
+  static unprocessable(message, options) {
+    return new _SkeinHttpError(422, message, options);
+  }
 };
 function isSkeinHttpError(value) {
   return value instanceof SkeinHttpError;

package/package.json

@@ -1,17 +1,17 @@
 {
   "name": "@skein-js/core",
-  "version": "0.4.0",
+  "version": "0.6.3",
   "description": "Framework-agnostic Agent Protocol engine for LangGraph.js — the heart of skein-js.",
   "license": "Apache-2.0",
   "author": "Maina Wycliffe <wmmaina7@gmail.com>",
-  "homepage": "https://github.com/mainawycliffe/skein-js/tree/main/packages/core#readme",
+  "homepage": "https://github.com/skein-js/skein-js/tree/main/packages/core#readme",
   "repository": {
     "type": "git",
-    "url": "git+https://github.com/mainawycliffe/skein-js.git",
+    "url": "git+https://github.com/skein-js/skein-js.git",
     "directory": "packages/core"
   },
   "bugs": {
-    "url": "https://github.com/mainawycliffe/skein-js/issues"
+    "url": "https://github.com/skein-js/skein-js/issues"
   },
   "keywords": [
     "typescript",