@zukhruf/coprocess 0.0.0-stage → 0.3.42

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 ezzabuzaid
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,49 @@
-# Temporary Holding Version
+# @zukhruf/coprocess
 
-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.
+A coprocess is a long-lived child process that the parent talks to over its stdin and stdout, as with `coproc` in bash and `|&` in ksh. A native helper that keeps a model loaded, or a command-line agent that reads one message at a time, is a coprocess. `Coprocess` starts the process, sends and receives values, tells you when the process exits, and stops it with SIGTERM and then SIGKILL. A value is JSON on one line; that is the only framing so far.
+
+The words in these documents have one meaning each. See the glossary in [CONTEXT.md](./CONTEXT.md).
+
+## Send a request and receive the answer
+
+A helper answers each request with one line. `request` sends a value and receives the next one.
+
+```ts
+import { Coprocess } from '@zukhruf/coprocess';
+
+const ocr = new Coprocess('/path/to/vision-worker', [], {
+  name: 'Vision worker',
+});
+const answer = await ocr.request({ path: '/tmp/receipt.png' });
+await ocr.close();
+```
+
+The process gives `unknown`. Parse it with your own schema, for example with zod.
+
+## Receive many values for one message
+
+An agent can answer one message with many lines, and a last line that says the work is done. Use `send` once and `receive` until that line comes.
+
+```ts
+claude.send({ type: 'user', message: { role: 'user', content: prompt } });
+let event = await claude.receive();
+while (!isResult(event)) event = await claude.receive();
+```
+
+## Know when the process exits
+
+`exited()` settles once, when the process ends, with the error that each later `receive` gets. A pool can listen to it and replace the worker at once.
+
+```ts
+void worker.exited().then(() => pool.replace(worker));
+```
+
+The error names the process, the exit code or signal, and the last 16 KiB of its stderr, for example `Vision worker exited (SIGKILL): <stderr>`. It does not contain the command line, because arguments can hold prompts or secrets.
+
+## Stop the process
+
+`kill()` sends SIGTERM. If the process is still alive after five seconds, it gets SIGKILL. A native helper without a signal handler stops at once; a process that saves its state first gets the time to do it. `close()` ends stdin, which asks the process to finish, and waits for the exit.
+
+## Decisions
+
+- [ADR 0001](./docs/adr/0001-the-exit-is-an-event-and-the-package-uses-execa.md): the exit is an event, and the package uses execa.

package/dist/coprocess.d.ts

@@ -0,0 +1,15 @@
+import { type Options } from 'execa';
+export interface CoprocessOptions extends Pick<Options, 'cwd' | 'env'> {
+    readonly name: string;
+}
+export declare class Coprocess {
+    #private;
+    constructor(file: string, args: readonly string[], options: CoprocessOptions);
+    exited(): Promise<Error>;
+    send(value: unknown): void;
+    receive(): Promise<unknown>;
+    request(value: unknown): Promise<unknown>;
+    kill(): void;
+    close(): Promise<void>;
+}
+//# sourceMappingURL=coprocess.d.ts.map

package/dist/coprocess.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"coprocess.d.ts","sourceRoot":"","sources":["../src/coprocess.ts"],"names":[],"mappings":"AAEA,OAAO,EAAmB,KAAK,OAAO,EAAS,MAAM,OAAO,CAAC;AAS7D,MAAM,WAAW,gBAAiB,SAAQ,IAAI,CAAC,OAAO,EAAE,KAAK,GAAG,KAAK,CAAC;IAEpE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;CACvB;AAOD,qBAAa,SAAS;;gBASlB,IAAI,EAAE,MAAM,EACZ,IAAI,EAAE,SAAS,MAAM,EAAE,EACvB,OAAO,EAAE,gBAAgB;IAgC3B,MAAM,IAAI,OAAO,CAAC,KAAK,CAAC;IAIxB,IAAI,CAAC,KAAK,EAAE,OAAO,GAAG,IAAI;IAMpB,OAAO,IAAI,OAAO,CAAC,OAAO,CAAC;IAkBjC,OAAO,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC;IAKzC,IAAI,IAAI,IAAI;IAKN,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;CAU7B"}

package/dist/coprocess.js

