@skein-js/agent-protocol 0.1.0 → 0.2.1
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +88 -24
- package/package.json +7 -6
package/README.md
CHANGED
|
@@ -1,22 +1,47 @@
|
|
|
1
1
|
# @skein-js/agent-protocol
|
|
2
2
|
|
|
3
|
-
|
|
4
|
-
|
|
5
|
-
|
|
6
|
-
|
|
7
|
-
|
|
8
|
-
|
|
9
|
-
|
|
10
|
-
|
|
11
|
-
|
|
3
|
+
> The framework-agnostic Agent Protocol **engine** — run engine, handler table, and SSE mapping. The heart of skein-js.
|
|
4
|
+
|
|
5
|
+
Part of **[skein-js](../../README.md)** — a TypeScript [Agent Protocol](https://github.com/langchain-ai/agent-protocol) server for [LangGraph.js](https://github.com/langchain-ai/langgraphjs), and a drop-in replacement for the LangGraph CLI.
|
|
6
|
+
|
|
7
|
+
**Status:** 🚧 Pre-alpha — implemented. Depends only on the [`@skein-js/core`](../core) contracts and is designed to be consumed on its own.
|
|
8
|
+
|
|
9
|
+
This is **the engine** at the heart of skein-js: a complete, framework-agnostic implementation of the
|
|
10
|
+
Agent Protocol for LangGraph.js. Build your own server on it — any HTTP framework, any storage/queue —
|
|
11
|
+
by injecting a [`ProtocolDeps`](#the-injected-contract-protocoldeps).
|
|
12
|
+
|
|
13
|
+
## Contents
|
|
12
14
|
|
|
13
|
-
|
|
14
|
-
|
|
15
|
+
- [What it does](#what-it-does)
|
|
16
|
+
- [Install](#install)
|
|
17
|
+
- [Usage](#usage)
|
|
18
|
+
- [Two layers](#two-layers)
|
|
19
|
+
- [The injected contract (`ProtocolDeps`)](#the-injected-contract-protocoldeps)
|
|
20
|
+
- [API](#api)
|
|
21
|
+
- [Reuse](#reuse)
|
|
22
|
+
- [Learn more](#learn-more)
|
|
23
|
+
- [License](#license)
|
|
24
|
+
|
|
25
|
+
## What it does
|
|
26
|
+
|
|
27
|
+
The **run engine + protocol handler table + SSE mapping**, and nothing else. It has no opinion about
|
|
28
|
+
your HTTP framework, your database, your queue, or your CLI — every collaborator is **injected**.
|
|
29
|
+
Give it a store, a queue, an event bus, a checkpointer, and a way to resolve graphs, and it serves
|
|
30
|
+
assistants, threads, the three run modes (wait / stream / background), the store, and
|
|
31
|
+
human-in-the-loop interrupt/resume — wire-compatible with the official `@langchain/langgraph-sdk`
|
|
32
|
+
client.
|
|
15
33
|
|
|
16
34
|
## Install
|
|
17
35
|
|
|
18
|
-
```
|
|
19
|
-
|
|
36
|
+
```bash
|
|
37
|
+
pnpm add @skein-js/agent-protocol @skein-js/core
|
|
38
|
+
```
|
|
39
|
+
|
|
40
|
+
`@langchain/langgraph` and `@langchain/langgraph-sdk` are peer dependencies — install them too if
|
|
41
|
+
your project doesn't already depend on them:
|
|
42
|
+
|
|
43
|
+
```bash
|
|
44
|
+
pnpm add @langchain/langgraph @langchain/langgraph-sdk
|
|
20
45
|
```
|
|
21
46
|
|
|
22
47
|
## Usage
|
|
@@ -26,10 +51,11 @@ import { createProtocolRuntime } from "@skein-js/agent-protocol";
|
|
|
26
51
|
|
|
27
52
|
const runtime = createProtocolRuntime({
|
|
28
53
|
store, // a SkeinStore (e.g. @skein-js/storage-memory, @skein-js/storage-postgres)
|
|
29
|
-
graphs, // a GraphResolver — load(
|
|
54
|
+
graphs, // a GraphResolver — ids + load(id) + schemas(id) (e.g. @skein-js/config's registry)
|
|
30
55
|
queue, // a RunQueue for background runs
|
|
31
56
|
bus, // a RunEventBus for streaming fan-out
|
|
32
57
|
checkpointer, // a LangGraph BaseCheckpointSaver (MemorySaver in dev)
|
|
58
|
+
// optional: auth, logger, clock, logRunActivity, runTimeoutMs
|
|
33
59
|
});
|
|
34
60
|
|
|
35
61
|
// One-time startup: register an assistant per graph, then start processing background runs.
|
|
@@ -51,22 +77,60 @@ runtime.worker.start();
|
|
|
51
77
|
|
|
52
78
|
`createProtocolRuntime` builds the service, handlers, and background worker over **one shared
|
|
53
79
|
context**, so cancelling a run through the service actually aborts it in the worker. Use the
|
|
54
|
-
individual `createProtocolService` / `createProtocolHandlers` factories only when
|
|
55
|
-
worker in the same process.
|
|
80
|
+
individual `createProtocolService` / `createProtocolHandlers` / `createRunWorker` factories only when
|
|
81
|
+
you don't run a worker in the same process.
|
|
56
82
|
|
|
57
83
|
### The injected contract (`ProtocolDeps`)
|
|
58
84
|
|
|
59
|
-
| Dependency
|
|
60
|
-
|
|
|
61
|
-
| `store`
|
|
62
|
-
| `graphs`
|
|
63
|
-
| `queue`
|
|
64
|
-
| `bus`
|
|
65
|
-
| `checkpointer`
|
|
85
|
+
| Dependency | Type | Responsibility |
|
|
86
|
+
| ----------------- | ---------------------------------------------- | ------------------------------------------------------------------------ |
|
|
87
|
+
| `store` | `SkeinStore` (core) | Protocol resource rows (assistants/threads/runs/store) |
|
|
88
|
+
| `graphs` | `GraphResolver` (this package) | Resolve a `graph_id` to a compiled graph + schemas |
|
|
89
|
+
| `queue` | `RunQueue` (core) | Hand background runs to a worker |
|
|
90
|
+
| `bus` | `RunEventBus` (core) | Fan run frames out to streaming clients |
|
|
91
|
+
| `checkpointer` | `BaseCheckpointSaver` (`@langchain/langgraph`) | Graph state, history, and interrupt/resume |
|
|
92
|
+
| `auth?` | `AuthEngine` (core) | Per-request 401/403 + ownership filtering; absent = all allowed |
|
|
93
|
+
| `logger?` | `Logger` (this package) | Structured logging; default no-op |
|
|
94
|
+
| `clock?` | `Clock` | Time source; default `() => new Date()` |
|
|
95
|
+
| `logRunActivity?` | `boolean` | Log per-run start/finish, tool calls, interrupts (`skein dev --verbose`) |
|
|
96
|
+
| `runTimeoutMs?` | `number` | Optional per-run wall-clock timeout → `"timeout"` |
|
|
66
97
|
|
|
67
98
|
Graph **state, history, and interrupt/resume are 100% LangGraph-native** via the checkpointer. The
|
|
68
99
|
`SkeinStore` owns only the protocol resource rows — it is deliberately not the checkpointer.
|
|
69
100
|
|
|
101
|
+
## API
|
|
102
|
+
|
|
103
|
+
- **Entry points:** `createProtocolRuntime(deps, options?)` → `{ service, handlers, worker }`;
|
|
104
|
+
`createProtocolService` / `buildProtocolService`; `createProtocolHandlers`; `createContext`;
|
|
105
|
+
`createRunWorker(ctx, options?)` (`RunWorkerOptions`: `maxConcurrency`, `shutdownGraceMs`).
|
|
106
|
+
- **Service surface** (`runtime.service`): `assistants` (`registerGraphAssistants`, `get`, `list`,
|
|
107
|
+
`search`, `schemas`), `threads` (`create`/`get`/`list`/`patch`/`delete`/`history`/`getState`),
|
|
108
|
+
`threadStream` (`stream` / `joinStream` / `command` — HIL resume, requires status `interrupted`),
|
|
109
|
+
`runs` (`createWait`/`createStream`/`createBackground`/`get`/`listByThread`/`cancel`/`delete`/`join`/`finalStatus`),
|
|
110
|
+
`store` (`put`/`get`/`delete`/`search`/`listNamespaces`).
|
|
111
|
+
- **Transport types:** `ProtocolRequest`, `ProtocolResponse` (`json` | `empty` | `sse`),
|
|
112
|
+
`ProtocolHandler`, `ProtocolHandlers`.
|
|
113
|
+
- **`SkeinBaseStore`** — bridges a `StoreRepo` into a LangGraph `BaseStore`, so graph nodes reach
|
|
114
|
+
long-term memory via `getStore()`. The engine attaches one to every run.
|
|
115
|
+
- **SSE helpers** (for adapters writing the stream themselves): `SSE_HEADERS`, `encodeFrame`,
|
|
116
|
+
`encodeTerminal`, `toSseEvents`, `parseAfterSeq`.
|
|
117
|
+
|
|
118
|
+
> **Note on duplicate type names.** `GraphResolver`, `CompiledGraphFactory`, `ResolvedGraph`, and
|
|
119
|
+
> `GraphSchemas` are exported here _and_ (structurally compatible copies) by [`@skein-js/config`](../config).
|
|
120
|
+
> `config`'s `GraphRegistry` satisfies this package's `GraphResolver` at wire-up time.
|
|
121
|
+
|
|
122
|
+
## Reuse
|
|
123
|
+
|
|
124
|
+
Runs graphs through `@langchain/langgraph` (`invoke`/`stream`, interrupts/resume) and uses the
|
|
125
|
+
injected `BaseCheckpointSaver` for state/history — never a reimplemented runtime. Wire types come
|
|
126
|
+
from `@langchain/langgraph-sdk` via [`@skein-js/core`](../core).
|
|
127
|
+
|
|
128
|
+
## Learn more
|
|
129
|
+
|
|
130
|
+
- [Agent Protocol surface](../../docs/agent-protocol.md) · [Streaming (SSE)](../../docs/streaming.md) · [Runs & Redis](../../docs/runs-and-redis.md)
|
|
131
|
+
- [Building your own adapter](../../docs/building-an-adapter.md) — mount this engine on any HTTP framework
|
|
132
|
+
- [skein-js overview](../../docs/index.md) · [Reuse-first architecture](../../docs/reuse.md) · [Root README](../../README.md)
|
|
133
|
+
|
|
70
134
|
## License
|
|
71
135
|
|
|
72
|
-
Apache-2.0
|
|
136
|
+
[Apache-2.0](../../LICENSE)
|
package/package.json
CHANGED
|
@@ -1,19 +1,20 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@skein-js/agent-protocol",
|
|
3
|
-
"version": "0.1
|
|
3
|
+
"version": "0.2.1",
|
|
4
4
|
"description": "Framework-agnostic Agent Protocol engine for LangGraph.js — run engine, handlers, and SSE, driven entirely by injected dependencies.",
|
|
5
5
|
"license": "Apache-2.0",
|
|
6
6
|
"author": "Maina Wycliffe <wmmaina7@gmail.com>",
|
|
7
|
-
"homepage": "https://github.com/mainawycliffe/skein/tree/main/packages/agent-protocol#readme",
|
|
7
|
+
"homepage": "https://github.com/mainawycliffe/skein-js/tree/main/packages/agent-protocol#readme",
|
|
8
8
|
"repository": {
|
|
9
9
|
"type": "git",
|
|
10
|
-
"url": "git+https://github.com/mainawycliffe/skein.git",
|
|
10
|
+
"url": "git+https://github.com/mainawycliffe/skein-js.git",
|
|
11
11
|
"directory": "packages/agent-protocol"
|
|
12
12
|
},
|
|
13
13
|
"bugs": {
|
|
14
|
-
"url": "https://github.com/mainawycliffe/skein/issues"
|
|
14
|
+
"url": "https://github.com/mainawycliffe/skein-js/issues"
|
|
15
15
|
},
|
|
16
16
|
"keywords": [
|
|
17
|
+
"typescript",
|
|
17
18
|
"langgraph",
|
|
18
19
|
"agent-protocol",
|
|
19
20
|
"agents",
|
|
@@ -43,14 +44,14 @@
|
|
|
43
44
|
},
|
|
44
45
|
"dependencies": {
|
|
45
46
|
"zod": "^3.25.76",
|
|
46
|
-
"@skein-js/core": "0.1
|
|
47
|
+
"@skein-js/core": "0.2.1"
|
|
47
48
|
},
|
|
48
49
|
"peerDependencies": {
|
|
49
50
|
"@langchain/langgraph": "^1.4.0",
|
|
50
51
|
"@langchain/langgraph-sdk": "^1.9.0"
|
|
51
52
|
},
|
|
52
53
|
"devDependencies": {
|
|
53
|
-
"@skein-js/storage-memory": "0.1
|
|
54
|
+
"@skein-js/storage-memory": "0.2.1"
|
|
54
55
|
},
|
|
55
56
|
"publishConfig": {
|
|
56
57
|
"access": "public"
|