@dejima/sdk 0.5.1

package/README.md

@@ -0,0 +1,99 @@
+# @dejima/sdk — TypeScript/JavaScript client
+
+Thin client for the [Dejima](https://dejima.tech/) API: run a fleet of
+AI coding agents on hardware you own. Mirrors the
+[Python client](https://pypi.org/project/dejima-sdk/).
+
+> **Alpha (0.x).** The API is stable in shape (`v1/`-prefixed) but fields may
+> change until `1.0`. The REST layer mirrors
+> [`openapi.yaml`](https://github.com/aoos/dejima/blob/master/openapi.yaml); the
+> only hand-written piece is the PTY `Session` helper.
+
+## Install
+
+```bash
+npm install @dejima/sdk
+# attach() uses the global WebSocket (Node 22+/browser) when present,
+# else falls back to the optional `ws` package:
+npm install ws        # only for Node < 22 with token auth
+```
+
+Requires Node 18+ (uses the global `fetch` and `AbortController`). ESM-only.
+
+## Quickstart
+
+```ts
+import { Client } from "@dejima/sdk";
+
+// host/token from $DEJIMA_HOST and $DEJIMA_TOKEN, or pass explicitly:
+const dj = new Client({ host: "100.84.12.7:7273" });
+
+const isl = await dj.createIsland("git@github.com:you/foo.git", { agent: "claude-code" });
+console.log(isl.name, isl.state);
+
+await dj.addAgent(isl.name, { type: "codex" });   // second agent, own worktree
+
+const out = await dj.exec(isl.name, ["git", "status", "--short"]);
+console.log(out.stdout, "exit", out.exit_code);
+
+for (const i of await dj.listIslands()) {
+  console.log(i.name, i.state, (i.agents ?? []).length, "agents");
+}
+
+console.log(await dj.overview());  // daemon health, VM memory, rollup
+```
+
+## Interactive sessions
+
+`attach()` opens the multi-attach PTY stream. The daemon speaks a small
+JSON-envelope protocol over the WebSocket — `Session` hides that, so you deal in
+raw `Uint8Array`. Pull-based (`recv`) or event-based (`onData`):
+
+```ts
+const s = await dj.attach(isl.name);     // or { agent: "p2" }
+s.resize(40, 120);
+s.sendText("ls -la\n");
+
+// pull style
+let chunk: Uint8Array | null;
+while ((chunk = await s.recv()) !== null) {
+  process.stdout.write(chunk);
+}
+
+// or event style
+s.onData((bytes) => process.stdout.write(bytes));
+s.onClose(() => console.log("session ended"));
+```
+
+`dj.attachTerminal("t1")` does the same for an operator host terminal.
+
+> Browser note: the global `WebSocket` cannot set request headers, so
+> token-authenticated attach needs Node with the `ws` package (or a
+> `wsFactory` you pass to `new Client(...)`). Operator (no-token) access works
+> anywhere.
+
+## API coverage
+
+The client covers the full v1 surface: islands (list/create/get/update/delete,
+hibernate/wake/reset/upgrade, clone, resources, workspace-ready, events), agents
+(list/add/get/update/remove, configure), exec & files, Port broker, capability
+broker, MCP broker (grants + `mcpCall`), credentials (Claude/GitHub/providers),
+operator tokens (create/list/revoke), webhooks, team activity feed, daemon (overview/agent-types/
+healthz/audit with filters + jsonl/csv export/clients/sessions-revoke/panic/
+admin-update/image-build/ssh keys), host terminals, and the PTY `Session`.
+
+Every non-2xx response rejects with a `DejimaError` (`.status`, `.description`).
+
+## Auth
+
+- **Operator** (unix socket / tailnet) needs no token.
+- **Autonomy path** uses a per-island bearer token — set `DEJIMA_TOKEN` or pass
+  `{ token }` to the constructor.
+
+## Development
+
+```bash
+npm install
+npm run build       # tsc -> dist/
+npm test            # tsx --test (no daemon required)
+```

package/dist/client.d.ts

@@ -0,0 +1,239 @@
+import { Session, WebSocketLike } from "./session.js";
+export interface ClientOptions {
+    /** `HOST:PORT` of the daemon (default `$DEJIMA_HOST` or 127.0.0.1:7273). */
+    host?: string;
+    /** Per-island bearer token (default `$DEJIMA_TOKEN`). */
+    token?: string;
+    /** `http` (default) or `https`. */
+    scheme?: "http" | "https";
+    /** Per-request timeout in milliseconds (default 30000). */
+    timeoutMs?: number;
+    /** Override the `fetch` implementation (for testing or older runtimes). */
+    fetch?: typeof fetch;
+    /** Override how the PTY WebSocket is opened (for testing or the browser). */
+    wsFactory?: (url: string, opts: {
+        headers?: Record<string, string>;
+    }) => WebSocketLike;
+}
+/** A client for one Dejima daemon. Mirrors the Python `dejima.Client`. */
+export declare class Client {
+    readonly host: string;
+    readonly token?: string;
+    readonly scheme: "http" | "https";
+    readonly base: string;
+    private readonly timeoutMs;
+    private readonly fetchImpl;
+    private readonly wsFactory?;
+    constructor(opts?: ClientOptions);
+    private url;
+    private request;
+    private json;
+    private seg;
+    private island;
+    /** All islands, most-recently-used first. */
+    listIslands(): Promise<any[]>;
+    /** Provision an island. `repo` is a git URL or local path. */
+    createIsland(repo: string, opts?: {
+        agent?: string;
+        name?: string;
+        image?: string;
+        cmd?: string;
+        resources?: Record<string, unknown>;
+        agents?: Array<Record<string, unknown>>;
+        role?: string;
+        githubIdentity?: string;
+        seedPath?: string;
+        owner?: string;
+        tags?: Record<string, string>;
+    }): Promise<any>;
+    /** Island detail (agents, presence, cpu/mem, git, health, resources, disk). */
+    getIsland(name: string): Promise<any>;
+    /** Update the island's cosmetic display title (`""` clears it). */
+    updateIsland(name: string, title: string): Promise<any>;
+    /** Purge an island. `force` bypasses the unpushed-work guard. */
+    deleteIsland(name: string, force?: boolean): Promise<void>;
+    /** Stop the container, preserving volumes. */
+    hibernate(name: string): Promise<any>;
+    /** Start a hibernated island's container against existing volumes. */
+    wake(name: string): Promise<any>;
+    /** Clear agent on-disk state (preserves the workspace). */
+    reset(name: string): Promise<any>;
+    /** Recreate the container against the current island image (both volumes preserved). */
+    upgrade(name: string): Promise<any>;
+    /** Copy an island (workspace + home volumes; Port grants dropped). */
+    cloneIsland(name: string, newName: string): Promise<any>;
+    /** Update memory limit (live) and/or OOM priority (needs a recreate). */
+    setResources(name: string, opts: {
+        memory?: string;
+        oomPriority?: number;
+    }): Promise<any>;
+    /** Whether the island's repo clone has landed in /workspace yet. */
+    workspaceReady(name: string): Promise<boolean>;
+    /** The island's recent event log (newest first). */
+    islandEvents(name: string): Promise<any[]>;
+    listAgents(name: string): Promise<any[]>;
+    /** Add an agent (its own worktree + tmux session). */
+    addAgent(name: string, opts?: {
+        type?: string;
+        label?: string;
+        cmd?: string;
+        provider?: string;
+        model?: string;
+    }): Promise<any>;
+    getAgent(name: string, agentId: string): Promise<any>;
+    /** Rename an agent's cosmetic label (`""` clears it). */
+    updateAgent(name: string, agentId: string, label: string): Promise<any>;
+    /** Remove a non-primary agent (kills its session, prunes its worktree). */
+    removeAgent(name: string, agentId: string): Promise<void>;
+    /** Set an agent's LLM provider/model (key-requiring frameworks only). */
+    configureAgent(name: string, agentId: string, opts: {
+        provider?: string;
+        model?: string;
+    }): Promise<any>;
+    /** Run a one-shot command. Returns `{stdout, stderr, exit_code}`. */
+    exec(name: string, cmd: string[]): Promise<any>;
+    /** Read a file from the island (defaults to the primary worktree). */
+    readFile(name: string, path: string): Promise<Uint8Array>;
+    /** Write a file into the island. */
+    writeFile(name: string, path: string, data: Uint8Array | string): Promise<void>;
+    /** Fetch container/agent logs as text. */
+    logs(name: string, opts?: {
+        agent?: string;
+    }): Promise<string>;
+    listPortScopes(name: string): Promise<any>;
+    grantPortScope(name: string, hostPath: string, mode?: "ro" | "rw"): Promise<any>;
+    revokePortScope(name: string, scope: string): Promise<void>;
+    portIntake(name: string, scope: string, srcRel: string, dest?: string): Promise<any>;
+    portExport(name: string, src: string): Promise<any>;
+    portWrite(name: string, scope: string, src: string, destRel: string): Promise<any>;
+    listCapabilityGrants(name: string): Promise<any>;
+    grantCapability(name: string, target: string): Promise<any>;
+    revokeCapability(name: string, target: string): Promise<void>;
+    /** Invoke a granted capability. Operators name `island`; an in-island token is pinned. */
+    executeCapability(target: string, opts?: {
+        island?: string;
+        args?: Record<string, string>;
+    }): Promise<any>;
+    listMcpGrants(name: string): Promise<any>;
+    grantMcp(name: string, server: string): Promise<any>;
+    revokeMcp(name: string, server: string): Promise<void>;
+    /** Invoke a JSON-RPC `method` on a granted MCP server (deny-all; ledgered). */
+    mcpCall(server: string, method: string, opts?: {
+        island?: string;
+        params?: unknown;
+    }): Promise<any>;
+    pushClaudeCredentials(credentialsJson: string): Promise<void>;
+    claudeCredentialsStatus(): Promise<any>;
+    listGitHubIdentities(): Promise<any>;
+    putGitHubIdentity(name: string, opts: {
+        login: string;
+        token: string;
+        id?: number;
+        host?: string;
+        default?: boolean;
+    }): Promise<any>;
+    deleteGitHubIdentity(name: string): Promise<any>;
+    githubRepos(name: string): Promise<any>;
+    listProviders(): Promise<any>;
+    putProvider(provider: string, opts: {
+        apiKey: string;
+        baseUrl?: string;
+        envVar?: string;
+        default?: boolean;
+    }): Promise<any>;
+    deleteProvider(provider: string): Promise<any>;
+    listTokens(): Promise<any>;
+    /**
+     * Mint an operator bearer token. `role` is `owner`/`operator`/`viewer`;
+     * `islands` scopes it (empty = all). The response carries the bearer `secret` —
+     * returned ONCE and never stored in the clear.
+     */
+    createToken(role: "owner" | "operator" | "viewer", opts?: {
+        label?: string;
+        islands?: string[];
+    }): Promise<any>;
+    revokeToken(tokenId: string): Promise<void>;
+    listSubscriptions(): Promise<any[]>;
+    subscribeWebhook(url: string, opts?: {
+        secret?: string;
+        events?: string[];
+    }): Promise<any>;
+    unsubscribeWebhook(subscriptionId: string): Promise<void>;
+    overview(): Promise<any>;
+    agentTypes(): Promise<any>;
+    /** Reachability probe; resolves true when the daemon answers. */
+    healthz(): Promise<boolean>;
+    /**
+     * The audit ledger (brokered ops + `api.request` + lifecycle) + a hash-chain
+     * verdict. Filters compose; `limit` tails the filtered result. `since`/`until`
+     * are RFC3339; `typePrefix` matches the entry-type prefix. With
+     * `format: "jsonl" | "csv"` the daemon streams a text export — this resolves
+     * that string instead of the parsed envelope.
+     */
+    audit(opts?: {
+        limit?: number;
+        since?: string;
+        until?: string;
+        island?: string;
+        typePrefix?: string;
+        actor?: string;
+        decision?: "allowed" | "denied";
+        format?: "json" | "jsonl" | "csv";
+    }): Promise<any>;
+    /**
+     * The team activity feed — a curated, human-rendered timeline over the audit
+     * ledger (who launched what, which agent did what), newest first. `kind` is
+     * `lifecycle`/`broker`/`system`; `since`/`until` are RFC3339.
+     */
+    activity(opts?: {
+        actor?: string;
+        island?: string;
+        owner?: string;
+        kind?: "lifecycle" | "broker" | "system";
+        decision?: "allowed" | "denied";
+        since?: string;
+        until?: string;
+        limit?: number;
+    }): Promise<any>;
+    /** Recent attach/detach events across every island (newest first). */
+    clientHistory(): Promise<any[]>;
+    /** Drop every active websocket client across every island. */
+    revokeSessions(): Promise<any>;
+    panicStatus(): Promise<any>;
+    panic(opts?: {
+        reason?: string;
+    }): Promise<any>;
+    unpanic(): Promise<any>;
+    adminUpdate(opts?: {
+        execute?: boolean;
+        force?: boolean;
+    }): Promise<any>;
+    /** Rebuild the island image; resolves the combined build output as text. */
+    imageBuild(): Promise<string>;
+    authorizeSshKey(publicKey: string): Promise<any>;
+    listSshKeys(): Promise<any>;
+    listTerminals(): Promise<any>;
+    createTerminal(opts?: {
+        label?: string;
+    }): Promise<any>;
+    deleteTerminal(terminalId: string): Promise<void>;
+    relabelTerminal(terminalId: string, label: string): Promise<any>;
+    /** The WebSocket URL for an interactive PTY session (multi-attach). */
+    sessionUrl(name: string, opts?: {
+        agent?: string;
+    }): string;
+    /** The WebSocket URL for a host terminal's PTY session. */
+    terminalSessionUrl(terminalId: string, opts?: {
+        label?: string;
+    }): string;
+    private wsBase;
+    /** Open an island's PTY session stream. Resolves once the socket is open. */
+    attach(name: string, opts?: {
+        agent?: string;
+    }): Promise<Session>;
+    /** Open a host terminal's PTY session stream. */
+    attachTerminal(terminalId: string, opts?: {
+        label?: string;
+    }): Promise<Session>;
+    private openSession;
+}

package/dist/client.js

@@ -0,0 +1,504 @@
+import { DejimaError } from "./errors.js";
+import { Session } from "./session.js";
+const DEFAULT_HOST = "127.0.0.1:7273";
+/** Drop `undefined` values so optional fields are simply omitted from the body. */
+function clean(obj) {
+    const out = {};
+    for (const [k, v] of Object.entries(obj))
+        if (v !== undefined)
+            out[k] = v;
+    return out;
+}
+function env(name) {
+    const g = globalThis;
+    return typeof g.process !== "undefined" ? g.process.env?.[name] : undefined;
+}
+/** A client for one Dejima daemon. Mirrors the Python `dejima.Client`. */
+export class Client {
+    host;
+    token;
+    scheme;
+    base;
+    timeoutMs;
+    fetchImpl;
+    wsFactory;
+    constructor(opts = {}) {
+        this.host = opts.host ?? env("DEJIMA_HOST") ?? DEFAULT_HOST;
+        this.token = opts.token ?? env("DEJIMA_TOKEN");
+        this.scheme = opts.scheme ?? "http";
+        this.base = `${this.scheme}://${this.host}`;
+        this.timeoutMs = opts.timeoutMs ?? 30000;
+        const f = opts.fetch ?? globalThis.fetch;
+        if (!f)
+            throw new Error("no fetch available; pass options.fetch");
+        this.fetchImpl = f.bind(globalThis);
+        this.wsFactory = opts.wsFactory;
+    }
+    // ----- low-level ------------------------------------------------------
+    url(path, query) {
+        let u = this.base + path;
+        if (query) {
+            const qs = Object.entries(query)
+                .filter(([, v]) => v !== undefined)
+                .map(([k, v]) => `${encodeURIComponent(k)}=${encodeURIComponent(String(v))}`)
+                .join("&");
+            if (qs)
+                u += `?${qs}`;
+        }
+        return u;
+    }
+    async request(method, path, opts = {}) {
+        const headers = {};
+        if (this.token)
+            headers["Authorization"] = `Bearer ${this.token}`;
+        if (opts.accept)
+            headers["Accept"] = opts.accept;
+        let body = opts.body;
+        if (opts.json !== undefined) {
+            headers["Content-Type"] = "application/json";
+            body = JSON.stringify(opts.json);
+        }
+        const ctrl = new AbortController();
+        const timer = setTimeout(() => ctrl.abort(), this.timeoutMs);
+        let resp;
+        try {
+            resp = await this.fetchImpl(this.url(path, opts.query), { method, headers, body, signal: ctrl.signal });
+        }
+        finally {
+            clearTimeout(timer);
+        }
+        if (!resp.ok)
+            throw new DejimaError(resp.status, await errorMessage(resp));
+        return resp;
+    }
+    async json(method, path, opts = {}) {
+        const r = await this.request(method, path, opts);
+        const text = await r.text();
+        return (text ? JSON.parse(text) : undefined);
+    }
+    seg(s) {
+        return encodeURIComponent(s);
+    }
+    island(name) {
+        return `/v1/islands/${this.seg(name)}`;
+    }
+    // ===== islands ========================================================
+    /** All islands, most-recently-used first. */
+    listIslands() {
+        return this.json("GET", "/v1/islands");
+    }
+    /** Provision an island. `repo` is a git URL or local path. */
+    createIsland(repo, opts = {}) {
+        const body = clean({
+            repo,
+            agent: opts.agent,
+            name: opts.name,
+            image: opts.image,
+            cmd: opts.cmd,
+            resources: opts.resources,
+            agents: opts.agents,
+            role: opts.role,
+            github_identity: opts.githubIdentity,
+            seed_path: opts.seedPath,
+            owner: opts.owner,
+            tags: opts.tags,
+        });
+        return this.json("POST", "/v1/islands", { json: body });
+    }
+    /** Island detail (agents, presence, cpu/mem, git, health, resources, disk). */
+    getIsland(name) {
+        return this.json("GET", this.island(name));
+    }
+    /** Update the island's cosmetic display title (`""` clears it). */
+    updateIsland(name, title) {
+        return this.json("PATCH", this.island(name), { json: { title } });
+    }
+    /** Purge an island. `force` bypasses the unpushed-work guard. */
+    async deleteIsland(name, force = false) {
+        await this.request("DELETE", this.island(name), { query: force ? { force: true } : undefined });
+    }
+    /** Stop the container, preserving volumes. */
+    hibernate(name) {
+        return this.json("POST", `${this.island(name)}/hibernate`);
+    }
+    /** Start a hibernated island's container against existing volumes. */
+    wake(name) {
+        return this.json("POST", `${this.island(name)}/wake`);
+    }
+    /** Clear agent on-disk state (preserves the workspace). */
+    reset(name) {
+        return this.json("POST", `${this.island(name)}/reset`);
+    }
+    /** Recreate the container against the current island image (both volumes preserved). */
+    upgrade(name) {
+        return this.json("POST", `${this.island(name)}/upgrade`);
+    }
+    /** Copy an island (workspace + home volumes; Port grants dropped). */
+    cloneIsland(name, newName) {
+        return this.json("POST", `${this.island(name)}/clone`, { json: { new_name: newName } });
+    }
+    /** Update memory limit (live) and/or OOM priority (needs a recreate). */
+    setResources(name, opts) {
+        const body = {};
+        if (opts.memory !== undefined)
+            body.memory = opts.memory;
+        if (opts.oomPriority !== undefined)
+            body.oom_priority = opts.oomPriority;
+        return this.json("PUT", `${this.island(name)}/resources`, { json: body });
+    }
+    /** Whether the island's repo clone has landed in /workspace yet. */
+    async workspaceReady(name) {
+        const r = await this.json("GET", `${this.island(name)}/workspace-ready`);
+        return Boolean(r?.ready);
+    }
+    /** The island's recent event log (newest first). */
+    islandEvents(name) {
+        return this.json("GET", `${this.island(name)}/events`);
+    }
+    // ===== agents =========================================================
+    listAgents(name) {
+        return this.json("GET", `${this.island(name)}/agents`);
+    }
+    /** Add an agent (its own worktree + tmux session). */
+    addAgent(name, opts = {}) {
+        return this.json("POST", `${this.island(name)}/agents`, { json: clean({ ...opts }) });
+    }
+    getAgent(name, agentId) {
+        return this.json("GET", `${this.island(name)}/agents/${this.seg(agentId)}`);
+    }
+    /** Rename an agent's cosmetic label (`""` clears it). */
+    updateAgent(name, agentId, label) {
+        return this.json("PATCH", `${this.island(name)}/agents/${this.seg(agentId)}`, { json: { label } });
+    }
+    /** Remove a non-primary agent (kills its session, prunes its worktree). */
+    async removeAgent(name, agentId) {
+        await this.request("DELETE", `${this.island(name)}/agents/${this.seg(agentId)}`);
+    }
+    /** Set an agent's LLM provider/model (key-requiring frameworks only). */
+    configureAgent(name, agentId, opts) {
+        const body = {};
+        if (opts.provider !== undefined)
+            body.provider = opts.provider;
+        if (opts.model !== undefined)
+            body.model = opts.model;
+        return this.json("PATCH", `${this.island(name)}/agents/${this.seg(agentId)}/config`, { json: body });
+    }
+    // ===== exec / files / logs -------------------------------------------
+    /** Run a one-shot command. Returns `{stdout, stderr, exit_code}`. */
+    exec(name, cmd) {
+        return this.json("POST", `${this.island(name)}/exec`, { json: { cmd } });
+    }
+    /** Read a file from the island (defaults to the primary worktree). */
+    async readFile(name, path) {
+        const r = await this.request("GET", `${this.island(name)}/files/${encodePath(path)}`);
+        return new Uint8Array(await r.arrayBuffer());
+    }
+    /** Write a file into the island. */
+    async writeFile(name, path, data) {
+        await this.request("PUT", `${this.island(name)}/files/${encodePath(path)}`, { body: data });
+    }
+    /** Fetch container/agent logs as text. */
+    async logs(name, opts = {}) {
+        const r = await this.request("GET", `${this.island(name)}/logs`, { query: clean({ agent: opts.agent }) });
+        return r.text();
+    }
+    // ===== port broker ----------------------------------------------------
+    listPortScopes(name) {
+        return this.json("GET", `${this.island(name)}/port/scopes`);
+    }
+    grantPortScope(name, hostPath, mode = "ro") {
+        return this.json("POST", `${this.island(name)}/port/scopes`, { json: { host_path: hostPath, mode } });
+    }
+    async revokePortScope(name, scope) {
+        await this.request("DELETE", `${this.island(name)}/port/scopes/${this.seg(scope)}`);
+    }
+    portIntake(name, scope, srcRel, dest) {
+        return this.json("POST", `${this.island(name)}/port/intake`, { json: clean({ scope, src_rel: srcRel, dest }) });
+    }
+    portExport(name, src) {
+        return this.json("POST", `${this.island(name)}/port/export`, { json: { src } });
+    }
+    portWrite(name, scope, src, destRel) {
+        return this.json("POST", `${this.island(name)}/port/write`, { json: { scope, src, dest_rel: destRel } });
+    }
+    // ===== capability broker ---------------------------------------------
+    listCapabilityGrants(name) {
+        return this.json("GET", `${this.island(name)}/capability/grants`);
+    }
+    grantCapability(name, target) {
+        return this.json("POST", `${this.island(name)}/capability/grants`, { json: { target } });
+    }
+    async revokeCapability(name, target) {
+        await this.request("DELETE", `${this.island(name)}/capability/grants/${this.seg(target)}`);
+    }
+    /** Invoke a granted capability. Operators name `island`; an in-island token is pinned. */
+    executeCapability(target, opts = {}) {
+        return this.json("POST", "/v1/capabilities/execute", { json: clean({ target, island: opts.island, args: opts.args }) });
+    }
+    // ===== MCP broker -----------------------------------------------------
+    listMcpGrants(name) {
+        return this.json("GET", `${this.island(name)}/mcp/grants`);
+    }
+    grantMcp(name, server) {
+        return this.json("POST", `${this.island(name)}/mcp/grants`, { json: { server } });
+    }
+    async revokeMcp(name, server) {
+        await this.request("DELETE", `${this.island(name)}/mcp/grants/${this.seg(server)}`);
+    }
+    /** Invoke a JSON-RPC `method` on a granted MCP server (deny-all; ledgered). */
+    mcpCall(server, method, opts = {}) {
+        return this.json("POST", "/v1/mcp/call", { json: clean({ server, method, island: opts.island, params: opts.params }) });
+    }
+    // ===== credentials ----------------------------------------------------
+    async pushClaudeCredentials(credentialsJson) {
+        await this.request("PUT", "/v1/credentials/claude", { json: { credentials_json: credentialsJson } });
+    }
+    claudeCredentialsStatus() {
+        return this.json("GET", "/v1/credentials/claude");
+    }
+    listGitHubIdentities() {
+        return this.json("GET", "/v1/credentials/github");
+    }
+    putGitHubIdentity(name, opts) {
+        const body = clean({ login: opts.login, token: opts.token, id: opts.id, host: opts.host, default: opts.default || undefined });
+        return this.json("PUT", `/v1/credentials/github/${this.seg(name)}`, { json: body });
+    }
+    deleteGitHubIdentity(name) {
+        return this.json("DELETE", `/v1/credentials/github/${this.seg(name)}`);
+    }
+    githubRepos(name) {
+        return this.json("GET", `/v1/credentials/github/${this.seg(name)}/repos`);
+    }
+    listProviders() {
+        return this.json("GET", "/v1/credentials/providers");
+    }
+    putProvider(provider, opts) {
+        const body = clean({ api_key: opts.apiKey, base_url: opts.baseUrl, env_var: opts.envVar, default: opts.default || undefined });
+        return this.json("PUT", `/v1/credentials/providers/${this.seg(provider)}`, { json: body });
+    }
+    deleteProvider(provider) {
+        return this.json("DELETE", `/v1/credentials/providers/${this.seg(provider)}`);
+    }
+    // ===== operator tokens (owner-only) ----------------------------------
+    listTokens() {
+        return this.json("GET", "/v1/tokens");
+    }
+    /**
+     * Mint an operator bearer token. `role` is `owner`/`operator`/`viewer`;
+     * `islands` scopes it (empty = all). The response carries the bearer `secret` —
+     * returned ONCE and never stored in the clear.
+     */
+    createToken(role, opts = {}) {
+        return this.json("POST", "/v1/tokens", { json: clean({ role, label: opts.label, islands: opts.islands }) });
+    }
+    async revokeToken(tokenId) {
+        await this.request("DELETE", `/v1/tokens/${this.seg(tokenId)}`);
+    }
+    // ===== events / webhooks ---------------------------------------------
+    listSubscriptions() {
+        return this.json("GET", "/v1/events/subscriptions");
+    }
+    subscribeWebhook(url, opts = {}) {
+        return this.json("POST", "/v1/events/subscribe", { json: clean({ url, secret: opts.secret, events: opts.events }) });
+    }
+    async unsubscribeWebhook(subscriptionId) {
+        await this.request("DELETE", `/v1/events/subscriptions/${this.seg(subscriptionId)}`);
+    }
+    // ===== daemon ---------------------------------------------------------
+    overview() {
+        return this.json("GET", "/v1/overview");
+    }
+    agentTypes() {
+        return this.json("GET", "/v1/agent-types");
+    }
+    /** Reachability probe; resolves true when the daemon answers. */
+    async healthz() {
+        try {
+            await this.request("GET", "/v1/healthz");
+            return true;
+        }
+        catch (e) {
+            if (e instanceof DejimaError)
+                return false;
+            throw e;
+        }
+    }
+    /**
+     * The audit ledger (brokered ops + `api.request` + lifecycle) + a hash-chain
+     * verdict. Filters compose; `limit` tails the filtered result. `since`/`until`
+     * are RFC3339; `typePrefix` matches the entry-type prefix. With
+     * `format: "jsonl" | "csv"` the daemon streams a text export — this resolves
+     * that string instead of the parsed envelope.
+     */
+    async audit(opts = {}) {
+        const query = clean({
+            limit: opts.limit,
+            since: opts.since,
+            until: opts.until,
+            island: opts.island,
+            type: opts.typePrefix,
+            actor: opts.actor,
+            decision: opts.decision,
+            format: opts.format,
+        });
+        if (opts.format === "jsonl" || opts.format === "csv") {
+            return (await this.request("GET", "/v1/audit", { query })).text();
+        }
+        return this.json("GET", "/v1/audit", { query });
+    }
+    /**
+     * The team activity feed — a curated, human-rendered timeline over the audit
+     * ledger (who launched what, which agent did what), newest first. `kind` is
+     * `lifecycle`/`broker`/`system`; `since`/`until` are RFC3339.
+     */
+    activity(opts = {}) {
+        return this.json("GET", "/v1/activity", {
+            query: clean({
+                actor: opts.actor,
+                island: opts.island,
+                owner: opts.owner,
+                kind: opts.kind,
+                decision: opts.decision,
+                since: opts.since,
+                until: opts.until,
+                limit: opts.limit,
+            }),
+        });
+    }
+    /** Recent attach/detach events across every island (newest first). */
+    clientHistory() {
+        return this.json("GET", "/v1/clients");
+    }
+    /** Drop every active websocket client across every island. */
+    revokeSessions() {
+        return this.json("POST", "/v1/sessions/revoke");
+    }
+    panicStatus() {
+        return this.json("GET", "/v1/panic");
+    }
+    panic(opts = {}) {
+        return this.json("POST", "/v1/panic", { json: clean({ reason: opts.reason }) });
+    }
+    unpanic() {
+        return this.json("DELETE", "/v1/panic");
+    }
+    adminUpdate(opts = {}) {
+        return this.json("POST", "/v1/admin/update", { json: { execute: opts.execute ?? false, force: opts.force ?? false } });
+    }
+    /** Rebuild the island image; resolves the combined build output as text. */
+    async imageBuild() {
+        const r = await this.request("POST", "/v1/image/build");
+        return r.text();
+    }
+    authorizeSshKey(publicKey) {
+        return this.json("POST", "/v1/ssh/account-keys", { json: { public_key: publicKey } });
+    }
+    listSshKeys() {
+        return this.json("GET", "/v1/ssh/account-keys");
+    }
+    // ===== host terminals (operator-only; requires --host-terminals) -----
+    listTerminals() {
+        return this.json("GET", "/v1/terminals");
+    }
+    createTerminal(opts = {}) {
+        return this.json("POST", "/v1/terminals", { json: clean({ label: opts.label }) });
+    }
+    async deleteTerminal(terminalId) {
+        await this.request("DELETE", `/v1/terminals/${this.seg(terminalId)}`);
+    }
+    relabelTerminal(terminalId, label) {
+        return this.json("PATCH", `/v1/terminals/${this.seg(terminalId)}`, { json: { label } });
+    }
+    // ===== session (WebSocket PTY) ---------------------------------------
+    /** The WebSocket URL for an interactive PTY session (multi-attach). */
+    sessionUrl(name, opts = {}) {
+        const base = this.wsBase();
+        return opts.agent
+            ? `${base}${this.island(name)}/agents/${this.seg(opts.agent)}/session`
+            : `${base}${this.island(name)}/session`;
+    }
+    /** The WebSocket URL for a host terminal's PTY session. */
+    terminalSessionUrl(terminalId, opts = {}) {
+        let url = `${this.wsBase()}/v1/terminals/${this.seg(terminalId)}/session`;
+        if (opts.label)
+            url += `?label=${encodeURIComponent(opts.label)}`;
+        return url;
+    }
+    wsBase() {
+        return `${this.scheme === "https" ? "wss" : "ws"}://${this.host}`;
+    }
+    /** Open an island's PTY session stream. Resolves once the socket is open. */
+    attach(name, opts = {}) {
+        return this.openSession(this.sessionUrl(name, opts));
+    }
+    /** Open a host terminal's PTY session stream. */
+    attachTerminal(terminalId, opts = {}) {
+        return this.openSession(this.terminalSessionUrl(terminalId, opts));
+    }
+    async openSession(url) {
+        const headers = {};
+        if (this.token)
+            headers["Authorization"] = `Bearer ${this.token}`;
+        let ws;
+        if (this.wsFactory) {
+            ws = this.wsFactory(url, { headers });
+        }
+        else {
+            ws = await defaultWebSocket(url, headers);
+        }
+        await waitOpen(ws);
+        return new Session(ws);
+    }
+}
+function encodePath(path) {
+    // Keep slashes (the daemon matches {path...}) but escape each segment.
+    return path.split("/").map(encodeURIComponent).join("/");
+}
+async function errorMessage(resp) {
+    const body = (await resp.text()).trim();
+    try {
+        const data = JSON.parse(body);
+        if (data && typeof data.error === "string")
+            return data.error;
+    }
+    catch {
+        /* not JSON */
+    }
+    return body || resp.statusText;
+}
+/**
+ * Open a WebSocket using the Node `ws` package when available (it can set the
+ * Authorization header), falling back to the global `WebSocket` (browser / Node
+ * 22+ — note that the global cannot set request headers, so token auth needs the
+ * `ws` package or operator/no-token access).
+ */
+async function defaultWebSocket(url, headers) {
+    try {
+        const mod = await import("ws");
+        const WS = mod.default ?? mod.WebSocket ?? mod;
+        return new WS(url, { headers });
+    }
+    catch {
+        const G = globalThis;
+        if (typeof G.WebSocket === "function")
+            return new G.WebSocket(url);
+        throw new DejimaError(0, "no WebSocket available; install 'ws' or pass options.wsFactory");
+    }
+}
+function waitOpen(ws) {
+    return new Promise((resolve, reject) => {
+        const ok = () => resolve();
+        const bad = (e) => reject(new DejimaError(0, `websocket error: ${e?.message ?? e}`));
+        if (typeof ws.on === "function") {
+            ws.on("open", ok);
+            ws.on("error", bad);
+        }
+        else if (typeof ws.addEventListener === "function") {
+            ws.addEventListener("open", ok);
+            ws.addEventListener("error", bad);
+        }
+        else {
+            resolve(); // injected fake with no events; assume ready
+        }
+    });
+}

package/dist/errors.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Raised when the daemon returns a non-2xx response. The daemon's error body is
+ * JSON (`{"error": "..."}`); {@link message} is the extracted text when present,
+ * else the raw body.
+ */
+export declare class DejimaError extends Error {
+    readonly status: number;
+    /** Alias of {@link Error.message}, mirroring the Python client's `.message`. */
+    readonly description: string;
+    constructor(status: number, message: string);
+}

package/dist/errors.js

@@ -0,0 +1,16 @@
+/**
+ * Raised when the daemon returns a non-2xx response. The daemon's error body is
+ * JSON (`{"error": "..."}`); {@link message} is the extracted text when present,
+ * else the raw body.
+ */
+export class DejimaError extends Error {
+    status;
+    /** Alias of {@link Error.message}, mirroring the Python client's `.message`. */
+    description;
+    constructor(status, message) {
+        super(`HTTP ${status}: ${message}`);
+        this.name = "DejimaError";
+        this.status = status;
+        this.description = message;
+    }
+}

package/dist/index.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Dejima — TypeScript/JavaScript client for the Dejima API.
+ *
+ * ```ts
+ * import { Client } from "@dejima/sdk";
+ * const dj = new Client();                 // reads DEJIMA_HOST / DEJIMA_TOKEN
+ * const isl = await dj.createIsland("git@github.com:you/foo.git", { agent: "claude-code" });
+ * console.log(await dj.listIslands());
+ * ```
+ *
+ * Alpha (0.x): fields may change until 1.0. The REST layer mirrors
+ * `openapi.yaml`; the only hand-written ergonomic piece is the PTY `Session`.
+ */
+export { Client } from "./client.js";
+export type { ClientOptions } from "./client.js";
+export { Session } from "./session.js";
+export type { SessionEnvelope, WebSocketLike } from "./session.js";
+export { DejimaError } from "./errors.js";
+export declare const VERSION = "0.5.1";

package/dist/index.js

@@ -0,0 +1,17 @@
+/**
+ * Dejima — TypeScript/JavaScript client for the Dejima API.
+ *
+ * ```ts
+ * import { Client } from "@dejima/sdk";
+ * const dj = new Client();                 // reads DEJIMA_HOST / DEJIMA_TOKEN
+ * const isl = await dj.createIsland("git@github.com:you/foo.git", { agent: "claude-code" });
+ * console.log(await dj.listIslands());
+ * ```
+ *
+ * Alpha (0.x): fields may change until 1.0. The REST layer mirrors
+ * `openapi.yaml`; the only hand-written ergonomic piece is the PTY `Session`.
+ */
+export { Client } from "./client.js";
+export { Session } from "./session.js";
+export { DejimaError } from "./errors.js";
+export const VERSION = "0.5.1";

package/dist/session.d.ts

@@ -0,0 +1,70 @@
+import { DejimaError } from "./errors.js";
+/** One PTY session envelope on the wire (see openapi.yaml `SessionEnvelope`). */
+export interface SessionEnvelope {
+    type: "hello" | "data" | "resize" | "error";
+    b64?: string;
+    rows?: number;
+    cols?: number;
+    attached?: Array<{
+        label: string;
+        joined_at: string;
+    }>;
+}
+/**
+ * A WebSocket as this SDK uses it. Both the browser `WebSocket`
+ * (`addEventListener`) and the Node `ws` package (`on`) satisfy this; tests
+ * inject a fake.
+ */
+export interface WebSocketLike {
+    send(data: string): void;
+    close(): void;
+    addEventListener?(type: string, listener: (ev: any) => void): void;
+    removeEventListener?(type: string, listener: (ev: any) => void): void;
+    on?(event: string, listener: (...args: any[]) => void): void;
+}
+/**
+ * An attached PTY session over the daemon's JSON-envelope WebSocket protocol.
+ *
+ * The wire is JSON envelopes with terminal bytes base64-encoded. {@link send}
+ * and {@link recv} deal in raw `Uint8Array`; the framing is handled for you.
+ * You can also drive it event-style with {@link onData}/{@link onClose}.
+ */
+export declare class Session {
+    private ws;
+    /** Buffered output chunks not yet pulled by recv(). */
+    private buffer;
+    /** Pending recv() resolvers waiting for the next chunk. */
+    private waiters;
+    private dataCbs;
+    private closeCbs;
+    private errorCbs;
+    private done;
+    /** Clients attached to this session at connect time (from the `hello`). */
+    attached: Array<{
+        label: string;
+        joined_at: string;
+    }>;
+    constructor(ws: WebSocketLike);
+    private wire;
+    private onMessage;
+    private finish;
+    /** Send raw bytes to the PTY (keystrokes). */
+    send(data: Uint8Array): void;
+    /** Send a UTF-8 string to the PTY. */
+    sendText(text: string): void;
+    /** Resize the PTY. */
+    resize(rows: number, cols: number): void;
+    /**
+     * Pull the next chunk of PTY output as raw bytes, or `null` once the session
+     * has closed. Mirrors the Python client's blocking `recv()`.
+     */
+    recv(): Promise<Uint8Array | null>;
+    /** Register a callback for each output chunk. */
+    onData(cb: (bytes: Uint8Array) => void): void;
+    /** Register a callback for when the session closes. */
+    onClose(cb: () => void): void;
+    /** Register a callback for a server `error` envelope. */
+    onError(cb: (e: DejimaError) => void): void;
+    /** Close the underlying socket. */
+    close(): void;
+}

package/dist/session.js

@@ -0,0 +1,144 @@
+import { DejimaError } from "./errors.js";
+function base64Encode(bytes) {
+    // Cross-runtime base64 (Buffer in Node, btoa in the browser).
+    const g = globalThis;
+    if (typeof g.Buffer !== "undefined")
+        return g.Buffer.from(bytes).toString("base64");
+    let bin = "";
+    for (const b of bytes)
+        bin += String.fromCharCode(b);
+    return g.btoa(bin);
+}
+function base64Decode(s) {
+    const g = globalThis;
+    if (typeof g.Buffer !== "undefined")
+        return new Uint8Array(g.Buffer.from(s, "base64"));
+    const bin = g.atob(s);
+    const out = new Uint8Array(bin.length);
+    for (let i = 0; i < bin.length; i++)
+        out[i] = bin.charCodeAt(i);
+    return out;
+}
+/**
+ * An attached PTY session over the daemon's JSON-envelope WebSocket protocol.
+ *
+ * The wire is JSON envelopes with terminal bytes base64-encoded. {@link send}
+ * and {@link recv} deal in raw `Uint8Array`; the framing is handled for you.
+ * You can also drive it event-style with {@link onData}/{@link onClose}.
+ */
+export class Session {
+    ws;
+    /** Buffered output chunks not yet pulled by recv(). */
+    buffer = [];
+    /** Pending recv() resolvers waiting for the next chunk. */
+    waiters = [];
+    dataCbs = [];
+    closeCbs = [];
+    errorCbs = [];
+    done = false;
+    /** Clients attached to this session at connect time (from the `hello`). */
+    attached = [];
+    constructor(ws) {
+        this.ws = ws;
+        this.wire("message", (ev) => this.onMessage(typeof ev === "string" ? ev : ev?.data));
+        this.wire("close", () => this.finish());
+        this.wire("error", () => this.finish());
+    }
+    wire(event, fn) {
+        if (typeof this.ws.on === "function")
+            this.ws.on(event, fn);
+        else if (typeof this.ws.addEventListener === "function")
+            this.ws.addEventListener(event, fn);
+    }
+    onMessage(raw) {
+        if (raw == null)
+            return;
+        const text = typeof raw === "string" ? raw : raw.toString("utf-8");
+        let env;
+        try {
+            env = JSON.parse(text);
+        }
+        catch {
+            return;
+        }
+        switch (env.type) {
+            case "hello":
+                this.attached = env.attached ?? [];
+                break;
+            case "data": {
+                const bytes = base64Decode(env.b64 ?? "");
+                for (const cb of this.dataCbs)
+                    cb(bytes);
+                const w = this.waiters.shift();
+                if (w)
+                    w(bytes);
+                else
+                    this.buffer.push(bytes);
+                break;
+            }
+            case "error": {
+                // The daemon puts the plaintext error in `b64` for error envelopes.
+                const err = new DejimaError(0, env.b64 ?? "session error");
+                for (const cb of this.errorCbs)
+                    cb(err);
+                this.finish();
+                break;
+            }
+        }
+    }
+    finish() {
+        if (this.done)
+            return;
+        this.done = true;
+        for (const cb of this.closeCbs)
+            cb();
+        for (const w of this.waiters.splice(0))
+            w(null);
+    }
+    /** Send raw bytes to the PTY (keystrokes). */
+    send(data) {
+        this.ws.send(JSON.stringify({ type: "data", b64: base64Encode(data) }));
+    }
+    /** Send a UTF-8 string to the PTY. */
+    sendText(text) {
+        this.send(new TextEncoder().encode(text));
+    }
+    /** Resize the PTY. */
+    resize(rows, cols) {
+        this.ws.send(JSON.stringify({ type: "resize", rows, cols }));
+    }
+    /**
+     * Pull the next chunk of PTY output as raw bytes, or `null` once the session
+     * has closed. Mirrors the Python client's blocking `recv()`.
+     */
+    recv() {
+        const queued = this.buffer.shift();
+        if (queued)
+            return Promise.resolve(queued);
+        if (this.done)
+            return Promise.resolve(null);
+        return new Promise((resolve) => this.waiters.push(resolve));
+    }
+    /** Register a callback for each output chunk. */
+    onData(cb) {
+        this.dataCbs.push(cb);
+    }
+    /** Register a callback for when the session closes. */
+    onClose(cb) {
+        this.closeCbs.push(cb);
+    }
+    /** Register a callback for a server `error` envelope. */
+    onError(cb) {
+        this.errorCbs.push(cb);
+    }
+    /** Close the underlying socket. */
+    close() {
+        try {
+            this.ws.close();
+        }
+        catch {
+            /* best effort */
+        }
+        this.finish();
+    }
+}

package/package.json

@@ -0,0 +1,53 @@
+{
+  "name": "@dejima/sdk",
+  "version": "0.5.1",
+  "description": "TypeScript/JavaScript client for the Dejima API — run a fleet of AI coding agents on hardware you own.",
+  "license": "MIT",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "test": "tsx --test test/*.test.ts"
+  },
+  "keywords": [
+    "dejima",
+    "ai-agents",
+    "claude-code",
+    "codex",
+    "sandbox",
+    "self-hosted"
+  ],
+  "homepage": "https://dejima.tech/",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/aoos/dejima.git",
+    "directory": "sdk/ts"
+  },
+  "bugs": {
+    "url": "https://github.com/aoos/dejima/issues"
+  },
+  "devDependencies": {
+    "@types/node": "^20.0.0",
+    "@types/ws": "^8.5.0",
+    "tsx": "^4.7.0",
+    "typescript": "^5.4.0"
+  },
+  "optionalDependencies": {
+    "ws": "^8.16.0"
+  }
+}