@@ -0,0 +1,85 @@
+import { createInterface } from 'node:readline';
+import { execa } from 'execa';
+import { Latch } from '@zukhruf/async';
+// The last part of stderr an exit reports: enough for a native crash, and
+// bounded, because a process can write to stderr for hours. execa's maxBuffer
+// would end the process instead.
+const tail = 16_384;
+// A long-lived child process that takes JSON values on stdin and gives them
+// on stdout, one value per line. What a value means is the caller's
+// protocol: one answer per request, or many lines until one says the work is
+// done. The exit is an event: exited settles when the process ends, and every
+// receive after it fails with the stderr of the process.
+export class Coprocess {
+    #name;
+    #stdin;
+    #lines;
+    #kill;
+    #exit = new Latch();
+    #stderr = '';
+    constructor(file, args, options) {
+        const { name, ...spawning } = options;
+        this.#name = name;
+        // execa's kill sends SIGTERM and, if the process is still alive after
+        // five seconds, SIGKILL, as Kubernetes and systemd stop a process: one
+        // that shuts down on its own, such as one that saves its state, gets the
+        // time.
+        const subprocess = execa(file, args, { ...spawning, buffer: false });
+        this.#stdin = subprocess.stdin;
+        this.#kill = () => subprocess.kill();
+        this.#lines = createInterface({ input: subprocess.stdout })[Symbol.asyncIterator]();
+        subprocess.stderr.on('data', (chunk) => {
+            this.#stderr = (this.#stderr + chunk.toString()).slice(-tail);
+        });
+        // A process that failed to start or exited closes stdin under a write;
+        // the exit, not the write, tells the caller what happened.
+        subprocess.stdin.on('error', () => undefined);
+        subprocess.then(({ exitCode }) => this.#exit.open(this.#exited(exitCode)), (error) => this.#exit.open(error.exitCode === undefined && error.signal === undefined
+            ? new Error(`${name} could not start`, { cause: error })
+            : this.#exited(error.signal ?? error.exitCode)));
+    }
+    // Settles with the error that receives get, once the process ended.
+    exited() {
+        return this.#exit.wait();
+    }
+    send(value) {
+        this.#stdin.write(`${JSON.stringify(value)}\n`);
+    }
+    // The next value the process gives. Rejects when the process exits first,
+    // or when the line is not JSON.
+    async receive() {
+        const next = await Promise.race([
+            this.#lines.next(),
+            this.#exit.wait().then((error) => {
+                throw error;
+            }),
+        ]);
+        if (next.done)
+            throw await this.#exit.wait();
+        try {
+            return JSON.parse(next.value);
+        }
+        catch (error) {
+            throw new Error(`${this.#name} gave a line that is not JSON`, {
+                cause: error,
+            });
+        }
+    }
+    // Sends a value and receives the one that answers it.
+    request(value) {
+        this.send(value);
+        return this.receive();
+    }
+    kill() {
+        this.#kill();
+    }
+    // Ends stdin, which asks the process to finish, and waits for its exit.
+    async close() {
+        this.#stdin.end();
+        await this.#exit.wait();
+    }
+    #exited(status) {
+        return new Error(`${this.#name} exited (${status}): ${this.#stderr.trim()}`);
+    }
+}
+//# sourceMappingURL=coprocess.js.map

package/dist/coprocess.js.map

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

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+export { Coprocess, type CoprocessOptions } from './coprocess.ts';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,KAAK,gBAAgB,EAAE,MAAM,gBAAgB,CAAC"}

package/dist/index.js

@@ -0,0 +1,2 @@
+export { Coprocess } from "./coprocess.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,SAAS,EAAyB,MAAM,gBAAgB,CAAC"}

package/package.json

@@ -1,6 +1,49 @@
 {
   "name": "@zukhruf/coprocess",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.3.42",
+  "description": "A coprocess: a long-lived child process that the parent talks to over stdin and stdout, with JSON values on lines, and stops with SIGTERM and then SIGKILL after a grace period.",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/JanuaryLabs/zukhruf",
+    "directory": "packages/coprocess"
+  },
+  "bugs": {
+    "url": "https://github.com/JanuaryLabs/zukhruf/issues"
+  },
+  "homepage": "https://github.com/JanuaryLabs/zukhruf/tree/main/packages/coprocess#readme",
+  "keywords": [
+    "coprocess",
+    "child-process",
+    "subprocess",
+    "json-lines",
+    "ndjson",
+    "jsonl",
+    "stdio",
+    "worker",
+    "sigterm"
+  ],
+  "type": "module",
+  "exports": {
+    "./package.json": "./package.json",
+    ".": {
+      "@zukhruf/source": "./src/index.ts",
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "!dist/spec/**",
+    "!**/*.tsbuildinfo",
+    "!**/*.test.*"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@zukhruf/async": "^0.3.42",
+    "execa": "10.2.1"
+  }
+}