@hasna-internal/kai-terminal 0.1.1-rc.2

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 DeepSeek
+
+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.i18n.yaml

@@ -0,0 +1,6 @@
+# Bilingual-pair consistency record (docs/i18n/README.md): the git blob hash of each
+# side as of the last confirmed-consistent state. Both languages carry equal authority;
+# after editing either side, bring the other along and re-record with:
+#   pnpm run verify-translation-pairing --write packages/terminal/terminal/README.md
+README.md: e8959a1128575a00285a9d3b1165569d2dfbdc04
+README.zh.md: 16a24ad94ea07f27927a9ac30fc026b13e084874

package/README.md

@@ -0,0 +1,41 @@
+# @hasna-internal/kai-terminal
+
+English | [中文](README.zh.md)
+
+Owner-scoped persistent PTY seam. `TerminalSessionService` registers as `ctx.terminals`, mints opaque session ids, routes creation through named backends, fences every operation to the exact live `Agent`, and awaits backend quiescence when that agent or the service disposes.
+
+## Contract
+
+- Backends register one stable `type` and return an unpublished `TerminalBackendSession`; failed or cancelled setup must clean partial resources, and a failed cleanup rejects with `TerminalBackendCleanupError` so the registry can retain it across cancellation.
+- Spawn cancellation preserves the caller's exact abort reason. Service disposal and owner loss remain distinct machine-routable failures after backend setup.
+- Owner and service disposal abort unpublished setup through a service-owned signal and await backend settlement plus rollback before returning.
+- A rollback-close or backend-reported startup cleanup failure rejects the disposing lifecycle instead of claiming quiescence. Caller-triggered cancellation still receives its exact reason; lifecycle-triggered rollback failure also rejects the pending spawn.
+- A backend cleanup failure that follows caller cancellation remains owner activity until owner or service disposal consumes and reports it, so lifecycle policy cannot mistake failed cleanup for quiescence.
+- `hasOwnerActivity(owner)` spans unpublished setup through final close, so lifecycle policy can fence the exact owner without a publication race.
+- A successful spawn publishes one `TerminalSessionId`. The optional `name` is owner-local display metadata, never authority.
+- One session accepts at most one live send operation. Reads and signals may observe it; another send fails until the operation settles.
+- `TerminalSendResult.waitReason` and `sessionStatus` are independent. `session_exit` describes the top-level PTY process, not an arbitrary foreground command.
+- `kill()` and disposal resolve only after the backend's captured process tree is quiescent. A cleanup failure rejects instead of claiming success and clears the matching backend and registry fences so a later close can retry without disturbing a newer attempt.
+
+The seam contains no `node-pty`, sandbox, tool-schema, prompt, task, or terminal-rendering policy. Implementations own terminal mechanics; consumers own model presentation and optional background-job registration.
+
+## Model Experience
+
+### Indirect consumer
+
+#### What the model sees
+
+Nothing directly. This package registers no prompt or tool; `@hasna-internal/kai-tool-terminal` owns visible schemas and result text.
+
+#### Token effect
+
+None directly. Live session state stays process-local until a consumer returns a bounded result.
+
+#### KV Cache effect
+
+No direct invalidation; the named consumer owns request-prefix changes.
+
+## Known Limitations and Deferred Work
+
+- Sessions are process-local and are not restored after a harness restart.
+- Cross-agent sharing is intentionally absent; a future shared-session design needs a separate authority contract.

package/README.zh.md

