aicomputer 0.1.0

package/README.md

@@ -0,0 +1,88 @@
+# agentcomputer
+
+TypeScript SDK for Agent Computer.
+
+## Install
+
+```bash
+pnpm add agentcomputer
+```
+
+## Authenticate
+
+```ts
+import { AgentComputer } from "agentcomputer";
+
+const client = new AgentComputer({
+  apiKey: process.env.AGENTCOMPUTER_API_KEY!,
+});
+```
+
+## Quickstart
+
+```ts
+import { AgentComputer } from "agentcomputer";
+
+const client = new AgentComputer({
+  apiKey: process.env.AGENTCOMPUTER_API_KEY!,
+});
+
+const computer = await client.computers.create({
+  displayName: "Quickstart computer",
+});
+
+await computer.ensureRunning();
+
+const result = await computer.commands.run(["node", "--version"]);
+console.log(result.stdout.trim());
+
+await computer.ensureStopped();
+```
+
+## Run a command
+
+```ts
+const result = await computer.commands.run(["python3", "-c", "print('hello')"]);
+console.log(result.exitCode, result.stdout);
+```
+
+For long-lived commands, use the typed command handle:
+
+```ts
+const server = await computer.commands.start(
+  ["python3", "-m", "http.server", "3000"],
+  {
+    onStdout: (chunk) => process.stdout.write(chunk),
+    onStderr: (chunk) => process.stderr.write(chunk),
+  },
+);
+
+await server.wait({ rejectOnNonZero: false });
+```
+
+## Publish a port
+
+```ts
+await computer.waitForPort(3000);
+const published = await computer.ports.publish({ port: 3000, name: "app" });
+console.log(published.public_url);
+```
+
+## PTY sessions
+
+```ts
+const shell = await computer.pty.create({
+  cols: 120,
+  rows: 32,
+  onData: (chunk) => process.stdout.write(chunk),
+});
+
+await shell.sendInput("uname -a\n");
+await shell.resize(140, 40);
+await shell.kill();
+```
+
+## Docs
+
+- Web docs: `https://micro.agentcomputer.ai/docs/typescript-sdk`
+- Generated API reference is published from the package source into the docs site.

package/dist/index.d.ts

