@chopin-ai/workspace 0.0.0-stage → 0.3.0

package/LICENSE

@@ -0,0 +1,202 @@
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/dist/container.d.ts

@@ -0,0 +1,26 @@
+import { type Workspace, type WorkspaceProvider } from "./workspace.js";
+/** Runs the container CLI with `args` and resolves with its standard output. */
+export type ContainerCli = (args: readonly string[]) => Promise<string>;
+export interface ContainerWorkspaceOptions {
+    /** Image every workspace boots from; it must keep running on its own. */
+    image: string;
+    /** Names containers and volumes; providers with different prefixes never see each other's workspaces. */
+    prefix?: string;
+    /** Where the volume is mounted, also the working directory. */
+    mountPath?: string;
+    limits?: {
+        cpus?: number;
+        memory?: string;
+        pids?: number;
+    };
+    binary?: string;
+    cli?: ContainerCli;
+}
+export declare function containerCli(binary: string): ContainerCli;
+/** One container and one named volume per owner on the local container engine. */
+export declare class ContainerWorkspaceProvider implements WorkspaceProvider {
+    #private;
+    constructor(options: ContainerWorkspaceOptions);
+    open(owner: string): Workspace;
+    list(): Promise<Workspace[]>;
+}

package/dist/container.js

@@ -0,0 +1,136 @@
+import { execFile } from "node:child_process";
+import { createHash } from "node:crypto";
+import { promisify } from "node:util";
+import { carried } from "./workspace.js";
+const OWNER_LABEL = "chopin.owner";
+const PROVIDER_LABEL = "chopin.provider";
+const execFileAsync = promisify(execFile);
+export function containerCli(binary) {
+    return async (args) => (await execFileAsync(binary, args, { maxBuffer: 16 * 1024 * 1024 })).stdout;
+}
+/** One container and one named volume per owner on the local container engine. */
+export class ContainerWorkspaceProvider {
+    #options;
+    #queues = new Map();
+    // Lifecycle steps check and then act; two at once on one container would both create it.
+    #serial = (name, work) => {
+        const run = (this.#queues.get(name) ?? Promise.resolve()).then(work, work);
+        const tail = run.then(() => { }, () => { }).finally(() => {
+            if (this.#queues.get(name) === tail)
+                this.#queues.delete(name);
+        });
+        this.#queues.set(name, tail);
+        return run;
+    };
+    constructor(options) {
+        const binary = options.binary ?? "docker";
+        this.#options = {
+            ...options,
+            prefix: options.prefix ?? "chopin",
+            mountPath: options.mountPath ?? "/workspace",
+            binary,
+            cli: options.cli ?? containerCli(binary),
+        };
+    }
+    open(owner) {
+        if (owner === "" || /[\r\n]/.test(owner))
+            throw new Error("a workspace owner is a non-empty single line");
+        return new ContainerWorkspace(owner, this.#options, this.#serial);
+    }
+    async list() {
+        const out = await this.#options.cli([
+            "ps", "--all", "--filter", `label=${PROVIDER_LABEL}=${this.#options.prefix}`,
+            "--format", `{{.Label "${OWNER_LABEL}"}}`,
+        ]);
+        // Owners exactly as labelled, spaces included.
+        return out.split("\n").filter((owner) => owner !== "").map((owner) => this.open(owner));
+    }
+}
+class ContainerWorkspace {
+    owner;
+    root;
+    #name;
+    #options;
+    #serial;
+    constructor(owner, options, serial) {
+        this.owner = owner;
+        this.root = options.mountPath;
+        this.#options = options;
+        this.#serial = serial;
+        this.#name = `${options.prefix}-${createHash("sha256").update(owner).digest("hex").slice(0, 16)}`;
+    }
+    async state() {
+        const out = await this.#options.cli(["ps", "--all", "--filter", `name=^${this.#name}$`, "--format", "{{.State}}"]);
+        const [state] = lines(out);
+        if (state === undefined)
+            return "absent";
+        if (state === "running" || state === "paused")
+            return state;
+        return "stopped";
+    }
+    start() {
+        return this.#serial(this.#name, () => this.#start());
+    }
+    async #start() {
+        const state = await this.state();
+        if (state === "running")
+            return;
+        if (state === "paused") {
+            await this.#cli("unpause", this.#name);
+            return;
+        }
+        if (state === "absent")
+            await this.#create();
+        await this.#cli("start", this.#name);
+    }
+    pause() {
+        return this.#serial(this.#name, () => this.#pause());
+    }
+    async #pause() {
+        if (await this.state() === "running")
+            await this.#cli("pause", this.#name);
+    }
+    stop() {
+        return this.#serial(this.#name, () => this.#stop());
+    }
+    async #stop() {
+        const state = await this.state();
+        if (state === "paused")
+            await this.#cli("unpause", this.#name);
+        if (state === "paused" || state === "running")
+            await this.#cli("stop", this.#name);
+    }
+    destroy() {
+        return this.#serial(this.#name, () => this.#destroy());
+    }
+    async #destroy() {
+        if (await this.state() !== "absent")
+            await this.#cli("rm", "--force", this.#name);
+        await this.#cli("volume", "rm", "--force", this.#name);
+    }
+    command(argv, env = {}) {
+        const carry = carried(argv, env);
+        const names = Object.keys(carry.env);
+        const inside = names.length === 0 ? argv : ["sh", "-c", carry.exec, "sh", ...argv];
+        return {
+            argv: [this.#options.binary, "exec", "--interactive", ...names.flatMap((name) => ["--env", name]), this.#name, ...inside],
+            env: carry.env,
+        };
+    }
+    async #create() {
+        const { prefix, mountPath, image, limits } = this.#options;
+        const labels = ["--label", `${PROVIDER_LABEL}=${prefix}`, "--label", `${OWNER_LABEL}=${this.owner}`];
+        await this.#cli("volume", "create", ...labels, this.#name);
+        await this.#cli("create", "--name", this.#name, ...labels, "--hostname", "workspace", "--mount", `type=volume,src=${this.#name},dst=${mountPath}`, "--workdir", mountPath, "--init", "--security-opt", "no-new-privileges", ...flag("--cpus", limits?.cpus), ...flag("--memory", limits?.memory), ...flag("--pids-limit", limits?.pids), image);
+    }
+    async #cli(...args) {
+        await this.#options.cli(args);
+    }
+}
+function flag(name, value) {
+    return value === undefined ? [] : [name, String(value)];
+}
+function lines(out) {
+    return out.split("\n").map((line) => line.trim()).filter((line) => line !== "");
+}
+//# sourceMappingURL=container.js.map

