@threahq/remote-session 0.1.0

package/lifecycle.d.ts

@@ -0,0 +1,41 @@
+import type { ShutdownOptions } from "./session.js";
+/** The slice of `process` the lifecycle wiring touches, narrowed so it can be unit-tested with a fake. */
+export interface LifecycleProcess {
+    /** The host's pid, read once at wiring: after the host dies, `process.ppid` names whoever adopted us. */
+    ppid: number;
+    on(event: string, listener: (arg?: unknown) => void): unknown;
+    stdin: {
+        on(event: string, listener: (arg?: unknown) => void): unknown;
+    };
+    stderr: {
+        write(chunk: string): unknown;
+    };
+    exit(code: number): never;
+}
+export interface LifecycleOptions {
+    /** Prefix for shutdown log lines, e.g. "[threa-channel]". */
+    logPrefix?: string;
+    /** Bound on teardown so a hung Threa request can't hold the process past its host's kill grace window. */
+    exitGuardMs?: number;
+    /** Is the process with this pid still running? Decides whether a closed stdin is the host's death or its choice. */
+    parentAlive?: (pid: number) => boolean;
+    /** Wait before probing the parent: a host that was just killed may not be reaped yet. */
+    parentProbeDelayMs?: number;
+}
+/**
+ * Route every way the process can die through one graceful teardown, so the
+ * session marks presence offline + fails its in-flight claim instead of just
+ * vanishing. A host runtime typically never respawns a dead stdio child
+ * mid-session, so a silent drop strands the scratchpad as "busy" with nobody to
+ * answer until a human restarts. The paths covered:
+ *  - SIGINT/SIGTERM — the host's normal stop, and a 2nd Ctrl-C.
+ *  - SIGHUP — terminal/SSH/tmux disconnect (previously an unhandled hard kill).
+ *  - stdin end/close — the parent's write end closed: the host exited, was
+ *    killed, or was swapped out by an auto-update. The session we serve is gone,
+ *    so exit rather than linger as an orphan that keeps renewing the claim.
+ *  - uncaughtException/unhandledRejection — a steady-state throw would otherwise
+ *    vanish the process with no log and no cleanup; log it and exit non-zero.
+ */
+export declare function wireLifecycle(server: {
+    shutdown(options?: ShutdownOptions): Promise<void>;
+}, host: LifecycleProcess, options?: LifecycleOptions): void;

package/package.json

@@ -0,0 +1,44 @@
+{
+  "name": "@threahq/remote-session",
+  "version": "0.1.0",
+  "description": "SDK for connecting an interactive agent runtime to a Threa scratchpad: session linking, claiming work, presence and claim renewal, /steer and /stop, attachments, and interim or final replies. A connector implements deliverTurn; the SDK runs the loop.",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/threahq/threa.git",
+    "directory": "extensions/remote-session"
+  },
+  "homepage": "https://threa.io/developers",
+  "bugs": {
+    "url": "https://github.com/threahq/threa/issues"
+  },
+  "keywords": [
+    "threa",
+    "bot",
+    "agent",
+    "runtime",
+    "connector",
+    "sdk"
+  ],
+  "type": "module",
+  "sideEffects": false,
+  "main": "./index.js",
+  "types": "./index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./index.d.ts",
+      "import": "./index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "dependencies": {
+    "@threahq/bot-runtime-client": "^0.1.0",
+    "socket.io-client": "^4.8.1"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}