Skip to content

Commit 5a10f46

Browse files
steipetesteipete
committed
docs: document sdk package facades
1 parent bdfeece commit 5a10f46

10 files changed

Lines changed: 55 additions & 0 deletions

File tree

‎packages/gateway-client/src/index.ts‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,5 @@
1+
// Public gateway-client package surface: connection client, device auth,
2+
// readiness helpers, event-loop readiness, and timeout utilities.
13
export * from "./client.js";
24
export * from "./device-auth.js";
35
export * from "./event-loop-ready.js";

‎packages/llm-runtime/src/index.ts‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,4 @@
1+
// Public LLM runtime package surface for provider registry and stream helpers.
12
export {
23
clearApiProviders,
34
getApiProvider,

‎packages/net-policy/src/index.ts‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,5 @@
1+
// Public network policy package surface for IP parsing, redaction, and URL
2+
// userinfo stripping helpers.
13
export * from "./ip.js";
24
export * from "./ipv4.js";
35
export * from "./redact-sensitive-url.js";

‎packages/net-policy/src/url-userinfo.ts‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,4 @@
1+
/** Strip username/password credentials from a URL string when it parses. */
12
export function stripUrlUserInfo(value: string): string {
23
try {
34
const parsed = new URL(value);

‎packages/sdk/src/client.ts‎

Lines changed: 18 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -28,10 +28,13 @@ import type {
2828
ToolInvokeResult,
2929
} from "./types.js";
3030

31+
// High-level OpenClaw SDK client. Namespaces below translate friendly SDK calls
32+
// into current Gateway RPC methods and normalize event streams for consumers.
3133
const MAX_REPLAY_RUNS = 100;
3234
const MAX_REPLAY_EVENTS_PER_RUN = 500;
3335
const MAX_NORMALIZED_REPLAY_EVENTS = 2000;
3436

37+
/** Connection and transport options for the OpenClaw SDK client. */
3538
export type OpenClawOptions = {
3639
gateway?: "auto" | (string & {});
3740
url?: string;
@@ -52,6 +55,8 @@ function resolveGatewayUrl(options: OpenClawOptions): string | undefined {
5255
}
5356

5457
function runStatusFromWaitPayload(payload: unknown): RunResult["status"] {
58+
// Gateway wait payloads come from several runtime paths. Preserve timeout vs
59+
// cancellation semantics from metadata instead of trusting one status field.
5560
const record =
5661
typeof payload === "object" && payload !== null
5762
? (payload as Record<string, unknown> & { aborted?: unknown; status?: unknown })
@@ -300,6 +305,7 @@ function normalizeChatProjectionEvent(
300305
};
301306
}
302307

308+
/** Root SDK client with namespaces for agents, sessions, runs, and gateway APIs. */
303309
export class OpenClaw {
304310
readonly agents: AgentsNamespace;
305311
readonly sessions: SessionsNamespace;
@@ -541,6 +547,7 @@ export class OpenClaw {
541547
}
542548
}
543549

550+
/** Agent-scoped helper for runs and identity lookups. */
544551
export class Agent {
545552
constructor(
546553
private readonly client: OpenClaw,
@@ -561,6 +568,7 @@ export class Agent {
561568
}
562569
}
563570

571+
/** Run handle for streaming events, waiting, and cancellation. */
564572
export class Run {
565573
constructor(
566574
private readonly client: OpenClaw,
@@ -607,6 +615,7 @@ export class Run {
607615
}
608616
}
609617

618+
/** Session handle for sending messages and session-scoped mutations. */
610619
export class Session {
611620
constructor(
612621
private readonly client: OpenClaw,
@@ -642,6 +651,7 @@ export class Session {
642651
}
643652
}
644653

654+
/** Agent management namespace. */
645655
export class AgentsNamespace {
646656
constructor(private readonly client: OpenClaw) {}
647657

@@ -666,6 +676,7 @@ export class AgentsNamespace {
666676
}
667677
}
668678

679+
/** Session management namespace. */
669680
export class SessionsNamespace {
670681
constructor(private readonly client: OpenClaw) {}
671682

@@ -698,6 +709,7 @@ export class SessionsNamespace {
698709
}
699710
}
700711

712+
/** Run creation and lifecycle namespace. */
701713
export class RunsNamespace {
702714
constructor(private readonly client: OpenClaw) {}
703715

@@ -746,6 +758,7 @@ class RpcNamespace {
746758
}
747759
}
748760

761+
/** Task query and cancellation namespace. */
749762
export class TasksNamespace extends RpcNamespace {
750763
constructor(client: OpenClaw) {
751764
super(client, "tasks");
@@ -767,6 +780,7 @@ export class TasksNamespace extends RpcNamespace {
767780
}
768781
}
769782

783+
/** Model catalog and auth status namespace. */
770784
export class ModelsNamespace extends RpcNamespace {
771785
constructor(client: OpenClaw) {
772786
super(client, "models");
@@ -781,6 +795,7 @@ export class ModelsNamespace extends RpcNamespace {
781795
}
782796
}
783797

798+
/** Tool catalog, effective tool, and direct invocation namespace. */
784799
export class ToolsNamespace extends RpcNamespace {
785800
constructor(client: OpenClaw) {
786801
super(client, "tools");
@@ -806,6 +821,7 @@ export class ToolsNamespace extends RpcNamespace {
806821
}
807822
}
808823

824+
/** Run/session artifact listing and download namespace. */
809825
export class ArtifactsNamespace extends RpcNamespace {
810826
constructor(client: OpenClaw) {
811827
super(client, "artifacts");
@@ -830,6 +846,7 @@ export class ArtifactsNamespace extends RpcNamespace {
830846
}
831847
}
832848

849+
/** Approval request listing and response namespace. */
833850
export class ApprovalsNamespace {
834851
constructor(private readonly client: OpenClaw) {}
835852

@@ -842,6 +859,7 @@ export class ApprovalsNamespace {
842859
}
843860
}
844861

862+
/** Environment discovery namespace. */
845863
export class EnvironmentsNamespace extends RpcNamespace {
846864
constructor(client: OpenClaw) {
847865
super(client, "environments");

‎packages/sdk/src/event-hub.ts‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,15 +1,19 @@
11
import type { GatewayEvent } from "./types.js";
22

3+
// Async event hub with bounded replay for SDK event streams.
34
type Listener<T> = (event: T) => void;
45

6+
/** Replay settings for EventHub streams. */
57
export type EventHubOptions = {
68
replayLimit?: number;
79
};
810

11+
/** Per-stream options for including replayed events. */
912
export type EventStreamOptions = {
1013
replay?: boolean;
1114
};
1215

16+
/** Small publish/subscribe hub used by SDK transports and normalized events. */
1317
export class EventHub<T> {
1418
private readonly replayLimit: number;
1519
private readonly replayEvents: T[] = [];

‎packages/sdk/src/index.ts‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,5 @@
1+
// Public OpenClaw SDK entrypoint. Re-export client namespaces, event helpers,
2+
// transport, and stable SDK types from focused modules.
13
export {
24
Agent,
35
AgentsNamespace,

‎packages/sdk/src/normalize.ts‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,6 @@
11
import type { GatewayEvent, JsonObject, OpenClawEvent, OpenClawEventType } from "./types.js";
22

3+
// Normalize raw Gateway events into stable SDK event types and common metadata.
34
function asRecord(value: unknown): JsonObject {
45
return typeof value === "object" && value !== null ? (value as JsonObject) : {};
56
}
@@ -152,6 +153,7 @@ function normalizeNamedEventType(event: GatewayEvent): OpenClawEventType {
152153
}
153154
}
154155

156+
/** Normalize a raw Gateway event into the public SDK event shape. */
155157
export function normalizeGatewayEvent(event: GatewayEvent): OpenClawEvent {
156158
const payload = asRecord(event.payload);
157159
const runId = readString(payload.runId);

‎packages/sdk/src/transport.ts‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -7,6 +7,8 @@ import type {
77
OpenClawTransport,
88
} from "./types.js";
99

10+
// Gateway transport adapter that converts the lower-level GatewayClient into the
11+
// SDK transport interface and replays raw events for late subscribers.
1012
type GatewayClientLike = {
1113
request<T = unknown>(
1214
method: string,
@@ -18,6 +20,7 @@ type GatewayClientLike = {
1820

1921
const RAW_EVENT_REPLAY_LIMIT = 1000;
2022

23+
/** Options passed through to the Gateway websocket client. */
2124
export type GatewayClientTransportOptions = {
2225
url?: string;
2326
connectChallengeTimeoutMs?: number;
@@ -66,6 +69,7 @@ function toGatewayEvent(event: unknown): GatewayEvent {
6669
};
6770
}
6871

72+
/** Connectable SDK transport backed by @openclaw/gateway-client. */
6973
export class GatewayClientTransport implements ConnectableOpenClawTransport {
7074
private readonly eventsHub = new EventHub<GatewayEvent>({
7175
replayLimit: RAW_EVENT_REPLAY_LIMIT,
@@ -147,6 +151,7 @@ export class GatewayClientTransport implements ConnectableOpenClawTransport {
147151
}
148152
}
149153

154+
/** Narrow an SDK transport to one that supports explicit connect. */
150155
export function isConnectableTransport(
151156
transport: OpenClawTransport,
152157
): transport is ConnectableOpenClawTransport {

‎packages/sdk/src/types.ts‎

Lines changed: 18 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,17 +1,22 @@
1+
// Public SDK data contracts for Gateway transport, runs, sessions, tools,
2+
// artifacts, tasks, environments, and normalized event streams.
13
export type JsonObject = Record<string, unknown>;
24

5+
/** Per-request options accepted by SDK transports. */
36
export type GatewayRequestOptions = {
47
expectFinal?: boolean;
58
timeoutMs?: number | null;
69
};
710

11+
/** Raw event payload emitted by the Gateway transport. */
812
export type GatewayEvent = {
913
event: string;
1014
payload?: unknown;
1115
seq?: number;
1216
stateVersion?: unknown;
1317
};
1418

19+
/** Minimal transport interface consumed by the OpenClaw SDK client. */
1520
export type OpenClawTransport = {
1621
request<T = unknown>(
1722
method: string,
@@ -22,17 +27,20 @@ export type OpenClawTransport = {
2227
close?(): Promise<void> | void;
2328
};
2429

30+
/** Transport variant that requires an explicit connection step. */
2531
export type ConnectableOpenClawTransport = OpenClawTransport & {
2632
connect(): Promise<void>;
2733
};
2834

35+
/** Desired runtime/harness selection for future per-run execution routing. */
2936
export type RuntimeSelection =
3037
| "auto"
3138
| { type: "embedded"; id: "openclaw" | "codex" | (string & {}) }
3239
| { type: "cli"; id: "claude-cli" | (string & {}) }
3340
| { type: "acp"; harness: "claude" | "cursor" | "gemini" | "opencode" | (string & {}) }
3441
| { type: "managed"; provider: "local" | "node" | "testbox" | "cloud" | (string & {}) };
3542

43+
/** Desired execution environment selection for future per-run routing. */
3644
export type EnvironmentSelection =
3745
| { type: "local"; cwd?: string }
3846
| { type: "gateway"; url?: string; cwd?: string }
@@ -60,6 +68,7 @@ export type WorkspaceSelection = {
6068

6169
export type ApprovalMode = "ask" | "never" | "auto" | "trusted";
6270

71+
/** Terminal and non-terminal status values returned by Run.wait. */
6372
export type RunStatus = "accepted" | "completed" | "failed" | "cancelled" | "timed_out";
6473

6574
export type RunTimestamp = string | number;
@@ -71,6 +80,7 @@ export type SDKMessage = {
7180
toolCallId?: string;
7281
};
7382

83+
/** Metadata for an artifact attached to a run, task, or session. */
7484
export type ArtifactSummary = {
7585
id: string;
7686
runId?: string;
@@ -122,6 +132,7 @@ export type ArtifactsDownloadResult = {
122132

123133
export type TaskStatus = "queued" | "running" | "completed" | "failed" | "cancelled" | "timed_out";
124134

135+
/** Gateway task summary returned by task list/get calls. */
125136
export type TaskSummary = {
126137
id: string;
127138
taskId?: string;
@@ -176,6 +187,7 @@ export type SDKError = {
176187
details?: unknown;
177188
};
178189

190+
/** Parameters for direct tool invocation through the SDK. */
179191
export type ToolInvokeParams = {
180192
args?: JsonObject;
181193
sessionKey?: string;
@@ -194,6 +206,7 @@ export type ToolInvokeResult = {
194206
error?: SDKError;
195207
};
196208

209+
/** Normalized result returned by Run.wait. */
197210
export type RunResult = {
198211
runId: string;
199212
status: RunStatus;
@@ -217,6 +230,7 @@ export type RunResult = {
217230
raw?: unknown;
218231
};
219232

233+
/** Stable SDK event type taxonomy derived from raw Gateway events. */
220234
export type OpenClawEventType =
221235
| "run.created"
222236
| "run.queued"
@@ -247,6 +261,7 @@ export type OpenClawEventType =
247261
| "git.pr"
248262
| "raw";
249263

264+
/** Normalized SDK event with common run/session/task metadata. */
250265
export type OpenClawEvent<TData = unknown> = {
251266
version: 1;
252267
id: string;
@@ -261,6 +276,7 @@ export type OpenClawEvent<TData = unknown> = {
261276
raw?: GatewayEvent;
262277
};
263278

279+
/** Parameters for creating an agent run. */
264280
export type AgentRunParams = {
265281
input: string;
266282
agentId?: string;
@@ -279,6 +295,7 @@ export type AgentRunParams = {
279295
idempotencyKey?: string;
280296
};
281297

298+
/** Parameters for creating a session. */
282299
export type SessionCreateParams = {
283300
key?: string;
284301
agentId?: string;
@@ -289,6 +306,7 @@ export type SessionCreateParams = {
289306
message?: string;
290307
};
291308

309+
/** Parameters for sending a message to an existing session. */
292310
export type SessionSendParams = {
293311
key: string;
294312
message: string;

0 commit comments

Comments
 (0)