@osdlc/agent-seat 0.0.0-stage → 0.7.1

package/dist/index.js

@@ -0,0 +1,61 @@
+/**
+ * `@osdlc/agent-seat`: put an interactive coding-agent session in front of a
+ * person, in the terminal app, multiplexer or editor they already use.
+ *
+ * A {@link Host} is one place a session can open: a terminal tab, a tmux
+ * session, a WezTerm pane, a VS Code terminal. A host fulfils the contract in
+ * parts (open a session, run a command, send text, find, focus, capture,
+ * close); a caller asks for the part it needs with {@link requirePart} and gets
+ * a {@link HostPartMissing} error when the host lacks it, never a silent
+ * fallback to another host.
+ *
+ * A {@link Harness} is the agent CLI the session runs (claude, codex, ...).
+ * Every host runs any harness through {@link harnessArgv}, so where a session
+ * opens and which agent runs in it are independent choices.
+ *
+ * {@link hostRegistry} builds every built-in host. Hosts that remember panes or
+ * read an IDE companion's registry keep their files under the caller's
+ * `runtimeDir`.
+ */
+import { makeCmuxHost } from "./hosts/cmux.js";
+import { makeHerdrHost } from "./hosts/herdr.js";
+import { makeJetbrainsHost } from "./hosts/jetbrains.js";
+import { makeOrcaHost } from "./hosts/orca.js";
+import { makeOttyHost } from "./hosts/otty.js";
+import { terminalHost } from "./hosts/terminal.js";
+import { makeTmuxHost } from "./hosts/tmux.js";
+import { makeVscodeHost } from "./hosts/vscode.js";
+import { makeWeztermHost } from "./hosts/wezterm.js";
+export { HOST_NAMES, HostNameSchema, HostPartMissing, WAIT_TIMEOUT_EXIT, hostCanWait, onPath, requirePart, supportsPlatform, } from "./contract.js";
+export { CLAUDE_HOOK_EVENTS, ClaudeSessionFlagsSchema, HarnessSchema, claudeHookSettings, claudeResumeArgv, claudeSessionArgv, codexSessionsDir, findCodexSessionId, harnessArgv, harnessAvailable, harnessNativeSend, harnessOrNull, hasInteractiveArgv, parseRolloutMeta, walkRolloutFiles, withEnv, wrapperSession, } from "./harness.js";
+export { ensureWorkspace } from "./open-workspace.js";
+export { makeCmuxHost } from "./hosts/cmux.js";
+export { makeHerdrHost } from "./hosts/herdr.js";
+export { JETBRAINS_PROTOCOL, makeJetbrainsHost } from "./hosts/jetbrains.js";
+export { ORCA_BUNDLED_CLI, makeOrcaHost } from "./hosts/orca.js";
+export { makeOttyHost } from "./hosts/otty.js";
+export { hostRegistryDir } from "./hosts/registry.js";
+export { makeTerminalHost, terminalHost } from "./hosts/terminal.js";
+export { insideTmux, makeTmuxHost, tmuxAttachArgv, tmuxIdSessionName, tmuxSessionName, tmuxSwitchClientArgv, } from "./hosts/tmux.js";
+export { makeVscodeHost } from "./hosts/vscode.js";
+export { liveWindows, subprocessTransport, } from "./hosts/vscode-client.js";
+export { makeWeztermHost } from "./hosts/wezterm.js";
+/**
+ * Every built-in host, by name. Each one is a wrapper: it opens a terminal or
+ * workspace and runs whichever harness the request names, so none hardcodes an
+ * agent CLI. A consumer that wants a fake builds its own `HostRegistry`.
+ */
+export function hostRegistry(opts) {
+    const { runtimeDir } = opts;
+    return {
+        terminal: terminalHost,
+        orca: makeOrcaHost({ repoRoot: opts.repoRoot, runtimeDir }),
+        cmux: makeCmuxHost({}),
+        tmux: makeTmuxHost({}),
+        herdr: makeHerdrHost({ runtimeDir }),
+        otty: makeOttyHost(),
+        wezterm: makeWeztermHost({ runtimeDir }),
+        vscode: makeVscodeHost({ runtimeDir }),
+        jetbrains: makeJetbrainsHost({ runtimeDir, settings: opts.jetbrains }),
+    };
+}

package/dist/open-workspace.d.ts

@@ -0,0 +1,9 @@
+/**
+ * The one policy for opening a host's workspace before a launch: when
+ * `host.open_workspace` is on and the host fulfils the optional
+ * `openWorkspace` part, call it before `session`/`terminal`. `send`, `find`
+ * and `focus` never come through here.
+ */
+import type { Host } from './contract.ts';
+/** Opens a workspace for `cwd` on `host` when `enabled` and the host can; a host without the part is left alone. */
+export declare function ensureWorkspace(host: Host, cwd: string, enabled: boolean, notice: (line: string) => void): void;

package/dist/open-workspace.js