@@ -0,0 +1,380 @@
+import { ComputerImageResponse, AccessSessionResponse, createPublicApiClient, ListPublishedPortsResponse, PublishedPortResponse, PublishedPortMutationResponse, ListSharesResponse, ShareResponse, ListSnapshotsResponse, SnapshotResponse, ComputerResponse, ComputerConnectionResponse, CreateSSHCertificateRequest, SSHCertificateResponse, CreateComputerRequest, ListSSHKeysResponse, CreateSSHKeyRequest, SSHKeyEnvelope, PublicApiClientOptions, AccessTokenProvider, MeResponse, UsageEnvelope, ResolveShareResponse, CreateAccessSessionRequest, AccessSessionEnvelope, OperationResponse } from '@microagentcomputer/public-api-client';
+export { AccessSessionEnvelope, AccessSessionResponse, AccessTokenProvider, ComputerConnectionResponse, ComputerImageResponse, ComputerMutationResponse, ComputerResponse, CreateAccessSessionRequest, CreateComputerRequest, CreateEmailShareRequest, CreateLinkShareRequest, CreatePublishedPortRequest, CreateSSHCertificateRequest, CreateSSHKeyRequest, ExecCommandRequest, ExecCommandResponse, MeResponse, OperationResponse, PublicApiError, PublishedPortResponse, ResolveShareResponse, RestoreSnapshotRequest, SSHCertificateResponse, ShareResponse, SnapshotResponse, UpdateComputerRequest, UsageEnvelope } from '@microagentcomputer/public-api-client';
+
+type LowLevelClient = ReturnType<typeof createPublicApiClient>;
+type ComputerState = ComputerResponse["state"];
+type ComputerSource = CreateComputerRequest["source"];
+type ComputerCapability = "process" | "files" | "git" | (string & {});
+type WaitOptions = {
+    pollIntervalMs?: number;
+    timeoutMs?: number;
+    signal?: AbortSignal;
+};
+type AgentComputerOptions = Omit<PublicApiClientOptions, "accessToken" | "baseUrl"> & {
+    baseUrl?: string;
+    apiKey?: AccessTokenProvider;
+    accessToken?: AccessTokenProvider;
+    defaultPollIntervalMs?: number;
+    defaultOperationTimeoutMs?: number;
+    defaultComputerStateTimeoutMs?: number;
+    defaultConnectRequestTimeoutMs?: number;
+};
+type ComputerCreateOptions = {
+    handle?: string;
+    displayName?: string;
+    source?: ComputerSource;
+    authorizedKeys?: string[];
+};
+type ComputerEnsureOptions = ComputerCreateOptions & {
+    id?: string;
+    start?: boolean;
+    updateMetadata?: boolean;
+};
+type ComputerUpdateOptions = {
+    displayName?: string;
+};
+type CommandRunOptions = {
+    cwd?: string;
+    env?: Record<string, string>;
+    timeoutMs?: number;
+    requestTimeoutMs?: number;
+    user?: string;
+    signal?: AbortSignal;
+};
+type CommandStartOptions = CommandRunOptions & {
+    tag?: string;
+    stdin?: boolean;
+    onStdout?: CommandOutputHandler;
+    onStderr?: CommandOutputHandler;
+    onExit?: (result: CommandResult) => void;
+};
+type PtyStartOptions = Omit<CommandRunOptions, "timeoutMs"> & {
+    cols?: number;
+    rows?: number;
+    tag?: string;
+    onData?: PtyOutputHandler;
+    onExit?: (result: PtyResult) => void;
+};
+type ExecSessionCreateOptions = {
+    ttlSeconds?: number;
+    signal?: AbortSignal;
+};
+type CommandSelector = number | string | {
+    pid: number;
+} | {
+    tag: string;
+};
+type CommandSignal = "SIGTERM" | "SIGKILL";
+type CommandOutputHandler = (chunk: string, raw: Uint8Array) => void;
+type PtyOutputHandler = (chunk: string, raw: Uint8Array) => void;
+type CommandInfo = {
+    pid: number;
+    tag?: string;
+    cmd: string;
+    args: string[];
+    envs: Record<string, string>;
+    cwd?: string;
+};
+type CommandResult = {
+    pid: number;
+    tag?: string;
+    stdout: string;
+    stderr: string;
+    exitCode: number;
+    status: string;
+    error?: string;
+};
+type PtyResult = {
+    pid: number;
+    tag?: string;
+    output: string;
+    exitCode: number;
+    status: string;
+    error?: string;
+};
+type ShareLinkOptions = {
+    expiresAt?: string;
+    allowBrowser?: boolean;
+    allowVnc?: boolean;
+    signal?: AbortSignal;
+};
+type ShareEmailOptions = ShareLinkOptions & {
+    email: string;
+};
+type PublishPortOptions = {
+    port: number;
+    name?: string;
+    signal?: AbortSignal;
+};
+type SnapshotRestoreOptions = {
+    handle?: string;
+    displayName?: string;
+    authorizedKeys?: string[];
+    signal?: AbortSignal;
+};
+declare class AgentComputer {
+    readonly images: ComputerImagesClient;
+    readonly computers: ComputersClient;
+    readonly snapshots: SnapshotsClient;
+    readonly sshKeys: SSHKeysClient;
+    private readonly client;
+    private readonly fetchImpl;
+    private readonly defaultPollIntervalMs;
+    private readonly defaultOperationTimeoutMs;
+    private readonly defaultComputerStateTimeoutMs;
+    private readonly defaultConnectRequestTimeoutMs;
+    constructor(options?: AgentComputerOptions);
+    me(signal?: AbortSignal): Promise<MeResponse>;
+    usage(signal?: AbortSignal): Promise<UsageEnvelope>;
+    resolveShare(shareToken: string, signal?: AbortSignal): Promise<ResolveShareResponse>;
+    redeemShare(shareToken: string, body?: Partial<CreateAccessSessionRequest>, signal?: AbortSignal): Promise<AccessSessionEnvelope>;
+    waitForOperation(operationOrId: string | Pick<OperationResponse, "id">, options?: WaitOptions): Promise<OperationResponse>;
+    waitForComputerState(computerId: string, targetState: ComputerState, options?: WaitOptions): Promise<Computer>;
+    computer(idOrHandle: string): Promise<Computer>;
+    /** @internal */
+    internalClient(): LowLevelClient;
+    /** @internal */
+    internalFetch(): typeof fetch;
+    /** @internal */
+    internalDefaultPollIntervalMs(): number;
+    /** @internal */
+    internalDefaultComputerStateTimeoutMs(): number;
+    /** @internal */
+    internalDefaultOperationTimeoutMs(): number;
+    /** @internal */
+    internalDefaultConnectRequestTimeoutMs(): number;
+}
+declare class ComputerImagesClient {
+    private readonly sdk;
+    constructor(sdk: AgentComputer);
+    list(signal?: AbortSignal): Promise<ComputerImageResponse[]>;
+    get(imageId: string, signal?: AbortSignal): Promise<ComputerImageResponse>;
+    getDefault(signal?: AbortSignal): Promise<ComputerImageResponse>;
+}
+declare class ComputersClient {
+    private readonly sdk;
+    constructor(sdk: AgentComputer);
+    list(signal?: AbortSignal): Promise<Computer[]>;
+    get(computerId: string, signal?: AbortSignal): Promise<Computer>;
+    getByHandle(handle: string, signal?: AbortSignal): Promise<Computer | null>;
+    resolve(idOrHandle: string, signal?: AbortSignal): Promise<Computer>;
+    create(options?: ComputerCreateOptions, signal?: AbortSignal): Promise<Computer>;
+    ensure(options?: ComputerEnsureOptions, signal?: AbortSignal): Promise<Computer>;
+    private defaultSource;
+}
+declare class Computer {
+    private readonly sdk;
+    private computer;
+    readonly commands: ComputerCommandsClient;
+    readonly pty: ComputerPtyClient;
+    readonly files: ComputerFilesClient;
+    readonly git: ComputerGitClient;
+    readonly ports: ComputerPortsClient;
+    readonly shares: ComputerSharesClient;
+    readonly snapshots: ComputerSnapshotsClient;
+    constructor(sdk: AgentComputer, computer: ComputerResponse);
+    get raw(): ComputerResponse;
+    get id(): string;
+    get handle(): string;
+    get displayName(): string;
+    get state(): ComputerState;
+    get sourceKind(): ComputerResponse["source_kind"];
+    get sourceSnapshotId(): string | null | undefined;
+    get createdAt(): string;
+    get updatedAt(): string;
+    get deletedAt(): string | null | undefined;
+    get primaryUrl(): string;
+    get failureReason(): string | null | undefined;
+    internalSdk(): AgentComputer;
+    refresh(signal?: AbortSignal): Promise<Computer>;
+    update(options: ComputerUpdateOptions, signal?: AbortSignal): Promise<Computer>;
+    start(signal?: AbortSignal): Promise<Computer>;
+    stop(signal?: AbortSignal): Promise<Computer>;
+    delete(signal?: AbortSignal): Promise<void>;
+    ensureRunning(options?: WaitOptions): Promise<Computer>;
+    ensureStopped(options?: WaitOptions): Promise<Computer>;
+    waitUntilRunning(options?: WaitOptions): Promise<Computer>;
+    waitUntilStopped(options?: WaitOptions): Promise<Computer>;
+    getConnection(signal?: AbortSignal): Promise<ComputerConnectionResponse>;
+    createBrowserAccess(options?: ExecSessionCreateOptions): Promise<AccessSessionResponse>;
+    createVNCAccess(options?: ExecSessionCreateOptions): Promise<AccessSessionResponse>;
+    createSSHCertificate(body: CreateSSHCertificateRequest, signal?: AbortSignal): Promise<SSHCertificateResponse>;
+    execCapabilities(signal?: AbortSignal): Promise<readonly string[]>;
+    supportsCapability(capability: ComputerCapability, signal?: AbortSignal): Promise<boolean>;
+    requireCapability(capability: "files" | "git", signal?: AbortSignal): Promise<readonly string[]>;
+    waitForPort(port: number, options?: WaitOptions): Promise<PublishedPortResponse>;
+    waitForUrl(url: string, options?: WaitOptions): Promise<Response>;
+    waitForProcess(selectorOrPredicate: CommandSelector | ((command: CommandInfo) => boolean), options?: WaitOptions): Promise<CommandInfo>;
+    waitForFile(path: string, options?: WaitOptions): Promise<void>;
+}
+declare class ExecTransportError extends Error {
+    readonly status?: number;
+    readonly code?: string;
+    readonly details?: unknown;
+    constructor(message: string, options?: {
+        status?: number;
+        code?: string;
+        details?: unknown;
+    });
+}
+declare class UnsupportedCapabilityError extends Error {
+    readonly capability: "files" | "git";
+    readonly availableCapabilities: readonly string[];
+    constructor(capability: "files" | "git", availableCapabilities?: readonly string[]);
+}
+declare class CommandExitError extends Error {
+    readonly result: CommandResult;
+    constructor(result: CommandResult);
+}
+type ExecGatewayMethod = "List" | "Start" | "Connect" | "Update" | "SendInput" | "SendSignal" | "CloseStdin";
+declare class ExecGatewayConnection {
+    private readonly client;
+    private readonly fetchImpl;
+    private readonly computerId;
+    readonly session: AccessSessionResponse;
+    constructor(client: LowLevelClient, fetchImpl: typeof fetch, computerId: string, session: AccessSessionResponse);
+    close(signal?: AbortSignal): Promise<void>;
+    requestJson<T>(method: ExecGatewayMethod, body: unknown, options?: {
+        signal?: AbortSignal;
+        requestTimeoutMs?: number;
+    }): Promise<T>;
+    openStream(method: "Start" | "Connect", body: unknown, options?: {
+        signal?: AbortSignal;
+        requestTimeoutMs?: number;
+    }): Promise<ReadableStreamDefaultReader<Uint8Array>>;
+    private endpoint;
+    private authorizationHeader;
+    private request;
+}
+declare class CommandHandle {
+    private readonly commands;
+    private readonly gateway;
+    private readonly reader;
+    private readonly selector;
+    private readonly stdoutChunks;
+    private readonly stderrChunks;
+    private readonly pidPromise;
+    private readonly resultPromise;
+    private pidResolve;
+    private pidReject;
+    private resolvedPid?;
+    private closed;
+    constructor(commands: ComputerCommandsClient, gateway: ExecGatewayConnection, reader: ReadableStreamDefaultReader<Uint8Array>, initialSelector: CommandSelector | undefined, handlers?: Pick<CommandStartOptions, "onStdout" | "onStderr" | "onExit">);
+    get pid(): number;
+    get stdout(): string;
+    get stderr(): string;
+    wait(options?: {
+        rejectOnNonZero?: boolean;
+    }): Promise<CommandResult>;
+    disconnect(): Promise<void>;
+    kill(signal?: CommandSignal, requestSignal?: AbortSignal): Promise<void>;
+    sendStdin(data: string | Uint8Array, requestSignal?: AbortSignal): Promise<void>;
+    closeStdin(requestSignal?: AbortSignal): Promise<void>;
+    awaitPid(): Promise<number>;
+    private currentSelector;
+    private consume;
+}
+declare class PtySession {
+    private readonly commands;
+    private readonly gateway;
+    private readonly reader;
+    private readonly selector;
+    private readonly outputChunks;
+    private readonly pidPromise;
+    private readonly resultPromise;
+    private pidResolve;
+    private pidReject;
+    private resolvedPid?;
+    private closed;
+    constructor(commands: ComputerCommandsClient, gateway: ExecGatewayConnection, reader: ReadableStreamDefaultReader<Uint8Array>, initialSelector: CommandSelector | undefined, handlers?: Pick<PtyStartOptions, "onData" | "onExit">);
+    get pid(): number;
+    get output(): string;
+    wait(options?: {
+        rejectOnNonZero?: boolean;
+    }): Promise<PtyResult>;
+    sendInput(data: string | Uint8Array, requestSignal?: AbortSignal): Promise<void>;
+    resize(cols: number, rows: number, requestSignal?: AbortSignal): Promise<void>;
+    kill(signal?: CommandSignal, requestSignal?: AbortSignal): Promise<void>;
+    disconnect(): Promise<void>;
+    awaitPid(): Promise<number>;
+    private currentSelector;
+    private consume;
+}
+declare class ComputerCommandsClient {
+    private readonly computer;
+    constructor(computer: Computer);
+    run(command: string | readonly string[], options?: CommandRunOptions): Promise<CommandResult>;
+    start(command: string | readonly string[], options?: CommandStartOptions): Promise<CommandHandle>;
+    connect(selector: CommandSelector, options?: Omit<CommandStartOptions, "stdin">): Promise<CommandHandle>;
+    list(signal?: AbortSignal): Promise<CommandInfo[]>;
+    sendStdin(selector: CommandSelector, data: string | Uint8Array, signal?: AbortSignal): Promise<void>;
+    sendPtyInput(selector: CommandSelector, data: string | Uint8Array, signal?: AbortSignal): Promise<void>;
+    closeStdin(selector: CommandSelector, signal?: AbortSignal): Promise<void>;
+    kill(selector: CommandSelector, signalName?: CommandSignal, signal?: AbortSignal): Promise<void>;
+    resizePty(selector: CommandSelector, cols: number, rows: number, signal?: AbortSignal): Promise<void>;
+    private sendProcessInput;
+    /** @internal */
+    createGateway(options: {
+        signal?: AbortSignal;
+        requestTimeoutMs?: number;
+    }): Promise<ExecGatewayConnection>;
+}
+declare class ComputerPtyClient {
+    private readonly computer;
+    constructor(computer: Computer);
+    create(options?: PtyStartOptions): Promise<PtySession>;
+    start(command: string | readonly string[], options?: PtyStartOptions): Promise<PtySession>;
+    attach(selector: CommandSelector, options?: Pick<PtyStartOptions, "requestTimeoutMs" | "signal" | "onData" | "onExit">): Promise<PtySession>;
+    connect(selector: CommandSelector, options?: Pick<PtyStartOptions, "requestTimeoutMs" | "signal" | "onData" | "onExit">): Promise<PtySession>;
+}
+declare class ComputerFilesClient {
+    private readonly computer;
+    constructor(computer: Computer);
+    readText(path: string, signal?: AbortSignal): Promise<string>;
+    writeText(path: string, content: string, signal?: AbortSignal): Promise<void>;
+    remove(path: string, signal?: AbortSignal): Promise<void>;
+}
+declare class ComputerGitClient {
+    private readonly computer;
+    constructor(computer: Computer);
+    status(signal?: AbortSignal): Promise<string>;
+    clone(repoUrl: string, signal?: AbortSignal): Promise<void>;
+    pull(signal?: AbortSignal): Promise<void>;
+}
+declare class ComputerPortsClient {
+    private readonly computer;
+    constructor(computer: Computer);
+    list(signal?: AbortSignal): Promise<ListPublishedPortsResponse["ports"]>;
+    publish(options: PublishPortOptions): Promise<PublishedPortResponse>;
+    delete(port: number, signal?: AbortSignal): Promise<PublishedPortMutationResponse["port"]>;
+}
+declare class ComputerSharesClient {
+    private readonly computer;
+    constructor(computer: Computer);
+    list(signal?: AbortSignal): Promise<ListSharesResponse["shares"]>;
+    createLink(options?: ShareLinkOptions): Promise<ShareResponse>;
+    createEmail(options: ShareEmailOptions): Promise<ShareResponse>;
+    delete(shareId: string, signal?: AbortSignal): Promise<void>;
+}
+declare class ComputerSnapshotsClient {
+    private readonly computer;
+    constructor(computer: Computer);
+    list(signal?: AbortSignal): Promise<ListSnapshotsResponse["snapshots"]>;
+    create(signal?: AbortSignal): Promise<SnapshotResponse>;
+}
+declare class SnapshotsClient {
+    private readonly sdk;
+    constructor(sdk: AgentComputer);
+    get(snapshotId: string, signal?: AbortSignal): Promise<SnapshotResponse>;
+    delete(snapshotId: string, signal?: AbortSignal): Promise<SnapshotResponse>;
+    restore(snapshotId: string, options?: SnapshotRestoreOptions): Promise<Computer>;
+}
+declare class SSHKeysClient {
+    private readonly sdk;
+    constructor(sdk: AgentComputer);
+    list(signal?: AbortSignal): Promise<ListSSHKeysResponse["ssh_keys"]>;
+    create(body: CreateSSHKeyRequest, signal?: AbortSignal): Promise<SSHKeyEnvelope["ssh_key"]>;
+    delete(sshKeyId: string, signal?: AbortSignal): Promise<void>;
+}
+
+export { AgentComputer, type AgentComputerOptions, CommandExitError, CommandHandle, type CommandInfo, type CommandOutputHandler, type CommandResult, type CommandRunOptions, type CommandSelector, type CommandSignal, type CommandStartOptions, Computer, type ComputerCapability, ComputerCommandsClient, type ComputerCreateOptions, type ComputerEnsureOptions, ComputerFilesClient, ComputerGitClient, ComputerImagesClient, ComputerPortsClient, ComputerPtyClient, ComputerSharesClient, ComputerSnapshotsClient, type ComputerSource, type ComputerState, type ComputerUpdateOptions, ComputersClient, type ExecSessionCreateOptions, ExecTransportError, type PtyOutputHandler, type PtyResult, PtySession, type PtyStartOptions, type PublishPortOptions, SSHKeysClient, type ShareEmailOptions, type ShareLinkOptions, type SnapshotRestoreOptions, SnapshotsClient, UnsupportedCapabilityError, type WaitOptions };