@dreamlake/dreamlake-cli 0.98.0 → 0.99.0
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/dist/api/index.d.ts +212 -10
- package/dist/api/index.js +6 -0
- package/dist/api/native-experiments.d.ts +77 -0
- package/dist/api/native-experiments.js +31 -0
- package/dist/api/sessions.d.ts +240 -7
- package/dist/api/sessions.js +56 -1
- package/dist/api/skills.d.ts +122 -0
- package/dist/api/skills.js +220 -0
- package/dist/cli/experiments/index.js +2 -0
- package/dist/cli/experiments/native-commands.d.ts +13 -0
- package/dist/cli/experiments/native-commands.js +88 -0
- package/dist/cli/help-examples.generated.js +22 -5
- package/dist/cli/index.js +2 -0
- package/dist/cli/session-affiliation.js +3 -2
- package/dist/cli/sessions/affiliation.d.ts +12 -1
- package/dist/cli/sessions/affiliation.js +37 -0
- package/dist/cli/sessions/control.d.ts +11 -0
- package/dist/cli/sessions/control.js +49 -4
- package/dist/cli/sessions/index.js +70 -17
- package/dist/cli/sessions/live.d.ts +85 -0
- package/dist/cli/sessions/live.js +258 -0
- package/dist/cli/sessions/runner/exec.d.ts +118 -6
- package/dist/cli/sessions/runner/exec.js +298 -47
- package/dist/cli/sessions/runner/native.js +4 -1
- package/dist/cli/sessions/runner/serve.d.ts +37 -2
- package/dist/cli/sessions/runner/serve.js +273 -28
- package/dist/cli/sessions/wrap.d.ts +63 -0
- package/dist/cli/sessions/wrap.js +226 -0
- package/dist/cli/skill/index.d.ts +19 -1
- package/dist/cli/skill/index.js +65 -12
- package/dist/cli/skill/read.d.ts +25 -0
- package/dist/cli/skill/read.js +65 -0
- package/dist/cli/skill/registry.d.ts +95 -0
- package/dist/cli/skill/registry.js +284 -0
- package/dist/cli/skill/reminders.js +2 -1
- package/dist/cli/version.d.ts +1 -1
- package/dist/cli/version.js +1 -1
- package/package.json +9 -9
package/dist/api/sessions.d.ts
CHANGED
|
@@ -3,6 +3,175 @@
|
|
|
3
3
|
import { type Transport } from "./client.js";
|
|
4
4
|
export type Provider = "codex" | "claude";
|
|
5
5
|
export type RunState = "unknown" | "running" | "working" | "waiting" | "idle" | "error" | "stopped";
|
|
6
|
+
/** Ordered: each level includes the ones before it. */
|
|
7
|
+
export declare const PERMISSION_LEVELS: readonly ["read-only", "workspace-write", "full-access"];
|
|
8
|
+
export type PermissionLevel = (typeof PERMISSION_LEVELS)[number];
|
|
9
|
+
/** Position on the ladder; -1 for anything that is not a level (an unrecorded level sits below every level). */
|
|
10
|
+
export declare const levelIndex: (level: unknown) => number;
|
|
11
|
+
/** A move from `from` to `to` that widens access. The server treats a session without a recorded level the
|
|
12
|
+
* same way: any level set on it is a raise and needs the person's explicit `raise: true`. */
|
|
13
|
+
export declare const isPermissionRaise: (from: unknown, to: unknown) => boolean;
|
|
14
|
+
/** Who moved a recorded policy: `token` is any holder of the owner's bearer token (CLI, script, a native
|
|
15
|
+
* agent), `agent` the built-in agent proven by its turn lease, `runner` only on a `permission_mismatch`
|
|
16
|
+
* entry. The server never infers a person; a raise needs the explicit `raise: true` the CLI sets after asking. */
|
|
17
|
+
export type PermissionOrigin = "token" | "agent" | "runner";
|
|
18
|
+
export interface PermissionChange {
|
|
19
|
+
level: PermissionLevel;
|
|
20
|
+
origin: PermissionOrigin;
|
|
21
|
+
at: string;
|
|
22
|
+
byUserId: string;
|
|
23
|
+
reason?: string;
|
|
24
|
+
/** On a `permission_mismatch` entry: what the runner reported running under; authority stays at `level`. */
|
|
25
|
+
observedLevel?: PermissionLevel;
|
|
26
|
+
}
|
|
27
|
+
/** What a session is doing now, as its own hooks (`source: hook`) or its runner (`source: runner`) report it.
|
|
28
|
+
* A `starting` / `running` beat older than 60 s reads as `uncertain`. */
|
|
29
|
+
export type LiveState = "starting" | "running" | "waiting-for-user" | "idle" | "stopped" | "uncertain";
|
|
30
|
+
export type LiveStateSource = "hook" | "runner";
|
|
31
|
+
export interface LiveCurrent {
|
|
32
|
+
tool?: string;
|
|
33
|
+
/** First 200 characters of the prompt; redacted on ingest; owner-only. */
|
|
34
|
+
promptHead?: string;
|
|
35
|
+
}
|
|
36
|
+
/** Bounds the server enforces on a heartbeat / event body (400 beyond them); the CLI truncates to them. */
|
|
37
|
+
export declare const LIVE_LIMITS: {
|
|
38
|
+
readonly tool: 128;
|
|
39
|
+
readonly promptHead: 200;
|
|
40
|
+
readonly name: 128;
|
|
41
|
+
readonly subagentId: 128;
|
|
42
|
+
};
|
|
43
|
+
export declare const LIVE_STATES: readonly LiveState[];
|
|
44
|
+
/** One beat from a session's own hooks or from its runner. `runnerId` present means the beat comes from
|
|
45
|
+
* that runner (`source: runner`, and it must be the session's bound runner: `409 session_runner_mismatch`);
|
|
46
|
+
* absent, from the owner's hook relay (`source: hook`). `source` may only agree with that. `at` is the
|
|
47
|
+
* sender's clock (clamped to the server's now); an older `at` than the stored beat is not written. */
|
|
48
|
+
export interface HeartbeatInput {
|
|
49
|
+
liveState: LiveState;
|
|
50
|
+
current?: LiveCurrent;
|
|
51
|
+
at: string;
|
|
52
|
+
source?: LiveStateSource;
|
|
53
|
+
runnerId?: string;
|
|
54
|
+
}
|
|
55
|
+
export interface HeartbeatResult {
|
|
56
|
+
accepted: boolean;
|
|
57
|
+
liveState: LiveState;
|
|
58
|
+
liveStateReported: LiveState;
|
|
59
|
+
liveStateAt: string;
|
|
60
|
+
liveStateReceivedAt: string;
|
|
61
|
+
liveStateSource: LiveStateSource;
|
|
62
|
+
current: LiveCurrent | null;
|
|
63
|
+
}
|
|
64
|
+
export type SessionEventKind = "SubagentStart" | "SubagentStop";
|
|
65
|
+
/** A native subagent lifecycle event; `runnerId` / `source` follow the heartbeat rule. `tokens` is a total. */
|
|
66
|
+
export interface SessionEventInput {
|
|
67
|
+
kind: SessionEventKind;
|
|
68
|
+
/** `^[A-Za-z0-9._:-]{1,128}$` */
|
|
69
|
+
subagentId: string;
|
|
70
|
+
name?: string;
|
|
71
|
+
at: string;
|
|
72
|
+
finished?: string;
|
|
73
|
+
tokens?: number;
|
|
74
|
+
source?: LiveStateSource;
|
|
75
|
+
runnerId?: string;
|
|
76
|
+
}
|
|
77
|
+
/** A native subagent as the tree and the watch stream show it. */
|
|
78
|
+
export interface SubagentNode {
|
|
79
|
+
id: string;
|
|
80
|
+
kind: "subagent";
|
|
81
|
+
name: string | null;
|
|
82
|
+
liveState: LiveState;
|
|
83
|
+
startedAt: string | null;
|
|
84
|
+
finishedAt: string | null;
|
|
85
|
+
tokens: number | null;
|
|
86
|
+
lastEvent: SessionEventKind;
|
|
87
|
+
lastEventAt: string;
|
|
88
|
+
source: LiveStateSource;
|
|
89
|
+
}
|
|
90
|
+
/** A session in `GET …/:id/tree`: managed children (by `parentSessionId`, breadth-first, depth ≤ 3,
|
|
91
|
+
* ≤ 200 nodes) followed by the node's native subagents. `isolation` is what the runner recorded at
|
|
92
|
+
* start (`null` for sessions started before it existed or registered by Nymph); `tokens` is not
|
|
93
|
+
* relayed for sessions yet (`null`). */
|
|
94
|
+
export interface SessionTreeNode {
|
|
95
|
+
id: string;
|
|
96
|
+
kind: "session";
|
|
97
|
+
name: string;
|
|
98
|
+
provider: Provider;
|
|
99
|
+
parentSessionId: string | null;
|
|
100
|
+
liveState: LiveState | null;
|
|
101
|
+
liveStateAt: string | null;
|
|
102
|
+
current: LiveCurrent | null;
|
|
103
|
+
permissionLevel: PermissionLevel | null;
|
|
104
|
+
isolation: {
|
|
105
|
+
kind: IsolationKind;
|
|
106
|
+
repo: string;
|
|
107
|
+
branch?: string;
|
|
108
|
+
baseRef?: string;
|
|
109
|
+
cwd?: string;
|
|
110
|
+
mode?: RunMode;
|
|
111
|
+
} | null;
|
|
112
|
+
pod: unknown;
|
|
113
|
+
cwd: string;
|
|
114
|
+
repositoryRoot: string | null;
|
|
115
|
+
runnerId: string | null;
|
|
116
|
+
tokens: number | null;
|
|
117
|
+
finishedAt: string | null;
|
|
118
|
+
createdAt: string;
|
|
119
|
+
children: (SessionTreeNode | SubagentNode)[];
|
|
120
|
+
}
|
|
121
|
+
export interface SessionTree {
|
|
122
|
+
session: SessionTreeNode;
|
|
123
|
+
nodeCount: number;
|
|
124
|
+
subagentCount: number;
|
|
125
|
+
truncated: boolean;
|
|
126
|
+
cycleDetected: boolean;
|
|
127
|
+
}
|
|
128
|
+
/** Frames of `GET …/terminal-sessions/watch` (SSE). No catch-up: the stream carries exactly what happens
|
|
129
|
+
* after `ready.at`; after `end` or a disconnect re-read the list (and `/tree`) before reconnecting. */
|
|
130
|
+
export type WatchEvent = {
|
|
131
|
+
type: "ready";
|
|
132
|
+
at: string;
|
|
133
|
+
sessionId: string | null;
|
|
134
|
+
quietMs: number;
|
|
135
|
+
maxDelayMs: number;
|
|
136
|
+
timeoutMs: number;
|
|
137
|
+
catchUp: false;
|
|
138
|
+
} | {
|
|
139
|
+
type: "liveState" | "heartbeat";
|
|
140
|
+
sessionId: string;
|
|
141
|
+
liveState: LiveState;
|
|
142
|
+
liveStateReported: LiveState;
|
|
143
|
+
liveStateAt: string;
|
|
144
|
+
liveStateReceivedAt: string;
|
|
145
|
+
liveStateSource: LiveStateSource;
|
|
146
|
+
current: LiveCurrent | null;
|
|
147
|
+
at: string;
|
|
148
|
+
} | {
|
|
149
|
+
type: "subagent";
|
|
150
|
+
sessionId: string;
|
|
151
|
+
subagent: SubagentNode;
|
|
152
|
+
at: string;
|
|
153
|
+
} | {
|
|
154
|
+
type: "receipt";
|
|
155
|
+
sessionId: string;
|
|
156
|
+
command: Command;
|
|
157
|
+
at: string;
|
|
158
|
+
} | {
|
|
159
|
+
type: "permission";
|
|
160
|
+
sessionId: string;
|
|
161
|
+
permissionLevel: PermissionLevel;
|
|
162
|
+
permissionChangedAt: string;
|
|
163
|
+
entry: PermissionChange;
|
|
164
|
+
at: string;
|
|
165
|
+
} | {
|
|
166
|
+
type: "end";
|
|
167
|
+
reason: "timeout";
|
|
168
|
+
at: string;
|
|
169
|
+
} | {
|
|
170
|
+
type: "error";
|
|
171
|
+
error: "access_expired" | "access_unavailable" | "session_watch_unavailable";
|
|
172
|
+
at: string;
|
|
173
|
+
};
|
|
174
|
+
export declare const WATCH_EVENT_TYPES: readonly ["ready", "liveState", "heartbeat", "subagent", "receipt", "permission", "end", "error"];
|
|
6
175
|
export interface Session {
|
|
7
176
|
id: string;
|
|
8
177
|
name: string;
|
|
@@ -20,6 +189,18 @@ export interface Session {
|
|
|
20
189
|
archivedAt?: string | null;
|
|
21
190
|
runnerId?: string | null;
|
|
22
191
|
permissionLevel?: PermissionLevel | null;
|
|
192
|
+
/** Diagnostics only: the level the runner last said it ran under; never authority. Owner-only. */
|
|
193
|
+
observedPermissionLevel?: PermissionLevel | null;
|
|
194
|
+
/** Oldest first, last 50. Owner-only (other viewers get null). */
|
|
195
|
+
permissionHistory?: PermissionChange[] | null;
|
|
196
|
+
permissionChangedAt?: string | null;
|
|
197
|
+
/** Effective live state (stale active beats read `uncertain`); `liveStateReported` keeps the raw value. */
|
|
198
|
+
liveState?: LiveState | null;
|
|
199
|
+
liveStateReported?: LiveState | null;
|
|
200
|
+
liveStateAt?: string | null;
|
|
201
|
+
liveStateReceivedAt?: string | null;
|
|
202
|
+
liveStateSource?: LiveStateSource | null;
|
|
203
|
+
current?: LiveCurrent | null;
|
|
23
204
|
claudeConfigDir?: string | null;
|
|
24
205
|
archiveOnly?: boolean | null;
|
|
25
206
|
visibility: "public" | "private" | "team";
|
|
@@ -68,12 +249,11 @@ export interface Conversation {
|
|
|
68
249
|
nativeSessionId: string;
|
|
69
250
|
messages: ConversationMessage[];
|
|
70
251
|
}
|
|
71
|
-
export declare const COMMAND_KINDS: readonly ["start", "resume", "stop", "send", "sync", "status", "subagents"];
|
|
252
|
+
export declare const COMMAND_KINDS: readonly ["start", "resume", "restart", "stop", "send", "sync", "status", "subagents"];
|
|
72
253
|
export type CommandKind = (typeof COMMAND_KINDS)[number];
|
|
73
254
|
export type CommandStatus = "pending" | "running" | "completed" | "failed" | "cancelled" | "uncertain";
|
|
74
255
|
export declare const TERMINAL: ReadonlySet<CommandStatus>;
|
|
75
256
|
export type IsolationKind = "repo" | "worktree" | "pod";
|
|
76
|
-
export type PermissionLevel = "read-only" | "workspace-write" | "full-access";
|
|
77
257
|
export type RunMode = "tmux" | "headless";
|
|
78
258
|
export interface StartInput {
|
|
79
259
|
parentSessionId?: string;
|
|
@@ -97,6 +277,17 @@ export type CommandInput = {
|
|
|
97
277
|
mode?: RunMode;
|
|
98
278
|
permissionLevel?: PermissionLevel;
|
|
99
279
|
};
|
|
280
|
+
/** Stop, then resume the same native session under a new recorded level. Lowering always passes; raising
|
|
281
|
+
* needs `raise: true` (the person's confirmation, asked for by the CLI) and a runner that advertises a
|
|
282
|
+
* `humanPermissionCap` at or above the level. The built-in agent never raises. */
|
|
283
|
+
restart: {
|
|
284
|
+
sessionId: string;
|
|
285
|
+
permissionLevel: PermissionLevel;
|
|
286
|
+
prompt?: string;
|
|
287
|
+
mode?: RunMode;
|
|
288
|
+
reason?: string;
|
|
289
|
+
raise?: boolean;
|
|
290
|
+
};
|
|
100
291
|
stop: {
|
|
101
292
|
sessionId: string;
|
|
102
293
|
};
|
|
@@ -157,12 +348,17 @@ export interface Runner {
|
|
|
157
348
|
capabilities: RunnerCapabilities;
|
|
158
349
|
online: boolean;
|
|
159
350
|
lastSeenAt: string;
|
|
351
|
+
/** Set when the runner said goodbye (`deregister`); cleared by its next sign of life. */
|
|
352
|
+
offlineAt?: string | null;
|
|
160
353
|
createdAt: string;
|
|
161
354
|
}
|
|
162
355
|
export interface RunnerCapabilities {
|
|
163
356
|
providers: Provider[];
|
|
164
357
|
isolation: IsolationKind[];
|
|
165
358
|
modes: RunMode[];
|
|
359
|
+
/** Runner-wide ceiling for raises a person asks for (`sessions serve --max-human-permission`). Absent: the
|
|
360
|
+
* start level stays a hard ceiling and no restart or PATCH can raise above it on this runner. */
|
|
361
|
+
humanPermissionCap?: PermissionLevel;
|
|
166
362
|
}
|
|
167
363
|
export interface RunnerRegistration {
|
|
168
364
|
runnerKey: string;
|
|
@@ -219,6 +415,36 @@ export declare function sessionsApi(t: Transport, namespace: string): {
|
|
|
219
415
|
}>;
|
|
220
416
|
rename: (sessionId: string, name: string) => Promise<Session>;
|
|
221
417
|
archive: (sessionId: string, archived: boolean) => Promise<Session>;
|
|
418
|
+
/** Move the recorded permission level without a runner round-trip. Only the record moves: the running
|
|
419
|
+
* process keeps its level until the next `resume` / `restart` re-applies it. Same rule as `restart`:
|
|
420
|
+
* lowering always passes; raising needs `raise: true` and the executing runner's `humanPermissionCap`
|
|
421
|
+
* (`403 session_permission_raise_unconfirmed` / `session_permission_cap`); a child never passes its
|
|
422
|
+
* parent (`403 parent_permission_ceiling`, `409 parent_permission_changed`). */
|
|
423
|
+
permission: (sessionId: string, input: {
|
|
424
|
+
permissionLevel: PermissionLevel;
|
|
425
|
+
reason?: string;
|
|
426
|
+
raise?: boolean;
|
|
427
|
+
}) => Promise<{
|
|
428
|
+
session: Session;
|
|
429
|
+
changed: boolean;
|
|
430
|
+
}>;
|
|
431
|
+
/** The session with its managed children and native subagents. */
|
|
432
|
+
tree: (sessionId: string) => Promise<SessionTree>;
|
|
433
|
+
/** Live frames for one session or all of the caller's. Ends after the server's 15-minute timeout
|
|
434
|
+
* (`end`) or on `signal`; frames of an unknown type are passed through with their `type`. The stream
|
|
435
|
+
* has no total deadline of its own: without a caller signal an internal one stands in, so the
|
|
436
|
+
* transport's 30 s request timeout is never armed, and it is released when the generator closes. */
|
|
437
|
+
watch: (query?: {
|
|
438
|
+
sessionId?: string;
|
|
439
|
+
}, signal?: AbortSignal) => AsyncGenerator<WatchEvent>;
|
|
440
|
+
/** Report what a session is doing now. Bounded (5 s): a relay must never hold up the session it
|
|
441
|
+
* reports on. The body is never logged by the SDK. */
|
|
442
|
+
heartbeat: (sessionId: string, input: HeartbeatInput) => Promise<HeartbeatResult>;
|
|
443
|
+
/** Relay a native subagent start / stop; one child row per (session, subagentId), merged atomically. */
|
|
444
|
+
event: (sessionId: string, input: SessionEventInput) => Promise<{
|
|
445
|
+
sessionId: string;
|
|
446
|
+
subagent: SubagentNode;
|
|
447
|
+
}>;
|
|
222
448
|
/** Register native session metadata without a host; the runner uses this after `start`. */
|
|
223
449
|
register: (input: {
|
|
224
450
|
provider: Provider;
|
|
@@ -253,21 +479,28 @@ export declare function sessionsApi(t: Transport, namespace: string): {
|
|
|
253
479
|
}) => Promise<{
|
|
254
480
|
commands: Command[];
|
|
255
481
|
}>;
|
|
256
|
-
|
|
482
|
+
/** `options` bounds one read on its own (the runner's cancel probe uses a 2 s deadline and signal). */
|
|
483
|
+
get: (commandId: string, wait?: number, options?: {
|
|
484
|
+
signal?: AbortSignal;
|
|
485
|
+
timeoutMs?: number;
|
|
486
|
+
}) => Promise<Command<"start" | "stop" | "restart" | "status" | "resume" | "send" | "sync" | "subagents">>;
|
|
257
487
|
/** Wait up to `seconds` (server-bounded per call; loops for longer waits) for a terminal state. */
|
|
258
|
-
wait: (commandId: string, seconds: number, signal?: AbortSignal) => Promise<Command<"start" | "stop" | "status" | "resume" | "send" | "sync" | "subagents">>;
|
|
259
|
-
cancel: (commandId: string) => Promise<Command<"start" | "stop" | "status" | "resume" | "send" | "sync" | "subagents">>;
|
|
488
|
+
wait: (commandId: string, seconds: number, signal?: AbortSignal) => Promise<Command<"start" | "stop" | "restart" | "status" | "resume" | "send" | "sync" | "subagents">>;
|
|
489
|
+
cancel: (commandId: string) => Promise<Command<"start" | "stop" | "restart" | "status" | "resume" | "send" | "sync" | "subagents">>;
|
|
260
490
|
renew: (commandId: string, runnerId: string, leaseToken: string) => Promise<{
|
|
261
491
|
leaseMs: number;
|
|
262
492
|
cancelRequested?: boolean;
|
|
263
493
|
}>;
|
|
264
|
-
reconcile: (commandId: string, runnerId: string, observation: Record<string, unknown>) => Promise<Command<"start" | "stop" | "status" | "resume" | "send" | "sync" | "subagents">>;
|
|
265
|
-
finish: (commandId: string, runnerId: string, receipt: CommandReceipt) => Promise<Command<"start" | "stop" | "status" | "resume" | "send" | "sync" | "subagents">>;
|
|
494
|
+
reconcile: (commandId: string, runnerId: string, observation: Record<string, unknown>) => Promise<Command<"start" | "stop" | "restart" | "status" | "resume" | "send" | "sync" | "subagents">>;
|
|
495
|
+
finish: (commandId: string, runnerId: string, receipt: CommandReceipt) => Promise<Command<"start" | "stop" | "restart" | "status" | "resume" | "send" | "sync" | "subagents">>;
|
|
266
496
|
};
|
|
267
497
|
runners: {
|
|
268
498
|
list: () => Promise<Runner[]>;
|
|
269
499
|
register: (input: RunnerRegistration) => Promise<Runner>;
|
|
270
500
|
claim: (runnerId: string, seconds: number, signal?: AbortSignal) => Promise<ClaimedCommand | null>;
|
|
501
|
+
/** The runner is exiting: list it offline now instead of after the heartbeat window. Bounded so
|
|
502
|
+
* a shutdown never hangs on the network. */
|
|
503
|
+
deregister: (runnerId: string) => Promise<Runner | null>;
|
|
271
504
|
};
|
|
272
505
|
};
|
|
273
506
|
export type SessionsApi = ReturnType<typeof sessionsApi>;
|
package/dist/api/sessions.js
CHANGED
|
@@ -1,9 +1,22 @@
|
|
|
1
1
|
/** Agent sessions and the session control plane. Mirrors
|
|
2
2
|
* dreamlake-server `routes/terminal-sessions.ts` and `session-control/`. */
|
|
3
3
|
import { isObjectId, seg } from "./client.js";
|
|
4
|
+
import { serverEvents } from "./streams.js";
|
|
5
|
+
/** Ordered: each level includes the ones before it. */
|
|
6
|
+
export const PERMISSION_LEVELS = ["read-only", "workspace-write", "full-access"];
|
|
7
|
+
/** Position on the ladder; -1 for anything that is not a level (an unrecorded level sits below every level). */
|
|
8
|
+
export const levelIndex = (level) => PERMISSION_LEVELS.indexOf(String(level));
|
|
9
|
+
/** A move from `from` to `to` that widens access. The server treats a session without a recorded level the
|
|
10
|
+
* same way: any level set on it is a raise and needs the person's explicit `raise: true`. */
|
|
11
|
+
export const isPermissionRaise = (from, to) => levelIndex(to) > levelIndex(from);
|
|
12
|
+
/** Bounds the server enforces on a heartbeat / event body (400 beyond them); the CLI truncates to them. */
|
|
13
|
+
export const LIVE_LIMITS = { tool: 128, promptHead: 200, name: 128, subagentId: 128 };
|
|
14
|
+
export const LIVE_STATES = ["starting", "running", "waiting-for-user", "idle", "stopped", "uncertain"];
|
|
15
|
+
export const WATCH_EVENT_TYPES = ["ready", "liveState", "heartbeat", "subagent", "receipt", "permission", "end", "error"];
|
|
4
16
|
export const COMMAND_KINDS = [
|
|
5
17
|
"start",
|
|
6
18
|
"resume",
|
|
19
|
+
"restart",
|
|
7
20
|
"stop",
|
|
8
21
|
"send",
|
|
9
22
|
"sync",
|
|
@@ -41,6 +54,44 @@ export function sessionsApi(t, namespace) {
|
|
|
41
54
|
}),
|
|
42
55
|
rename: async (sessionId, name) => (await t.request("PATCH", `${base}/${id(sessionId)}/name`, { json: { name } })).session,
|
|
43
56
|
archive: async (sessionId, archived) => (await t.request("PATCH", `${base}/${id(sessionId)}/archive`, { json: { archived } })).session,
|
|
57
|
+
/** Move the recorded permission level without a runner round-trip. Only the record moves: the running
|
|
58
|
+
* process keeps its level until the next `resume` / `restart` re-applies it. Same rule as `restart`:
|
|
59
|
+
* lowering always passes; raising needs `raise: true` and the executing runner's `humanPermissionCap`
|
|
60
|
+
* (`403 session_permission_raise_unconfirmed` / `session_permission_cap`); a child never passes its
|
|
61
|
+
* parent (`403 parent_permission_ceiling`, `409 parent_permission_changed`). */
|
|
62
|
+
permission: async (sessionId, input) => t.request("PATCH", `${base}/${id(sessionId)}/permission`, { json: input }),
|
|
63
|
+
/** The session with its managed children and native subagents. */
|
|
64
|
+
tree: async (sessionId) => t.request("GET", `${base}/${id(sessionId)}/tree`),
|
|
65
|
+
/** Live frames for one session or all of the caller's. Ends after the server's 15-minute timeout
|
|
66
|
+
* (`end`) or on `signal`; frames of an unknown type are passed through with their `type`. The stream
|
|
67
|
+
* has no total deadline of its own: without a caller signal an internal one stands in, so the
|
|
68
|
+
* transport's 30 s request timeout is never armed, and it is released when the generator closes. */
|
|
69
|
+
watch: async function* (query = {}, signal) {
|
|
70
|
+
if (!t.raw)
|
|
71
|
+
throw new Error("transport_does_not_support_streaming");
|
|
72
|
+
const own = signal ? null : new AbortController();
|
|
73
|
+
try {
|
|
74
|
+
const response = await t.raw("GET", `${base}/watch`, {
|
|
75
|
+
query: query.sessionId ? { sessionId: id(query.sessionId) } : {},
|
|
76
|
+
signal: signal ?? own.signal,
|
|
77
|
+
timeoutMs: null,
|
|
78
|
+
headers: { Accept: "text/event-stream" },
|
|
79
|
+
});
|
|
80
|
+
for await (const frame of serverEvents(response)) {
|
|
81
|
+
if (!frame.event || !frame.data || typeof frame.data !== "object")
|
|
82
|
+
continue;
|
|
83
|
+
yield { type: frame.event, ...frame.data };
|
|
84
|
+
}
|
|
85
|
+
}
|
|
86
|
+
finally {
|
|
87
|
+
own?.abort();
|
|
88
|
+
}
|
|
89
|
+
},
|
|
90
|
+
/** Report what a session is doing now. Bounded (5 s): a relay must never hold up the session it
|
|
91
|
+
* reports on. The body is never logged by the SDK. */
|
|
92
|
+
heartbeat: async (sessionId, input) => t.request("POST", `${base}/${id(sessionId)}/heartbeat`, { json: input, timeoutMs: 5000 }),
|
|
93
|
+
/** Relay a native subagent start / stop; one child row per (session, subagentId), merged atomically. */
|
|
94
|
+
event: async (sessionId, input) => t.request("POST", `${base}/${id(sessionId)}/events`, { json: input, timeoutMs: 5000 }),
|
|
44
95
|
/** Register native session metadata without a host; the runner uses this after `start`. */
|
|
45
96
|
register: (input) => t.request("POST", "/terminal-sessions/register", {
|
|
46
97
|
json: input,
|
|
@@ -57,7 +108,8 @@ export function sessionsApi(t, namespace) {
|
|
|
57
108
|
},
|
|
58
109
|
}),
|
|
59
110
|
list: (query = {}) => t.request("GET", commands, { query }),
|
|
60
|
-
|
|
111
|
+
/** `options` bounds one read on its own (the runner's cancel probe uses a 2 s deadline and signal). */
|
|
112
|
+
get: async (commandId, wait, options = {}) => (await t.request("GET", `${commands}/${id(commandId)}`, { ...(wait === undefined ? {} : { query: { wait } }), ...options })).command,
|
|
61
113
|
/** Wait up to `seconds` (server-bounded per call; loops for longer waits) for a terminal state. */
|
|
62
114
|
wait: async (commandId, seconds, signal) => {
|
|
63
115
|
const deadline = Date.now() + seconds * 1000;
|
|
@@ -80,6 +132,9 @@ export function sessionsApi(t, namespace) {
|
|
|
80
132
|
register: async (input) => (await t.request("POST", runners, { json: input }))
|
|
81
133
|
.runner,
|
|
82
134
|
claim: async (runnerId, seconds, signal) => (await t.request("POST", `${runners}/${id(runnerId)}/claim`, { json: { wait: seconds }, signal, ...long(seconds) })).command,
|
|
135
|
+
/** The runner is exiting: list it offline now instead of after the heartbeat window. Bounded so
|
|
136
|
+
* a shutdown never hangs on the network. */
|
|
137
|
+
deregister: async (runnerId) => (await t.request("DELETE", `${runners}/${id(runnerId)}`, { timeoutMs: 5000 }))?.runner ?? null,
|
|
83
138
|
},
|
|
84
139
|
};
|
|
85
140
|
}
|
|
@@ -0,0 +1,122 @@
|
|
|
1
|
+
import { ApiError, type Transport } from "./client.js";
|
|
2
|
+
export interface SkillsVersion {
|
|
3
|
+
tag: string;
|
|
4
|
+
commit: string;
|
|
5
|
+
}
|
|
6
|
+
export interface SkillsListEntry {
|
|
7
|
+
name: string;
|
|
8
|
+
description: string;
|
|
9
|
+
requires: string[];
|
|
10
|
+
tools: unknown;
|
|
11
|
+
/** Number of files in the skill directory. */
|
|
12
|
+
files: number;
|
|
13
|
+
}
|
|
14
|
+
export interface SkillsList {
|
|
15
|
+
version: SkillsVersion;
|
|
16
|
+
skills: SkillsListEntry[];
|
|
17
|
+
/** Retired name → current name. */
|
|
18
|
+
renamed: Record<string, string>;
|
|
19
|
+
}
|
|
20
|
+
export interface SkillFileEntry {
|
|
21
|
+
path: string;
|
|
22
|
+
bytes: number;
|
|
23
|
+
sha256: string;
|
|
24
|
+
/** False for a file that is not UTF-8; the file route answers 415 for it. */
|
|
25
|
+
text: boolean;
|
|
26
|
+
}
|
|
27
|
+
export interface SkillDetail {
|
|
28
|
+
version: SkillsVersion;
|
|
29
|
+
name: string;
|
|
30
|
+
/** Present when the request named a retired skill name. */
|
|
31
|
+
renamedFrom?: string;
|
|
32
|
+
/** The skill's `skill.json`. */
|
|
33
|
+
manifest: Record<string, unknown>;
|
|
34
|
+
/** The skill's `SKILL.md`. */
|
|
35
|
+
body: string;
|
|
36
|
+
files: SkillFileEntry[];
|
|
37
|
+
}
|
|
38
|
+
/**
|
|
39
|
+
* The shared read shape: the agent tool `dreamlake_skills_read` returns these
|
|
40
|
+
* fields plus its code-point paging fields (`start`, `end`, `total`, `next`,
|
|
41
|
+
* `complete`); here the whole file is returned, so there is no paging. The
|
|
42
|
+
* tool clips its file index to a budget and says so with `filesTruncated`;
|
|
43
|
+
* here `files` is always complete, so `filesTruncated` is `false` and
|
|
44
|
+
* `filesTotal === files.length`.
|
|
45
|
+
*/
|
|
46
|
+
export interface SkillReadResult {
|
|
47
|
+
tag: string;
|
|
48
|
+
commit: string;
|
|
49
|
+
skill: string;
|
|
50
|
+
renamedFrom?: string;
|
|
51
|
+
path: string;
|
|
52
|
+
sha256: string;
|
|
53
|
+
content: string;
|
|
54
|
+
/** Every file path in the skill, sorted. */
|
|
55
|
+
files: string[];
|
|
56
|
+
filesTotal: number;
|
|
57
|
+
/** Always `false`: the index is never clipped here. The agent tool sets `true` when it clipped its first page's index. */
|
|
58
|
+
filesTruncated: boolean;
|
|
59
|
+
}
|
|
60
|
+
export interface SkillFileResult {
|
|
61
|
+
status: 200 | 304;
|
|
62
|
+
tag: string;
|
|
63
|
+
commit: string;
|
|
64
|
+
path: string;
|
|
65
|
+
/** From the ETag; on 304 it names the representation the caller already holds. */
|
|
66
|
+
sha256: string;
|
|
67
|
+
/** Null on 304. */
|
|
68
|
+
content: string | null;
|
|
69
|
+
}
|
|
70
|
+
/** Fields every read surface exposes. */
|
|
71
|
+
export declare const SKILL_READ_FIELDS: readonly ["tag", "commit", "skill", "path", "sha256", "content", "files", "filesTotal", "filesTruncated"];
|
|
72
|
+
/** Present only when the request named a retired skill name. */
|
|
73
|
+
export declare const SKILL_READ_OPTIONAL_FIELDS: readonly ["renamedFrom"];
|
|
74
|
+
/** Fields only the paged agent tool carries: the code-point window of the page. */
|
|
75
|
+
export declare const SKILL_READ_PAGING_FIELDS: readonly ["start", "end", "total", "next", "complete"];
|
|
76
|
+
export declare const DEFAULT_SKILL_FILE = "SKILL.md";
|
|
77
|
+
/** The server's typed refusals and the status each one carries; the last two come only from the paged agent tool. */
|
|
78
|
+
export declare const SKILLS_ERROR_CODES: {
|
|
79
|
+
readonly skills_unavailable: 503;
|
|
80
|
+
readonly skills_lock_mismatch: 503;
|
|
81
|
+
readonly skill_not_found: 404;
|
|
82
|
+
readonly skill_file_not_found: 404;
|
|
83
|
+
readonly skill_path_invalid: 400;
|
|
84
|
+
readonly skill_file_binary: 415;
|
|
85
|
+
readonly skill_result_too_large: 413;
|
|
86
|
+
readonly skill_range_invalid: 400;
|
|
87
|
+
};
|
|
88
|
+
export type SkillsErrorCode = keyof typeof SKILLS_ERROR_CODES;
|
|
89
|
+
export declare const isSkillsErrorCode: (code: unknown) => code is SkillsErrorCode;
|
|
90
|
+
/** A refusal the skills registry defines. `code` is the identity callers branch on. */
|
|
91
|
+
export declare class SkillsError extends ApiError {
|
|
92
|
+
readonly code: SkillsErrorCode;
|
|
93
|
+
constructor(status: number, code: SkillsErrorCode, body?: unknown, requestId?: string);
|
|
94
|
+
}
|
|
95
|
+
/** Map a transport failure onto the typed refusal when it is one; other failures pass through. */
|
|
96
|
+
export declare function skillsFailure(error: unknown): unknown;
|
|
97
|
+
/** Skill names as the server validates them (`services/skillsBundle.ts`). */
|
|
98
|
+
export declare const SKILL_NAME: RegExp;
|
|
99
|
+
/** A relative, forward-slash path inside a skill: no `..`, no leading `/`, no empty segment. */
|
|
100
|
+
export declare const SKILL_FILE_PATH: RegExp;
|
|
101
|
+
export declare const skillContentSha256: (text: string) => string;
|
|
102
|
+
export declare function requireSkillName(skill: string): string;
|
|
103
|
+
/**
|
|
104
|
+
* The path as the server resolves it (`services/skillsTar.ts` safeRelativePath):
|
|
105
|
+
* `.` segments dropped, `..` refused — so the `path` returned is the one the
|
|
106
|
+
* file index lists and the agent tool reports.
|
|
107
|
+
*/
|
|
108
|
+
export declare function requireSkillPath(path: string): string;
|
|
109
|
+
export declare function skillsApi(t: Transport): {
|
|
110
|
+
list: () => Promise<SkillsList>;
|
|
111
|
+
skill: (name: string) => Promise<SkillDetail>;
|
|
112
|
+
read: (input: {
|
|
113
|
+
skill: string;
|
|
114
|
+
path?: string;
|
|
115
|
+
}) => Promise<SkillReadResult>;
|
|
116
|
+
file: (input: {
|
|
117
|
+
skill: string;
|
|
118
|
+
path: string;
|
|
119
|
+
ifNoneMatch?: string;
|
|
120
|
+
}) => Promise<SkillFileResult>;
|
|
121
|
+
};
|
|
122
|
+
export type SkillsApi = ReturnType<typeof skillsApi>;
|