@agentorg/computer-sdk 0.0.0-stage → 0.0.35

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.
@@ -0,0 +1,282 @@
1
+ import type { components } from "./generated/schema.js";
2
+ type Schemas = components["schemas"];
3
+ export type ComputerInfo = Schemas["Computer"];
4
+ export type ComputerDetail = Schemas["ComputerDetail"];
5
+ export type ServiceInfo = Schemas["ServiceInfo"];
6
+ export type ComputerLog = Schemas["ComputerLogs"]["logs"][number];
7
+ export type LiveSurface = Schemas["Surface"];
8
+ export type LiveMode = Schemas["LiveMode"];
9
+ export type LiveSession = Schemas["LiveSession"];
10
+ /**
11
+ * What happens to a terminal, as it happens: the agent's command or a person's shell. And
12
+ * `refused`, with why, when what this connection asked wasn't done.
13
+ */
14
+ export type TerminalEvent = Schemas["TerminalEvent"];
15
+ export interface LiveHandle {
16
+ close(): void;
17
+ /** Resolves when the socket closes, with why. */
18
+ closed: Promise<{
19
+ code: number;
20
+ reason: string;
21
+ }>;
22
+ }
23
+ /** What an operating connection can do. What can't be done comes back as a `refused` event. */
24
+ export interface TerminalsHandle extends LiveHandle {
25
+ /** Start a shell of your own. It arrives as a `start` event, which carries its id. */
26
+ openShell(columns: number, rows: number): void;
27
+ /** Type into a running terminal, the agent's included: a long text as several messages. */
28
+ sendInput(id: string, text: string): void;
29
+ resize(id: string, columns: number, rows: number): void;
30
+ stop(id: string): void;
31
+ }
32
+ export interface ConnectionOpts {
33
+ /** The control token; `AGENTCOMPUTER_API_KEY` by default. */
34
+ apiKey?: string;
35
+ /** The service's address; `AGENTCOMPUTER_API_URL`, else `http://127.0.0.1:7878`. */
36
+ apiUrl?: string;
37
+ }
38
+ export interface CreateOpts extends ConnectionOpts {
39
+ access: Schemas["Access"];
40
+ browser?: boolean;
41
+ /** How it is isolated: a container by default, and no other is offered now. */
42
+ isolation?: Schemas["Isolation"];
43
+ workspace?: string;
44
+ /** A folder whose files its workspace starts with, copied once when it is made. */
45
+ copyFrom?: string;
46
+ name?: string;
47
+ /** How long until it stops, in milliseconds. By default it doesn't. */
48
+ timeoutMs?: number;
49
+ metadata?: Record<string, string>;
50
+ }
51
+ /** This computer, attached whole: its files and commands reach all of it, as the service's user. */
52
+ export interface AttachOpts extends Omit<CreateOpts, "isolation" | "workspace" | "copyFrom" | "browser"> {
53
+ /** Its work folder, where commands and relative paths start. Detaching never removes it. */
54
+ workspace: string;
55
+ /** A headless browser of its own, or the person's own browser, signed in. */
56
+ browser?: boolean | "own";
57
+ /** Whether its agent has the machine's screen, through Cua Driver. */
58
+ screen?: boolean;
59
+ }
60
+ export interface CommandResult {
61
+ exitCode: number;
62
+ output: string;
63
+ seconds: number;
64
+ }
65
+ export interface RunningCommand {
66
+ sessionId: string;
67
+ output: string;
68
+ }
69
+ /** The service refused, or a computer's tool failed. */
70
+ export declare class ComputerError extends Error {
71
+ readonly code: number;
72
+ constructor(code: number, message: string);
73
+ }
74
+ /** What the command tools answer. */
75
+ interface CommandAnswer {
76
+ exit_code: number | null;
77
+ seconds: number;
78
+ session_id: string | null;
79
+ text: string;
80
+ }
81
+ /** An MCP client for one endpoint, connected when first used. */
82
+ declare class Endpoint {
83
+ #private;
84
+ constructor(url: string | null, token: string);
85
+ text(name: string, args: Record<string, unknown>): Promise<string>;
86
+ command(name: string, args: Record<string, unknown>): Promise<CommandAnswer>;
87
+ close(): Promise<void>;
88
+ }
89
+ type Opener = (surface: LiveSurface, mode: LiveMode) => Promise<LiveSession>;
90
+ /** Every terminal on the computer: the agent's commands and a person's shells alike. */
91
+ declare class Terminals {
92
+ #private;
93
+ constructor(open: Opener);
94
+ /**
95
+ * Each terminal as it starts, writes and exits: those already there first, each with the end of
96
+ * what it wrote. Operating, the default, can also open a shell and act on any of them.
97
+ */
98
+ connect(opts: {
99
+ onEvent: (event: TerminalEvent) => void;
100
+ mode?: LiveMode;
101
+ }): Promise<TerminalsHandle>;
102
+ }
103
+ /** Commands on a computer with the terminal level. */
104
+ declare class Commands {
105
+ #private;
106
+ constructor(endpoint: Endpoint);
107
+ /** Run a command to its end. */
108
+ run(cmd: string, opts?: {
109
+ cwd?: string;
110
+ }): Promise<CommandResult>;
111
+ /** Start a command and return while it runs, unless it ends at once. */
112
+ run(cmd: string, opts: {
113
+ cwd?: string;
114
+ background: true;
115
+ }): Promise<RunningCommand | CommandResult>;
116
+ /** Type into a running command, and return what it wrote since. */
117
+ sendStdin(sessionId: string, data: string): Promise<string>;
118
+ }
119
+ /** Files in a computer's workspace. */
120
+ declare class Files {
121
+ #private;
122
+ constructor(endpoint: Endpoint);
123
+ /** A text file's content, whole: a line too long for the tool to return is an error. */
124
+ read(path: string): Promise<string>;
125
+ /** Make a new file, or fill an empty one. */
126
+ write(path: string, content: string): Promise<void>;
127
+ /** Replace exact text, and return the unified diff. */
128
+ edit(path: string, oldText: string, newText: string, opts?: {
129
+ replaceAll?: boolean;
130
+ }): Promise<string>;
131
+ /** A folder's entries, the first thousand. */
132
+ list(path?: string): Promise<({
133
+ name: string;
134
+ type: "dir";
135
+ size?: undefined;
136
+ } | {
137
+ name: string;
138
+ type: "file";
139
+ size: number;
140
+ })[]>;
141
+ /** Lines matching text under a folder, as `path:line:text`. */
142
+ search(pattern: string, opts?: {
143
+ path?: string;
144
+ regex?: boolean;
145
+ }): Promise<string[]>;
146
+ }
147
+ /** One computer. Make one with `Computer.create`. */
148
+ export declare class Computer {
149
+ #private;
150
+ readonly computerID: string;
151
+ readonly commands: Commands;
152
+ readonly files: Files;
153
+ readonly terminals: Terminals;
154
+ private constructor();
155
+ static create(opts: CreateOpts): Promise<Computer>;
156
+ /** This computer, attached whole. Killing it detaches it and removes nothing of the machine's. */
157
+ static attach(opts: AttachOpts): Promise<Computer>;
158
+ /** A computer made earlier. Its token was shown when it was made, and only then. */
159
+ static connect(computerID: string, opts: ConnectionOpts & {
160
+ accessToken: string;
161
+ }): Promise<Computer>;
162
+ static list(opts?: ConnectionOpts & {
163
+ state?: Schemas["ComputerState"];
164
+ }): Promise<ComputerInfo[]>;
165
+ static serviceInfo(opts?: ConnectionOpts): Promise<ServiceInfo>;
166
+ static getInfo(computerID: string, opts?: ConnectionOpts): Promise<ComputerDetail>;
167
+ /** It now stops this long from now, replacing any earlier timeout. */
168
+ static setTimeout(computerID: string, timeoutMs: number, opts?: ConnectionOpts): Promise<ComputerInfo>;
169
+ static stop(computerID: string, opts?: ConnectionOpts): Promise<ComputerInfo>;
170
+ static start(computerID: string, opts?: ConnectionOpts & {
171
+ timeoutMs?: number;
172
+ }): Promise<ComputerInfo>;
173
+ static getLogs(computerID: string, opts?: ConnectionOpts): Promise<ComputerLog[]>;
174
+ /** A one-time ticket to open one of its surfaces live, within a minute. */
175
+ static createLiveSession(computerID: string, session: {
176
+ surface: LiveSurface;
177
+ mode?: LiveMode;
178
+ }, opts?: ConnectionOpts): Promise<LiveSession>;
179
+ static kill(computerID: string, opts?: ConnectionOpts): Promise<void>;
180
+ /** The endpoint to give an MCP client. */
181
+ getMcpUrl(endpoint?: "computer" | "browser"): string;
182
+ /** The token for those endpoints. */
183
+ getMcpToken(): string;
184
+ getInfo(): Promise<{
185
+ computerID: string;
186
+ name: string;
187
+ state: components["schemas"]["ComputerState"];
188
+ reason: string | null;
189
+ progress: components["schemas"]["Progress"] | null;
190
+ access: components["schemas"]["Access"];
191
+ isolation: components["schemas"]["Isolation"];
192
+ attached: boolean;
193
+ version: string | null;
194
+ browser: boolean | "own";
195
+ screen: boolean;
196
+ workspace: string | null;
197
+ startedAt: string;
198
+ endAt: string | null;
199
+ metadata: components["schemas"]["Metadata"];
200
+ endpoints: components["schemas"]["Endpoints"];
201
+ } & {
202
+ uptimeSeconds: number;
203
+ surfaces: components["schemas"]["SurfaceInfo"][];
204
+ tools: {
205
+ computer: string[];
206
+ browser: string[];
207
+ screen: string[];
208
+ };
209
+ }>;
210
+ isRunning(): Promise<boolean>;
211
+ setTimeout(timeoutMs: number): Promise<{
212
+ computerID: string;
213
+ name: string;
214
+ state: components["schemas"]["ComputerState"];
215
+ reason: string | null;
216
+ progress: components["schemas"]["Progress"] | null;
217
+ access: components["schemas"]["Access"];
218
+ isolation: components["schemas"]["Isolation"];
219
+ attached: boolean;
220
+ version: string | null;
221
+ browser: boolean | "own";
222
+ screen: boolean;
223
+ workspace: string | null;
224
+ startedAt: string;
225
+ endAt: string | null;
226
+ metadata: components["schemas"]["Metadata"];
227
+ endpoints: components["schemas"]["Endpoints"];
228
+ }>;
229
+ stop(): Promise<{
230
+ computerID: string;
231
+ name: string;
232
+ state: components["schemas"]["ComputerState"];
233
+ reason: string | null;
234
+ progress: components["schemas"]["Progress"] | null;
235
+ access: components["schemas"]["Access"];
236
+ isolation: components["schemas"]["Isolation"];
237
+ attached: boolean;
238
+ version: string | null;
239
+ browser: boolean | "own";
240
+ screen: boolean;
241
+ workspace: string | null;
242
+ startedAt: string;
243
+ endAt: string | null;
244
+ metadata: components["schemas"]["Metadata"];
245
+ endpoints: components["schemas"]["Endpoints"];
246
+ }>;
247
+ start(opts?: {
248
+ timeoutMs?: number;
249
+ }): Promise<{
250
+ computerID: string;
251
+ name: string;
252
+ state: components["schemas"]["ComputerState"];
253
+ reason: string | null;
254
+ progress: components["schemas"]["Progress"] | null;
255
+ access: components["schemas"]["Access"];
256
+ isolation: components["schemas"]["Isolation"];
257
+ attached: boolean;
258
+ version: string | null;
259
+ browser: boolean | "own";
260
+ screen: boolean;
261
+ workspace: string | null;
262
+ startedAt: string;
263
+ endAt: string | null;
264
+ metadata: components["schemas"]["Metadata"];
265
+ endpoints: components["schemas"]["Endpoints"];
266
+ }>;
267
+ liveSession(surface: LiveSurface, mode?: LiveMode): Promise<{
268
+ url: string;
269
+ protocol: string;
270
+ surface: components["schemas"]["Surface"];
271
+ mode: components["schemas"]["LiveMode"];
272
+ expiresAt: string;
273
+ }>;
274
+ getLogs(): Promise<{
275
+ timestamp: string;
276
+ line: string;
277
+ }[]>;
278
+ kill(): Promise<void>;
279
+ /** Close this object's connection. The computer keeps running. */
280
+ close(): Promise<void>;
281
+ }
282
+ export {};
package/package.json CHANGED
@@ -1,6 +1,34 @@
1
1
  {
2
2
  "name": "@agentorg/computer-sdk",
3
- "version": "0.0.0-stage",
4
- "stub": true,
5
- "description": "Temporary package placeholder for staged publishing"
6
- }
3
+ "version": "0.0.35",
4
+ "description": "AgentComputer's TypeScript client: make, attach and use computers for agents",
5
+ "license": "Apache-2.0",
6
+ "repository": {
7
+ "type": "git",
8
+ "url": "git+https://github.com/uniac-ai/AgentComputer.git",
9
+ "directory": "packages/sdk"
10
+ },
11
+ "type": "module",
12
+ "exports": {
13
+ ".": {
14
+ "agentcomputer-source": "./src/sdk.ts",
15
+ "types": "./dist/types/sdk.d.ts",
16
+ "default": "./dist/sdk.js"
17
+ }
18
+ },
19
+ "files": [
20
+ "dist/sdk.js",
21
+ "dist/types",
22
+ "dist/THIRD_PARTY_LICENSES.txt",
23
+ "NOTICE"
24
+ ],
25
+ "scripts": {
26
+ "build": "tsc -p tsconfig.json"
27
+ },
28
+ "engines": {
29
+ "node": ">=22.15"
30
+ },
31
+ "publishConfig": {
32
+ "tag": "next"
33
+ }
34
+ }