dsh-live-teams 0.1.0

package/lib/command-queue.d.ts

@@ -0,0 +1,60 @@
+import { ErrorCode } from "./errors.js";
+//#region src/command-queue.d.ts
+export type CommandState = 'pending' | 'leased' | 'admitted' | 'applied' | 'failed';
+export interface CommandRecord {
+  commandId: string;
+  idempotencyKey: string;
+  causationId: string | undefined;
+  sessionId: string;
+  bindingGeneration: number;
+  mode: 'queue' | 'steer';
+  reason: string;
+  content: readonly unknown[];
+  requestId: string;
+  state: CommandState;
+  receipt: string | undefined;
+  failureCode: ErrorCode | undefined;
+  failureDetail: string | undefined;
+  revision: number;
+}
+type QueueOptions = {
+  workspacePath: string;
+  teamId: string;
+  deliver: (record: CommandRecord) => Promise<{
+    accepted?: true;
+  } | void>;
+  bindingGenerationOf?: ((sessionId: string) => Promise<number | undefined> | number | undefined) | undefined;
+  now?: (() => number) | undefined;
+};
+type AdmissionRequest = {
+  idempotencyKey: string;
+  sessionId: string;
+  bindingGeneration: number;
+  mode: 'queue' | 'steer';
+  content: readonly unknown[];
+  reason?: string;
+  causationId?: string;
+};
+export declare class SessionCommandQueue {
+  private readonly workspacePath;
+  private readonly teamId;
+  private readonly deliver;
+  private readonly bindingGenerationOf;
+  private readonly now;
+  private readonly file;
+  constructor(options: QueueOptions);
+  list(): Promise<CommandRecord[]>;
+  listPending(teamId?: string): Promise<CommandRecord[]>;
+  admit(request: AdmissionRequest): Promise<{
+    record: CommandRecord;
+    duplicate: boolean;
+  }>;
+  dispatch(commandId: string): Promise<CommandRecord>;
+  retry(commandId: string): Promise<CommandRecord>;
+  get(commandId: string): Promise<CommandRecord | undefined>;
+  private transition;
+  private mutate;
+  private read;
+}
+export declare function createCommandQueue(options: QueueOptions): SessionCommandQueue;
+//#endregion

package/lib/command-queue.js