@@ -0,0 +1,12 @@
+/**
+ * The one policy for opening a host's workspace before a launch: when
+ * `host.open_workspace` is on and the host fulfils the optional
+ * `openWorkspace` part, call it before `session`/`terminal`. `send`, `find`
+ * and `focus` never come through here.
+ */
+/** Opens a workspace for `cwd` on `host` when `enabled` and the host can; a host without the part is left alone. */
+export function ensureWorkspace(host, cwd, enabled, notice) {
+    if (!enabled || host.openWorkspace === undefined)
+        return;
+    host.openWorkspace({ cwd, notice });
+}

package/dist/util.d.ts

@@ -0,0 +1,50 @@
+/**
+ * Small private helpers the hosts share. Nothing here is exported from the
+ * package entry.
+ */
+/** A plain object (not null, not an array). */
+export declare function isRecord(v: unknown): v is Record<string, unknown>;
+/** `v` when it is a string, else null. */
+export declare function strOrNull(v: unknown): string | null;
+/** A non-empty string, else null. */
+export declare function nonEmptyString(v: unknown): string | null;
+/** `JSON.parse(text)`, or null when it is not valid JSON. */
+export declare function parseJsonOrNull(text: string): unknown;
+/** The parsed JSON in `path`, or null when it is missing, unreadable or not JSON. */
+export declare function readJsonOrNull(path: string): unknown;
+/** Write `data` as JSON to `path` atomically (temp file, fsync, rename). */
+export declare function writeJsonAtomic(path: string, data: unknown): void;
+/** Create `dir` and its parents; an existing directory is fine. */
+export declare function ensureDir(dir: string): void;
+/** Block the thread for `ms` milliseconds. For sync code that backs off between polls. */
+export declare function sleepSync(ms: number): void;
+/**
+ * True when `pid` names a running process. Signal 0 delivers nothing; it only
+ * asks the OS whether the process exists. `EPERM` means it exists but belongs
+ * to another user, so it is alive. Pids are recycled, so a reused pid reads as
+ * alive.
+ */
+export declare function pidAlive(pid: number): boolean;
+/** `bin`'s path on `PATH` (PATHEXT-aware on Windows), or null. */
+export declare function which(bin: string): string | null;
+/**
+ * True when this module runs inside a `bun build --compile` standalone binary,
+ * read from a module URL (pass `import.meta.url`).
+ */
+export declare function isCompiledBinary(metaUrl: string): boolean;
+/** The first `hexChars` lowercase hex digits of the sha256 of `text`. */
+export declare function shortHash(text: string, hexChars: number): string;
+/** `text` with anything outside `[A-Za-z0-9_-]` rewritten to `_`. */
+export declare function safeName(text: string): string;
+/**
+ * A collision-free stand-in for a session id where the id itself cannot go (a tmux session
+ * name, a title tag, a file name): the id's first 12 characters through {@link safeName}, for a
+ * person to read, then `-` and the first `hashChars` hex digits of the sha256 of the whole id.
+ * The hash keeps apart ids that share a prefix, differ only in a rewritten character, or differ
+ * only in case.
+ */
+export declare function sessionIdSlug(sessionId: string, hashChars?: number): string;
+/** The real path of `p`: symlinks in the part that exists resolved, the rest re-attached. */
+export declare function realResolve(p: string): string;
+/** Whether `child` is `parent` or inside it, comparing real paths. */
+export declare function isWithin(child: string, parent: string): boolean;

package/dist/util.js