package/dist/container.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"container.js","sourceRoot":"","sources":["../src/container.ts"],"names":[],"mappings":"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"}

package/dist/directory.d.ts

@@ -0,0 +1,19 @@
+import { type Workspace, type WorkspaceProvider } from "./workspace.js";
+export interface DirectoryWorkspaceOptions {
+    /**
+     * Directories no command in the workspace may read or write, each a real path with no symbolic link on the way,
+     * since that is how the sandbox sees them. Only macOS enforces this; elsewhere commands run unconfined.
+     */
+    hidden?: readonly string[];
+}
+/**
+ * Single-user local mode: the workspace is a directory of this machine, used as it is. There is nothing to start or
+ * stop, and nothing is ever deleted: the directory is the user's own.
+ */
+export declare class DirectoryWorkspaceProvider implements WorkspaceProvider {
+    #private;
+    constructor(root: string, options?: DirectoryWorkspaceOptions);
+    open(owner: string): Workspace;
+    /** Nothing here can be reclaimed. */
+    list(): Promise<Workspace[]>;
+}

package/dist/directory.js

@@ -0,0 +1,45 @@
+import { carried } from "./workspace.js";
+/**
+ * Single-user local mode: the workspace is a directory of this machine, used as it is. There is nothing to start or
+ * stop, and nothing is ever deleted: the directory is the user's own.
+ */
+export class DirectoryWorkspaceProvider {
+    #root;
+    #hidden;
+    constructor(root, options = {}) {
+        this.#root = root;
+        this.#hidden = options.hidden ?? [];
+    }
+    open(owner) {
+        return {
+            owner,
+            root: this.#root,
+            state: async () => "running",
+            start: async () => { },
+            pause: async () => { },
+            stop: async () => { },
+            destroy: async () => {
+                throw new Error(`${this.#root} is the user's own directory and is never destroyed`);
+            },
+            command: (argv, env = {}) => {
+                const carry = carried(argv, env);
+                return confined({ argv: ["sh", "-c", `cd "$1" && shift && ${carry.exec}`, "sh", this.#root, ...argv], env: carry.env }, this.#hidden);
+            },
+        };
+    }
+    /** Nothing here can be reclaimed. */
+    async list() {
+        return [];
+    }
+}
+/** `launch` under a macOS sandbox that denies every file operation within `hidden`, and allows all else. */
+function confined(launch, hidden) {
+    if (hidden.length === 0 || process.platform !== "darwin")
+        return launch;
+    // Paths travel as parameters, so none is ever quoted into the profile.
+    const params = hidden.flatMap((path, i) => ["-D", `HIDDEN_${i}=${path}`]);
+    const denied = hidden.map((_, i) => `(subpath (param "HIDDEN_${i}"))`).join(" ");
+    const profile = `(version 1)(allow default)(deny file-read* file-write* ${denied})`;
+    return { argv: ["/usr/bin/sandbox-exec", ...params, "-p", profile, ...launch.argv], env: launch.env };
+}
+//# sourceMappingURL=directory.js.map

package/dist/directory.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"directory.js","sourceRoot":"","sources":["../src/directory.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAuD,MAAM,gBAAgB,CAAC;AAU9F;;;GAGG;AACH,MAAM,OAAO,0BAA0B;IAC5B,KAAK,CAAS;IACd,OAAO,CAAoB;IAEpC,YAAY,IAAY,EAAE,OAAO,GAA8B,EAAE;QAC/D,IAAI,CAAC,KAAK,GAAG,IAAI,CAAC;QAClB,IAAI,CAAC,OAAO,GAAG,OAAO,CAAC,MAAM,IAAI,EAAE,CAAC;IACtC,CAAC;IAED,IAAI,CAAC,KAAa;QAChB,OAAO;YACL,KAAK;YACL,IAAI,EAAE,IAAI,CAAC,KAAK;YAChB,KAAK,EAAE,KAAK,IAAI,EAAE,CAAC,SAAS;YAC5B,KAAK,EAAE,KAAK,IAAI,EAAE,GAAE,CAAC;YACrB,KAAK,EAAE,KAAK,IAAI,EAAE,GAAE,CAAC;YACrB,IAAI,EAAE,KAAK,IAAI,EAAE,GAAE,CAAC;YACpB,OAAO,EAAE,KAAK,IAAI,EAAE;gBAClB,MAAM,IAAI,KAAK,CAAC,GAAG,IAAI,CAAC,KAAK,qDAAqD,CAAC,CAAC;YACtF,CAAC;YACD,OAAO,EAAE,CAAC,IAAI,EAAE,GAAG,GAAG,EAAE,EAAE,EAAE;gBAC1B,MAAM,KAAK,GAAG,OAAO,CAAC,IAAI,EAAE,GAAG,CAAC,CAAC;gBACjC,OAAO,QAAQ,CAAC,EAAE,IAAI,EAAE,CAAC,IAAI,EAAE,IAAI,EAAE,uBAAuB,KAAK,CAAC,IAAI,EAAE,EAAE,IAAI,EAAE,IAAI,CAAC,KAAK,EAAE,GAAG,IAAI,CAAC,EAAE,GAAG,EAAE,KAAK,CAAC,GAAG,EAAE,EAAE,IAAI,CAAC,OAAO,CAAC,CAAC;YACxI,CAAC;SACF,CAAC;IACJ,CAAC;IAED,qCAAqC;IACrC,KAAK,CAAC,IAAI;QACR,OAAO,EAAE,CAAC;IACZ,CAAC;CACF;AAED,4GAA4G;AAC5G,SAAS,QAAQ,CAAC,MAAc,EAAE,MAAyB;IACzD,IAAI,MAAM,CAAC,MAAM,KAAK,CAAC,IAAI,OAAO,CAAC,QAAQ,KAAK,QAAQ;QAAE,OAAO,MAAM,CAAC;IACxE,uEAAuE;IACvE,MAAM,MAAM,GAAG,MAAM,CAAC,OAAO,CAAC,CAAC,IAAI,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,IAAI,EAAE,UAAU,CAAC,IAAI,IAAI,EAAE,CAAC,CAAC,CAAC;IAC1E,MAAM,MAAM,GAAG,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,2BAA2B,CAAC,KAAK,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;IACjF,MAAM,OAAO,GAAG,0DAA0D,MAAM,GAAG,CAAC;IACpF,OAAO,EAAE,IAAI,EAAE,CAAC,uBAAuB,EAAE,GAAG,MAAM,EAAE,IAAI,EAAE,OAAO,EAAE,GAAG,MAAM,CAAC,IAAI,CAAC,EAAE,GAAG,EAAE,MAAM,CAAC,GAAG,EAAE,CAAC;AACxG,CAAC"}

package/dist/index.d.ts

@@ -0,0 +1,10 @@
+export { carried, isVariableName, reclaimIdle } from "./workspace.js";
+export type { Launch, Reclaimed, Workspace, WorkspaceProvider, WorkspaceState } from "./workspace.js";
+export { containerCli, ContainerWorkspaceProvider } from "./container.js";
+export type { ContainerCli, ContainerWorkspaceOptions } from "./container.js";
+export { diff, run, snapshot } from "./run.js";
+export type { RunOptions, RunResult } from "./run.js";
+export { DirectoryWorkspaceProvider } from "./directory.js";
+export type { DirectoryWorkspaceOptions } from "./directory.js";
+export { LoopbackWorkspaceProvider } from "./loopback.js";
+export type { LoopbackWorkspaceOptions } from "./loopback.js";

package/dist/index.js

@@ -0,0 +1,6 @@
+export { carried, isVariableName, reclaimIdle } from "./workspace.js";
+export { containerCli, ContainerWorkspaceProvider } from "./container.js";
+export { diff, run, snapshot } from "./run.js";
+export { DirectoryWorkspaceProvider } from "./directory.js";
+export { LoopbackWorkspaceProvider } from "./loopback.js";
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,cAAc,EAAE,WAAW,EAAE,MAAM,gBAAgB,CAAC;AAEtE,OAAO,EAAE,YAAY,EAAE,0BAA0B,EAAE,MAAM,gBAAgB,CAAC;AAE1E,OAAO,EAAE,IAAI,EAAE,GAAG,EAAE,QAAQ,EAAE,MAAM,UAAU,CAAC;AAE/C,OAAO,EAAE,0BAA0B,EAAE,MAAM,gBAAgB,CAAC;AAE5D,OAAO,EAAE,yBAAyB,EAAE,MAAM,eAAe,CAAC"}

package/dist/loopback-connect.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/loopback-connect.js

@@ -0,0 +1,17 @@
+// Run as `loopback-connect <port> serve --token <hex>`, where the execution daemon would be: hands the token to the
+// workspace listener on that loopback port, then joins this process's standard input and output to the daemon it starts.
+import { connect } from "node:net";
+const [port, verb, flag, token] = process.argv.slice(2);
+if (!/^\d{1,5}$/.test(port ?? "") || verb !== "serve" || flag !== "--token" || token === undefined) {
+    process.stderr.write("usage: loopback-connect <port> serve --token <hex>\n");
+    process.exit(2);
+}
+const link = connect(Number(port), "127.0.0.1", () => {
+    link.write(`${token}\n`);
+    process.stdin.pipe(link);
+    link.pipe(process.stdout);
+});
+link.on("error", (error) => process.stderr.write(`loopback-connect: ${error.message}\n`));
+// The daemon's last answer is written out whole before this process ends.
+link.on("close", (failed) => process.stdout.write("", () => process.exit(failed ? 1 : 0)));
+//# sourceMappingURL=loopback-connect.js.map

package/dist/loopback-connect.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"loopback-connect.js","sourceRoot":"","sources":["../src/loopback-connect.ts"],"names":[],"mappings":"AAAA,oHAAoH;AACpH,yHAAyH;AACzH,OAAO,EAAE,OAAO,EAAE,MAAM,UAAU,CAAC;AAEnC,MAAM,CAAC,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,KAAK,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC;AACxD,IAAI,CAAC,WAAW,CAAC,IAAI,CAAC,IAAI,IAAI,EAAE,CAAC,IAAI,IAAI,KAAK,OAAO,IAAI,IAAI,KAAK,SAAS,IAAI,KAAK,KAAK,SAAS,EAAE,CAAC;IACnG,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,sDAAsD,CAAC,CAAC;IAC7E,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;AAClB,CAAC;AACD,MAAM,IAAI,GAAG,OAAO,CAAC,MAAM,CAAC,IAAI,CAAC,EAAE,WAAW,EAAE,GAAG,EAAE;IACnD,IAAI,CAAC,KAAK,CAAC,GAAG,KAAK,IAAI,CAAC,CAAC;IACzB,OAAO,CAAC,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IACzB,IAAI,CAAC,IAAI,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC;AAC5B,CAAC,CAAC,CAAC;AACH,IAAI,CAAC,EAAE,CAAC,OAAO,EAAE,CAAC,KAAK,EAAE,EAAE,CAAC,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,qBAAqB,KAAK,CAAC,OAAO,IAAI,CAAC,CAAC,CAAC;AAC1F,0EAA0E;AAC1E,IAAI,CAAC,EAAE,CAAC,OAAO,EAAE,CAAC,MAAM,EAAE,EAAE,CAAC,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,EAAE,EAAE,GAAG,EAAE,CAAC,OAAO,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC"}

package/dist/loopback.d.ts

@@ -0,0 +1,23 @@
+import type { Workspace, WorkspaceProvider } from "./workspace.js";
+export interface LoopbackWorkspaceOptions {
+    /** The port the workspace's listener serves on the loopback address. */
+    port: number;
+    /** The persistent directory inside the workspace, where work happens. */
+    root: string;
+    /** The execution daemon as the listener starts it, the one command this workspace runs. */
+    daemon: string;
+    /** How long `start` waits for the listener to answer; a minute by default. */
+    startTimeoutMs?: number;
+}
+/**
+ * A workspace someone else runs beside the service on the same network, such as another container of the same pod,
+ * whose listener on a loopback port starts the execution daemon for each connection. Starting and stopping it is
+ * theirs. The daemon is all it runs: a byte stream carries no exit status, which any other command would need.
+ */
+export declare class LoopbackWorkspaceProvider implements WorkspaceProvider {
+    #private;
+    constructor(options: LoopbackWorkspaceOptions);
+    open(owner: string): Workspace;
+    /** Nothing here can be reclaimed: whoever runs the workspace does that. */
+    list(): Promise<Workspace[]>;
+}

package/dist/loopback.js

@@ -0,0 +1,65 @@
+import { connect } from "node:net";
+import { extname } from "node:path";
+import { setTimeout as sleep } from "node:timers/promises";
+import { fileURLToPath } from "node:url";
+/** The only address the workspace's listener is reached at: one no other machine can reach. */
+const LOOPBACK = "127.0.0.1";
+// The connector next to this module, run by Node as it is: compiled, or as source while testing.
+const CONNECTOR = fileURLToPath(new URL(`./loopback-connect${extname(fileURLToPath(import.meta.url))}`, import.meta.url));
+/**
+ * A workspace someone else runs beside the service on the same network, such as another container of the same pod,
+ * whose listener on a loopback port starts the execution daemon for each connection. Starting and stopping it is
+ * theirs. The daemon is all it runs: a byte stream carries no exit status, which any other command would need.
+ */
+export class LoopbackWorkspaceProvider {
+    #options;
+    constructor(options) {
+        if (!Number.isInteger(options.port) || options.port < 1 || options.port > 65_535)
+            throw new Error(`${options.port} is no port`);
+        this.#options = options;
+    }
+    open(owner) {
+        const { port, root, daemon, startTimeoutMs = 60_000 } = this.#options;
+        const at = `${LOOPBACK}:${port}`;
+        const managed = async () => {
+            throw new Error(`the workspace at ${at} is started and stopped by whoever runs it`);
+        };
+        return {
+            owner,
+            root,
+            state: async () => ((await answers(port)) ? "running" : "stopped"),
+            start: async () => {
+                const deadline = Date.now() + startTimeoutMs;
+                while (!(await answers(port))) {
+                    if (Date.now() >= deadline)
+                        throw new Error(`no workspace listener answered at ${at}`);
+                    await sleep(250);
+                }
+            },
+            pause: managed,
+            stop: managed,
+            destroy: managed,
+            command: (argv, env = {}) => {
+                if (argv.length !== 1 || argv[0] !== daemon || Object.keys(env).length > 0) {
+                    throw new Error(`the workspace at ${at} runs only its execution daemon, ${daemon}`);
+                }
+                return { argv: [process.execPath, CONNECTOR, String(port)], env: {} };
+            },
+        };
+    }
+    /** Nothing here can be reclaimed: whoever runs the workspace does that. */
+    async list() {
+        return [];
+    }
+}
+/** Whether a listener accepts a connection on the loopback `port` now. */
+function answers(port) {
+    return new Promise((resolve) => {
+        const probe = connect(port, LOOPBACK, () => {
+            probe.destroy();
+            resolve(true);
+        });
+        probe.on("error", () => resolve(false));
+    });
+}
+//# sourceMappingURL=loopback.js.map

package/dist/loopback.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"loopback.js","sourceRoot":"","sources":["../src/loopback.ts"],"names":[],"mappings":"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"}

package/dist/run.d.ts

@@ -0,0 +1,30 @@
+import type { Workspace } from "./workspace.js";
+export interface RunResult {
+    stdout: string;
+    stderr: string;
+    /** As a shell reports it: 128 plus the signal's number for a program a signal ended. */
+    exitCode: number;
+}
+export interface RunOptions {
+    /** Written to the program's standard input, which is closed either way. */
+    input?: string;
+}
+/**
+ * Runs a program inside the running workspace and collects all of its output, which callers take whole, such as a
+ * patch. However the program ends is a result, as is a program the workspace could not start, which ends with the
+ * code its launcher gives, such as 127 for one not found; only a launcher that could not start at all is an error.
+ */
+export declare function run(workspace: Workspace, argv: readonly string[], options?: RunOptions): Promise<RunResult>;
+/**
+ * The workspace's git work tree as a tree object, untracked files under the root included, for `diff` to compare
+ * against later.
+ * @returns `undefined` when the workspace root is not in a git work tree.
+ */
+export declare function snapshot(workspace: Workspace): Promise<string | undefined>;
+/**
+ * Everything changed under the workspace root since `base`, a `snapshot`, or since the last commit without one,
+ * untracked files included, as a binary patch with paths relative to the root: the bytes git wrote, whatever the
+ * files' encodings.
+ * @returns `undefined` when the workspace root is not in a git work tree.
+ */
+export declare function diff(workspace: Workspace, base?: string): Promise<Uint8Array | undefined>;

package/dist/run.js

@@ -0,0 +1,85 @@
+import { execFile } from "node:child_process";
+import { constants } from "node:os";
+/**
+ * Runs a program inside the running workspace and collects all of its output, which callers take whole, such as a
+ * patch. However the program ends is a result, as is a program the workspace could not start, which ends with the
+ * code its launcher gives, such as 127 for one not found; only a launcher that could not start at all is an error.
+ */
+export async function run(workspace, argv, options = {}) {
+    const result = await execute(workspace, argv, options);
+    return { ...result, stdout: result.stdout.toString("utf8") };
+}
+/** `run`, keeping standard output as the bytes the program wrote. */
+function execute(workspace, argv, options) {
+    const { argv: [binary, ...args], env } = workspace.command(argv);
+    return new Promise((resolve, reject) => {
+        const child = execFile(binary, args, { env: { ...process.env, ...env }, maxBuffer: Infinity, encoding: "buffer" }, (error, stdout, stderr) => {
+            const ended = (exitCode) => resolve({ stdout, stderr: stderr.toString("utf8"), exitCode });
+            if (error === null)
+                return ended(0);
+            if (typeof error.code === "number")
+                return ended(error.code);
+            const signal = error.signal === undefined || error.signal === null ? undefined : constants.signals[error.signal];
+            if (signal === undefined)
+                return reject(error);
+            ended(128 + signal);
+        });
+        // A program that exits without reading its input fails through its exit code, not through the pipe.
+        child.stdin?.on("error", () => { });
+        child.stdin?.end(options.input);
+    });
+}
+/**
+ * The workspace's git work tree as a tree object, untracked files under the root included, for `diff` to compare
+ * against later.
+ * @returns `undefined` when the workspace root is not in a git work tree.
+ */
+export async function snapshot(workspace) {
+    return (await inWorkTree(workspace, "git write-tree"))?.toString("utf8").trim();
+}
+/**
+ * Everything changed under the workspace root since `base`, a `snapshot`, or since the last commit without one,
+ * untracked files included, as a binary patch with paths relative to the root: the bytes git wrote, whatever the
+ * files' encodings.
+ * @returns `undefined` when the workspace root is not in a git work tree.
+ */
+export function diff(workspace, base) {
+    const since = '"${1:-$(git rev-parse --verify --quiet HEAD || git hash-object -t tree /dev/null)}"';
+    // Plumbing, so the user's diff settings, such as color, prefixes or external tools, never shape the patch.
+    const command = `git diff-index --cached --relative --patch --binary ${since}`;
+    return inWorkTree(workspace, command, ...(base === undefined ? [] : [base]));
+}
+/**
+ * Runs `command` with everything under the root staged in a throwaway index, so the work tree's own index stays
+ * untouched; a root inside a larger repository leaves the rest of it as the real index has it. The throwaway index
+ * starts as a copy of the real one, whose cached file stats spare rehashing unchanged files, and files are staged
+ * as a commit in this repository would record them. What git cannot stage, such as an unreadable file or a nested
+ * repository without a commit, is left out.
+ */
+async function inWorkTree(workspace, command, ...args) {
+    const script = [
+        // No repository only when nothing names one: no GIT_DIR and no `.git` up the tree. Any git failure past that is
+        // an error, even one git would also give outside a repository.
+        'if [ -z "${GIT_DIR:-}" ]; then dir=$(pwd -P); while [ ! -e "$dir/.git" ]; do [ "$dir" = / ] && exit 3; dir=${dir%/*}; dir=${dir:-/}; done; fi',
+        // The workspace may belong to another user than the one running this.
+        'n=${GIT_CONFIG_COUNT:-0}; export GIT_CONFIG_COUNT=$((n + 1)) "GIT_CONFIG_KEY_$n=safe.directory" "GIT_CONFIG_VALUE_$n=*"',
+        'inside=$(git rev-parse --is-inside-work-tree) || exit',
+        '[ "$inside" = true ] || exit 3',
+        'index="$(git rev-parse --git-path index)"',
+        'export GIT_INDEX_FILE="$(mktemp)"',
+        "trap 'rm -f \"$GIT_INDEX_FILE\"' EXIT",
+        // The copy keeps the index's own time, which git needs to notice a file changed within the same second.
+        'if [ -f "$index" ]; then cp -p "$index" "$GIT_INDEX_FILE"; else git read-tree --empty; fi',
+        "git add --all --ignore-errors -- .",
+        // Status 1: some path was left out.
+        'staged=$?; [ "$staged" -le 1 ] || exit "$staged"',
+        command,
+    ].join("\n");
+    const result = await execute(workspace, ["sh", "-c", script, "sh", ...args], {});
+    if (result.exitCode === 3)
+        return undefined;
+    if (result.exitCode !== 0)
+        throw new Error(`git failed in ${workspace.root}: ${result.stderr.trim()}`);
+    return result.stdout;
+}
+//# sourceMappingURL=run.js.map

package/dist/run.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"run.js","sourceRoot":"","sources":["../src/run.ts"],"names":[],"mappings":"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"}