@@ -0,0 +1,185 @@
+import { BINDING_STALE_MESSAGE, ERROR_CODES, LiveTeamsError } from "./errors.js";
+import { atomicWriteJson, clone, fileExists, readJson, withProcessLock } from "./storage.js";
+import path from "node:path";
+import { randomUUID } from "node:crypto";
+//#region src/command-queue.ts
+const DELIVERED_STATES = /* @__PURE__ */ new Set(["admitted", "applied"]);
+const AWAITING_DELIVERY_STATES = /* @__PURE__ */ new Set(["pending", "leased"]);
+function text(value) {
+	return typeof value === "string" && value.length > 0 ? value : void 0;
+}
+function findByIdempotencyKey(records, key) {
+	return records.find((record) => record.idempotencyKey === key);
+}
+var SessionCommandQueue = class {
+	workspacePath;
+	teamId;
+	deliver;
+	bindingGenerationOf;
+	now;
+	file;
+	constructor(options) {
+		if (text(options?.workspacePath) === void 0) throw new LiveTeamsError(ERROR_CODES.CAPABILITY_UNAVAILABLE, "command queue requires a workspacePath");
+		if (text(options?.teamId) === void 0) throw new LiveTeamsError(ERROR_CODES.CAPABILITY_UNAVAILABLE, "command queue requires a teamId");
+		if (typeof options?.deliver !== "function") throw new LiveTeamsError(ERROR_CODES.CAPABILITY_UNAVAILABLE, "command queue requires a delivery port");
+		this.workspacePath = path.resolve(options.workspacePath);
+		this.teamId = options.teamId;
+		this.deliver = options.deliver;
+		this.bindingGenerationOf = options.bindingGenerationOf;
+		this.now = options.now ?? Date.now;
+		this.now;
+		this.file = path.join(this.workspacePath, ".dsh-live-teams", "teams", this.teamId, "commands.json");
+	}
+	async list() {
+		return this.read();
+	}
+	async listPending(teamId) {
+		if (teamId !== void 0 && teamId !== this.teamId) return [];
+		return (await this.read()).filter((record) => AWAITING_DELIVERY_STATES.has(record.state));
+	}
+	async admit(request) {
+		const idempotencyKey = text(request?.idempotencyKey);
+		const sessionId = text(request?.sessionId);
+		if (idempotencyKey === void 0) throw new LiveTeamsError(ERROR_CODES.CAPABILITY_UNAVAILABLE, "admit requires an idempotencyKey");
+		if (sessionId === void 0) throw new LiveTeamsError(ERROR_CODES.CAPABILITY_UNAVAILABLE, "admit requires a sessionId");
+		if (request.mode !== "queue" && request.mode !== "steer") throw new LiveTeamsError(ERROR_CODES.DELIVERY_REJECTED, `Unsupported delivery mode "${String(request.mode)}"`);
+		if (!Number.isInteger(request.bindingGeneration)) throw new LiveTeamsError(ERROR_CODES.CAPABILITY_UNAVAILABLE, "admit requires a bindingGeneration");
+		return this.mutate((records) => {
+			const existing = findByIdempotencyKey(records, idempotencyKey);
+			if (existing !== void 0) return {
+				record: clone(existing),
+				duplicate: true
+			};
+			const record = {
+				commandId: randomUUID(),
+				idempotencyKey,
+				causationId: text(request.causationId),
+				sessionId,
+				bindingGeneration: request.bindingGeneration,
+				mode: request.mode,
+				reason: text(request.reason) ?? "unspecified",
+				content: clone(request.content ?? []),
+				requestId: `${this.teamId}:${idempotencyKey}`,
+				state: "pending",
+				receipt: void 0,
+				failureCode: void 0,
+				failureDetail: void 0,
+				revision: 1
+			};
+			records.push(record);
+			return {
+				record: clone(record),
+				duplicate: false
+			};
+		});
+	}
+	async dispatch(commandId) {
+		const reserved = await this.transition(commandId, (record) => {
+			if (DELIVERED_STATES.has(record.state)) return {
+				next: record,
+				stop: true
+			};
+			record.state = "leased";
+			record.revision += 1;
+			return {
+				next: record,
+				stop: false,
+				call: true
+			};
+		});
+		if (reserved.call !== true) return reserved.record;
+		let outcome;
+		try {
+			const current = typeof this.bindingGenerationOf === "function" ? await this.bindingGenerationOf(reserved.record.sessionId) : reserved.record.bindingGeneration;
+			if (current !== void 0 && current !== reserved.record.bindingGeneration) throw new LiveTeamsError(ERROR_CODES.BINDING_STALE, BINDING_STALE_MESSAGE, { auditDetail: `admitted for generation ${reserved.record.bindingGeneration}, current ${current}` });
+			await this.deliver(clone(reserved.record));
+			outcome = {
+				state: "admitted",
+				receipt: "accepted"
+			};
+		} catch (error) {
+			const domain = error instanceof LiveTeamsError ? error : new LiveTeamsError(ERROR_CODES.DELIVERY_REJECTED, error instanceof Error ? error.message : String(error), { cause: error });
+			outcome = {
+				state: "failed",
+				failureCode: domain.code,
+				failureDetail: domain.auditDetail ?? domain.message
+			};
+		}
+		return (await this.transition(commandId, (record) => {
+			record.state = outcome.state;
+			record.receipt = outcome.receipt;
+			record.failureCode = outcome.failureCode;
+			record.failureDetail = outcome.failureDetail;
+			record.revision += 1;
+			return {
+				next: record,
+				stop: true
+			};
+		})).record;
+	}
+	async retry(commandId) {
+		const prepared = await this.transition(commandId, (record) => {
+			record.state = "pending";
+			record.receipt = void 0;
+			record.failureCode = void 0;
+			record.failureDetail = void 0;
+			record.revision += 1;
+			return {
+				next: record,
+				stop: true
+			};
+		});
+		const before = (await this.read()).length;
+		const dispatched = await this.dispatch(prepared.record.commandId);
+		if (before !== (await this.read()).length) throw new LiveTeamsError(ERROR_CODES.STATE_CORRUPT, "retry changed the number of durable commands");
+		return dispatched;
+	}
+	async get(commandId) {
+		const record = (await this.read()).find((entry) => entry.commandId === commandId);
+		return record === void 0 ? void 0 : clone(record);
+	}
+	async transition(commandId, change) {
+		return this.mutate((records) => {
+			const index = records.findIndex((entry) => entry.commandId === commandId);
+			if (index < 0) throw new LiveTeamsError(ERROR_CODES.DELIVERY_REJECTED, `unknown command "${commandId}"`);
+			const outcome = change(records[index]);
+			records[index] = outcome.next;
+			return {
+				record: clone(outcome.next),
+				call: outcome.call === true
+			};
+		});
+	}
+	async mutate(change) {
+		return withProcessLock(this.file, async () => {
+			const records = await this.read();
+			const result = change(records);
+			await atomicWriteJson(this.file, {
+				schemaVersion: 1,
+				teamId: this.teamId,
+				commands: records
+			});
+			return result;
+		});
+	}
+	async read() {
+		if (!await fileExists(this.file)) return [];
+		let parsed;
+		try {
+			parsed = await readJson(this.file);
+		} catch (error) {
+			throw new LiveTeamsError(ERROR_CODES.STATE_CORRUPT, "command state is not readable JSON", {
+				cause: error,
+				auditDetail: `failed to read ${this.file}`
+			});
+		}
+		const commands = parsed !== null && typeof parsed === "object" ? parsed.commands : void 0;
+		if (!Array.isArray(commands)) throw new LiveTeamsError(ERROR_CODES.STATE_CORRUPT, "command state has no command list", { auditDetail: `invalid shape in ${this.file}` });
+		return commands;
+	}
+};
+function createCommandQueue(options) {
+	return new SessionCommandQueue(options);
+}
+//#endregion
+export { SessionCommandQueue, createCommandQueue };