@@ -0,0 +1,108 @@
+/**
+ * Small private helpers the hosts share. Nothing here is exported from the
+ * package entry.
+ */
+import { createHash } from 'node:crypto';
+import { mkdirSync, readFileSync } from 'node:fs';
+import { isAbsolute, resolve } from 'node:path';
+import { which as whichOn } from '@osdlc/detect-harness';
+import { atomicWrite } from '@osdlc/etag-write';
+import { nodeGuard } from '@osdlc/path-guard/node';
+/** A plain object (not null, not an array). */
+export function isRecord(v) {
+    return v !== null && typeof v === 'object' && !Array.isArray(v);
+}
+/** `v` when it is a string, else null. */
+export function strOrNull(v) {
+    return typeof v === 'string' ? v : null;
+}
+/** A non-empty string, else null. */
+export function nonEmptyString(v) {
+    return typeof v === 'string' && v !== '' ? v : null;
+}
+/** `JSON.parse(text)`, or null when it is not valid JSON. */
+export function parseJsonOrNull(text) {
+    try {
+        return JSON.parse(text);
+    }
+    catch {
+        return null;
+    }
+}
+/** The parsed JSON in `path`, or null when it is missing, unreadable or not JSON. */
+export function readJsonOrNull(path) {
+    try {
+        return JSON.parse(readFileSync(path, 'utf-8'));
+    }
+    catch {
+        return null;
+    }
+}
+/** Write `data` as JSON to `path` atomically (temp file, fsync, rename). */
+export function writeJsonAtomic(path, data) {
+    atomicWrite(path, JSON.stringify(data, null, 2));
+}
+/** Create `dir` and its parents; an existing directory is fine. */
+export function ensureDir(dir) {
+    mkdirSync(dir, { recursive: true });
+}
+/** Block the thread for `ms` milliseconds. For sync code that backs off between polls. */
+export function sleepSync(ms) {
+    Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms);
+}
+/**
+ * True when `pid` names a running process. Signal 0 delivers nothing; it only
+ * asks the OS whether the process exists. `EPERM` means it exists but belongs
+ * to another user, so it is alive. Pids are recycled, so a reused pid reads as
+ * alive.
+ */
+export function pidAlive(pid) {
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (e) {
+        return e.code === 'EPERM';
+    }
+}
+/** `bin`'s path on `PATH` (PATHEXT-aware on Windows), or null. */
+export function which(bin) {
+    return whichOn(bin, process.env);
+}
+/**
+ * True when this module runs inside a `bun build --compile` standalone binary,
+ * read from a module URL (pass `import.meta.url`).
+ */
+export function isCompiledBinary(metaUrl) {
+    return metaUrl.startsWith('file:///$bunfs/') || /^file:\/\/\/[A-Za-z]:\/~BUN\//.test(metaUrl);
+}
+/** The first `hexChars` lowercase hex digits of the sha256 of `text`. */
+export function shortHash(text, hexChars) {
+    return createHash('sha256').update(text).digest('hex').slice(0, hexChars);
+}
+/** `text` with anything outside `[A-Za-z0-9_-]` rewritten to `_`. */
+export function safeName(text) {
+    return text.replace(/[^A-Za-z0-9_-]/g, '_');
+}
+/**
+ * A collision-free stand-in for a session id where the id itself cannot go (a tmux session
+ * name, a title tag, a file name): the id's first 12 characters through {@link safeName}, for a
+ * person to read, then `-` and the first `hashChars` hex digits of the sha256 of the whole id.
+ * The hash keeps apart ids that share a prefix, differ only in a rewritten character, or differ
+ * only in case.
+ */
+export function sessionIdSlug(sessionId, hashChars = 8) {
+    return `${safeName(sessionId.slice(0, 12))}-${shortHash(sessionId, hashChars)}`;
+}
+/** `p` made absolute against the cwd. */
+function absolute(p) {
+    return isAbsolute(p) && process.platform !== 'win32' ? p : resolve(p);
+}
+/** The real path of `p`: symlinks in the part that exists resolved, the rest re-attached. */
+export function realResolve(p) {
+    return nodeGuard.realPath(absolute(p));
+}
+/** Whether `child` is `parent` or inside it, comparing real paths. */
+export function isWithin(child, parent) {
+    return nodeGuard.contains(absolute(parent), absolute(child));
+}

package/package.json

@@ -1,6 +1,79 @@
 {
   "name": "@osdlc/agent-seat",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.7.1",
+  "description": "Open an interactive coding-agent session (claude, codex, cursor, pi and others) in the terminal app, multiplexer or editor a person already uses: a terminal tab, tmux, WezTerm, cmux, herdr, Orca, otty, VS Code or a JetBrains IDE. One host contract in optional parts, any harness in any host.",
+  "license": "MIT OR Apache-2.0",
+  "author": "sksizer",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/osdlc/osdlc.git",
+    "directory": "packages/ts/agent-seat"
+  },
+  "homepage": "https://github.com/osdlc/osdlc/tree/main/packages/ts/agent-seat#readme",
+  "bugs": "https://github.com/osdlc/osdlc/issues",
+  "keywords": [
+    "agent",
+    "coding-agent",
+    "claude",
+    "codex",
+    "terminal",
+    "tmux",
+    "wezterm",
+    "vscode",
+    "jetbrains",
+    "session"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "type": "module",
+  "sideEffects": false,
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist/",
+    "README.md",
+    "CHANGELOG.md",
+    "LICENSE-MIT",
+    "LICENSE-APACHE",
+    "SECURITY.md",
+    "CONTRIBUTING.md"
+  ],
+  "engines": {
+    "node": "^22.22.2 || ^24.15.0 || >=26.0.0"
+  },
+  "dependencies": {
+    "zod": "^4.6.6",
+    "@osdlc/agent-call": "^0.9.0",
+    "@osdlc/command-seam": "^0.14.0",
+    "@osdlc/detect-harness": "^0.7.0",
+    "@osdlc/etag-write": "^0.3.1",
+    "@osdlc/path-guard": "^0.3.1",
+    "@osdlc/typed-git": "^0.13.0"
+  },
+  "devDependencies": {
+    "@types/node": "^26.1.0",
+    "@vitest/coverage-v8": "^5.0.5",
+    "oxlint": "^1.65.0",
+    "prettier": "3.9.6",
+    "typescript": "~6.0.3",
+    "vitest": "^5.0.5",
+    "@osdlc/prettier-config": "^0.3.1",
+    "@osdlc/tsconfig": "^0.4.1"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "clean": "node -e \"require('node:fs').rmSync('dist', { recursive: true, force: true })\"",
+    "test": "vitest run",
+    "smoke": "node tests/smoke.mjs",
+    "coverage": "vitest run --coverage",
+    "format": "prettier --write .",
+    "format:check": "prettier --check .",
+    "lint": "oxlint .",
+    "typecheck": "tsc --noEmit && tsc -p tsconfig.build.json --noEmit"
+  }
 }