@@ -0,0 +1,41 @@
+# @hasna-internal/kai-terminal
+
+[English](README.md) | 中文
+
+限定所有者范围的持久 PTY seam。`TerminalSessionService` 注册为 `ctx.terminals`，生成不透明的会话 id，通过具名后端路由创建操作，将每个操作限制在完全相同的活跃 `Agent` 内，并在该 agent（智能体）或服务 dispose（资源释放）时等待后端完全停稳。
+
+## 约定
+
+- 后端注册一个稳定的 `type`，并返回尚未发布的 `TerminalBackendSession`；失败或取消的设置过程必须清理部分资源。若清理失败，则以 `TerminalBackendCleanupError` 拒绝，使注册表能在取消后继续保留该清理失败。
+- spawn 取消会保留调用方提供的确切中止原因。后端设置完成后，服务 dispose 与所有者消失仍分别对应可供机器路由的不同失败。
+- 所有者与服务的 dispose 会通过服务持有的信号中止尚未发布的设置，并等待后端结算和回滚后才返回。
+- 如果回滚关闭失败，或后端报告启动清理失败，dispose 生命周期会以拒绝结束，不会声称已经完全停稳。调用方触发的取消仍收到其确切原因；生命周期触发的回滚失败也会拒绝待完成的 spawn。
+- 调用方取消后发生的后端清理失败仍算作所有者活动，直到所有者或服务 dispose 并消费、报告该失败，避免生命周期策略把失败的清理误判为完全停稳。
+- `hasOwnerActivity(owner)` 覆盖从尚未发布的设置到最终关闭的全过程，使生命周期策略能精确限制对应所有者，不受发布竞态影响。
+- 成功的 spawn 会发布一个 `TerminalSessionId`。可选的 `name` 只是所有者本地的显示元数据，绝不代表权限。
+- 一个会话最多接受一个活跃的发送操作。读取和信号操作可以观察该发送；在当前操作结算前，另一项发送会失败。
+- `TerminalSendResult.waitReason` 与 `sessionStatus` 相互独立。`session_exit` 描述顶层 PTY 进程，而不是任意前台命令。
+- `kill()` 与 dispose 只会在后端捕获的进程树完全停稳后完成。清理失败会以拒绝结束，而非声称成功；同时它会清除匹配的后端和注册表限制，使后续关闭能够重试，且不会干扰较新的尝试。
+
+该 seam 不包含 `node-pty`、沙箱、工具 schema、提示词、任务或终端渲染策略。实现负责终端机制；消费方负责模型呈现和可选的后台任务注册。
+
+## 模型体验
+
+### 间接消费方
+
+#### 模型看到的内容
+
+没有直接可见内容。此包不注册提示词或工具；可见 schema 和结果文本由 `@hasna-internal/kai-tool-terminal` 负责。
+
+#### Token 影响
+
+没有直接影响。活跃会话状态会保留在进程本地，直到消费方返回有界结果。
+
+#### KV Cache 影响
+
+不会直接失效；请求前缀变更由上述消费方负责。
+
+## 已知限制与暂缓事项
+
+- 会话只存在于进程本地，harness 重启后不会恢复。
+- 系统有意不支持跨 agent 共享；未来的共享会话设计需要独立的权限约定。

package/lib/index.js