package/dist/workspace.d.ts

@@ -0,0 +1,58 @@
+export type WorkspaceState = "absent" | "stopped" | "paused" | "running";
+/** One owner's isolated machine. Its volume outlives every state but `destroy`. */
+export interface Workspace {
+    readonly owner: string;
+    /** The persistent directory inside the workspace, where work happens. */
+    readonly root: string;
+    state(): Promise<WorkspaceState>;
+    /** Brings the workspace to running: creates, boots or resumes it as needed. */
+    start(): Promise<void>;
+    /** Freezes its processes and keeps their memory; `start` resumes them. */
+    pause(): Promise<void>;
+    /** Releases compute and keeps the volume; `start` boots it again. */
+    stop(): Promise<void>;
+    /** Deletes the workspace together with its volume. */
+    destroy(): Promise<void>;
+    /** How to run `argv` inside the running workspace, in its root, with stdio attached and `env` set. */
+    command(argv: readonly string[], env?: Readonly<Record<string, string>>): Launch;
+}
+/** A command line, and what to add to the environment it is started with. */
+export interface Launch {
+    argv: string[];
+    env: Record<string, string>;
+}
+/**
+ * Whether a workspace can carry a variable of this name: a portable name, other than `_`, which a shell sets anew
+ * for every command it starts, and those under which workspaces carry variables.
+ */
+export declare function isVariableName(name: string): boolean;
+/**
+ * Carries variables into a workspace with no value on any command line and none of their names in the launcher's own
+ * environment, where a PATH or a preload would change how the launcher runs. Each travels under a name of its own,
+ * and `exec`, a shell command that runs "$@", sets it under its name; one the shell does not keep as given, such as
+ * a variable it computes or holds read-only, stops the command from starting rather than reaching it changed.
+ */
+export declare function carried(argv: readonly string[], env: Readonly<Record<string, string>>): {
+    env: Record<string, string>;
+    exec: string;
+};
+export interface WorkspaceProvider {
+    /** The owner's workspace. Nothing is created until it is started. */
+    open(owner: string): Workspace;
+    /** Every workspace this provider has created and not destroyed. */
+    list(): Promise<Workspace[]>;
+}
+/** What a sweep did: the owners whose workspaces it stopped, and those it could not, with why. */
+export interface Reclaimed {
+    stopped: string[];
+    failed: {
+        owner: string;
+        error: unknown;
+    }[];
+}
+/**
+ * Stops the workspaces of owners idle for at least `idleMs`, a few at a time, keeping their volumes. An owner is
+ * asked again right before its workspace stops, so work that began meanwhile keeps it; a workspace that fails to
+ * stop keeps no other from stopping.
+ */
+export declare function reclaimIdle(provider: WorkspaceProvider, lastActive: (owner: string) => number | undefined, idleMs: number, now?: number): Promise<Reclaimed>;

