dsh-live-teams 0.1.0

package/lib/scope.d.ts

@@ -0,0 +1,62 @@
+//#region src/scope.d.ts
+/**
+ * Declared task scope: what a task says it may touch, and how two declarations are
+ * compared. The comparison is deliberately conservative — it reports an overlap when
+ * a declaration *could* collide, because a missed overlap costs somebody's edits while
+ * a reported one costs throughput (B30).
+ */
+export declare const MAX_PATHS = 32;
+/**
+ * Work that writes code, and therefore needs the isolation Gate C has not built yet
+ * (ADR 0008; design §22), and the same set the parallel-write rules apply to. `work` is
+ * listed because a generic kind does not promise it is documentation — the safe reading
+ * of an unknown is "it writes", and the refusals name the kinds that are exempt.
+ */
+export declare const CODING_KINDS: ReadonlySet<string>;
+/**
+ * Paths that every task effectively shares, so touching one collides with any active
+ * writer: manifests and lockfiles, repository internals, CI configuration and build
+ * entry points. The deployment may extend this list with `sharedPaths`.
+ */
+export declare const SHARED_PATH_DEFAULTS: readonly string[];
+/** Normalise one entry, or refuse it. Returns undefined for an unusable value. */
+export declare function normalizeScopePath(value: unknown): string | undefined;
+/** Normalise a whole declaration; undefined when any entry is unusable, or on duplicates. */
+export declare function normalizeScope(paths: unknown): string[] | undefined;
+/**
+ * The literal prefix a pattern can be reduced to: everything before the first segment
+ * that contains a wildcard. `src/**\/*.ts` reduces to `src`, `a/b*` to `a`.
+ */
+export declare function literalPrefix(entry: string): string;
+/**
+ * True when the two entries could touch the same file. Segment-boundary prefixes only,
+ * so `a/b` and `a/bc` stay apart; a wildcard reduces to its literal prefix, which makes
+ * this report overlaps that a particular run would not have produced.
+ */
+export declare function scopesIntersect(left: string, right: string): boolean;
+export type ScopeOverlap = {
+  left: string;
+  right: string;
+  shared: boolean;
+};
+export type ScopeConflict = {
+  kind: 'overlap';
+  left: string;
+  right: string;
+} | {
+  kind: 'shared';
+  left: string;
+  right: string;
+};
+/**
+ * Compare two declarations. Shared hotspots are reported separately from concrete
+ * overlaps: the lead's action differs — one is "narrow the scope or serialise the two
+ * tasks", the other is "these files are shared by everything".
+ */
+export declare function scopeConflict(left: readonly string[], right: readonly string[], shared?: readonly string[]): ScopeConflict | undefined;
+/** Changed paths that fall outside a declaration. */
+export declare function outsideScope(changed: readonly string[], declared: readonly string[]): string[];
+/** Two declarations that a reviewer can compare without re-reading the contract. */
+export declare function scopeSummary(paths: readonly string[] | undefined): string;
+export declare function resolveWorkspacePath(workspacePath: string, entry: string): string;
+//#endregion

package/lib/scope.js