package/lib/compatibility.js

@@ -0,0 +1,109 @@
+import { createRequire } from "node:module";
+//#region src/compatibility.ts
+/**
+* Read a host service the way the plugin itself does.
+*
+* Cordis **throws** when a service that was not declared in `inject` is read as a property, so a
+* compatibility check that pokes at `ctx.tools` does not report a missing service — it crashes the
+* plugin it was meant to protect. The safe reader is `ctx.get(name)`; the property access stays as a
+* fallback for a plain object, wrapped so that a throwing host reads as "not available".
+*/
+function service(host, name) {
+	try {
+		const get = host.get;
+		if (typeof get === "function") return get.call(host, name);
+	} catch {
+		return;
+	}
+	try {
+		return host[name];
+	} catch {
+		return;
+	}
+}
+function hasFunction(host, name, member) {
+	const value = service(host, name);
+	if (value === void 0 || value === null) return false;
+	if (member === void 0) return true;
+	try {
+		return typeof value[member] === "function";
+	} catch {
+		return false;
+	}
+}
+/**
+* The host surfaces this plugin calls, and whether it can live without them.
+*
+* Keep this list honest: it is the contract with the host. Adding a call to a new service without
+* adding it here means the next DSH release can remove it silently.
+*/
+const HOST_CAPABILITIES = Object.freeze([
+	{
+		name: "sessionController.create",
+		required: true,
+		present: (host) => hasFunction(host, "sessionController", "create")
+	},
+	{
+		name: "agents.get",
+		required: true,
+		present: (host) => hasFunction(host, "agents", "get")
+	},
+	{
+		name: "systemPrompt",
+		required: true,
+		present: (host) => service(host, "systemPrompt") !== void 0 && service(host, "systemPrompt") !== null
+	},
+	{
+		name: "workspaceRegistry",
+		required: true,
+		present: (host) => service(host, "workspaceRegistry") !== void 0 && service(host, "workspaceRegistry") !== null
+	},
+	{
+		name: "tools.register",
+		required: false,
+		present: (host) => hasFunction(host, "tools", "register")
+	},
+	{
+		name: "webServer.register",
+		required: false,
+		present: (host) => hasFunction(host, "webServer", "register")
+	}
+]);
+/** The version of the host packages this plugin is running against, when it can be read. */
+function hostVersion() {
+	try {
+		const require = createRequire(import.meta.url);
+		for (const name of ["@deepseek-ai/dsh-agent", "@deepseek-ai/dsh-session"]) try {
+			const manifest = require(`${name}/package.json`);
+			if (typeof manifest.version === "string") return manifest.version;
+		} catch {}
+	} catch {}
+}
+/** The versions this plugin declares support for, read from its own manifest. */
+function declaredReleases() {
+	try {
+		const manifest = createRequire(import.meta.url)("../package.json");
+		return Object.keys(manifest.dsh?.compatibility?.dshReleases ?? {});
+	} catch {
+		return [];
+	}
+}
+function checkCompatibility(host, options = {}) {
+	const capabilities = options.capabilities ?? HOST_CAPABILITIES;
+	const missing = capabilities.filter((capability) => capability.required && !capability.present(host)).map((capability) => capability.name);
+	const absent = capabilities.filter((capability) => !capability.required && !capability.present(host)).map((capability) => capability.name);
+	const version = options.hostVersion ?? hostVersion();
+	const declared = options.declared ?? declaredReleases();
+	const undeclared = version !== void 0 && declared.length > 0 && !declared.includes(version);
+	const verdict = missing.length > 0 ? "incompatible" : absent.length > 0 || undeclared ? "degraded" : "compatible";
+	const detail = missing.length > 0 ? `DSH ${version ?? "of unknown version"} does not offer ${missing.join(", ")}; the team stays off until the plugin is updated` : absent.length > 0 ? `running without ${absent.join(", ")}; the team works, the surfaces they serve do not` : undeclared ? `DSH ${version ?? "of unknown version"} is not in this plugin's declared releases (${declared.join(", ")}); everything the plugin calls is present` : `DSH ${version ?? "of unknown version"} offers everything this plugin calls`;
+	return {
+		verdict,
+		...version === void 0 ? {} : { hostVersion: version },
+		missing,
+		absent,
+		detail
+	};
+}
+//#endregion
+export { HOST_CAPABILITIES, checkCompatibility, declaredReleases, hostVersion };

