@palai/sdk 0.1.0 → 0.3.0

package/dist/resources/workspaces.d.ts

@@ -0,0 +1,94 @@
+import type { Session, Workspace, WorkspaceRepository } from "../generated/types.ts";
+import type { Palai } from "../client.ts";
+import { type CallOptions, type Page } from "./shared.ts";
+/**
+ * WorkspaceCreateParams declares what a workspace holds.
+ *
+ * `mount_path` is what makes N repositories ONE workspace: `api` and `web` are two checkouts under a
+ * single allocation root that an agent can walk between in one sandbox — which is the whole reason a
+ * workspace holds more than one. Two entries cannot share a mount path; the server refuses the create
+ * and names the colliding path. `requested_ref` is optional and empty means the binding's own default
+ * branch.
+ */
+export interface WorkspaceCreateParams {
+    repositories: WorkspaceRepository[];
+}
+export interface WorkspaceManifest {
+    object: "workspace.manifest";
+    workspace_id: string;
+    tree_checksum: string;
+    entry_count: number;
+    size_bytes: number;
+    entries: {
+        path: string;
+        digest: string;
+        size: number;
+        mode: number;
+        [key: string]: unknown;
+    }[];
+    exclusions: string[];
+    created_at: string;
+}
+/**
+ * The /v1/workspaces resource: open a workspace holding N repositories, read it back, and ask which
+ * sessions share its tree.
+ *
+ * ‼️ A WORKSPACE IS THE DURABLE THING AND A SESSION ATTACHES TO IT. That is the shape a caller has to
+ * hold: open one workspace, then open as many sessions on it as you have conversations to run, and all
+ * of them read and write ONE checkout on ONE machine. Opening a session per conversation without a
+ * workspace — which is what this SDK used to do — gives each one a tree of its own that the others
+ * cannot see, and a machine bill per conversation.
+ *
+ * Mirrors the `Sessions` resource shape: a class taking the client, each method with a trailing
+ * `options: CallOptions`.
+ */
+export declare class Workspaces {
+    #private;
+    constructor(client: Palai);
+    /** Read the complete tenant-scoped immutable file manifest. */
+    manifest(manifestID: string, options?: CallOptions): Promise<WorkspaceManifest>;
+    /**
+     * create opens a workspace holding the declared repositories (201).
+     *
+     * ‼️ IT RETURNS BEFORE THE TREE EXISTS, and the clone is asynchronous because it takes as long as N
+     * clones take — a create that waited would make a five-repository workspace a request that times out.
+     *
+     * ‼️ DO NOT WAIT FOR `ready`. `status` is the workspace's PLACEMENT state, not its contents: `ready`
+     * means a machine holds it, so a workspace nothing has run on yet stays `requested` however complete
+     * its tree is. Measured on a live stack: a workspace whose two repositories were fully published sat
+     * at `requested` indefinitely until a session ran on it. Open a session and send a message — the
+     * first run places the workspace and pays no clone, which is the whole point of cloning at create.
+     *
+     * Like `sessions.create` it carries no idempotency key: creation is unkeyed, a retried create mints
+     * a NEW workspace, so a torn connection is left alone rather than retried into a duplicate tree.
+     */
+    create(params: WorkspaceCreateParams, options?: CallOptions): Promise<Workspace>;
+    /**
+     * list answers which workspaces this project has, newest first, each with its repositories.
+     *
+     * ‼️ IT IS THE READ EVERY CALLER NEEDS FIRST AND THE ONE THIS SURFACE SHIPPED WITHOUT. `create` and
+     * `retrieve` let a caller open a workspace and read back the one they just made; neither answers "which
+     * do I have?" — and since a session is born ON a workspace, every screen that opens one has to offer a
+     * choice. Measured on production: `GET /v1/workspaces` answered 405, while the admin console had already
+     * been written against a fixture that served it.
+     */
+    list(options?: CallOptions): Promise<Page<Workspace>>;
+    /**
+     * retrieve reads one workspace: its lifecycle state, the machine holding it if any, and its
+     * repositories at their mount paths, in the order genesis builds them.
+     *
+     * `machine_id` is null between runs and that is the ORDINARY state, not an error — the hold is
+     * released when every session on the tree goes idle and taken again on the next placement.
+     */
+    retrieve(workspaceId: string, options?: CallOptions): Promise<Workspace>;
+    /**
+     * sessions lists the sessions sharing this workspace's tree, in creation order.
+     *
+     * THIS IS THE READ THAT MAKES THE SHARED TREE USABLE. Everything a caller can do to a session —
+     * steering it, reading its events, configuring it — is addressed by session id, so "which ids are on
+     * this workspace" is the question that turns one workspace into N conversations. An empty roster is
+     * an answer, not a miss: a workspace nobody has opened a session on yet still exists.
+     */
+    sessions(workspaceId: string, options?: CallOptions): Promise<Page<Session>>;
+}
+//# sourceMappingURL=workspaces.d.ts.map