@@ -0,0 +1,360 @@
+import { Service } from "@deepseek-ai/cordis";
+//#region lib/types/types.js
+/**
+* Types shared by PTY backends, the owner-scoped registry, and tool consumers.
+* Runtime service code lives in `./index.ts`.
+* @module @hasna-internal/kai-terminal/types
+*/
+/**
+* Backend-reported failure to clean partial resources after unpublished setup failed.
+* @param spawnError - original setup or cancellation failure.
+* @param cleanupError - failure that may leave backend-owned resources alive.
+*/
+var TerminalBackendCleanupError = class extends AggregateError {
+	spawnError;
+	cleanupError;
+	constructor(spawnError, cleanupError) {
+		super([spawnError, cleanupError], "PTY backend startup and cleanup both failed");
+		this.spawnError = spawnError;
+		this.cleanupError = cleanupError;
+		this.name = "TerminalBackendCleanupError";
+	}
+};
+//#endregion
+//#region lib/types/index.js
+/**
+* Owner-scoped persistent PTY registry. Backends own terminal mechanics while
+* this service owns ids, publication, authorization, and awaited cleanup.
+* @module @hasna-internal/kai-terminal
+*/
+/** Error carrying a stable {@link TerminalErrorCode}. */
+var TerminalError = class extends Error {
+	code;
+	constructor(message, code) {
+		super(message);
+		this.code = code;
+		this.name = "TerminalError";
+	}
+};
+/**
+* Brand one registry-minted string as a {@link TerminalSessionId}.
+* @param value - raw registry-issued id.
+* @returns Same string with the PTY session brand.
+*/
+function TerminalSessionId(value) {
+	return value;
+}
+/** In-process registry for replaceable PTY backends and exact-Agent sessions. */
+var TerminalSessionService = class extends Service {
+	backends = /* @__PURE__ */ new Map();
+	sessions = /* @__PURE__ */ new Map();
+	reservedNames = /* @__PURE__ */ new Map();
+	pendingSpawns = /* @__PURE__ */ new Map();
+	ownerCleanups = /* @__PURE__ */ new Map();
+	disposedOwners = /* @__PURE__ */ new WeakSet();
+	nextId = 0;
+	disposing = false;
+	constructor(ctx) {
+		super(ctx, "terminals");
+		ctx.effect(() => () => this.disposeAll(), "pty teardown");
+	}
+	/**
+	* Register one backend type for this effect scope.
+	* @param backend - provider with a non-empty unique type.
+	* @returns disposer that removes exactly this contribution.
+	*/
+	registerBackend(backend) {
+		if (backend.type.length === 0) throw new Error("pty backend type must be non-empty");
+		if (this.backends.has(backend.type)) throw new TerminalError(`a PTY backend named "${backend.type}" is already registered`, "DUPLICATE_BACKEND");
+		const dispose = this.ctx.effect(() => {
+			this.backends.set(backend.type, backend);
+			return () => {
+				if (this.backends.get(backend.type) === backend) this.backends.delete(backend.type);
+			};
+		}, "pty.registerBackend()");
+		return () => void dispose();
+	}
+	/**
+	* List registered backend types in registration order.
+	* @returns fresh backend type names.
+	*/
+	listBackends() {
+		return [...this.backends.keys()];
+	}
+	/**
+	* Create and publish one owner-scoped session after backend setup succeeds.
+	* @param owner - exact registered Agent that owns access and cleanup.
+	* @param request - backend type plus optional owner-local name and cwd.
+	* @param signal - cancellation of unpublished setup.
+	* @returns published identity, metadata, status, and MOTD.
+	*/
+	async spawn(owner, request, signal) {
+		this.assertActive();
+		signal?.throwIfAborted();
+		this.ensureOwnerCleanup(owner);
+		const backend = this.backends.get(request.type);
+		if (backend === void 0) throw new TerminalError(`no PTY backend registered for "${request.type}"`, "NO_BACKEND");
+		if (request.name !== void 0 && request.name.length === 0) throw new Error("PTY session name must be non-empty");
+		const releaseName = this.reserveName(owner, request.name);
+		const spawnReservation = this.reserveSpawn(owner);
+		const backendSignal = signal === void 0 ? spawnReservation.signal : AbortSignal.any([signal, spawnReservation.signal]);
+		const sessionId = TerminalSessionId(`pty-${++this.nextId}`);
+		let session;
+		let cleanupFailure;
+		try {
+			session = await backend.spawn({
+				sessionId,
+				owner,
+				type: request.type,
+				...request.name !== void 0 ? { name: request.name } : {},
+				...request.cwd !== void 0 ? { cwd: request.cwd } : {},
+				signal: backendSignal
+			});
+			signal?.throwIfAborted();
+			if (this.disposing) throw new TerminalError("PTY service is disposing", "SERVICE_DISPOSING");
+			if (!this.isLiveOwner(owner)) throw new TerminalError("PTY owner is no longer live", "OWNER_NOT_LIVE");
+			const record = {
+				id: sessionId,
+				owner,
+				name: request.name,
+				type: request.type,
+				session,
+				active: void 0,
+				closing: void 0
+			};
+			this.sessions.set(sessionId, record);
+			return this.snapshot(record, session.motd);
+		} catch (error) {
+			if (error instanceof TerminalBackendCleanupError) cleanupFailure = { error: error.cleanupError };
+			let rollbackFailure;
+			if (session !== void 0 && !this.sessions.has(sessionId)) try {
+				await session.close("PTY spawn rolled back");
+			} catch (closeError) {
+				rollbackFailure = { error: closeError };
+				cleanupFailure = rollbackFailure;
+			}
+			let failure = error;
+			try {
+				signal?.throwIfAborted();
+				spawnReservation.signal.throwIfAborted();
+			} catch (cancellation) {
+				failure = cancellation;
+			}
+			if (rollbackFailure !== void 0 && signal?.aborted !== true) throw new AggregateError([failure, rollbackFailure.error], "PTY spawn and rollback both failed");
+			throw failure;
+		} finally {
+			spawnReservation.release(cleanupFailure);
+			releaseName();
+		}
+	}
+	/**
+	* Test whether an exact owner has a published session or unpublished spawn.
+	* @param owner - exact live owner to inspect.
+	* @returns true across the entire spawn-to-close interval, with no publication gap.
+	*/
+	hasOwnerActivity(owner) {
+		return (this.pendingSpawns.get(owner)?.size ?? 0) > 0 || [...this.sessions.values()].some((record) => record.owner === owner);
+	}
+	/**
+	* Start one exclusive interactive send.
+	* @param owner - exact session owner.
+	* @param id - target PTY identity.
+	* @param request - explicit text, submit behavior, and cancellation.
+	* @returns live operation handle for foreground await or task registration.
+	*/
+	startSend(owner, id, request) {
+		const record = this.expectOwned(owner, id);
+		if (record.closing !== void 0) throw new Error(`PTY session ${id} is closing`);
+		if (record.active !== void 0) throw new TerminalError(`PTY session ${id} already has an active send`, "SEND_ACTIVE");
+		const operation = record.session.startSend(request);
+		record.active = operation;
+		operation.done.then(() => {
+			record.active = void 0;
+		}, () => {
+			record.active = void 0;
+		});
+		return operation;
+	}
+	/**
+	* Read one bounded scrollback page from an owned session.
+	* @param owner - exact session owner.
+	* @param id - target PTY identity.
+	* @param request - optional newest-relative offset and line count.
+	* @returns bounded retained text and pagination metadata.
+	*/
+	read(owner, id, request = {}) {
+		return this.expectOwned(owner, id).session.read(request);
+	}
+	/**
+	* Deliver an allowed signal through an owned backend session.
+	* @param owner - exact session owner.
+	* @param id - target PTY identity.
+	* @param signal - allowed POSIX signal name.
+	* @returns delivered foreground process-group identity.
+	*/
+	signal(owner, id, signal) {
+		return this.expectOwned(owner, id).session.signal(signal);
+	}
+	/**
+	* Close one owned session and remove it only after quiescent backend cleanup.
+	* @param owner - exact session owner.
+	* @param id - target PTY identity.
+	* @param reason - diagnostic cleanup reason.
+	* @returns true for a newly closed session, false when the same close is already in flight.
+	*/
+	async kill(owner, id, reason = "model request") {
+		const record = this.expectOwned(owner, id);
+		if (record.closing !== void 0) {
+			await record.closing;
+			return false;
+		}
+		const closing = record.session.close(reason);
+		record.closing = closing;
+		try {
+			await closing;
+			this.sessions.delete(id);
+			return true;
+		} catch (error) {
+			record.closing = void 0;
+			throw error;
+		}
+	}
+	/**
+	* List fresh snapshots for exactly one owner.
+	* @param owner - exact owner whose sessions are visible.
+	* @returns owner-visible snapshots in publication order.
+	*/
+	list(owner) {
+		return [...this.sessions.values()].filter((record) => record.owner === owner).map((record) => this.snapshot(record));
+	}
+	assertActive() {
+		if (this.disposing) throw new TerminalError("PTY service is disposing", "SERVICE_DISPOSING");
+	}
+	isLiveOwner(owner) {
+		return !this.disposedOwners.has(owner) && this.ctx.get("agents")?.get(owner.id) === owner;
+	}
+	ensureOwnerCleanup(owner) {
+		if (!this.isLiveOwner(owner)) throw new TerminalError(`agent "${owner.id}" is not the registered PTY owner`, "OWNER_NOT_LIVE");
+		if (this.ownerCleanups.has(owner)) return;
+		const detach = owner.ctx.effect(() => async () => {
+			this.disposedOwners.add(owner);
+			this.ownerCleanups.delete(owner);
+			await this.disposeOwned(owner);
+		}, "pty.ownerCleanup()");
+		this.ownerCleanups.set(owner, detach);
+	}
+	reserveName(owner, name) {
+		if (name === void 0) return () => {};
+		if ([...this.sessions.values()].some((record) => record.owner === owner && record.name === name)) throw new TerminalError(`PTY session name "${name}" already exists for this owner`, "DUPLICATE_NAME");
+		const reserved = this.reservedNames.get(owner) ?? /* @__PURE__ */ new Set();
+		if (reserved.has(name)) throw new TerminalError(`PTY session name "${name}" is already being created`, "DUPLICATE_NAME");
+		reserved.add(name);
+		this.reservedNames.set(owner, reserved);
+		return () => {
+			reserved.delete(name);
+			if (reserved.size === 0) this.reservedNames.delete(owner);
+		};
+	}
+	reserveSpawn(owner) {
+		const controller = new AbortController();
+		const settlement = Promise.withResolvers();
+		const pending = {
+			owner,
+			controller,
+			settled: settlement.promise,
+			cleanupFailure: void 0
+		};
+		const owned = this.pendingSpawns.get(owner) ?? /* @__PURE__ */ new Set();
+		owned.add(pending);
+		this.pendingSpawns.set(owner, owned);
+		return {
+			signal: controller.signal,
+			release: (cleanupFailure) => {
+				pending.cleanupFailure = cleanupFailure;
+				if (cleanupFailure === void 0) this.removePendingSpawn(pending);
+				settlement.resolve();
+			}
+		};
+	}
+	removePendingSpawn(pending) {
+		const owned = this.pendingSpawns.get(pending.owner);
+		if (owned === void 0) return;
+		owned.delete(pending);
+		if (owned.size === 0) this.pendingSpawns.delete(pending.owner);
+	}
+	async abortPendingSpawns(owner, reason) {
+		const pending = owner === void 0 ? [...this.pendingSpawns.values()].flatMap((owned) => [...owned]) : [...this.pendingSpawns.get(owner) ?? []];
+		for (const spawn of pending) spawn.controller.abort(reason);
+		await Promise.all(pending.map((spawn) => spawn.settled));
+		const failures = pending.flatMap((spawn) => spawn.cleanupFailure === void 0 ? [] : [spawn.cleanupFailure.error]);
+		for (const spawn of pending) this.removePendingSpawn(spawn);
+		if (failures.length > 0) throw new AggregateError(failures, "failed to roll back unpublished PTY setup");
+	}
+	expectOwned(owner, id) {
+		const record = this.sessions.get(id);
+		if (record === void 0) throw new TerminalError(`unknown PTY session ${id}`, "NO_SESSION");
+		if (record.owner !== owner) throw new TerminalError(`PTY session ${id} belongs to another agent`, "FOREIGN_SESSION");
+		return record;
+	}
+	snapshot(record, motd) {
+		return {
+			sessionId: record.id,
+			...record.name !== void 0 ? { name: record.name } : {},
+			type: record.type,
+			...record.session.pid !== void 0 ? { pid: record.session.pid } : {},
+			status: record.session.status(),
+			...motd !== void 0 ? { motd } : {}
+		};
+	}
+	async abortAndClose(owner, abortReason, closeReason) {
+		const failures = [];
+		try {
+			await this.abortPendingSpawns(owner, abortReason);
+		} catch (error) {
+			failures.push(error);
+		}
+		const records = [...this.sessions.values()].filter((record) => owner === void 0 || record.owner === owner);
+		try {
+			await this.closeRecords(records, closeReason);
+		} catch (error) {
+			failures.push(error);
+		}
+		if (failures.length > 0) throw new AggregateError(failures, "failed to clean up PTY lifecycle");
+	}
+	async disposeOwned(owner) {
+		try {
+			await this.abortAndClose(owner, new TerminalError("PTY owner is no longer live", "OWNER_NOT_LIVE"), "PTY owner disposed");
+		} finally {
+			this.reservedNames.delete(owner);
+		}
+	}
+	async disposeAll() {
+		this.disposing = true;
+		try {
+			await this.abortAndClose(void 0, new TerminalError("PTY service is disposing", "SERVICE_DISPOSING"), "PTY service disposed");
+		} finally {
+			this.backends.clear();
+			this.reservedNames.clear();
+			this.pendingSpawns.clear();
+			const cleanups = [...this.ownerCleanups.values()];
+			this.ownerCleanups.clear();
+			await Promise.all(cleanups.map((cleanup) => Promise.resolve(cleanup())));
+		}
+	}
+	async closeRecords(records, reason) {
+		const failures = (await Promise.allSettled(records.map(async (record) => {
+			const closing = record.closing ?? record.session.close(reason);
+			record.closing = closing;
+			try {
+				await closing;
+				this.sessions.delete(record.id);
+			} catch (error) {
+				if (record.closing === closing) record.closing = void 0;
+				throw error;
+			}
+		}))).filter((result) => result.status === "rejected").map((result) => result.reason);
+		if (failures.length > 0) throw new AggregateError(failures, `failed to close ${failures.length} PTY session(s)`);
+	}
+};
+//#endregion
+export { TerminalBackendCleanupError, TerminalError, TerminalSessionId, TerminalSessionService, TerminalSessionService as default };

