@valethq/sdk 0.0.0-stage → 0.1.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/LICENSE +661 -0
- package/package.json +22 -4
- package/src/catalog.ts +53 -0
- package/src/context.ts +51 -0
- package/src/events.ts +103 -0
- package/src/http.ts +23 -0
- package/src/identity.ts +8 -0
- package/src/index.ts +14 -0
- package/src/inference.ts +121 -0
- package/src/manifest.ts +30 -0
- package/src/platform.ts +19 -0
- package/src/plugin.ts +60 -0
- package/src/scopes.ts +66 -0
- package/src/store.ts +194 -0
- package/src/tools.ts +44 -0
- package/src/version.ts +1 -0
- package/src/ws.ts +23 -0
- package/README.md +0 -3
package/src/store.ts
ADDED
|
@@ -0,0 +1,194 @@
|
|
|
1
|
+
import type { Denial } from "./events";
|
|
2
|
+
import type { ChannelBinding } from "./platform";
|
|
3
|
+
import type { Role, ToolResult } from "./tools";
|
|
4
|
+
|
|
5
|
+
export interface Project {
|
|
6
|
+
id: string;
|
|
7
|
+
name: string;
|
|
8
|
+
workspaceDir: string;
|
|
9
|
+
settings: Record<string, unknown>;
|
|
10
|
+
createdAt: number;
|
|
11
|
+
updatedAt: number;
|
|
12
|
+
}
|
|
13
|
+
export interface Session {
|
|
14
|
+
id: string;
|
|
15
|
+
projectId: string;
|
|
16
|
+
title: string | null;
|
|
17
|
+
color: string | null;
|
|
18
|
+
parentSessionId: string | null;
|
|
19
|
+
status: "idle" | "running" | "archived";
|
|
20
|
+
settings: SessionSettings;
|
|
21
|
+
providerState: Record<string, unknown>;
|
|
22
|
+
createdAt: number;
|
|
23
|
+
updatedAt: number;
|
|
24
|
+
lastMessageAt: number | null;
|
|
25
|
+
}
|
|
26
|
+
export interface SessionSettings {
|
|
27
|
+
model?: { provider: string; model: string; fallbacks?: { provider: string; model: string }[] };
|
|
28
|
+
persona?: string; // persona override; default comes from the project
|
|
29
|
+
titlePlaceholder?: string; // title derived from the first message; an auto title may replace it only while session.title still equals it
|
|
30
|
+
[pluginNamespace: string]: unknown; // e.g. "agent": { queueMode: "interrupt" }
|
|
31
|
+
}
|
|
32
|
+
export interface Run {
|
|
33
|
+
id: string;
|
|
34
|
+
sessionId: string;
|
|
35
|
+
triggerMessageId: string | null;
|
|
36
|
+
status: "queued" | "running" | "complete" | "cancelled" | "error" | "interrupted";
|
|
37
|
+
role: Role;
|
|
38
|
+
provider: string | null;
|
|
39
|
+
model: string | null;
|
|
40
|
+
startedAt: number | null;
|
|
41
|
+
endedAt: number | null;
|
|
42
|
+
error: string | null;
|
|
43
|
+
usage: Record<string, number>;
|
|
44
|
+
}
|
|
45
|
+
export interface Message {
|
|
46
|
+
id: string;
|
|
47
|
+
sessionId: string;
|
|
48
|
+
seq: number;
|
|
49
|
+
role: "user" | "assistant" | "system" | "tool";
|
|
50
|
+
authorPrincipalId: string | null;
|
|
51
|
+
runId: string | null;
|
|
52
|
+
status: "streaming" | "complete" | "error" | "interrupted";
|
|
53
|
+
origin: (ChannelBinding & { externalId?: string }) | null;
|
|
54
|
+
meta: Record<string, unknown>;
|
|
55
|
+
createdAt: number;
|
|
56
|
+
updatedAt: number;
|
|
57
|
+
}
|
|
58
|
+
export interface Part {
|
|
59
|
+
id: string;
|
|
60
|
+
messageId: string;
|
|
61
|
+
idx: number;
|
|
62
|
+
status: "streaming" | "complete" | "error" | "interrupted";
|
|
63
|
+
type: PartData["type"];
|
|
64
|
+
data: PartData;
|
|
65
|
+
createdAt: number;
|
|
66
|
+
updatedAt: number;
|
|
67
|
+
}
|
|
68
|
+
export interface Principal {
|
|
69
|
+
id: string;
|
|
70
|
+
displayName: string;
|
|
71
|
+
role: Role;
|
|
72
|
+
}
|
|
73
|
+
|
|
74
|
+
export type PartData =
|
|
75
|
+
| { type: "text"; text: string }
|
|
76
|
+
| { type: "reasoning"; text: string }
|
|
77
|
+
| {
|
|
78
|
+
type: "tool-call";
|
|
79
|
+
callId: string;
|
|
80
|
+
name: string;
|
|
81
|
+
title?: string;
|
|
82
|
+
input: unknown;
|
|
83
|
+
output?: string;
|
|
84
|
+
result?: ToolResult;
|
|
85
|
+
status: "pending" | "running" | "done" | "error" | "cancelled" | "denied";
|
|
86
|
+
}
|
|
87
|
+
| { type: "file"; blobId: string; name: string; mime: string }
|
|
88
|
+
| { type: "notice"; level: "info" | "warn" | "error"; text: string } // "turn interrupted by restart", "exec job 12 finished"
|
|
89
|
+
// by: "valet" or a harness label. Only a completed valet compaction with a summary changes valet's history.
|
|
90
|
+
| {
|
|
91
|
+
type: "compaction";
|
|
92
|
+
by: string;
|
|
93
|
+
status: "in_progress" | "completed" | "failed" | "cancelled";
|
|
94
|
+
coversThroughSeq: number;
|
|
95
|
+
summary?: string;
|
|
96
|
+
error?: string;
|
|
97
|
+
};
|
|
98
|
+
|
|
99
|
+
export type CancelledResult = { cancelled: true; cancelReason?: string; denied?: Denial };
|
|
100
|
+
export interface ActorRef {
|
|
101
|
+
principalId: string;
|
|
102
|
+
}
|
|
103
|
+
|
|
104
|
+
export interface Store {
|
|
105
|
+
/** A view whose writes carry this actor on `caller.actor`. The claim is vouched for by your plugin id, and hooks see both. A message write defaults the actor to its author. */
|
|
106
|
+
as(actor: ActorRef): Store;
|
|
107
|
+
projects: {
|
|
108
|
+
get(id: string): Project | undefined;
|
|
109
|
+
list(): Project[];
|
|
110
|
+
create(
|
|
111
|
+
p: Pick<Project, "name" | "workspaceDir"> & { settings?: Project["settings"] },
|
|
112
|
+
): Promise<Project | CancelledResult>;
|
|
113
|
+
update(
|
|
114
|
+
id: string,
|
|
115
|
+
patch: Partial<Pick<Project, "name" | "settings">>,
|
|
116
|
+
): Promise<Project | CancelledResult>;
|
|
117
|
+
};
|
|
118
|
+
sessions: {
|
|
119
|
+
get(id: string): Session | undefined;
|
|
120
|
+
list(q: { projectId?: string; status?: Session["status"]; limit?: number; before?: number }): Session[];
|
|
121
|
+
create(s: {
|
|
122
|
+
projectId: string;
|
|
123
|
+
title?: string;
|
|
124
|
+
settings?: SessionSettings;
|
|
125
|
+
parentSessionId?: string;
|
|
126
|
+
}): Promise<Session | CancelledResult>;
|
|
127
|
+
update(
|
|
128
|
+
id: string,
|
|
129
|
+
patch: Partial<Pick<Session, "title" | "color" | "status" | "settings">>,
|
|
130
|
+
): Promise<Session | CancelledResult>;
|
|
131
|
+
delete(id: string): Promise<Session | CancelledResult>;
|
|
132
|
+
setProviderState(id: string, provider: string, state: unknown): void; // no event: private bookkeeping for one provider
|
|
133
|
+
bind(id: string, binding: ChannelBinding): Promise<void>;
|
|
134
|
+
findByBinding(platform: string, conversationId: string): Session | undefined;
|
|
135
|
+
};
|
|
136
|
+
messages: {
|
|
137
|
+
list(
|
|
138
|
+
sessionId: string,
|
|
139
|
+
q?: { beforeSeq?: number; limit?: number },
|
|
140
|
+
): { message: Message; parts: Part[] }[];
|
|
141
|
+
create(m: {
|
|
142
|
+
sessionId: string;
|
|
143
|
+
role: Message["role"];
|
|
144
|
+
authorPrincipalId?: string;
|
|
145
|
+
runId?: string;
|
|
146
|
+
origin?: Message["origin"];
|
|
147
|
+
status?: Message["status"];
|
|
148
|
+
meta?: Record<string, unknown>;
|
|
149
|
+
parts: PartData[];
|
|
150
|
+
}): Promise<{ message: Message; parts: Part[] } | CancelledResult>;
|
|
151
|
+
/** Opens a streaming part; deltas go out as `message.delta` signals and are checkpointed to the row every 500ms. */
|
|
152
|
+
openPart(messageId: string, data: PartData): PartWriter;
|
|
153
|
+
complete(messageId: string, status: "complete" | "error" | "interrupted"): Promise<void>;
|
|
154
|
+
};
|
|
155
|
+
runs: {
|
|
156
|
+
get(id: string): Run | undefined;
|
|
157
|
+
create(r: { sessionId: string; triggerMessageId?: string; role: Role }): Run;
|
|
158
|
+
update(
|
|
159
|
+
id: string,
|
|
160
|
+
patch: Partial<Pick<Run, "status" | "provider" | "model" | "error">> & {
|
|
161
|
+
usage?: Record<string, number>;
|
|
162
|
+
},
|
|
163
|
+
): void;
|
|
164
|
+
cancel(id: string, by: string): Promise<void>; // emits run.cancel
|
|
165
|
+
};
|
|
166
|
+
principals: {
|
|
167
|
+
get(id: string): Principal | undefined;
|
|
168
|
+
resolveIdentity(platform: string, externalId: string, fallback?: { displayName: string }): Principal; // unknown -> new guest
|
|
169
|
+
link(principalId: string, platform: string, externalId: string): Promise<void>;
|
|
170
|
+
setRole(principalId: string, role: Role): Promise<void>;
|
|
171
|
+
};
|
|
172
|
+
blobs: {
|
|
173
|
+
put(bytes: Uint8Array | Blob, meta: { mime?: string; name?: string }): Promise<{ id: string }>;
|
|
174
|
+
path(id: string): string;
|
|
175
|
+
};
|
|
176
|
+
}
|
|
177
|
+
|
|
178
|
+
export interface PartWriter {
|
|
179
|
+
readonly partId: string;
|
|
180
|
+
append(delta: string): void;
|
|
181
|
+
replace(data: PartData): void;
|
|
182
|
+
close(status: "complete" | "error" | "interrupted", final?: PartData): void;
|
|
183
|
+
}
|
|
184
|
+
|
|
185
|
+
export interface PluginStorage {
|
|
186
|
+
kv: {
|
|
187
|
+
get<T>(key: string): T | undefined;
|
|
188
|
+
set(key: string, value: unknown): void;
|
|
189
|
+
delete(key: string): void;
|
|
190
|
+
list(prefix?: string): string[];
|
|
191
|
+
};
|
|
192
|
+
/** Plugin-owned tables, named p_<namespace>_*. Migrations run before activate(). */
|
|
193
|
+
sql: { migrate(migrations: { id: string; up: string }[]): void; db: import("bun:sqlite").Database };
|
|
194
|
+
}
|
package/src/tools.ts
ADDED
|
@@ -0,0 +1,44 @@
|
|
|
1
|
+
import type { Caller } from "./events";
|
|
2
|
+
|
|
3
|
+
export type Role = "owner" | "trusted" | "guest";
|
|
4
|
+
|
|
5
|
+
export interface ToolSpec {
|
|
6
|
+
name: string;
|
|
7
|
+
description: string;
|
|
8
|
+
inputSchema: Record<string, unknown>;
|
|
9
|
+
}
|
|
10
|
+
|
|
11
|
+
export interface ToolDefinition<Input = unknown> extends ToolSpec {
|
|
12
|
+
/** Lowest role this tool serves (the run's effective role, section 8.3). The providing plugin enforces it: the SDK's `defineTool` applies it in `list` and again in `invoke`. Core and valet-agent do not. Default "owner". */
|
|
13
|
+
minRole?: Role;
|
|
14
|
+
timeoutMs?: number;
|
|
15
|
+
invoke(input: Input, call: ToolCall): Promise<ToolResult>;
|
|
16
|
+
}
|
|
17
|
+
|
|
18
|
+
export interface ToolCall {
|
|
19
|
+
sessionId: string;
|
|
20
|
+
runId: string;
|
|
21
|
+
callId: string;
|
|
22
|
+
role: Role;
|
|
23
|
+
/** Stamped by core: the plugin making the call and the principal behind the run. */
|
|
24
|
+
caller: Caller;
|
|
25
|
+
cwd: string;
|
|
26
|
+
signal: AbortSignal;
|
|
27
|
+
/** Streams partial output to the tool-call part and to WS subscribers. */
|
|
28
|
+
progress(update: { outputDelta?: string; status?: string }): void;
|
|
29
|
+
}
|
|
30
|
+
|
|
31
|
+
export interface ToolResult {
|
|
32
|
+
content: ({ type: "text"; text: string } | { type: "image"; mime: string; blobId: string })[];
|
|
33
|
+
isError?: boolean;
|
|
34
|
+
meta?: Record<string, unknown>;
|
|
35
|
+
}
|
|
36
|
+
|
|
37
|
+
export interface ToolProvider {
|
|
38
|
+
/** Re-read on each run, so tools can depend on session or project. */
|
|
39
|
+
list(scope: {
|
|
40
|
+
sessionId: string;
|
|
41
|
+
projectId: string;
|
|
42
|
+
role: Role;
|
|
43
|
+
}): ToolDefinition[] | Promise<ToolDefinition[]>;
|
|
44
|
+
}
|
package/src/version.ts
ADDED
|
@@ -0,0 +1 @@
|
|
|
1
|
+
export const CORE_API_VERSION = "0.1.0";
|
package/src/ws.ts
ADDED
|
@@ -0,0 +1,23 @@
|
|
|
1
|
+
import type { RequestContext } from "./http";
|
|
2
|
+
import type { Disposable } from "./plugin";
|
|
3
|
+
|
|
4
|
+
export type ClientFrame =
|
|
5
|
+
| { type: "sub"; topics: string[]; since?: Record<string, number> } // resume from per-topic seq
|
|
6
|
+
| { type: "unsub"; topics: string[] }
|
|
7
|
+
| { type: "call"; id: string; method: string; params?: unknown } // routed to a plugin handler by "<namespace>." prefix
|
|
8
|
+
| { type: "ping" };
|
|
9
|
+
|
|
10
|
+
export type ServerFrame =
|
|
11
|
+
| { type: "event"; topic: string; seq: number; name: string; data: unknown }
|
|
12
|
+
| { type: "result"; id: string; ok: true; data?: unknown }
|
|
13
|
+
| { type: "result"; id: string; ok: false; error: { code: string; message: string } } // code "denied" carries the Denial
|
|
14
|
+
| { type: "gap"; topic: string } // asked-for seq fell off the buffer: refetch state over REST
|
|
15
|
+
| { type: "pong" };
|
|
16
|
+
|
|
17
|
+
export interface WsHost {
|
|
18
|
+
handle(
|
|
19
|
+
method: string,
|
|
20
|
+
fn: (params: unknown, ctx: RequestContext) => unknown | Promise<unknown>,
|
|
21
|
+
): Disposable;
|
|
22
|
+
publish(topic: string, name: string, data: unknown): void;
|
|
23
|
+
}
|
package/README.md
DELETED