@skein-js/core 0.5.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"> & {
@@ -78,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 {
@@ -156,6 +212,12 @@ 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
@@ -196,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
@@ -251,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
@@ -260,6 +330,7 @@ interface SkeinStore {
  */
 interface SkeinStoreSnapshot {
     assistants: [string, Assistant][];
+    assistantVersions: [string, AssistantVersion][];
     threads: [string, Thread][];
     runs: [string, Run][];
     runKwargs: [string, RunKwargs][];
@@ -361,8 +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;
 
-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.5.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",