package/lib/invariant.js

@@ -0,0 +1,23 @@
+//#region lib/types/invariant.js
+/**
+* Package-owned invariant companion for `@hasna-internal/kai-terminal`.
+* @module @hasna-internal/kai-terminal/invariant
+*/
+const PACKAGE_NAME = "@hasna-internal/kai-terminal";
+/** Cordis companion plugin name. */
+const name = "terminal-invariant";
+/** Service required before the companion can reserve package ownership. */
+const inject = ["invariants"];
+/**
+* No runtime invariant: backend and owner-scoped session registries are private mutable state,
+* and the service exposes neither an independent lifecycle stream nor an unscoped snapshot.
+*/
+const install = () => {};
+/**
+* Register this package's invariant companion.
+* @param ctx - Cordis context carrying the invariant service.
+* @returns the installed registration's disposer after setup succeeds.
+*/
+const apply = (ctx) => Promise.resolve(ctx.invariants.register(PACKAGE_NAME, install));
+//#endregion
+export { apply, inject, name };

package/lib/types/index.d.ts

@@ -0,0 +1,120 @@
+/**
+ * Owner-scoped persistent PTY registry. Backends own terminal mechanics while
+ * this service owns ids, publication, authorization, and awaited cleanup.
+ * @module @hasna-internal/kai-terminal
+ */
+import { Context, Service } from '@deepseek-ai/cordis';
+import type { Agent } from '@hasna-internal/kai-agent';
+import type { TerminalBackend, TerminalReadRequest, TerminalReadResult, TerminalSendOperation, TerminalSendRequest, TerminalSessionIdValue, TerminalSessionSnapshot, TerminalSignal, TerminalSignalResult, TerminalSpawnRequest, TerminalSpawnResult } from './types.ts';
+export type { TerminalBackend, TerminalBackendSession, TerminalBackendSpawnSpec, TerminalReadRequest, TerminalReadResult, TerminalSendOperation, TerminalSendRead, TerminalSendRequest, TerminalSendResult, TerminalSessionSnapshot, TerminalSessionStatus, TerminalSignal, TerminalSignalResult, TerminalSpawnRequest, TerminalSpawnResult, TerminalWaitReason, } from './types.ts';
+export { TerminalBackendCleanupError } from './types.ts';
+/** Opaque identity minted by {@link TerminalSessionService} for one live PTY session. */
+export type TerminalSessionId = TerminalSessionIdValue;
+declare module '@deepseek-ai/cordis' {
+    interface Context {
+        terminals: TerminalSessionService;
+    }
+}
+/** Machine-routable PTY service failures. */
+export type TerminalErrorCode = 'DUPLICATE_BACKEND' | 'DUPLICATE_NAME' | 'FOREIGN_SESSION' | 'NO_BACKEND' | 'NO_SESSION' | 'OWNER_NOT_LIVE' | 'SEND_ACTIVE' | 'SERVICE_DISPOSING';
+/** Error carrying a stable {@link TerminalErrorCode}. */
+export declare class TerminalError extends Error {
+    readonly code: TerminalErrorCode;
+    constructor(message: string, code: TerminalErrorCode);
+}
+/**
+ * Brand one registry-minted string as a {@link TerminalSessionId}.
+ * @param value - raw registry-issued id.
+ * @returns Same string with the PTY session brand.
+ */
+export declare function TerminalSessionId(value: string): TerminalSessionId;
+/** In-process registry for replaceable PTY backends and exact-Agent sessions. */
+export declare class TerminalSessionService extends Service {
+    private readonly backends;
+    private readonly sessions;
+    private readonly reservedNames;
+    private readonly pendingSpawns;
+    private readonly ownerCleanups;
+    private readonly disposedOwners;
+    private nextId;
+    private disposing;
+    constructor(ctx: Context);
+    /**
+     * Register one backend type for this effect scope.
+     * @param backend - provider with a non-empty unique type.
+     * @returns disposer that removes exactly this contribution.
+     */
+    registerBackend(backend: TerminalBackend): () => void;
+    /**
+     * List registered backend types in registration order.
+     * @returns fresh backend type names.
+     */
+    listBackends(): string[];
+    /**
+     * Create and publish one owner-scoped session after backend setup succeeds.
+     * @param owner - exact registered Agent that owns access and cleanup.
+     * @param request - backend type plus optional owner-local name and cwd.
+     * @param signal - cancellation of unpublished setup.
+     * @returns published identity, metadata, status, and MOTD.
+     */
+    spawn(owner: Agent, request: TerminalSpawnRequest, signal?: AbortSignal): Promise<TerminalSpawnResult>;
+    /**
+     * Test whether an exact owner has a published session or unpublished spawn.
+     * @param owner - exact live owner to inspect.
+     * @returns true across the entire spawn-to-close interval, with no publication gap.
+     */
+    hasOwnerActivity(owner: Agent): boolean;
+    /**
+     * Start one exclusive interactive send.
+     * @param owner - exact session owner.
+     * @param id - target PTY identity.
+     * @param request - explicit text, submit behavior, and cancellation.
+     * @returns live operation handle for foreground await or task registration.
+     */
+    startSend(owner: Agent, id: TerminalSessionId, request: TerminalSendRequest): TerminalSendOperation;
+    /**
+     * Read one bounded scrollback page from an owned session.
+     * @param owner - exact session owner.
+     * @param id - target PTY identity.
+     * @param request - optional newest-relative offset and line count.
+     * @returns bounded retained text and pagination metadata.
+     */
+    read(owner: Agent, id: TerminalSessionId, request?: TerminalReadRequest): TerminalReadResult;
+    /**
+     * Deliver an allowed signal through an owned backend session.
+     * @param owner - exact session owner.
+     * @param id - target PTY identity.
+     * @param signal - allowed POSIX signal name.
+     * @returns delivered foreground process-group identity.
+     */
+    signal(owner: Agent, id: TerminalSessionId, signal: TerminalSignal): Promise<TerminalSignalResult>;
+    /**
+     * Close one owned session and remove it only after quiescent backend cleanup.
+     * @param owner - exact session owner.
+     * @param id - target PTY identity.
+     * @param reason - diagnostic cleanup reason.
+     * @returns true for a newly closed session, false when the same close is already in flight.
+     */
+    kill(owner: Agent, id: TerminalSessionId, reason?: string): Promise<boolean>;
+    /**
+     * List fresh snapshots for exactly one owner.
+     * @param owner - exact owner whose sessions are visible.
+     * @returns owner-visible snapshots in publication order.
+     */
+    list(owner: Agent): TerminalSessionSnapshot[];
+    private assertActive;
+    private isLiveOwner;
+    private ensureOwnerCleanup;
+    private reserveName;
+    private reserveSpawn;
+    private removePendingSpawn;
+    private abortPendingSpawns;
+    private expectOwned;
+    private snapshot;
+    private abortAndClose;
+    private disposeOwned;
+    private disposeAll;
+    private closeRecords;
+}
+export default TerminalSessionService;
+//# sourceMappingURL=index.d.ts.map