package/dist/workspace.js

@@ -0,0 +1,67 @@
+const VARIABLE = /^[A-Za-z_][A-Za-z0-9_]*$/;
+const CARRIED = "CHOPIN_ENV_";
+/**
+ * Whether a workspace can carry a variable of this name: a portable name, other than `_`, which a shell sets anew
+ * for every command it starts, and those under which workspaces carry variables.
+ */
+export function isVariableName(name) {
+    return VARIABLE.test(name) && name !== "_" && !name.startsWith(CARRIED);
+}
+/**
+ * Carries variables into a workspace with no value on any command line and none of their names in the launcher's own
+ * environment, where a PATH or a preload would change how the launcher runs. Each travels under a name of its own,
+ * and `exec`, a shell command that runs "$@", sets it under its name; one the shell does not keep as given, such as
+ * a variable it computes or holds read-only, stops the command from starting rather than reaching it changed.
+ */
+export function carried(argv, env) {
+    if (argv.length === 0)
+        throw new Error("there is no command to run");
+    const names = Object.keys(env);
+    if (names.length === 0)
+        return { env: {}, exec: 'exec "$@"' };
+    const invalid = names.find((name) => !isVariableName(name));
+    if (invalid !== undefined)
+        throw new Error(`${JSON.stringify(invalid)} is not a variable name a workspace can carry`);
+    const carrier = (name) => CARRIED + name;
+    // A subshell tries each export first, since a failing one would end the shell itself.
+    const set = names.map((name) => {
+        const value = `"$${carrier(name)}"`;
+        return `{ (export ${name}=${value}) 2>/dev/null && export ${name}=${value} && [ "$${name}" = ${value} ] || { echo "the workspace's shell keeps its own ${name}" >&2; exit 126; }; }`;
+    });
+    return {
+        env: Object.fromEntries(names.map((name) => [carrier(name), env[name]])),
+        exec: `${set.join(" && ")} && unset ${names.map(carrier).join(" ")} && exec "$@"`,
+    };
+}
+/**
+ * Stops the workspaces of owners idle for at least `idleMs`, a few at a time, keeping their volumes. An owner is
+ * asked again right before its workspace stops, so work that began meanwhile keeps it; a workspace that fails to
+ * stop keeps no other from stopping.
+ */
+export async function reclaimIdle(provider, lastActive, idleMs, now = Date.now()) {
+    const reclaimed = { stopped: [], failed: [] };
+    const idle = (owner) => {
+        const active = lastActive(owner);
+        return active === undefined || now - active >= idleMs;
+    };
+    const queue = (await provider.list()).filter((workspace) => idle(workspace.owner));
+    const worker = async () => {
+        for (let workspace = queue.shift(); workspace !== undefined; workspace = queue.shift()) {
+            try {
+                const state = await workspace.state();
+                if ((state !== "running" && state !== "paused") || !idle(workspace.owner))
+                    continue;
+                await workspace.stop();
+                reclaimed.stopped.push(workspace.owner);
+            }
+            catch (error) {
+                reclaimed.failed.push({ owner: workspace.owner, error });
+            }
+        }
+    };
+    await Promise.all(Array.from({ length: RECLAIMING_AT_ONCE }, worker));
+    return reclaimed;
+}
+/** How many workspaces a sweep stops at once, so an engine with many is not flooded. */
+const RECLAIMING_AT_ONCE = 8;
+//# sourceMappingURL=workspace.js.map