package/lib/context-provider.d.ts

@@ -0,0 +1,110 @@
+import { MemberRecord, TeamState } from "./team-store.js";
+import { TeamTask } from "./task-store.js";
+import { LiveTeamsRole } from "./roles.js";
+//#region src/context-provider.d.ts
+export declare const MEMBERSHIP_CONTEXT_NAME = "live-teams:membership";
+export declare const MEMBERSHIP_CONTEXT_ORDER = 125;
+export declare function sessionIdOf(assemblyContext: unknown): string | undefined;
+export type MembershipMember = Pick<MemberRecord, 'memberId' | 'displayName' | 'role' | 'availability' | 'bindingGeneration' | 'contractRevision' | 'note'> & {
+  sessionId?: string;
+  roles?: readonly string[];
+  [key: string]: unknown;
+};
+export type RoleRegistrySync = {
+  resolve: (value: string) => Pick<LiveTeamsRole, 'body'> | undefined;
+};
+export type MembershipScope = {
+  teamId: string;
+  /** Set when a human wrote into this member's Session mid-attempt (B31). */
+  humanIntervenedAt?: number;
+  teamName?: string;
+  activeAttemptId?: string;
+  activeTask?: TeamTask;
+  tasks?: readonly TeamTask[];
+  formalToolsAvailable?: boolean;
+  roleRegistry?: RoleRegistrySync;
+  teamState?: TeamState;
+  workspacePath?: string;
+  live?: (member: MemberRecord) => boolean;
+  /**
+   * Comments addressed to this member that it has not acknowledged. A comment is stored with
+   * `wakePolicy: never`, so nothing wakes the Session for it — without this line the recipient never
+   * learns it was written (external review, finding 13).
+   */
+  comments?: readonly {
+    from: string;
+    content: string;
+    at: number;
+  }[];
+};
+export declare function renderMembership(member: MembershipMember, scope: MembershipScope): string;
+type SyncStore = {
+  memberBySessionSync: (teamId: string, sessionId: string) => MembershipMember | undefined;
+  teamStateSync?: (teamId: string) => TeamState | undefined;
+  attemptSync?: (teamId: string, taskId: string) => {
+    humanIntervenedAt?: number;
+    humanIntervenedContractRevision?: number;
+    generation: number;
+  } | undefined;
+  activeTaskForMemberSync?: (teamId: string, memberId: string) => TeamTask | undefined;
+  tasksSync?: (teamId: string) => readonly TeamTask[] | undefined;
+};
+export type MembershipContextBinding = {
+  readonly store: SyncStore;
+  readonly teamId: string;
+  readonly teamName?: string | (() => string);
+  readonly workspacePath?: string;
+  readonly enabled?: () => boolean;
+  readonly roleRegistry?: RoleRegistrySync;
+  readonly live?: (member: MemberRecord) => boolean;
+  readonly activeTaskForMemberSync?: (teamId: string, memberId: string) => TeamTask | undefined;
+  readonly tasksSync?: (teamId: string) => readonly TeamTask[] | undefined;
+  readonly attemptSync?: (teamId: string, taskId: string) => {
+    humanIntervenedAt?: number;
+    humanIntervenedContractRevision?: number;
+    generation: number;
+  } | undefined;
+  /** Unread comments for a member, read synchronously because the context is assembled that way. */
+  readonly commentsSync?: (teamId: string, memberId: string) => readonly {
+    from: string;
+    content: string;
+    at: number;
+  }[];
+};
+export type MembershipContextOptions = {
+  readonly store?: SyncStore;
+  readonly teamId?: string;
+  readonly teamName?: string | (() => string);
+  readonly workspacePath?: string;
+  readonly onError?: (error: unknown) => void;
+  readonly formalToolsAvailable?: boolean;
+  readonly roleRegistry?: RoleRegistrySync;
+  readonly resolveSession?: (sessionId: string) => MembershipContextBinding | undefined;
+  readonly enabled?: () => boolean;
+  readonly live?: (member: MemberRecord) => boolean;
+  readonly activeTaskForMemberSync?: (teamId: string, memberId: string) => TeamTask | undefined;
+  readonly tasksSync?: (teamId: string) => readonly TeamTask[] | undefined;
+  readonly attemptSync?: (teamId: string, taskId: string) => {
+    humanIntervenedAt?: number;
+    humanIntervenedContractRevision?: number;
+    generation: number;
+  } | undefined;
+  readonly commentsSync?: (teamId: string, memberId: string) => readonly {
+    from: string;
+    content: string;
+    at: number;
+  }[];
+};
+export type MembershipContextProvider = {
+  name: string;
+  order: number;
+  teamId: string;
+  text: (assemblyContext: unknown) => string;
+  definition: () => {
+    name: string;
+    order: number;
+    text: (assemblyContext: unknown) => string;
+  };
+};
+export declare function createMembershipContextProvider(options: MembershipContextOptions): MembershipContextProvider;
+//#endregion