package/lib/types/invariant.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Package-owned invariant companion for `@hasna-internal/kai-terminal`.
+ * @module @hasna-internal/kai-terminal/invariant
+ */
+import type { Context } from '@deepseek-ai/cordis';
+/** Cordis companion plugin name. */
+export declare const name = "terminal-invariant";
+/** Service required before the companion can reserve package ownership. */
+export declare const inject: string[];
+/**
+ * Register this package's invariant companion.
+ * @param ctx - Cordis context carrying the invariant service.
+ * @returns the installed registration's disposer after setup succeeds.
+ */
+export declare const apply: (ctx: Context) => Promise<() => void>;
+//# sourceMappingURL=invariant.d.ts.map

package/lib/types/types.d.ts

@@ -0,0 +1,159 @@
+/**
+ * Types shared by PTY backends, the owner-scoped registry, and tool consumers.
+ * Runtime service code lives in `./index.ts`.
+ * @module @hasna-internal/kai-terminal/types
+ */
+import type { Branded } from '@hasna-internal/kai-brand';
+import type { Agent } from '@hasna-internal/kai-agent';
+/** Internal exported basis for the public `TerminalSessionId` type/value pair. */
+export type TerminalSessionIdValue = Branded<'TerminalSessionId'>;
+/**
+ * Backend-reported failure to clean partial resources after unpublished setup failed.
+ * @param spawnError - original setup or cancellation failure.
+ * @param cleanupError - failure that may leave backend-owned resources alive.
+ */
+export declare class TerminalBackendCleanupError extends AggregateError {
+    readonly spawnError: unknown;
+    readonly cleanupError: unknown;
+    constructor(spawnError: unknown, cleanupError: unknown);
+}
+/** Why one interactive send returned control to its caller. */
+export type TerminalWaitReason = 'stdin_read' | 'inferred_idle' | 'timeout' | 'session_exit';
+/**
+ * Signals the model-facing PTY surface permits for foreground process groups.
+ * Kept member-identical to `SubprocessTerminalSignal` in
+ * `@hasna-internal/kai-subprocess` without a cross-seam dependency; change both together.
+ */
+export type TerminalSignal = 'SIGINT' | 'SIGTERM' | 'SIGKILL' | 'SIGTSTP' | 'SIGHUP';
+/** Top-level PTY process status, independent of a send's wait reason. */
+export type TerminalSessionStatus = {
+    kind: 'running';
+} | {
+    kind: 'exited';
+    exitCode: number | null;
+    signal: NodeJS.Signals | null;
+};
+/** Request to create one owner-scoped PTY session. */
+export interface TerminalSpawnRequest {
+    /** Registered backend type. */
+    type: string;
+    /** Optional owner-local display name. */
+    name?: string;
+    /** Optional initial working directory interpreted by the backend. */
+    cwd?: string;
+}
+/** Fully identified request handed from the registry to a backend. */
+export interface TerminalBackendSpawnSpec extends TerminalSpawnRequest {
+    /** Registry-minted session identity. */
+    sessionId: TerminalSessionIdValue;
+    /** Exact live owner for authority-aware backend setup. */
+    owner: Agent;
+    /** Cancellation of unpublished backend setup. */
+    signal?: AbortSignal;
+}
+/** Input for one line-oriented terminal interaction. */
+export interface TerminalSendRequest {
+    /** UTF-8 text to write. */
+    text: string;
+    /** Whether to write the backend's Enter sequence after {@link text}. */
+    submit: boolean;
+    /** Cancellation for the wait; backends also interrupt the foreground command. */
+    signal?: AbortSignal;
+}
+/** Incremental output consumed from one live send operation. */
+export interface TerminalSendRead {
+    /** Output produced since the previous operation read. */
+    delta: string;
+    /** Whether unread operation output was dropped by the backend's bound. */
+    truncated: boolean;
+}
+/** Settled result for one foreground or background send. */
+export interface TerminalSendResult {
+    /** Bounded rendered terminal delta remaining at settlement. */
+    viewport: string;
+    /** Why the wait returned; this does not imply arbitrary child-process exit. */
+    waitReason: TerminalWaitReason;
+    /** Top-level session status observed at settlement. */
+    sessionStatus: TerminalSessionStatus;
+    /** Whether output was dropped from the operation or retained scrollback. */
+    truncated: boolean;
+}
+/** Live backend-owned send; exactly one may be active per PTY session. */
+export interface TerminalSendOperation {
+    /** Resolves after readiness, timeout, cancellation, or top-level process exit. */
+    done: Promise<TerminalSendResult>;
+    /** Consume output produced since the prior call. */
+    readOutput(): TerminalSendRead;
+    /** Request `SIGINT`; returns false after the operation settled. */
+    cancel(): boolean;
+}
+/** Request for one backward scrollback page. */
+export interface TerminalReadRequest {
+    /** Offset from the newest retained line; defaults are backend-owned. */
+    offset?: number;
+    /** Requested line count; backend limits still apply. */
+    count?: number;
+}
+/** Bounded scrollback page. */
+export interface TerminalReadResult {
+    /** Retained text in chronological order. */
+    text: string;
+    /** Number of lines currently retained. */
+    totalLines: number;
+    /** Inclusive newest-relative offset of the first returned line. */
+    lineBegin: number;
+    /** Exclusive newest-relative offset after the returned page. */
+    lineEnd: number;
+    /** Whether older retained output or the requested result exceeded a bound. */
+    truncated: boolean;
+}
+/** Result of delivering a signal to a verified foreground process group. */
+export interface TerminalSignalResult {
+    /** True only after the backend delivered the signal. */
+    delivered: true;
+    /** Process group that received the signal. */
+    targetPgid: number;
+}
+/** Owner-visible summary of one published PTY session. */
+export interface TerminalSessionSnapshot {
+    /** Registry-minted identity used by every operation. */
+    sessionId: TerminalSessionIdValue;
+    /** Optional owner-local display name. */
+    name?: string;
+    /** Backend type that created the session. */
+    type: string;
+    /** Top-level process id when the backend has one. */
+    pid?: number;
+    /** Current top-level process status. */
+    status: TerminalSessionStatus;
+}
+/** Backend-owned live session retained by {@link TerminalSessionService}. */
+export interface TerminalBackendSession {
+    /** Initial bounded terminal output returned from `terminal_open`. */
+    readonly motd: string;
+    /** Top-level process id when one exists. */
+    readonly pid?: number;
+    /** Start one exclusive send operation. */
+    startSend(request: TerminalSendRequest): TerminalSendOperation;
+    /** Read one bounded page from retained scrollback. */
+    read(request: TerminalReadRequest): TerminalReadResult;
+    /** Signal the verified foreground process group. */
+    signal(signal: TerminalSignal): Promise<TerminalSignalResult>;
+    /** Observe top-level process status. */
+    status(): TerminalSessionStatus;
+    /** Idempotently close the captured owned process tree and await quiescence. */
+    close(reason: string): Promise<void>;
+}
+/** Replaceable provider for one PTY session type. */
+export interface TerminalBackend {
+    /** Stable type selected by {@link TerminalSpawnRequest.type}. */
+    readonly type: string;
+    /** Create an unpublished session or reject after cleaning partial resources; cleanup failure uses {@link TerminalBackendCleanupError}. */
+    spawn(spec: TerminalBackendSpawnSpec): Promise<TerminalBackendSession>;
+}
+/** Successful publication returned by {@link TerminalSessionService.spawn}. */
+export interface TerminalSpawnResult extends TerminalSessionSnapshot {
+    /** Initial bounded output captured before publication. */
+    motd: string;
+}
+//# sourceMappingURL=types.d.ts.map

