@valethq/sdk 0.0.0-stage → 0.2.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/src/store.ts ADDED
@@ -0,0 +1,204 @@
1
+ import type { Denial } from "./events";
2
+ import type { PartTypes } from "./parttypes";
3
+ import type { ChannelBinding } from "./platform";
4
+ import type { Role, ToolResult } from "./tools";
5
+
6
+ export interface Project {
7
+ id: string;
8
+ name: string;
9
+ workspaceDir: string;
10
+ settings: Record<string, unknown>;
11
+ createdAt: number;
12
+ updatedAt: number;
13
+ }
14
+ export interface Session {
15
+ id: string;
16
+ projectId: string;
17
+ title: string | null;
18
+ color: string | null;
19
+ parentSessionId: string | null;
20
+ status: "idle" | "running" | "archived";
21
+ settings: SessionSettings;
22
+ providerState: Record<string, unknown>;
23
+ createdAt: number;
24
+ updatedAt: number;
25
+ lastMessageAt: number | null;
26
+ /** When the model last answered (latest assistant message); null until it has. */
27
+ lastResponseAt: number | null;
28
+ }
29
+ export interface SessionSettings {
30
+ model?: { provider: string; model: string; fallbacks?: { provider: string; model: string }[] };
31
+ persona?: string; // persona override; default comes from the project
32
+ titlePlaceholder?: string; // title derived from the first message; an auto title may replace it only while session.title still equals it
33
+ [pluginNamespace: string]: unknown; // e.g. "agent": { queueMode: "interrupt" }
34
+ }
35
+ export interface Run {
36
+ id: string;
37
+ sessionId: string;
38
+ triggerMessageId: string | null;
39
+ status: "queued" | "running" | "complete" | "cancelled" | "error" | "interrupted";
40
+ role: Role;
41
+ provider: string | null;
42
+ model: string | null;
43
+ startedAt: number | null;
44
+ endedAt: number | null;
45
+ error: string | null;
46
+ usage: Record<string, number>;
47
+ }
48
+ export interface Message {
49
+ id: string;
50
+ sessionId: string;
51
+ seq: number;
52
+ role: "user" | "assistant" | "system" | "tool";
53
+ authorPrincipalId: string | null;
54
+ runId: string | null;
55
+ status: "streaming" | "complete" | "error" | "interrupted";
56
+ origin: (ChannelBinding & { externalId?: string }) | null;
57
+ meta: Record<string, unknown>;
58
+ createdAt: number;
59
+ updatedAt: number;
60
+ }
61
+ export interface Part {
62
+ id: string;
63
+ messageId: string;
64
+ idx: number;
65
+ status: "streaming" | "complete" | "error" | "interrupted";
66
+ type: PartData["type"];
67
+ data: PartData;
68
+ createdAt: number;
69
+ updatedAt: number;
70
+ }
71
+ export interface Principal {
72
+ id: string;
73
+ displayName: string;
74
+ role: Role;
75
+ }
76
+
77
+ export type PartData =
78
+ | { type: "text"; text: string }
79
+ | { type: "reasoning"; text: string }
80
+ | {
81
+ type: "tool-call";
82
+ callId: string;
83
+ name: string;
84
+ title?: string;
85
+ input: unknown;
86
+ output?: string;
87
+ result?: ToolResult;
88
+ status: "pending" | "running" | "done" | "error" | "cancelled" | "denied";
89
+ }
90
+ | { type: "file"; blobId: string; name: string; mime: string }
91
+ | { type: "notice"; level: "info" | "warn" | "error"; text: string } // "turn interrupted by restart", "exec job 12 finished"
92
+ // by: "valet" or a harness label. Only a completed valet compaction with a summary changes valet's history.
93
+ | {
94
+ type: "compaction";
95
+ by: string;
96
+ status: "in_progress" | "completed" | "failed" | "cancelled";
97
+ coversThroughSeq: number;
98
+ summary?: string;
99
+ error?: string;
100
+ }
101
+ // kind: a registered part type id (9.4). title is the collapsed header, text what the model sees.
102
+ | { type: "custom"; kind: string; title: string; text: string; data: unknown };
103
+
104
+ export type CancelledResult = { cancelled: true; cancelReason?: string; denied?: Denial };
105
+ export interface ActorRef {
106
+ principalId: string;
107
+ }
108
+
109
+ export interface Store {
110
+ /** 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. */
111
+ as(actor: ActorRef): Store;
112
+ projects: {
113
+ get(id: string): Project | undefined;
114
+ list(): Project[];
115
+ create(
116
+ p: Pick<Project, "name" | "workspaceDir"> & { settings?: Project["settings"] },
117
+ ): Promise<Project | CancelledResult>;
118
+ // spec-gap: workspaceDir is patchable (relocate) and delete exists; the doc's Store lists neither.
119
+ update(
120
+ id: string,
121
+ patch: Partial<Pick<Project, "name" | "workspaceDir" | "settings">>,
122
+ ): Promise<Project | CancelledResult>;
123
+ /** Unregisters the project; refuses while it still has sessions. Never touches the directory. */
124
+ delete(id: string): Promise<Project | CancelledResult>;
125
+ };
126
+ sessions: {
127
+ get(id: string): Session | undefined;
128
+ list(q: { projectId?: string; status?: Session["status"]; limit?: number; before?: number }): Session[];
129
+ create(s: {
130
+ projectId: string;
131
+ title?: string;
132
+ settings?: SessionSettings;
133
+ parentSessionId?: string;
134
+ }): Promise<Session | CancelledResult>;
135
+ update(
136
+ id: string,
137
+ patch: Partial<Pick<Session, "title" | "color" | "status" | "settings">>,
138
+ ): Promise<Session | CancelledResult>;
139
+ delete(id: string): Promise<Session | CancelledResult>;
140
+ setProviderState(id: string, provider: string, state: unknown): void; // no event: private bookkeeping for one provider
141
+ bind(id: string, binding: ChannelBinding): Promise<void>;
142
+ findByBinding(platform: string, conversationId: string): Session | undefined;
143
+ };
144
+ messages: {
145
+ list(
146
+ sessionId: string,
147
+ q?: { beforeSeq?: number; limit?: number },
148
+ ): { message: Message; parts: Part[] }[];
149
+ create(m: {
150
+ sessionId: string;
151
+ role: Message["role"];
152
+ authorPrincipalId?: string;
153
+ runId?: string;
154
+ origin?: Message["origin"];
155
+ status?: Message["status"];
156
+ meta?: Record<string, unknown>;
157
+ parts: PartData[];
158
+ }): Promise<{ message: Message; parts: Part[] } | CancelledResult>;
159
+ /** Opens a streaming part; deltas go out as `message.delta` signals and are checkpointed to the row every 500ms. */
160
+ openPart(messageId: string, data: PartData): PartWriter;
161
+ complete(messageId: string, status: "complete" | "error" | "interrupted"): Promise<void>;
162
+ };
163
+ runs: {
164
+ get(id: string): Run | undefined;
165
+ create(r: { sessionId: string; triggerMessageId?: string; role: Role }): Run;
166
+ update(
167
+ id: string,
168
+ patch: Partial<Pick<Run, "status" | "provider" | "model" | "error">> & {
169
+ usage?: Record<string, number>;
170
+ },
171
+ ): void;
172
+ cancel(id: string, by: string): Promise<void>; // emits run.cancel
173
+ };
174
+ principals: {
175
+ get(id: string): Principal | undefined;
176
+ resolveIdentity(platform: string, externalId: string, fallback?: { displayName: string }): Principal; // unknown -> new guest
177
+ link(principalId: string, platform: string, externalId: string): Promise<void>;
178
+ setRole(principalId: string, role: Role): Promise<void>;
179
+ };
180
+ /** Plugin-defined part types (9.4). */
181
+ partTypes: PartTypes;
182
+ blobs: {
183
+ put(bytes: Uint8Array | Blob, meta: { mime?: string; name?: string }): Promise<{ id: string }>;
184
+ path(id: string): string;
185
+ };
186
+ }
187
+
188
+ export interface PartWriter {
189
+ readonly partId: string;
190
+ append(delta: string): void;
191
+ replace(data: PartData): void;
192
+ close(status: "complete" | "error" | "interrupted", final?: PartData): void;
193
+ }
194
+
195
+ export interface PluginStorage {
196
+ kv: {
197
+ get<T>(key: string): T | undefined;
198
+ set(key: string, value: unknown): void;
199
+ delete(key: string): void;
200
+ list(prefix?: string): string[];
201
+ };
202
+ /** Plugin-owned tables, named p_<namespace>_*. Migrations run before activate(). */
203
+ sql: { migrate(migrations: { id: string; up: string }[]): void; db: import("bun:sqlite").Database };
204
+ }
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
@@ -1,3 +0,0 @@
1
- # Temporary Holding Version
2
-
3
- This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.