@@ -0,0 +1,133 @@
+import path from "node:path";
+//#region src/scope.ts
+/**
+* Declared task scope: what a task says it may touch, and how two declarations are
+* compared. The comparison is deliberately conservative — it reports an overlap when
+* a declaration *could* collide, because a missed overlap costs somebody's edits while
+* a reported one costs throughput (B30).
+*/
+const MAX_PATHS = 32;
+/**
+* Work that writes code, and therefore needs the isolation Gate C has not built yet
+* (ADR 0008; design §22), and the same set the parallel-write rules apply to. `work` is
+* listed because a generic kind does not promise it is documentation — the safe reading
+* of an unknown is "it writes", and the refusals name the kinds that are exempt.
+*/
+const CODING_KINDS = /* @__PURE__ */ new Set([
+	"implementation",
+	"repair",
+	"integration",
+	"work"
+]);
+const GLOB_CHARS = /[*?[\]{}!()]/;
+/**
+* Paths that every task effectively shares, so touching one collides with any active
+* writer: manifests and lockfiles, repository internals, CI configuration and build
+* entry points. The deployment may extend this list with `sharedPaths`.
+*/
+const SHARED_PATH_DEFAULTS = Object.freeze([
+	"package.json",
+	"package-lock.json",
+	"pnpm-lock.yaml",
+	"pnpm-workspace.yaml",
+	"yarn.lock",
+	"pyproject.toml",
+	"requirements.txt",
+	"Cargo.toml",
+	"Cargo.lock",
+	"go.mod",
+	"go.sum",
+	".git/**",
+	".github/**",
+	".gitlab-ci.yml",
+	"Jenkinsfile",
+	"Dockerfile",
+	"docker-compose.yml",
+	"docker-compose.yaml",
+	"Makefile"
+]);
+/** Normalise one entry, or refuse it. Returns undefined for an unusable value. */
+function normalizeScopePath(value) {
+	if (typeof value !== "string") return void 0;
+	const trimmed = value.trim();
+	if (trimmed.length === 0 || trimmed.length > 512) return void 0;
+	const slashed = trimmed.replace(/\\/gu, "/");
+	if (slashed.startsWith("/") || /^[A-Za-z]:/u.test(slashed)) return void 0;
+	const segments = slashed.split("/").filter((segment) => segment.length > 0 && segment !== ".");
+	if (segments.length === 0) return void 0;
+	if (segments.some((segment) => segment === "..")) return void 0;
+	return segments.join("/");
+}
+/** Normalise a whole declaration; undefined when any entry is unusable, or on duplicates. */
+function normalizeScope(paths) {
+	if (!Array.isArray(paths)) return void 0;
+	if (paths.length === 0 || paths.length > 32) return void 0;
+	const normalized = [];
+	for (const entry of paths) {
+		const value = normalizeScopePath(entry);
+		if (value === void 0) return void 0;
+		if (normalized.includes(value)) return void 0;
+		normalized.push(value);
+	}
+	return normalized;
+}
+/**
+* The literal prefix a pattern can be reduced to: everything before the first segment
+* that contains a wildcard. `src/**\/*.ts` reduces to `src`, `a/b*` to `a`.
+*/
+function literalPrefix(entry) {
+	const segments = entry.split("/");
+	const first = segments.findIndex((segment) => GLOB_CHARS.test(segment));
+	return (first < 0 ? segments : segments.slice(0, first)).join("/");
+}
+/**
+* True when the two entries could touch the same file. Segment-boundary prefixes only,
+* so `a/b` and `a/bc` stay apart; a wildcard reduces to its literal prefix, which makes
+* this report overlaps that a particular run would not have produced.
+*/
+function scopesIntersect(left, right) {
+	if (left.length === 0 || right.length === 0) return true;
+	if (left === right) return true;
+	return left.startsWith(`${right}/`) || right.startsWith(`${left}/`);
+}
+/**
+* Compare two declarations. Shared hotspots are reported separately from concrete
+* overlaps: the lead's action differs — one is "narrow the scope or serialise the two
+* tasks", the other is "these files are shared by everything".
+*/
+function scopeConflict(left, right, shared = SHARED_PATH_DEFAULTS) {
+	const reduce = (entry) => literalPrefix(entry);
+	const overlaps = (entry, other) => scopesIntersect(reduce(entry), reduce(other));
+	let sharedHit;
+	for (const a of left) for (const b of right) {
+		if (!overlaps(a, b)) continue;
+		if (!shared.some((candidate) => overlaps(a, candidate) || overlaps(b, candidate))) return {
+			kind: "overlap",
+			left: a,
+			right: b
+		};
+		sharedHit ??= {
+			kind: "shared",
+			left: a,
+			right: b
+		};
+	}
+	return sharedHit;
+}
+/** Changed paths that fall outside a declaration. */
+function outsideScope(changed, declared) {
+	return changed.filter((candidate) => {
+		const normalized = normalizeScopePath(candidate);
+		if (normalized === void 0) return false;
+		return !declared.some((entry) => scopesIntersect(literalPrefix(entry), normalized));
+	});
+}
+/** Two declarations that a reviewer can compare without re-reading the contract. */
+function scopeSummary(paths) {
+	return paths === void 0 || paths.length === 0 ? "not declared" : paths.join(", ");
+}
+function resolveWorkspacePath(workspacePath, entry) {
+	return path.join(workspacePath, ...entry.split("/"));
+}
+//#endregion
+export { CODING_KINDS, MAX_PATHS, SHARED_PATH_DEFAULTS, literalPrefix, normalizeScope, normalizeScopePath, outsideScope, resolveWorkspacePath, scopeConflict, scopeSummary, scopesIntersect };

package/lib/session-bridge.d.ts