package/dist/resources/workspaces.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"workspaces.d.ts","sourceRoot":"","sources":["../../src/resources/workspaces.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,SAAS,EAAE,mBAAmB,EAAE,MAAM,uBAAuB,CAAC;AACrF,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,cAAc,CAAC;AAC1C,OAAO,EAAiB,KAAK,WAAW,EAAE,KAAK,IAAI,EAAE,MAAM,aAAa,CAAC;AAEzE;;;;;;;;GAQG;AACH,MAAM,WAAW,qBAAqB;IACpC,YAAY,EAAE,mBAAmB,EAAE,CAAC;CACrC;AAED,MAAM,WAAW,iBAAiB;IAChC,MAAM,EAAE,oBAAoB,CAAC;IAC7B,YAAY,EAAE,MAAM,CAAC;IACrB,aAAa,EAAE,MAAM,CAAC;IACtB,WAAW,EAAE,MAAM,CAAC;IACpB,UAAU,EAAE,MAAM,CAAC;IACnB,OAAO,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAC;QAAC,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAA;KAAE,EAAE,CAAC;IAChG,UAAU,EAAE,MAAM,EAAE,CAAC;IACrB,UAAU,EAAE,MAAM,CAAC;CACpB;AAED;;;;;;;;;;;;GAYG;AACH,qBAAa,UAAU;;IAGrB,YAAY,MAAM,EAAE,KAAK,EAExB;IAED,+DAA+D;IACzD,QAAQ,CAAC,UAAU,EAAE,MAAM,EAAE,OAAO,GAAE,WAAgB,GAAG,OAAO,CAAC,iBAAiB,CAAC,CAExF;IAED;;;;;;;;;;;;;;OAcG;IACG,MAAM,CAAC,MAAM,EAAE,qBAAqB,EAAE,OAAO,GAAE,WAAgB,GAAG,OAAO,CAAC,SAAS,CAAC,CAWzF;IAED;;;;;;;;OAQG;IACG,IAAI,CAAC,OAAO,GAAE,WAAgB,GAAG,OAAO,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC,CAG9D;IAED;;;;;;OAMG;IACG,QAAQ,CAAC,WAAW,EAAE,MAAM,EAAE,OAAO,GAAE,WAAgB,GAAG,OAAO,CAAC,SAAS,CAAC,CAOjF;IAED;;;;;;;OAOG;IACG,QAAQ,CAAC,WAAW,EAAE,MAAM,EAAE,OAAO,GAAE,WAAgB,GAAG,OAAO,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC,CAOrF;CACF"}

package/dist/resources/workspaces.js