package/dist/workspace.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"workspace.js","sourceRoot":"","sources":["../src/workspace.ts"],"names":[],"mappings":"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"}

package/loopback-listener.sh

@@ -0,0 +1,16 @@
+#!/bin/sh
+# Serves this workspace to an agent service beside it on the same network, as LoopbackWorkspaceProvider reaches it:
+#   loopback-listener.sh <port> <daemon>
+# Each connection starts the execution daemon with the connection as its standard input and output, under the token
+# the connection's first line carries; one that sends nothing was only checking the listener is up. It listens on the
+# loopback address alone, which nothing outside this network can reach. The daemon's path, and this script's, have no
+# space, colon or comma, which the relay's addresses would split on.
+set -eu
+if [ "${1-}" = --connection ]; then
+  read -r token || exit 0
+  case $token in '' | *[!0-9a-f]*) exit 2 ;; esac
+  exec "$2" serve --token "$token"
+fi
+case ${1-}:${2-} in '' | :* | *[!0-9]*:* | *:) echo "usage: loopback-listener.sh <port> <daemon>" >&2; exit 2 ;; esac
+# Once a connection stops sending, the daemon is given time to answer what it was asked; it ends sooner by itself.
+exec socat -t 10 "TCP-LISTEN:$1,bind=127.0.0.1,reuseaddr,fork" "EXEC:$0 --connection $2"

package/package.json

@@ -1,6 +1,25 @@
 {
   "name": "@chopin-ai/workspace",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.3.0",
+  "description": "Per-user workspace lifecycle interface with directory and container implementations",
+  "license": "Apache-2.0",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/CodePrometheus/chopin-ai.git",
+    "directory": "packages/workspace"
+  },
+  "type": "module",
+  "engines": {
+    "node": ">=24.8.0"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "loopback-listener.sh"
+  ]
 }

package/README.md

@@ -1,3 +0,0 @@
-# Temporary Holding Version
-
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.