@@ -0,0 +1,76 @@
+import { LiveTeamsError } from "./errors.js";
+//#region src/session-bridge.d.ts
+export interface SessionDescriptor {
+  sessionId: string;
+  workspaceId: string | undefined;
+  cwd: string | undefined;
+  title: string | undefined;
+  status: 'idle' | 'running' | 'unknown';
+  live: boolean;
+  subagentOwned: boolean;
+  seq: number;
+  agentPreset: string | undefined;
+  /**
+   * DSH's Session-list projection keeps a Session blank until its first
+   * `turn/start`, and the session list hides blank Sessions: the Workspace
+   * browser adopts one as its provisional "New session" row and never lists it
+   * (`sessionVisible` / `connectWorkspace` in @deepseek-ai/dsh-client-ui-workspace).
+   *
+   * Only `list` reports this flag, so `undefined` means "not reported", never
+   * "known to be visible".
+   */
+  blank?: boolean;
+}
+export interface SessionController {
+  create(payload: Record<string, unknown>): Promise<unknown>;
+  inspect(sessionId: string): Promise<unknown>;
+  list?(request: Record<string, unknown>, signal?: AbortSignal): Promise<unknown>;
+  rename(payload: {
+    sessionId: string;
+    title: string;
+  }): Promise<unknown>;
+  prompt(payload: {
+    requestId: string;
+    sessionId: string;
+    mode: 'queue' | 'steer';
+    content: readonly unknown[];
+  }, signal: AbortSignal): Promise<unknown>;
+  cancel(payload: {
+    sessionId: string;
+  }): void;
+}
+export interface SessionBridge {
+  create(request: {
+    sessionId?: string;
+    workspaceId?: string;
+    cwd?: string;
+    agentPreset?: string;
+  }): Promise<SessionDescriptor>;
+  inspect(sessionId: string): Promise<SessionDescriptor | undefined>;
+  validateAttachment(sessionId: string, workspaceId: string): Promise<SessionDescriptor>;
+  rename(sessionId: string, title: string): Promise<{
+    title: string;
+    seq: number | undefined;
+  }>;
+  selectModel(sessionId: string, selection: unknown): never;
+  deliver(sessionId: string, envelope: {
+    requestId: string;
+    mode: 'queue' | 'steer';
+    content: readonly unknown[];
+  }): Promise<{
+    accepted: true;
+  }>;
+  interrupt(sessionId: string, reason: string): Promise<{
+    accepted: true;
+  }>;
+  reconcile(sessionIds: readonly string[]): Promise<SessionDescriptor[]>;
+}
+export declare function toBridgeError(error: unknown): LiveTeamsError;
+export interface SessionBridgeDeps {
+  controller: SessionController | null | undefined;
+  agents?: {
+    get?: (sessionId: string) => unknown;
+  };
+}
+export declare function createSessionBridge({ controller, agents }: SessionBridgeDeps): SessionBridge;
+//#endregion

package/lib/session-bridge.js