@@ -0,0 +1,88 @@
+import { callArgs, enc } from "./shared.js";
+/**
+ * The /v1/workspaces resource: open a workspace holding N repositories, read it back, and ask which
+ * sessions share its tree.
+ *
+ * ‼️ A WORKSPACE IS THE DURABLE THING AND A SESSION ATTACHES TO IT. That is the shape a caller has to
+ * hold: open one workspace, then open as many sessions on it as you have conversations to run, and all
+ * of them read and write ONE checkout on ONE machine. Opening a session per conversation without a
+ * workspace — which is what this SDK used to do — gives each one a tree of its own that the others
+ * cannot see, and a machine bill per conversation.
+ *
+ * Mirrors the `Sessions` resource shape: a class taking the client, each method with a trailing
+ * `options: CallOptions`.
+ */
+export class Workspaces {
+    #client;
+    constructor(client) {
+        this.#client = client;
+    }
+    /** Read the complete tenant-scoped immutable file manifest. */
+    async manifest(manifestID, options = {}) {
+        return (await this.#client.request("GET", `/v1/workspace-manifests/${enc(manifestID)}`, callArgs(options))).body;
+    }
+    /**
+     * create opens a workspace holding the declared repositories (201).
+     *
+     * ‼️ IT RETURNS BEFORE THE TREE EXISTS, and the clone is asynchronous because it takes as long as N
+     * clones take — a create that waited would make a five-repository workspace a request that times out.
+     *
+     * ‼️ DO NOT WAIT FOR `ready`. `status` is the workspace's PLACEMENT state, not its contents: `ready`
+     * means a machine holds it, so a workspace nothing has run on yet stays `requested` however complete
+     * its tree is. Measured on a live stack: a workspace whose two repositories were fully published sat
+     * at `requested` indefinitely until a session ran on it. Open a session and send a message — the
+     * first run places the workspace and pays no clone, which is the whole point of cloning at create.
+     *
+     * Like `sessions.create` it carries no idempotency key: creation is unkeyed, a retried create mints
+     * a NEW workspace, so a torn connection is left alone rather than retried into a duplicate tree.
+     */
+    async create(params, options = {}) {
+        if (!params.repositories || params.repositories.length === 0) {
+            // The server refuses this, and a local complaint beats a round trip for a call the caller could
+            // not have meant.
+            throw new TypeError("palai: workspaces.create requires at least one repository");
+        }
+        const result = await this.#client.request("POST", "/v1/workspaces", {
+            body: { repositories: params.repositories },
+            ...callArgs(options),
+        });
+        return result.body;
+    }
+    /**
+     * list answers which workspaces this project has, newest first, each with its repositories.
+     *
+     * ‼️ IT IS THE READ EVERY CALLER NEEDS FIRST AND THE ONE THIS SURFACE SHIPPED WITHOUT. `create` and
+     * `retrieve` let a caller open a workspace and read back the one they just made; neither answers "which
+     * do I have?" — and since a session is born ON a workspace, every screen that opens one has to offer a
+     * choice. Measured on production: `GET /v1/workspaces` answered 405, while the admin console had already
+     * been written against a fixture that served it.
+     */
+    async list(options = {}) {
+        const result = await this.#client.request("GET", "/v1/workspaces", callArgs(options));
+        return result.body;
+    }
+    /**
+     * retrieve reads one workspace: its lifecycle state, the machine holding it if any, and its
+     * repositories at their mount paths, in the order genesis builds them.
+     *
+     * `machine_id` is null between runs and that is the ORDINARY state, not an error — the hold is
+     * released when every session on the tree goes idle and taken again on the next placement.
+     */
+    async retrieve(workspaceId, options = {}) {
+        const result = await this.#client.request("GET", `/v1/workspaces/${enc(workspaceId)}`, callArgs(options));
+        return result.body;
+    }
+    /**
+     * sessions lists the sessions sharing this workspace's tree, in creation order.
+     *
+     * THIS IS THE READ THAT MAKES THE SHARED TREE USABLE. Everything a caller can do to a session —
+     * steering it, reading its events, configuring it — is addressed by session id, so "which ids are on
+     * this workspace" is the question that turns one workspace into N conversations. An empty roster is
+     * an answer, not a miss: a workspace nobody has opened a session on yet still exists.
+     */
+    async sessions(workspaceId, options = {}) {
+        const result = await this.#client.request("GET", `/v1/workspaces/${enc(workspaceId)}/sessions`, callArgs(options));
+        return result.body;
+    }
+}
+//# sourceMappingURL=workspaces.js.map