package/package.json

@@ -0,0 +1,47 @@
+{
+  "name": "@hasna-internal/kai-terminal",
+  "description": "Persistent PTY session seam for the DeepSeek Harness — owner-scoped ids, backend registry, interactive sends, reads, signals, and awaited cleanup",
+  "version": "0.1.1-rc.2",
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/deepseek-ai/deepseek-harness.git",
+    "directory": "packages/terminal/terminal"
+  },
+  "type": "module",
+  "main": "lib/index.js",
+  "types": "lib/types/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./lib/types/index.d.ts",
+      "default": "./lib/index.js"
+    },
+    "./invariant": {
+      "types": "./lib/types/invariant.d.ts",
+      "default": "./lib/invariant.js"
+    },
+    "./src/*": "./src/*",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "lib/index.js",
+    "lib/invariant.js",
+    "lib/types/**/*.d.ts"
+  ],
+  "license": "MIT",
+  "peerDependencies": {
+    "@hasna-internal/kai-agent": "^0.1.1-rc.2",
+    "@hasna-internal/kai-brand": "^0.1.1-rc.2",
+    "@deepseek-ai/cordis": "^4.0.1",
+    "@hasna-internal/kai-invariants": "^0.1.1-rc.2"
+  },
+  "devDependencies": {
+    "@hasna-internal/kai-agent": "^0.1.1-rc.2",
+    "@hasna-internal/kai-brand": "^0.1.1-rc.2",
+    "@deepseek-ai/cordis": "^4.0.1",
+    "@hasna-internal/kai-session": "^0.1.1-rc.2",
+    "@hasna-internal/kai-invariants": "^0.1.1-rc.2"
+  }
+}