@@ -0,0 +1,147 @@
+import { LiveTeamsError, translatePlatformError } from "./errors.js";
+//#region src/session-bridge.ts
+function record(value) {
+	return value !== null && typeof value === "object" && !Array.isArray(value) ? value : {};
+}
+function text(value) {
+	return typeof value === "string" && value.length > 0 ? value : void 0;
+}
+function isSubagentHeader(header) {
+	const value = record(header);
+	return value.origin === "subagent" || text(value.parentSession) !== void 0;
+}
+function isMissingSession(error) {
+	const value = record(error);
+	if (value.code === "session/not-found") return true;
+	if (typeof value.code === "string" && value.code.length > 0) return false;
+	return /not found/i.test(String(value.message ?? ""));
+}
+function isSubagentOwnership(error) {
+	const value = record(error);
+	if (value.code !== "session/agent-busy") return false;
+	const details = record(value.details);
+	return /subagent/i.test(String(details.reason ?? value.message ?? ""));
+}
+function toBridgeError(error) {
+	if (error instanceof LiveTeamsError) return error;
+	const translated = translatePlatformError(error);
+	if (!isSubagentOwnership(error)) return translated;
+	return new LiveTeamsError("CAPABILITY_UNAVAILABLE", "Session is owned by subagent routing and cannot be a team member", translated.auditDetail === void 0 ? { cause: error } : {
+		cause: error,
+		auditDetail: translated.auditDetail
+	});
+}
+function descriptorOf(inspection, liveAgent) {
+	const liveSession = record(record(liveAgent).session);
+	const meta = record(inspection.meta ?? inspection.header ?? liveSession.header);
+	const session = record(liveAgent).session;
+	const ownerHeader = record(session).header ?? meta;
+	const events = Array.isArray(inspection.events) ? inspection.events : [];
+	let title = text(meta.title);
+	let seq = typeof meta.seq === "number" ? meta.seq : 0;
+	for (const event of events) {
+		const value = record(event);
+		if (typeof value.seq === "number" && value.seq > seq) seq = value.seq;
+		if (value.type === "session/title") title = text(record(value.data).title) ?? title;
+	}
+	const statusValue = record(liveAgent).status;
+	return {
+		sessionId: text(meta.id) ?? "",
+		workspaceId: text(meta.workspaceId),
+		cwd: text(meta.cwd),
+		title,
+		status: statusValue === "idle" || statusValue === "running" ? statusValue : "unknown",
+		live: liveAgent !== void 0 && liveAgent !== null,
+		subagentOwned: isSubagentHeader(ownerHeader),
+		seq,
+		agentPreset: text(meta.agentPreset)
+	};
+}
+function createSessionBridge({ controller, agents }) {
+	if (controller === null || typeof controller !== "object") throw new LiveTeamsError("CAPABILITY_UNAVAILABLE", "sessionController is not available in this composition");
+	const liveAgentOf = (sessionId) => agents?.get?.(sessionId);
+	const bridge = {
+		async create(request) {
+			const sessionId = text(request?.sessionId);
+			if (sessionId === void 0) throw new LiveTeamsError("CAPABILITY_UNAVAILABLE", "create requires an explicit plugin-owned sessionId");
+			const payload = { sessionId };
+			if (text(request.workspaceId) !== void 0) payload.workspaceId = request.workspaceId;
+			if (text(request.cwd) !== void 0) payload.cwd = request.cwd;
+			if (text(request.agentPreset) !== void 0) payload.agentPreset = request.agentPreset;
+			try {
+				await controller.create(payload);
+			} catch (error) {
+				throw toBridgeError(error);
+			}
+			const descriptor = await bridge.inspect(sessionId);
+			if (descriptor === void 0) throw new LiveTeamsError("SESSION_NOT_FOUND", `Session "${sessionId}" was not readable after create`, { auditDetail: "create succeeded but inspect could not observe the Session" });
+			return descriptor;
+		},
+		async inspect(sessionId) {
+			try {
+				return descriptorOf(record(await controller.inspect(sessionId)), liveAgentOf(sessionId));
+			} catch (error) {
+				if (isMissingSession(error)) return void 0;
+				throw toBridgeError(error);
+			}
+		},
+		async validateAttachment(sessionId, workspaceId) {
+			const descriptor = await bridge.inspect(sessionId);
+			if (descriptor === void 0) throw new LiveTeamsError("SESSION_NOT_FOUND", `Session "${sessionId}" does not exist`, { auditDetail: "validateAttachment: inspect returned no Session" });
+			if (descriptor.subagentOwned) throw new LiveTeamsError("CAPABILITY_UNAVAILABLE", `Session "${sessionId}" is owned by subagent routing`, { auditDetail: "validateAttachment: subagent-owned Session cannot be a member" });
+			const expected = text(workspaceId);
+			if (expected !== void 0 && descriptor.workspaceId !== expected) throw new LiveTeamsError("SESSION_WRONG_WORKSPACE", `Session "${sessionId}" is not attached to workspace "${expected}"`, { auditDetail: `observed workspaceId=${String(descriptor.workspaceId)}` });
+			return descriptor;
+		},
+		async rename(sessionId, title) {
+			try {
+				const result = record(await controller.rename({
+					sessionId,
+					title
+				}));
+				return {
+					title: text(result.title) ?? title,
+					seq: typeof result.seq === "number" ? result.seq : void 0
+				};
+			} catch (error) {
+				throw toBridgeError(error);
+			}
+		},
+		selectModel() {
+			throw new LiveTeamsError("CAPABILITY_UNAVAILABLE", "Model selection is intentionally unavailable in this build", { auditDetail: "Phase 2 policy omits member model selection because selectModel also rewrites the deployment-wide default model. This must not be worked around silently." });
+		},
+		async deliver(sessionId, envelope) {
+			if (envelope.mode !== "queue" && envelope.mode !== "steer") throw new LiveTeamsError("DELIVERY_REJECTED", `Unsupported delivery mode "${String(envelope.mode)}"`);
+			try {
+				await controller.prompt({
+					requestId: envelope.requestId,
+					sessionId,
+					mode: envelope.mode,
+					content: envelope.content
+				}, new AbortController().signal);
+				return { accepted: true };
+			} catch (error) {
+				throw toBridgeError(error);
+			}
+		},
+		async interrupt(sessionId, _reason) {
+			try {
+				controller.cancel({ sessionId });
+				return { accepted: true };
+			} catch (error) {
+				throw toBridgeError(error);
+			}
+		},
+		async reconcile(sessionIds) {
+			const descriptors = [];
+			for (const sessionId of sessionIds) {
+				const descriptor = await bridge.inspect(sessionId);
+				if (descriptor !== void 0) descriptors.push(descriptor);
+			}
+			return descriptors;
+		}
+	};
+	return Object.freeze(bridge);
+}
+//#endregion
+export { createSessionBridge, toBridgeError };