package/dist/resources/workspaces.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"workspaces.js","sourceRoot":"","sources":["../../src/resources/workspaces.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,QAAQ,EAAE,GAAG,EAA+B,MAAM,aAAa,CAAC;AA0BzE;;;;;;;;;;;;GAYG;AACH,MAAM,OAAO,UAAU;IACrB,OAAO,CAAQ;IAEf,YAAY,MAAa;QACvB,IAAI,CAAC,OAAO,GAAG,MAAM,CAAC;IACxB,CAAC;IAED,+DAA+D;IAC/D,KAAK,CAAC,QAAQ,CAAC,UAAkB,EAAE,OAAO,GAAgB,EAAE;QAC1D,OAAO,CAAC,MAAM,IAAI,CAAC,OAAO,CAAC,OAAO,CAAoB,KAAK,EAAE,2BAA2B,GAAG,CAAC,UAAU,CAAC,EAAE,EAAE,QAAQ,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC;IACtI,CAAC;IAED;;;;;;;;;;;;;;OAcG;IACH,KAAK,CAAC,MAAM,CAAC,MAA6B,EAAE,OAAO,GAAgB,EAAE;QACnE,IAAI,CAAC,MAAM,CAAC,YAAY,IAAI,MAAM,CAAC,YAAY,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;YAC7D,gGAAgG;YAChG,kBAAkB;YAClB,MAAM,IAAI,SAAS,CAAC,2DAA2D,CAAC,CAAC;QACnF,CAAC;QACD,MAAM,MAAM,GAAG,MAAM,IAAI,CAAC,OAAO,CAAC,OAAO,CAAY,MAAM,EAAE,gBAAgB,EAAE;YAC7E,IAAI,EAAE,EAAE,YAAY,EAAE,MAAM,CAAC,YAAY,EAAE;YAC3C,GAAG,QAAQ,CAAC,OAAO,CAAC;SACrB,CAAC,CAAC;QACH,OAAO,MAAM,CAAC,IAAI,CAAC;IACrB,CAAC;IAED;;;;;;;;OAQG;IACH,KAAK,CAAC,IAAI,CAAC,OAAO,GAAgB,EAAE;QAClC,MAAM,MAAM,GAAG,MAAM,IAAI,CAAC,OAAO,CAAC,OAAO,CAAkB,KAAK,EAAE,gBAAgB,EAAE,QAAQ,CAAC,OAAO,CAAC,CAAC,CAAC;QACvG,OAAO,MAAM,CAAC,IAAI,CAAC;IACrB,CAAC;IAED;;;;;;OAMG;IACH,KAAK,CAAC,QAAQ,CAAC,WAAmB,EAAE,OAAO,GAAgB,EAAE;QAC3D,MAAM,MAAM,GAAG,MAAM,IAAI,CAAC,OAAO,CAAC,OAAO,CACvC,KAAK,EACL,kBAAkB,GAAG,CAAC,WAAW,CAAC,EAAE,EACpC,QAAQ,CAAC,OAAO,CAAC,CAClB,CAAC;QACF,OAAO,MAAM,CAAC,IAAI,CAAC;IACrB,CAAC;IAED;;;;;;;OAOG;IACH,KAAK,CAAC,QAAQ,CAAC,WAAmB,EAAE,OAAO,GAAgB,EAAE;QAC3D,MAAM,MAAM,GAAG,MAAM,IAAI,CAAC,OAAO,CAAC,OAAO,CACvC,KAAK,EACL,kBAAkB,GAAG,CAAC,WAAW,CAAC,WAAW,EAC7C,QAAQ,CAAC,OAAO,CAAC,CAClB,CAAC;QACF,OAAO,MAAM,CAAC,IAAI,CAAC;IACrB,CAAC;CACF"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@palai/sdk",
-  "version": "0.1.0",
+  "version": "0.3.0",
   "description": "TypeScript client for the Palai API: responses, sessions, agents, approvals, artifacts and streaming.",
   "license": "Apache-2.0",
   "type": "module",