package/lib/session-title.js

@@ -0,0 +1,35 @@
+//#region src/session-title.ts
+/** The one place the title format is defined. */
+function sessionTitleFor(displayName, teamName) {
+	return `${displayName} - ${teamName}`;
+}
+/**
+* Bring one Session's title in line with its membership.
+*
+* @returns the outcome, or `undefined` when the title could not be set — the
+*   caller must treat that as a reported inconvenience, not as a failure.
+*/
+async function applySessionTitle(dependencies, request) {
+	const to = sessionTitleFor(request.displayName, request.teamName);
+	const from = request.previousTitle ?? null;
+	if (request.previousTitle === to) return {
+		from,
+		to,
+		reason: request.reason,
+		renamed: false
+	};
+	try {
+		await dependencies.rename(request.sessionId, to);
+		return {
+			from,
+			to,
+			reason: request.reason,
+			renamed: true
+		};
+	} catch (error) {
+		dependencies.warn?.(`live-teams: could not title Session "${request.sessionId}": ${String(error)}`);
+		return;
+	}
+}
+//#endregion
+export { applySessionTitle, sessionTitleFor };

package/lib/storage.d.ts

@@ -0,0 +1,9 @@
+//#region src/storage.d.ts
+export declare function withProcessLock<T>(key: string, operation: () => Promise<T>): Promise<T>;
+export declare function atomicWrite(filePath: string, contents: string | Uint8Array): Promise<void>;
+export declare function atomicWriteJson(filePath: string, value: unknown): Promise<void>;
+export declare function readJson(filePath: string): Promise<unknown>;
+export declare function fileExists(filePath: string): Promise<boolean>;
+export declare function clone<T>(value: T): T;
+export declare const CURRENT_SCHEMA_VERSION = 1;
+//#endregion

package/lib/storage.js

@@ -0,0 +1,65 @@
+import path from "node:path";
+import { promises } from "node:fs";
+//#region src/storage.ts
+let temporaryFileCounter = 0;
+const locks = /* @__PURE__ */ new Map();
+async function withProcessLock(key, operation) {
+	const previous = locks.get(key) ?? Promise.resolve();
+	let release;
+	const current = new Promise((resolve) => {
+		release = resolve;
+	});
+	locks.set(key, current);
+	await previous;
+	try {
+		return await operation();
+	} finally {
+		release();
+		if (locks.get(key) === current) locks.delete(key);
+	}
+}
+async function atomicWrite(filePath, contents) {
+	const directory = path.dirname(filePath);
+	await promises.mkdir(directory, { recursive: true });
+	const basename = path.basename(filePath);
+	const temporaryPath = path.join(directory, `.${basename}.${process.pid}.${Date.now()}.${temporaryFileCounter++}.tmp`);
+	let handle;
+	try {
+		handle = await promises.open(temporaryPath, "wx", 384);
+		await handle.writeFile(contents);
+		await handle.sync();
+		await handle.close();
+		handle = void 0;
+		await promises.rename(temporaryPath, filePath);
+		const directoryHandle = await promises.open(directory, "r");
+		try {
+			await directoryHandle.sync();
+		} finally {
+			await directoryHandle.close();
+		}
+	} finally {
+		if (handle !== void 0) await handle.close().catch(() => void 0);
+		await promises.unlink(temporaryPath).catch(() => void 0);
+	}
+}
+async function atomicWriteJson(filePath, value) {
+	await atomicWrite(filePath, `${JSON.stringify(value, null, 2)}\n`);
+}
+async function readJson(filePath) {
+	return JSON.parse(await promises.readFile(filePath, "utf8"));
+}
+async function fileExists(filePath) {
+	try {
+		await promises.access(filePath);
+		return true;
+	} catch (error) {
+		if (error.code === "ENOENT") return false;
+		throw error;
+	}
+}
+function clone(value) {
+	return value === void 0 ? value : JSON.parse(JSON.stringify(value));
+}
+const CURRENT_SCHEMA_VERSION = 1;
+//#endregion
+export { CURRENT_SCHEMA_VERSION, atomicWrite, atomicWriteJson, clone, fileExists, readJson, withProcessLock };