@agimon-ai/doompi-workflow 0.0.1-alpha.76 → 0.0.1-alpha.78

package/dist/src/services/workflowRuns/index.mjs

@@ -0,0 +1,319 @@
+import { resolve } from "node:path";
+//#region src/services/workflowRuns/index.ts
+/**
+* MIRRORS @agimon-ai/workflow-mcp's on-disk registry
+* (src/services/WorkflowRegistryService.ts and WorkflowProgressService.ts in
+* that package). The engine keeps one directory per run under
+* `<home>/workspaces/<workspace>/<stage>/<runKey>/` holding a `run.json`
+* record and an append-only `progress.ndjson` job/step log; the hub only ever
+* reads them. The derivation is duplicated rather than imported because
+* doompi-web must not depend on the engine at runtime; the unit suite pins
+* this mirror against the package's published types.
+*/
+const DEFAULT_WORKFLOW_HOME_DIR_NAME = ".workflow-mcp";
+const WORKFLOW_HOME_ENV = "WORKFLOW_MCP_HOME";
+const WORKSPACES_DIR_NAME = "workspaces";
+const RUN_RECORD_FILE_NAME = "run.json";
+const PROGRESS_FILE_NAME = "progress.ndjson";
+const WORKFLOW_STAGES = [
+	"running",
+	"completed",
+	"error"
+];
+/**
+* Errored runs stay a day, which is how long recovery has to act on them.
+*
+* Finished runs have no retention of their own: a session keeps every run it
+* launched, grouped by outcome, for as long as the session lives. A run leaves
+* the view when the engine prunes its registry directory, not on a timer here,
+* because "what did this session run today" is a question asked long after the
+* run settled.
+*/
+const WORKFLOW_ERROR_RETENTION_MS = 864e5;
+/** The env key doompi-workflow stamps on runs it launches; ties a run to a Pi session. */
+const PI_SESSION_ENV = "PI_SESSION_ID";
+const PROGRESS_STATES = /* @__PURE__ */ new Set([
+	"running",
+	"completed",
+	"skipped",
+	"failed",
+	"pause_requested",
+	"paused",
+	"resumed"
+]);
+const OUTCOMES = /* @__PURE__ */ new Set([
+	"success",
+	"skipped",
+	"failed",
+	"interrupted"
+]);
+const EXECUTION_STATES = /* @__PURE__ */ new Set([
+	"running",
+	"pause_requested",
+	"paused",
+	"resume_requested"
+]);
+const STEP_TERMINAL_STATES = /* @__PURE__ */ new Set([
+	"completed",
+	"skipped",
+	"failed"
+]);
+/** The engine records its pre:/post: blocks under these reserved pseudo-job names. */
+const PHASE_JOB_PRE = "pre";
+const PHASE_JOB_POST = "post";
+const ANSI_ESCAPE_PATTERN = /\u001b\[[0-9;]*[A-Za-z]/g;
+/** Where workflow-mcp keeps its registry, mirroring the engine's own resolution. */
+function resolveWorkflowHome(input) {
+	return resolve(input.envValue !== void 0 && input.envValue !== "" ? input.envValue : resolve(input.homeDir, DEFAULT_WORKFLOW_HOME_DIR_NAME));
+}
+function isRecord(value) {
+	return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function asOptionalString(value) {
+	return typeof value === "string" && value !== "" ? value : void 0;
+}
+function asOptionalNumber(value) {
+	return typeof value === "number" && Number.isFinite(value) ? value : void 0;
+}
+function stripAnsi(text) {
+	return text.replace(ANSI_ESCAPE_PATTERN, "").trim();
+}
+/**
+* Validates one run.json into the wire shape plus scoping facts.
+*
+* Returns undefined for anything unreadable or a foreign format. The record
+* is trusted for its own stage: the registry rewrites it when a run moves
+* between stage directories.
+*/
+function parseWorkflowRunRecord(raw) {
+	let parsed;
+	try {
+		parsed = JSON.parse(raw);
+	} catch {
+		return;
+	}
+	if (!isRecord(parsed)) return void 0;
+	const runKey = asOptionalString(parsed.runKey);
+	const workspace = asOptionalString(parsed.workspace);
+	const workflowPath = asOptionalString(parsed.workflowPath);
+	const startedAt = asOptionalString(parsed.startedAt);
+	const stage = asOptionalString(parsed.stage);
+	if (!runKey || !workspace || !workflowPath || !startedAt) return void 0;
+	if (stage === void 0 || !WORKFLOW_STAGES.includes(stage)) return void 0;
+	const outcome = asOptionalString(parsed.outcome);
+	const executionState = asOptionalString(parsed.executionState);
+	const rawError = asOptionalString(parsed.errorMessage);
+	const env = isRecord(parsed.env) ? parsed.env : void 0;
+	const view = {
+		runKey,
+		workspace,
+		displayName: asOptionalString(parsed.displayName) ?? runKey,
+		...asOptionalString(parsed.workflowName) === void 0 ? {} : { workflowName: asOptionalString(parsed.workflowName) },
+		workflowPath,
+		stage,
+		...outcome !== void 0 && OUTCOMES.has(outcome) ? { outcome } : {},
+		...executionState !== void 0 && EXECUTION_STATES.has(executionState) ? { executionState } : {},
+		...asOptionalString(parsed.prompt) === void 0 ? {} : { prompt: asOptionalString(parsed.prompt) },
+		startedAt,
+		...asOptionalString(parsed.finishedAt) === void 0 ? {} : { finishedAt: asOptionalString(parsed.finishedAt) },
+		...rawError === void 0 ? {} : { errorMessage: stripAnsi(rawError) },
+		...asOptionalString(parsed.failedJob) === void 0 ? {} : { failedJob: asOptionalString(parsed.failedJob) },
+		...parsed.stale === true ? { stale: true } : {},
+		...asOptionalString(parsed.staleReason) === void 0 ? {} : { staleReason: asOptionalString(parsed.staleReason) },
+		...asOptionalString(parsed.worktreeBranch) === void 0 ? {} : { worktreeBranch: asOptionalString(parsed.worktreeBranch) },
+		jobs: []
+	};
+	const piSessionId = env === void 0 ? void 0 : asOptionalString(env[PI_SESSION_ENV]);
+	return {
+		view,
+		...piSessionId === void 0 ? {} : { piSessionId }
+	};
+}
+/**
+* Parses the append-only progress log. Malformed lines are skipped rather
+* than failing the file: a reader routinely catches a torn final line
+* mid-append.
+*/
+function parseWorkflowProgress(raw) {
+	const events = [];
+	for (const line of raw.split("\n")) {
+		const trimmed = line.trim();
+		if (trimmed === "") continue;
+		let parsed;
+		try {
+			parsed = JSON.parse(trimmed);
+		} catch {
+			continue;
+		}
+		if (!isRecord(parsed)) continue;
+		const type = parsed.type;
+		const status = asOptionalString(parsed.status);
+		const job = asOptionalString(parsed.job);
+		const at = asOptionalString(parsed.at);
+		if (type !== "job" && type !== "step" || !job || !at) continue;
+		if (status === void 0 || !PROGRESS_STATES.has(status)) continue;
+		const step = asOptionalString(parsed.step);
+		const index = asOptionalNumber(parsed.index);
+		const total = asOptionalNumber(parsed.total);
+		const reason = asOptionalString(parsed.reason);
+		events.push({
+			type,
+			status,
+			job,
+			...step === void 0 ? {} : { step },
+			...index === void 0 ? {} : { index },
+			...total === void 0 ? {} : { total },
+			...reason === void 0 ? {} : { reason },
+			at
+		});
+	}
+	return events;
+}
+function jobPhase(name) {
+	if (name === PHASE_JOB_PRE) return PHASE_JOB_PRE;
+	if (name === PHASE_JOB_POST) return PHASE_JOB_POST;
+	return "job";
+}
+/**
+* Folds the event log into the current job tree; later events win, so a job
+* that started and later failed reads as failed. Jobs and steps keep the
+* order of their first appearance.
+*/
+function foldWorkflowProgress(events) {
+	const jobs = [];
+	const jobByName = /* @__PURE__ */ new Map();
+	for (const event of events) {
+		let job = jobByName.get(event.job);
+		if (job === void 0) {
+			job = {
+				name: event.job,
+				phase: jobPhase(event.job),
+				status: event.status,
+				steps: []
+			};
+			jobByName.set(event.job, job);
+			jobs.push(job);
+		}
+		if (event.type === "job") {
+			job.status = event.status;
+			if (event.reason !== void 0) job.reason = event.reason;
+			if (event.index !== void 0) job.index = event.index;
+			if (event.total !== void 0) job.total = event.total;
+			if (event.status === "running" && job.startedAt === void 0) job.startedAt = event.at;
+			if (STEP_TERMINAL_STATES.has(event.status)) job.endedAt = event.at;
+			continue;
+		}
+		if (event.step === void 0) continue;
+		let step = job.steps.find((candidate) => candidate.name === event.step);
+		if (step === void 0) {
+			step = {
+				name: event.step,
+				status: event.status
+			};
+			job.steps.push(step);
+		}
+		step.status = event.status;
+		if (event.reason !== void 0) step.reason = event.reason;
+		if (event.status === "running" && step.startedAt === void 0) step.startedAt = event.at;
+		if (STEP_TERMINAL_STATES.has(event.status)) step.endedAt = event.at;
+	}
+	return jobs;
+}
+const ACTIVE_PROGRESS_STATES = /* @__PURE__ */ new Set([
+	"running",
+	"pause_requested",
+	"paused",
+	"resumed"
+]);
+/** The job and step a run is on right now, for the NOW breadcrumb. */
+function workflowPosition(jobs) {
+	for (let jobIndex = jobs.length - 1; jobIndex >= 0; jobIndex -= 1) {
+		const job = jobs[jobIndex];
+		if (!ACTIVE_PROGRESS_STATES.has(job.status)) continue;
+		for (let stepIndex = job.steps.length - 1; stepIndex >= 0; stepIndex -= 1) {
+			const step = job.steps[stepIndex];
+			if (ACTIVE_PROGRESS_STATES.has(step.status)) return {
+				job: job.name,
+				step: step.name,
+				...job.index === void 0 ? {} : { index: job.index },
+				...job.total === void 0 ? {} : { total: job.total }
+			};
+		}
+		return {
+			job: job.name,
+			...job.index === void 0 ? {} : { index: job.index },
+			...job.total === void 0 ? {} : { total: job.total }
+		};
+	}
+}
+/** The finished view: record fields plus the folded job tree and position. */
+function completeWorkflowRunView(view, jobs) {
+	const position = view.stage === "running" ? workflowPosition(jobs) : void 0;
+	return {
+		...view,
+		jobs,
+		...position === void 0 ? {} : { position }
+	};
+}
+/**
+* Whether a run belongs on a session's workflow tab: launched by that Pi
+* session, which is the same env test doompi-workflow's isSessionRun applies.
+*
+* The registry is one directory under $HOME shared by every repository and
+* every Pi session on the machine, so repository proximity is not ownership.
+* Scoping on it as well let two sessions open in one repo read each other's
+* history, and kept a dead session's runs on the board of every session that
+* replaced it. Fails closed on an unstamped record, which is what a launch
+* from the CLI rather than from a session leaves behind.
+*/
+function runBelongsToSession(run, sessionId) {
+	return run.piSessionId !== void 0 && run.piSessionId === sessionId;
+}
+function parseTime(value) {
+	if (value === void 0) return 0;
+	const time = Date.parse(value);
+	return Number.isFinite(time) ? time : 0;
+}
+const STAGE_ORDER = {
+	running: 0,
+	error: 1,
+	completed: 2
+};
+/**
+* Whether a run still belongs in the view.
+*
+* Only errored runs age out here, and slowly: everything else a session
+* started stays until the engine forgets the run itself.
+*/
+function withinRetention(run, now) {
+	if (run.stage !== "error") return true;
+	return now - (parseTime(run.finishedAt) || parseTime(run.startedAt)) < WORKFLOW_ERROR_RETENTION_MS;
+}
+/**
+* When a run last moved, which is what orders it within its group.
+*
+* A running run has only its start; a settled one is ordered by when it
+* settled, because a list kept for the whole session is read as a history and
+* two runs started together can finish an hour apart.
+*/
+function lastMovedAt(run) {
+	return run.stage === "running" ? parseTime(run.startedAt) : parseTime(run.finishedAt) || parseTime(run.startedAt);
+}
+/**
+* Running runs first, then errored (recovery acts on them), then finished;
+* newest first within a group, and each group capped on its own.
+*/
+function presentWorkflowRuns(runs, now) {
+	const groups = /* @__PURE__ */ new Map();
+	for (const run of runs) {
+		if (!withinRetention(run, now)) continue;
+		const group = groups.get(run.stage);
+		if (group) group.push(run);
+		else groups.set(run.stage, [run]);
+	}
+	return [...groups.entries()].sort(([left], [right]) => STAGE_ORDER[left] - STAGE_ORDER[right]).flatMap(([, group]) => group.sort((left, right) => lastMovedAt(right) - lastMovedAt(left)).slice(0, 24));
+}
+//#endregion
+export { PI_SESSION_ENV, PROGRESS_FILE_NAME, RUN_RECORD_FILE_NAME, WORKFLOW_ERROR_RETENTION_MS, WORKFLOW_HOME_ENV, WORKFLOW_STAGES, WORKSPACES_DIR_NAME, completeWorkflowRunView, foldWorkflowProgress, parseWorkflowProgress, parseWorkflowRunRecord, presentWorkflowRuns, resolveWorkflowHome, runBelongsToSession, workflowPosition };
+
+//# sourceMappingURL=index.mjs.map

package/dist/src/services/workflowRuns/index.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.mjs","names":[],"sources":["../../../../src/services/workflowRuns/index.ts"],"sourcesContent":["import { resolve } from 'node:path';\n\nimport type {\n  WorkflowJobPhase,\n  WorkflowJobView,\n  WorkflowOutcome,\n  WorkflowPosition,\n  WorkflowProgressState,\n  WorkflowRunView,\n  WorkflowStage,\n  WorkflowStepView,\n} from '../../types/webWorkflows';\n\n/**\n * MIRRORS @agimon-ai/workflow-mcp's on-disk registry\n * (src/services/WorkflowRegistryService.ts and WorkflowProgressService.ts in\n * that package). The engine keeps one directory per run under\n * `<home>/workspaces/<workspace>/<stage>/<runKey>/` holding a `run.json`\n * record and an append-only `progress.ndjson` job/step log; the hub only ever\n * reads them. The derivation is duplicated rather than imported because\n * doompi-web must not depend on the engine at runtime; the unit suite pins\n * this mirror against the package's published types.\n */\nconst DEFAULT_WORKFLOW_HOME_DIR_NAME = '.workflow-mcp';\nexport const WORKFLOW_HOME_ENV = 'WORKFLOW_MCP_HOME';\nexport const WORKSPACES_DIR_NAME = 'workspaces';\nexport const RUN_RECORD_FILE_NAME = 'run.json';\nexport const PROGRESS_FILE_NAME = 'progress.ndjson';\nexport const WORKFLOW_STAGES: readonly WorkflowStage[] = ['running', 'completed', 'error'];\n\n/**\n * Errored runs stay a day, which is how long recovery has to act on them.\n *\n * Finished runs have no retention of their own: a session keeps every run it\n * launched, grouped by outcome, for as long as the session lives. A run leaves\n * the view when the engine prunes its registry directory, not on a timer here,\n * because \"what did this session run today\" is a question asked long after the\n * run settled.\n */\nexport const WORKFLOW_ERROR_RETENTION_MS = 24 * 60 * 60 * 1000;\n/**\n * Upper bound per outcome group rather than over the whole list.\n *\n * One cap across every run let a long stream of green runs push a failure out\n * of the list, which is the one thing that must never fall off the end.\n */\nexport const MAX_PRESENTED_WORKFLOW_RUNS_PER_GROUP = 24;\n\n/** The env key doompi-workflow stamps on runs it launches; ties a run to a Pi session. */\nexport const PI_SESSION_ENV = 'PI_SESSION_ID';\n\nconst PROGRESS_STATES: ReadonlySet<string> = new Set([\n  'running',\n  'completed',\n  'skipped',\n  'failed',\n  'pause_requested',\n  'paused',\n  'resumed',\n]);\nconst OUTCOMES: ReadonlySet<string> = new Set(['success', 'skipped', 'failed', 'interrupted']);\nconst EXECUTION_STATES: ReadonlySet<string> = new Set(['running', 'pause_requested', 'paused', 'resume_requested']);\nconst STEP_TERMINAL_STATES: ReadonlySet<WorkflowProgressState> = new Set(['completed', 'skipped', 'failed']);\n/** The engine records its pre:/post: blocks under these reserved pseudo-job names. */\nconst PHASE_JOB_PRE = 'pre';\nconst PHASE_JOB_POST = 'post';\n\n// oxlint-disable-next-line no-control-regex -- stripping terminal color codes from errorMessage is the point\nconst ANSI_ESCAPE_PATTERN = /\\u001b\\[[0-9;]*[A-Za-z]/g;\n\nexport interface WorkflowHomeInput {\n  /** process.env.WORKFLOW_MCP_HOME, supplied by the caller. */\n  envValue: string | undefined;\n  /** os.homedir(), supplied by the caller. */\n  homeDir: string;\n}\n\n/** Where workflow-mcp keeps its registry, mirroring the engine's own resolution. */\nexport function resolveWorkflowHome(input: WorkflowHomeInput): string {\n  return resolve(\n    input.envValue !== undefined && input.envValue !== ''\n      ? input.envValue\n      : resolve(input.homeDir, DEFAULT_WORKFLOW_HOME_DIR_NAME),\n  );\n}\n\nfunction isRecord(value: unknown): value is Record<string, unknown> {\n  return typeof value === 'object' && value !== null && !Array.isArray(value);\n}\n\nfunction asOptionalString(value: unknown): string | undefined {\n  return typeof value === 'string' && value !== '' ? value : undefined;\n}\n\nfunction asOptionalNumber(value: unknown): number | undefined {\n  return typeof value === 'number' && Number.isFinite(value) ? value : undefined;\n}\n\nfunction stripAnsi(text: string): string {\n  return text.replace(ANSI_ESCAPE_PATTERN, '').trim();\n}\n\n/**\n * One run record plus the facts the hub needs for session scoping but the\n * page never sees.\n */\nexport interface ParsedWorkflowRun {\n  /** The wire view, before the progress log is folded in (jobs empty). */\n  view: WorkflowRunView;\n  /** env.PI_SESSION_ID from the record, when the launcher stamped one. */\n  piSessionId?: string;\n}\n\n/**\n * Validates one run.json into the wire shape plus scoping facts.\n *\n * Returns undefined for anything unreadable or a foreign format. The record\n * is trusted for its own stage: the registry rewrites it when a run moves\n * between stage directories.\n */\nexport function parseWorkflowRunRecord(raw: string): ParsedWorkflowRun | undefined {\n  let parsed: unknown;\n  try {\n    parsed = JSON.parse(raw);\n  } catch {\n    return undefined;\n  }\n  if (!isRecord(parsed)) return undefined;\n  const runKey = asOptionalString(parsed.runKey);\n  const workspace = asOptionalString(parsed.workspace);\n  const workflowPath = asOptionalString(parsed.workflowPath);\n  const startedAt = asOptionalString(parsed.startedAt);\n  const stage = asOptionalString(parsed.stage);\n  if (!runKey || !workspace || !workflowPath || !startedAt) return undefined;\n  if (stage === undefined || !WORKFLOW_STAGES.includes(stage as WorkflowStage)) return undefined;\n\n  const outcome = asOptionalString(parsed.outcome);\n  const executionState = asOptionalString(parsed.executionState);\n  const rawError = asOptionalString(parsed.errorMessage);\n  const env = isRecord(parsed.env) ? parsed.env : undefined;\n  const view: WorkflowRunView = {\n    runKey,\n    workspace,\n    displayName: asOptionalString(parsed.displayName) ?? runKey,\n    ...(asOptionalString(parsed.workflowName) === undefined\n      ? {}\n      : { workflowName: asOptionalString(parsed.workflowName) }),\n    workflowPath,\n    stage: stage as WorkflowStage,\n    ...(outcome !== undefined && OUTCOMES.has(outcome) ? { outcome: outcome as WorkflowOutcome } : {}),\n    ...(executionState !== undefined && EXECUTION_STATES.has(executionState)\n      ? { executionState: executionState as WorkflowRunView['executionState'] }\n      : {}),\n    ...(asOptionalString(parsed.prompt) === undefined ? {} : { prompt: asOptionalString(parsed.prompt) }),\n    startedAt,\n    ...(asOptionalString(parsed.finishedAt) === undefined ? {} : { finishedAt: asOptionalString(parsed.finishedAt) }),\n    ...(rawError === undefined ? {} : { errorMessage: stripAnsi(rawError) }),\n    ...(asOptionalString(parsed.failedJob) === undefined ? {} : { failedJob: asOptionalString(parsed.failedJob) }),\n    ...(parsed.stale === true ? { stale: true } : {}),\n    ...(asOptionalString(parsed.staleReason) === undefined\n      ? {}\n      : { staleReason: asOptionalString(parsed.staleReason) }),\n    ...(asOptionalString(parsed.worktreeBranch) === undefined\n      ? {}\n      : { worktreeBranch: asOptionalString(parsed.worktreeBranch) }),\n    jobs: [],\n  };\n  const piSessionId = env === undefined ? undefined : asOptionalString(env[PI_SESSION_ENV]);\n  return { view, ...(piSessionId === undefined ? {} : { piSessionId }) };\n}\n\ninterface WorkflowProgressEvent {\n  type: 'job' | 'step';\n  status: WorkflowProgressState;\n  job: string;\n  step?: string;\n  index?: number;\n  total?: number;\n  reason?: string;\n  at: string;\n}\n\n/**\n * Parses the append-only progress log. Malformed lines are skipped rather\n * than failing the file: a reader routinely catches a torn final line\n * mid-append.\n */\nexport function parseWorkflowProgress(raw: string): WorkflowProgressEvent[] {\n  const events: WorkflowProgressEvent[] = [];\n  for (const line of raw.split('\\n')) {\n    const trimmed = line.trim();\n    if (trimmed === '') continue;\n    let parsed: unknown;\n    try {\n      parsed = JSON.parse(trimmed);\n    } catch {\n      continue;\n    }\n    if (!isRecord(parsed)) continue;\n    const type = parsed.type;\n    const status = asOptionalString(parsed.status);\n    const job = asOptionalString(parsed.job);\n    const at = asOptionalString(parsed.at);\n    if ((type !== 'job' && type !== 'step') || !job || !at) continue;\n    if (status === undefined || !PROGRESS_STATES.has(status)) continue;\n    const step = asOptionalString(parsed.step);\n    const index = asOptionalNumber(parsed.index);\n    const total = asOptionalNumber(parsed.total);\n    const reason = asOptionalString(parsed.reason);\n    events.push({\n      type,\n      status: status as WorkflowProgressState,\n      job,\n      ...(step === undefined ? {} : { step }),\n      ...(index === undefined ? {} : { index }),\n      ...(total === undefined ? {} : { total }),\n      ...(reason === undefined ? {} : { reason }),\n      at,\n    });\n  }\n  return events;\n}\n\nfunction jobPhase(name: string): WorkflowJobPhase {\n  if (name === PHASE_JOB_PRE) return PHASE_JOB_PRE;\n  if (name === PHASE_JOB_POST) return PHASE_JOB_POST;\n  return 'job';\n}\n\n/**\n * Folds the event log into the current job tree; later events win, so a job\n * that started and later failed reads as failed. Jobs and steps keep the\n * order of their first appearance.\n */\nexport function foldWorkflowProgress(events: readonly WorkflowProgressEvent[]): WorkflowJobView[] {\n  const jobs: WorkflowJobView[] = [];\n  const jobByName = new Map<string, WorkflowJobView>();\n  for (const event of events) {\n    let job = jobByName.get(event.job);\n    if (job === undefined) {\n      job = { name: event.job, phase: jobPhase(event.job), status: event.status, steps: [] };\n      jobByName.set(event.job, job);\n      jobs.push(job);\n    }\n    if (event.type === 'job') {\n      job.status = event.status;\n      if (event.reason !== undefined) job.reason = event.reason;\n      if (event.index !== undefined) job.index = event.index;\n      if (event.total !== undefined) job.total = event.total;\n      if (event.status === 'running' && job.startedAt === undefined) job.startedAt = event.at;\n      if (STEP_TERMINAL_STATES.has(event.status)) job.endedAt = event.at;\n      continue;\n    }\n    if (event.step === undefined) continue;\n    let step: WorkflowStepView | undefined = job.steps.find((candidate) => candidate.name === event.step);\n    if (step === undefined) {\n      step = { name: event.step, status: event.status };\n      job.steps.push(step);\n    }\n    step.status = event.status;\n    if (event.reason !== undefined) step.reason = event.reason;\n    if (event.status === 'running' && step.startedAt === undefined) step.startedAt = event.at;\n    if (STEP_TERMINAL_STATES.has(event.status)) step.endedAt = event.at;\n  }\n  return jobs;\n}\n\nconst ACTIVE_PROGRESS_STATES: ReadonlySet<WorkflowProgressState> = new Set([\n  'running',\n  'pause_requested',\n  'paused',\n  'resumed',\n]);\n\n/** The job and step a run is on right now, for the NOW breadcrumb. */\nexport function workflowPosition(jobs: readonly WorkflowJobView[]): WorkflowPosition | undefined {\n  for (let jobIndex = jobs.length - 1; jobIndex >= 0; jobIndex -= 1) {\n    const job = jobs[jobIndex]!;\n    if (!ACTIVE_PROGRESS_STATES.has(job.status)) continue;\n    for (let stepIndex = job.steps.length - 1; stepIndex >= 0; stepIndex -= 1) {\n      const step = job.steps[stepIndex]!;\n      if (ACTIVE_PROGRESS_STATES.has(step.status)) {\n        return {\n          job: job.name,\n          step: step.name,\n          ...(job.index === undefined ? {} : { index: job.index }),\n          ...(job.total === undefined ? {} : { total: job.total }),\n        };\n      }\n    }\n    return {\n      job: job.name,\n      ...(job.index === undefined ? {} : { index: job.index }),\n      ...(job.total === undefined ? {} : { total: job.total }),\n    };\n  }\n  return undefined;\n}\n\n/** The finished view: record fields plus the folded job tree and position. */\nexport function completeWorkflowRunView(view: WorkflowRunView, jobs: WorkflowJobView[]): WorkflowRunView {\n  const position = view.stage === 'running' ? workflowPosition(jobs) : undefined;\n  return { ...view, jobs, ...(position === undefined ? {} : { position }) };\n}\n\n/**\n * Whether a run belongs on a session's workflow tab: launched by that Pi\n * session, which is the same env test doompi-workflow's isSessionRun applies.\n *\n * The registry is one directory under $HOME shared by every repository and\n * every Pi session on the machine, so repository proximity is not ownership.\n * Scoping on it as well let two sessions open in one repo read each other's\n * history, and kept a dead session's runs on the board of every session that\n * replaced it. Fails closed on an unstamped record, which is what a launch\n * from the CLI rather than from a session leaves behind.\n */\nexport function runBelongsToSession(run: ParsedWorkflowRun, sessionId: string): boolean {\n  return run.piSessionId !== undefined && run.piSessionId === sessionId;\n}\n\nfunction parseTime(value: string | undefined): number {\n  if (value === undefined) return 0;\n  const time = Date.parse(value);\n  return Number.isFinite(time) ? time : 0;\n}\n\nconst STAGE_ORDER: Readonly<Record<WorkflowStage, number>> = { running: 0, error: 1, completed: 2 };\n\n/**\n * Whether a run still belongs in the view.\n *\n * Only errored runs age out here, and slowly: everything else a session\n * started stays until the engine forgets the run itself.\n */\nfunction withinRetention(run: WorkflowRunView, now: number): boolean {\n  if (run.stage !== 'error') return true;\n  const settledAt = parseTime(run.finishedAt) || parseTime(run.startedAt);\n  return now - settledAt < WORKFLOW_ERROR_RETENTION_MS;\n}\n\n/**\n * When a run last moved, which is what orders it within its group.\n *\n * A running run has only its start; a settled one is ordered by when it\n * settled, because a list kept for the whole session is read as a history and\n * two runs started together can finish an hour apart.\n */\nfunction lastMovedAt(run: WorkflowRunView): number {\n  return run.stage === 'running' ? parseTime(run.startedAt) : parseTime(run.finishedAt) || parseTime(run.startedAt);\n}\n\n/**\n * Running runs first, then errored (recovery acts on them), then finished;\n * newest first within a group, and each group capped on its own.\n */\nexport function presentWorkflowRuns(runs: readonly WorkflowRunView[], now: number): WorkflowRunView[] {\n  const groups = new Map<WorkflowStage, WorkflowRunView[]>();\n  for (const run of runs) {\n    if (!withinRetention(run, now)) continue;\n    const group = groups.get(run.stage);\n    if (group) group.push(run);\n    else groups.set(run.stage, [run]);\n  }\n  return [...groups.entries()]\n    .sort(([left], [right]) => STAGE_ORDER[left] - STAGE_ORDER[right])\n    .flatMap(([, group]) =>\n      group\n        .sort((left, right) => lastMovedAt(right) - lastMovedAt(left))\n        .slice(0, MAX_PRESENTED_WORKFLOW_RUNS_PER_GROUP),\n    );\n}\n"],"mappings":";;;;;;;;;;;;AAuBA,MAAM,iCAAiC;AACvC,MAAa,oBAAoB;AACjC,MAAa,sBAAsB;AACnC,MAAa,uBAAuB;AACpC,MAAa,qBAAqB;AAClC,MAAa,kBAA4C;CAAC;CAAW;CAAa;AAAO;;;;;;;;;;AAWzF,MAAa,8BAA8B;;AAU3C,MAAa,iBAAiB;AAE9B,MAAM,kCAAuC,IAAI,IAAI;CACnD;CACA;CACA;CACA;CACA;CACA;CACA;AACF,CAAC;AACD,MAAM,2BAAgC,IAAI,IAAI;CAAC;CAAW;CAAW;CAAU;AAAa,CAAC;AAC7F,MAAM,mCAAwC,IAAI,IAAI;CAAC;CAAW;CAAmB;CAAU;AAAkB,CAAC;AAClH,MAAM,uCAA2D,IAAI,IAAI;CAAC;CAAa;CAAW;AAAQ,CAAC;;AAE3G,MAAM,gBAAgB;AACtB,MAAM,iBAAiB;AAGvB,MAAM,sBAAsB;;AAU5B,SAAgB,oBAAoB,OAAkC;CACpE,OAAO,QACL,MAAM,aAAa,KAAA,KAAa,MAAM,aAAa,KAC/C,MAAM,WACN,QAAQ,MAAM,SAAS,8BAA8B,CAC3D;AACF;AAEA,SAAS,SAAS,OAAkD;CAClE,OAAO,OAAO,UAAU,YAAY,UAAU,QAAQ,CAAC,MAAM,QAAQ,KAAK;AAC5E;AAEA,SAAS,iBAAiB,OAAoC;CAC5D,OAAO,OAAO,UAAU,YAAY,UAAU,KAAK,QAAQ,KAAA;AAC7D;AAEA,SAAS,iBAAiB,OAAoC;CAC5D,OAAO,OAAO,UAAU,YAAY,OAAO,SAAS,KAAK,IAAI,QAAQ,KAAA;AACvE;AAEA,SAAS,UAAU,MAAsB;CACvC,OAAO,KAAK,QAAQ,qBAAqB,EAAE,CAAC,CAAC,KAAK;AACpD;;;;;;;;AAoBA,SAAgB,uBAAuB,KAA4C;CACjF,IAAI;CACJ,IAAI;EACF,SAAS,KAAK,MAAM,GAAG;CACzB,QAAQ;EACN;CACF;CACA,IAAI,CAAC,SAAS,MAAM,GAAG,OAAO,KAAA;CAC9B,MAAM,SAAS,iBAAiB,OAAO,MAAM;CAC7C,MAAM,YAAY,iBAAiB,OAAO,SAAS;CACnD,MAAM,eAAe,iBAAiB,OAAO,YAAY;CACzD,MAAM,YAAY,iBAAiB,OAAO,SAAS;CACnD,MAAM,QAAQ,iBAAiB,OAAO,KAAK;CAC3C,IAAI,CAAC,UAAU,CAAC,aAAa,CAAC,gBAAgB,CAAC,WAAW,OAAO,KAAA;CACjE,IAAI,UAAU,KAAA,KAAa,CAAC,gBAAgB,SAAS,KAAsB,GAAG,OAAO,KAAA;CAErF,MAAM,UAAU,iBAAiB,OAAO,OAAO;CAC/C,MAAM,iBAAiB,iBAAiB,OAAO,cAAc;CAC7D,MAAM,WAAW,iBAAiB,OAAO,YAAY;CACrD,MAAM,MAAM,SAAS,OAAO,GAAG,IAAI,OAAO,MAAM,KAAA;CAChD,MAAM,OAAwB;EAC5B;EACA;EACA,aAAa,iBAAiB,OAAO,WAAW,KAAK;EACrD,GAAI,iBAAiB,OAAO,YAAY,MAAM,KAAA,IAC1C,CAAC,IACD,EAAE,cAAc,iBAAiB,OAAO,YAAY,EAAE;EAC1D;EACO;EACP,GAAI,YAAY,KAAA,KAAa,SAAS,IAAI,OAAO,IAAI,EAAW,QAA2B,IAAI,CAAC;EAChG,GAAI,mBAAmB,KAAA,KAAa,iBAAiB,IAAI,cAAc,IACnE,EAAkB,eAAoD,IACtE,CAAC;EACL,GAAI,iBAAiB,OAAO,MAAM,MAAM,KAAA,IAAY,CAAC,IAAI,EAAE,QAAQ,iBAAiB,OAAO,MAAM,EAAE;EACnG;EACA,GAAI,iBAAiB,OAAO,UAAU,MAAM,KAAA,IAAY,CAAC,IAAI,EAAE,YAAY,iBAAiB,OAAO,UAAU,EAAE;EAC/G,GAAI,aAAa,KAAA,IAAY,CAAC,IAAI,EAAE,cAAc,UAAU,QAAQ,EAAE;EACtE,GAAI,iBAAiB,OAAO,SAAS,MAAM,KAAA,IAAY,CAAC,IAAI,EAAE,WAAW,iBAAiB,OAAO,SAAS,EAAE;EAC5G,GAAI,OAAO,UAAU,OAAO,EAAE,OAAO,KAAK,IAAI,CAAC;EAC/C,GAAI,iBAAiB,OAAO,WAAW,MAAM,KAAA,IACzC,CAAC,IACD,EAAE,aAAa,iBAAiB,OAAO,WAAW,EAAE;EACxD,GAAI,iBAAiB,OAAO,cAAc,MAAM,KAAA,IAC5C,CAAC,IACD,EAAE,gBAAgB,iBAAiB,OAAO,cAAc,EAAE;EAC9D,MAAM,CAAC;CACT;CACA,MAAM,cAAc,QAAQ,KAAA,IAAY,KAAA,IAAY,iBAAiB,IAAI,eAAe;CACxF,OAAO;EAAE;EAAM,GAAI,gBAAgB,KAAA,IAAY,CAAC,IAAI,EAAE,YAAY;CAAG;AACvE;;;;;;AAkBA,SAAgB,sBAAsB,KAAsC;CAC1E,MAAM,SAAkC,CAAC;CACzC,KAAK,MAAM,QAAQ,IAAI,MAAM,IAAI,GAAG;EAClC,MAAM,UAAU,KAAK,KAAK;EAC1B,IAAI,YAAY,IAAI;EACpB,IAAI;EACJ,IAAI;GACF,SAAS,KAAK,MAAM,OAAO;EAC7B,QAAQ;GACN;EACF;EACA,IAAI,CAAC,SAAS,MAAM,GAAG;EACvB,MAAM,OAAO,OAAO;EACpB,MAAM,SAAS,iBAAiB,OAAO,MAAM;EAC7C,MAAM,MAAM,iBAAiB,OAAO,GAAG;EACvC,MAAM,KAAK,iBAAiB,OAAO,EAAE;EACrC,IAAK,SAAS,SAAS,SAAS,UAAW,CAAC,OAAO,CAAC,IAAI;EACxD,IAAI,WAAW,KAAA,KAAa,CAAC,gBAAgB,IAAI,MAAM,GAAG;EAC1D,MAAM,OAAO,iBAAiB,OAAO,IAAI;EACzC,MAAM,QAAQ,iBAAiB,OAAO,KAAK;EAC3C,MAAM,QAAQ,iBAAiB,OAAO,KAAK;EAC3C,MAAM,SAAS,iBAAiB,OAAO,MAAM;EAC7C,OAAO,KAAK;GACV;GACQ;GACR;GACA,GAAI,SAAS,KAAA,IAAY,CAAC,IAAI,EAAE,KAAK;GACrC,GAAI,UAAU,KAAA,IAAY,CAAC,IAAI,EAAE,MAAM;GACvC,GAAI,UAAU,KAAA,IAAY,CAAC,IAAI,EAAE,MAAM;GACvC,GAAI,WAAW,KAAA,IAAY,CAAC,IAAI,EAAE,OAAO;GACzC;EACF,CAAC;CACH;CACA,OAAO;AACT;AAEA,SAAS,SAAS,MAAgC;CAChD,IAAI,SAAS,eAAe,OAAO;CACnC,IAAI,SAAS,gBAAgB,OAAO;CACpC,OAAO;AACT;;;;;;AAOA,SAAgB,qBAAqB,QAA6D;CAChG,MAAM,OAA0B,CAAC;CACjC,MAAM,4BAAY,IAAI,IAA6B;CACnD,KAAK,MAAM,SAAS,QAAQ;EAC1B,IAAI,MAAM,UAAU,IAAI,MAAM,GAAG;EACjC,IAAI,QAAQ,KAAA,GAAW;GACrB,MAAM;IAAE,MAAM,MAAM;IAAK,OAAO,SAAS,MAAM,GAAG;IAAG,QAAQ,MAAM;IAAQ,OAAO,CAAC;GAAE;GACrF,UAAU,IAAI,MAAM,KAAK,GAAG;GAC5B,KAAK,KAAK,GAAG;EACf;EACA,IAAI,MAAM,SAAS,OAAO;GACxB,IAAI,SAAS,MAAM;GACnB,IAAI,MAAM,WAAW,KAAA,GAAW,IAAI,SAAS,MAAM;GACnD,IAAI,MAAM,UAAU,KAAA,GAAW,IAAI,QAAQ,MAAM;GACjD,IAAI,MAAM,UAAU,KAAA,GAAW,IAAI,QAAQ,MAAM;GACjD,IAAI,MAAM,WAAW,aAAa,IAAI,cAAc,KAAA,GAAW,IAAI,YAAY,MAAM;GACrF,IAAI,qBAAqB,IAAI,MAAM,MAAM,GAAG,IAAI,UAAU,MAAM;GAChE;EACF;EACA,IAAI,MAAM,SAAS,KAAA,GAAW;EAC9B,IAAI,OAAqC,IAAI,MAAM,MAAM,cAAc,UAAU,SAAS,MAAM,IAAI;EACpG,IAAI,SAAS,KAAA,GAAW;GACtB,OAAO;IAAE,MAAM,MAAM;IAAM,QAAQ,MAAM;GAAO;GAChD,IAAI,MAAM,KAAK,IAAI;EACrB;EACA,KAAK,SAAS,MAAM;EACpB,IAAI,MAAM,WAAW,KAAA,GAAW,KAAK,SAAS,MAAM;EACpD,IAAI,MAAM,WAAW,aAAa,KAAK,cAAc,KAAA,GAAW,KAAK,YAAY,MAAM;EACvF,IAAI,qBAAqB,IAAI,MAAM,MAAM,GAAG,KAAK,UAAU,MAAM;CACnE;CACA,OAAO;AACT;AAEA,MAAM,yCAA6D,IAAI,IAAI;CACzE;CACA;CACA;CACA;AACF,CAAC;;AAGD,SAAgB,iBAAiB,MAAgE;CAC/F,KAAK,IAAI,WAAW,KAAK,SAAS,GAAG,YAAY,GAAG,YAAY,GAAG;EACjE,MAAM,MAAM,KAAK;EACjB,IAAI,CAAC,uBAAuB,IAAI,IAAI,MAAM,GAAG;EAC7C,KAAK,IAAI,YAAY,IAAI,MAAM,SAAS,GAAG,aAAa,GAAG,aAAa,GAAG;GACzE,MAAM,OAAO,IAAI,MAAM;GACvB,IAAI,uBAAuB,IAAI,KAAK,MAAM,GACxC,OAAO;IACL,KAAK,IAAI;IACT,MAAM,KAAK;IACX,GAAI,IAAI,UAAU,KAAA,IAAY,CAAC,IAAI,EAAE,OAAO,IAAI,MAAM;IACtD,GAAI,IAAI,UAAU,KAAA,IAAY,CAAC,IAAI,EAAE,OAAO,IAAI,MAAM;GACxD;EAEJ;EACA,OAAO;GACL,KAAK,IAAI;GACT,GAAI,IAAI,UAAU,KAAA,IAAY,CAAC,IAAI,EAAE,OAAO,IAAI,MAAM;GACtD,GAAI,IAAI,UAAU,KAAA,IAAY,CAAC,IAAI,EAAE,OAAO,IAAI,MAAM;EACxD;CACF;AAEF;;AAGA,SAAgB,wBAAwB,MAAuB,MAA0C;CACvG,MAAM,WAAW,KAAK,UAAU,YAAY,iBAAiB,IAAI,IAAI,KAAA;CACrE,OAAO;EAAE,GAAG;EAAM;EAAM,GAAI,aAAa,KAAA,IAAY,CAAC,IAAI,EAAE,SAAS;CAAG;AAC1E;;;;;;;;;;;;AAaA,SAAgB,oBAAoB,KAAwB,WAA4B;CACtF,OAAO,IAAI,gBAAgB,KAAA,KAAa,IAAI,gBAAgB;AAC9D;AAEA,SAAS,UAAU,OAAmC;CACpD,IAAI,UAAU,KAAA,GAAW,OAAO;CAChC,MAAM,OAAO,KAAK,MAAM,KAAK;CAC7B,OAAO,OAAO,SAAS,IAAI,IAAI,OAAO;AACxC;AAEA,MAAM,cAAuD;CAAE,SAAS;CAAG,OAAO;CAAG,WAAW;AAAE;;;;;;;AAQlG,SAAS,gBAAgB,KAAsB,KAAsB;CACnE,IAAI,IAAI,UAAU,SAAS,OAAO;CAElC,OAAO,OADW,UAAU,IAAI,UAAU,KAAK,UAAU,IAAI,SAAS,KAC7C;AAC3B;;;;;;;;AASA,SAAS,YAAY,KAA8B;CACjD,OAAO,IAAI,UAAU,YAAY,UAAU,IAAI,SAAS,IAAI,UAAU,IAAI,UAAU,KAAK,UAAU,IAAI,SAAS;AAClH;;;;;AAMA,SAAgB,oBAAoB,MAAkC,KAAgC;CACpG,MAAM,yBAAS,IAAI,IAAsC;CACzD,KAAK,MAAM,OAAO,MAAM;EACtB,IAAI,CAAC,gBAAgB,KAAK,GAAG,GAAG;EAChC,MAAM,QAAQ,OAAO,IAAI,IAAI,KAAK;EAClC,IAAI,OAAO,MAAM,KAAK,GAAG;OACpB,OAAO,IAAI,IAAI,OAAO,CAAC,GAAG,CAAC;CAClC;CACA,OAAO,CAAC,GAAG,OAAO,QAAQ,CAAC,CAAC,CACzB,MAAM,CAAC,OAAO,CAAC,WAAW,YAAY,QAAQ,YAAY,MAAM,CAAC,CACjE,SAAS,GAAG,WACX,MACG,MAAM,MAAM,UAAU,YAAY,KAAK,IAAI,YAAY,IAAI,CAAC,CAAC,CAC7D,MAAM,GAAA,EAAwC,CACnD;AACJ"}

package/dist/src/services/workflowTerminal/index.cjs

@@ -0,0 +1,69 @@
+//#region src/services/workflowTerminal/index.ts
+const DEFAULT_REFRESH_MS = 750;
+const DEFAULT_LEASE_MS = 6e4;
+const NOT_HELD = "Another reader holds the keyboard for this run.";
+function createWorkflowTerminalService(deps) {
+	const refreshMs = deps.refreshMs ?? DEFAULT_REFRESH_MS;
+	const leaseMs = deps.leaseMs ?? DEFAULT_LEASE_MS;
+	const screens = /* @__PURE__ */ new Map();
+	const leases = /* @__PURE__ */ new Map();
+	const heldBy = (identity) => {
+		const lease = leases.get(identity);
+		if (lease === void 0) return void 0;
+		if (lease.expiresAt > deps.now()) return lease;
+		leases.delete(identity);
+	};
+	return {
+		async screen(identity, record, lines) {
+			const entry = screens.get(identity) ?? { lines: [] };
+			screens.set(identity, entry);
+			if (entry.inFlight) return entry.lines;
+			if (entry.at !== void 0 && deps.now() - entry.at < refreshMs) return entry.lines;
+			entry.inFlight = deps.terminal.screen(record, { lines });
+			try {
+				entry.lines = await entry.inFlight;
+			} finally {
+				entry.at = deps.now();
+				entry.inFlight = void 0;
+			}
+			return entry.lines;
+		},
+		capabilities(record) {
+			return deps.terminal.capabilities(record);
+		},
+		takeControl(identity, token) {
+			const holder = heldBy(identity);
+			if (holder !== void 0 && holder.token !== token) return false;
+			leases.set(identity, {
+				token,
+				expiresAt: deps.now() + leaseMs
+			});
+			return true;
+		},
+		releaseControl(identity, token) {
+			if (heldBy(identity)?.token === token) leases.delete(identity);
+		},
+		async write(identity, record, token, data) {
+			const holder = heldBy(identity);
+			if (holder === void 0 || holder.token !== token) throw new Error(NOT_HELD);
+			leases.set(identity, {
+				token,
+				expiresAt: deps.now() + leaseMs
+			});
+			await deps.terminal.write(record, data);
+		},
+		async resize(identity, record, token, columns, rows) {
+			const holder = heldBy(identity);
+			if (holder === void 0 || holder.token !== token) throw new Error(NOT_HELD);
+			return deps.terminal.resize(record, columns, rows);
+		},
+		forget(live) {
+			for (const identity of screens.keys()) if (!live.has(identity)) screens.delete(identity);
+			for (const identity of leases.keys()) if (!live.has(identity)) leases.delete(identity);
+		}
+	};
+}
+//#endregion
+exports.createWorkflowTerminalService = createWorkflowTerminalService;
+
+//# sourceMappingURL=index.cjs.map

package/dist/src/services/workflowTerminal/index.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.cjs","names":[],"sources":["../../../../src/services/workflowTerminal/index.ts"],"sourcesContent":["import type { WorkflowTerminalCapabilitiesView } from '../../types/webWorkflowTerminal';\n\n/**\n * One run's terminal, shared by every surface watching it.\n *\n * WHY COALESCING LIVES HERE:\n * Reading a multiplexer's screen forks a CLI, measured at roughly 75ms a call.\n * Several readers on one run (a step tab, a second browser, the session's own\n * panel) would otherwise each fork on their own timer, and a read that runs\n * long would have the next one start on top of it, unbounded. One read per run\n * at a time, no faster than the interval, however many surfaces are watching.\n *\n * WHY A CONTROL LEASE:\n * A run's terminal takes keystrokes from anyone who can reach it, so two\n * readers typing into one nested agent is a real state, not a hypothetical.\n * The lease does not make it impossible, since the session's own panel can\n * still type; it makes it visible, and keeps two cockpit tabs from fighting.\n */\n\n/** The engine's terminal facade, as this service needs it. */\nexport interface TerminalPort<Record> {\n  capabilities(record: Record): WorkflowTerminalCapabilitiesView;\n  screen(record: Record, options: { lines?: number }): Promise<string[]>;\n  write(record: Record, data: string): Promise<void>;\n  resize(record: Record, columns: number, rows: number): Promise<boolean>;\n}\n\nexport interface WorkflowTerminalDeps<Record> {\n  terminal: TerminalPort<Record>;\n  /** Injected so the cadence and the lease clock are assertable. */\n  now: () => number;\n  /** Shortest gap between two reads of one run. */\n  refreshMs?: number;\n  /** How long a keyboard lease survives without being renewed. */\n  leaseMs?: number;\n}\n\n/** A read in flight, and what the last one returned. */\ninterface ScreenEntry {\n  /**\n   * When the last read finished, absent until one has.\n   *\n   * Absent rather than zero: zero is a real instant, and a service whose clock\n   * starts near it would answer the very first read from an empty cache and\n   * paint nothing until the interval had passed.\n   */\n  at?: number;\n  lines: string[];\n  inFlight?: Promise<string[]>;\n}\n\ninterface Lease {\n  token: string;\n  expiresAt: number;\n}\n\nconst DEFAULT_REFRESH_MS = 750;\nconst DEFAULT_LEASE_MS = 60_000;\nconst NOT_HELD = 'Another reader holds the keyboard for this run.';\n\nexport interface WorkflowTerminalService<Record> {\n  /** The run's recent screen, reusing a recent read rather than forking again. */\n  screen(identity: string, record: Record, lines: number): Promise<string[]>;\n  capabilities(record: Record): WorkflowTerminalCapabilitiesView;\n  /** Takes the keyboard, or reports who has it. Renews when the holder asks again. */\n  takeControl(identity: string, token: string): boolean;\n  releaseControl(identity: string, token: string): void;\n  /** Writes on behalf of a lease holder; throws when the lease is not theirs. */\n  write(identity: string, record: Record, token: string, data: string): Promise<void>;\n  /**\n   * Matches the run's terminal to the holder's viewport.\n   *\n   * Behind the same lease as writing: geometry is shared by everyone watching,\n   * so a passive reader must not reflow the screen under the person typing.\n   */\n  resize(identity: string, record: Record, token: string, columns: number, rows: number): Promise<boolean>;\n  /** Drops what is remembered for runs that can never change again. */\n  forget(live: ReadonlySet<string>): void;\n}\n\nexport function createWorkflowTerminalService<Record>(\n  deps: WorkflowTerminalDeps<Record>,\n): WorkflowTerminalService<Record> {\n  const refreshMs = deps.refreshMs ?? DEFAULT_REFRESH_MS;\n  const leaseMs = deps.leaseMs ?? DEFAULT_LEASE_MS;\n  const screens = new Map<string, ScreenEntry>();\n  const leases = new Map<string, Lease>();\n\n  const heldBy = (identity: string): Lease | undefined => {\n    const lease = leases.get(identity);\n    if (lease === undefined) return undefined;\n    if (lease.expiresAt > deps.now()) return lease;\n    leases.delete(identity);\n    return undefined;\n  };\n\n  return {\n    async screen(identity, record, lines) {\n      const entry = screens.get(identity) ?? { lines: [] };\n      screens.set(identity, entry);\n      if (entry.inFlight) return entry.lines;\n      if (entry.at !== undefined && deps.now() - entry.at < refreshMs) return entry.lines;\n      entry.inFlight = deps.terminal.screen(record, { lines });\n      try {\n        entry.lines = await entry.inFlight;\n      } finally {\n        // Stamped after the read, not before: the interval is a gap between\n        // reads, so a slow scrape must not immediately earn another one.\n        entry.at = deps.now();\n        entry.inFlight = undefined;\n      }\n      return entry.lines;\n    },\n    capabilities(record) {\n      return deps.terminal.capabilities(record);\n    },\n    takeControl(identity, token) {\n      const holder = heldBy(identity);\n      if (holder !== undefined && holder.token !== token) return false;\n      leases.set(identity, { token, expiresAt: deps.now() + leaseMs });\n      return true;\n    },\n    releaseControl(identity, token) {\n      if (heldBy(identity)?.token === token) leases.delete(identity);\n    },\n    async write(identity, record, token, data) {\n      const holder = heldBy(identity);\n      if (holder === undefined || holder.token !== token) throw new Error(NOT_HELD);\n      leases.set(identity, { token, expiresAt: deps.now() + leaseMs });\n      await deps.terminal.write(record, data);\n    },\n    async resize(identity, record, token, columns, rows) {\n      const holder = heldBy(identity);\n      if (holder === undefined || holder.token !== token) throw new Error(NOT_HELD);\n      return deps.terminal.resize(record, columns, rows);\n    },\n    forget(live) {\n      for (const identity of screens.keys()) {\n        if (!live.has(identity)) screens.delete(identity);\n      }\n      for (const identity of leases.keys()) {\n        if (!live.has(identity)) leases.delete(identity);\n      }\n    },\n  };\n}\n"],"mappings":";AAwDA,MAAM,qBAAqB;AAC3B,MAAM,mBAAmB;AACzB,MAAM,WAAW;AAsBjB,SAAgB,8BACd,MACiC;CACjC,MAAM,YAAY,KAAK,aAAa;CACpC,MAAM,UAAU,KAAK,WAAW;CAChC,MAAM,0BAAU,IAAI,IAAyB;CAC7C,MAAM,yBAAS,IAAI,IAAmB;CAEtC,MAAM,UAAU,aAAwC;EACtD,MAAM,QAAQ,OAAO,IAAI,QAAQ;EACjC,IAAI,UAAU,KAAA,GAAW,OAAO,KAAA;EAChC,IAAI,MAAM,YAAY,KAAK,IAAI,GAAG,OAAO;EACzC,OAAO,OAAO,QAAQ;CAExB;CAEA,OAAO;EACL,MAAM,OAAO,UAAU,QAAQ,OAAO;GACpC,MAAM,QAAQ,QAAQ,IAAI,QAAQ,KAAK,EAAE,OAAO,CAAC,EAAE;GACnD,QAAQ,IAAI,UAAU,KAAK;GAC3B,IAAI,MAAM,UAAU,OAAO,MAAM;GACjC,IAAI,MAAM,OAAO,KAAA,KAAa,KAAK,IAAI,IAAI,MAAM,KAAK,WAAW,OAAO,MAAM;GAC9E,MAAM,WAAW,KAAK,SAAS,OAAO,QAAQ,EAAE,MAAM,CAAC;GACvD,IAAI;IACF,MAAM,QAAQ,MAAM,MAAM;GAC5B,UAAU;IAGR,MAAM,KAAK,KAAK,IAAI;IACpB,MAAM,WAAW,KAAA;GACnB;GACA,OAAO,MAAM;EACf;EACA,aAAa,QAAQ;GACnB,OAAO,KAAK,SAAS,aAAa,MAAM;EAC1C;EACA,YAAY,UAAU,OAAO;GAC3B,MAAM,SAAS,OAAO,QAAQ;GAC9B,IAAI,WAAW,KAAA,KAAa,OAAO,UAAU,OAAO,OAAO;GAC3D,OAAO,IAAI,UAAU;IAAE;IAAO,WAAW,KAAK,IAAI,IAAI;GAAQ,CAAC;GAC/D,OAAO;EACT;EACA,eAAe,UAAU,OAAO;GAC9B,IAAI,OAAO,QAAQ,CAAC,EAAE,UAAU,OAAO,OAAO,OAAO,QAAQ;EAC/D;EACA,MAAM,MAAM,UAAU,QAAQ,OAAO,MAAM;GACzC,MAAM,SAAS,OAAO,QAAQ;GAC9B,IAAI,WAAW,KAAA,KAAa,OAAO,UAAU,OAAO,MAAM,IAAI,MAAM,QAAQ;GAC5E,OAAO,IAAI,UAAU;IAAE;IAAO,WAAW,KAAK,IAAI,IAAI;GAAQ,CAAC;GAC/D,MAAM,KAAK,SAAS,MAAM,QAAQ,IAAI;EACxC;EACA,MAAM,OAAO,UAAU,QAAQ,OAAO,SAAS,MAAM;GACnD,MAAM,SAAS,OAAO,QAAQ;GAC9B,IAAI,WAAW,KAAA,KAAa,OAAO,UAAU,OAAO,MAAM,IAAI,MAAM,QAAQ;GAC5E,OAAO,KAAK,SAAS,OAAO,QAAQ,SAAS,IAAI;EACnD;EACA,OAAO,MAAM;GACX,KAAK,MAAM,YAAY,QAAQ,KAAK,GAClC,IAAI,CAAC,KAAK,IAAI,QAAQ,GAAG,QAAQ,OAAO,QAAQ;GAElD,KAAK,MAAM,YAAY,OAAO,KAAK,GACjC,IAAI,CAAC,KAAK,IAAI,QAAQ,GAAG,OAAO,OAAO,QAAQ;EAEnD;CACF;AACF"}

package/dist/src/services/workflowTerminal/index.mjs

@@ -0,0 +1,69 @@
+//#region src/services/workflowTerminal/index.ts
+const DEFAULT_REFRESH_MS = 750;
+const DEFAULT_LEASE_MS = 6e4;
+const NOT_HELD = "Another reader holds the keyboard for this run.";
+function createWorkflowTerminalService(deps) {
+	const refreshMs = deps.refreshMs ?? DEFAULT_REFRESH_MS;
+	const leaseMs = deps.leaseMs ?? DEFAULT_LEASE_MS;
+	const screens = /* @__PURE__ */ new Map();
+	const leases = /* @__PURE__ */ new Map();
+	const heldBy = (identity) => {
+		const lease = leases.get(identity);
+		if (lease === void 0) return void 0;
+		if (lease.expiresAt > deps.now()) return lease;
+		leases.delete(identity);
+	};
+	return {
+		async screen(identity, record, lines) {
+			const entry = screens.get(identity) ?? { lines: [] };
+			screens.set(identity, entry);
+			if (entry.inFlight) return entry.lines;
+			if (entry.at !== void 0 && deps.now() - entry.at < refreshMs) return entry.lines;
+			entry.inFlight = deps.terminal.screen(record, { lines });
+			try {
+				entry.lines = await entry.inFlight;
+			} finally {
+				entry.at = deps.now();
+				entry.inFlight = void 0;
+			}
+			return entry.lines;
+		},
+		capabilities(record) {
+			return deps.terminal.capabilities(record);
+		},
+		takeControl(identity, token) {
+			const holder = heldBy(identity);
+			if (holder !== void 0 && holder.token !== token) return false;
+			leases.set(identity, {
+				token,
+				expiresAt: deps.now() + leaseMs
+			});
+			return true;
+		},
+		releaseControl(identity, token) {
+			if (heldBy(identity)?.token === token) leases.delete(identity);
+		},
+		async write(identity, record, token, data) {
+			const holder = heldBy(identity);
+			if (holder === void 0 || holder.token !== token) throw new Error(NOT_HELD);
+			leases.set(identity, {
+				token,
+				expiresAt: deps.now() + leaseMs
+			});
+			await deps.terminal.write(record, data);
+		},
+		async resize(identity, record, token, columns, rows) {
+			const holder = heldBy(identity);
+			if (holder === void 0 || holder.token !== token) throw new Error(NOT_HELD);
+			return deps.terminal.resize(record, columns, rows);
+		},
+		forget(live) {
+			for (const identity of screens.keys()) if (!live.has(identity)) screens.delete(identity);
+			for (const identity of leases.keys()) if (!live.has(identity)) leases.delete(identity);
+		}
+	};
+}
+//#endregion
+export { createWorkflowTerminalService };
+
+//# sourceMappingURL=index.mjs.map

package/dist/src/services/workflowTerminal/index.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.mjs","names":[],"sources":["../../../../src/services/workflowTerminal/index.ts"],"sourcesContent":["import type { WorkflowTerminalCapabilitiesView } from '../../types/webWorkflowTerminal';\n\n/**\n * One run's terminal, shared by every surface watching it.\n *\n * WHY COALESCING LIVES HERE:\n * Reading a multiplexer's screen forks a CLI, measured at roughly 75ms a call.\n * Several readers on one run (a step tab, a second browser, the session's own\n * panel) would otherwise each fork on their own timer, and a read that runs\n * long would have the next one start on top of it, unbounded. One read per run\n * at a time, no faster than the interval, however many surfaces are watching.\n *\n * WHY A CONTROL LEASE:\n * A run's terminal takes keystrokes from anyone who can reach it, so two\n * readers typing into one nested agent is a real state, not a hypothetical.\n * The lease does not make it impossible, since the session's own panel can\n * still type; it makes it visible, and keeps two cockpit tabs from fighting.\n */\n\n/** The engine's terminal facade, as this service needs it. */\nexport interface TerminalPort<Record> {\n  capabilities(record: Record): WorkflowTerminalCapabilitiesView;\n  screen(record: Record, options: { lines?: number }): Promise<string[]>;\n  write(record: Record, data: string): Promise<void>;\n  resize(record: Record, columns: number, rows: number): Promise<boolean>;\n}\n\nexport interface WorkflowTerminalDeps<Record> {\n  terminal: TerminalPort<Record>;\n  /** Injected so the cadence and the lease clock are assertable. */\n  now: () => number;\n  /** Shortest gap between two reads of one run. */\n  refreshMs?: number;\n  /** How long a keyboard lease survives without being renewed. */\n  leaseMs?: number;\n}\n\n/** A read in flight, and what the last one returned. */\ninterface ScreenEntry {\n  /**\n   * When the last read finished, absent until one has.\n   *\n   * Absent rather than zero: zero is a real instant, and a service whose clock\n   * starts near it would answer the very first read from an empty cache and\n   * paint nothing until the interval had passed.\n   */\n  at?: number;\n  lines: string[];\n  inFlight?: Promise<string[]>;\n}\n\ninterface Lease {\n  token: string;\n  expiresAt: number;\n}\n\nconst DEFAULT_REFRESH_MS = 750;\nconst DEFAULT_LEASE_MS = 60_000;\nconst NOT_HELD = 'Another reader holds the keyboard for this run.';\n\nexport interface WorkflowTerminalService<Record> {\n  /** The run's recent screen, reusing a recent read rather than forking again. */\n  screen(identity: string, record: Record, lines: number): Promise<string[]>;\n  capabilities(record: Record): WorkflowTerminalCapabilitiesView;\n  /** Takes the keyboard, or reports who has it. Renews when the holder asks again. */\n  takeControl(identity: string, token: string): boolean;\n  releaseControl(identity: string, token: string): void;\n  /** Writes on behalf of a lease holder; throws when the lease is not theirs. */\n  write(identity: string, record: Record, token: string, data: string): Promise<void>;\n  /**\n   * Matches the run's terminal to the holder's viewport.\n   *\n   * Behind the same lease as writing: geometry is shared by everyone watching,\n   * so a passive reader must not reflow the screen under the person typing.\n   */\n  resize(identity: string, record: Record, token: string, columns: number, rows: number): Promise<boolean>;\n  /** Drops what is remembered for runs that can never change again. */\n  forget(live: ReadonlySet<string>): void;\n}\n\nexport function createWorkflowTerminalService<Record>(\n  deps: WorkflowTerminalDeps<Record>,\n): WorkflowTerminalService<Record> {\n  const refreshMs = deps.refreshMs ?? DEFAULT_REFRESH_MS;\n  const leaseMs = deps.leaseMs ?? DEFAULT_LEASE_MS;\n  const screens = new Map<string, ScreenEntry>();\n  const leases = new Map<string, Lease>();\n\n  const heldBy = (identity: string): Lease | undefined => {\n    const lease = leases.get(identity);\n    if (lease === undefined) return undefined;\n    if (lease.expiresAt > deps.now()) return lease;\n    leases.delete(identity);\n    return undefined;\n  };\n\n  return {\n    async screen(identity, record, lines) {\n      const entry = screens.get(identity) ?? { lines: [] };\n      screens.set(identity, entry);\n      if (entry.inFlight) return entry.lines;\n      if (entry.at !== undefined && deps.now() - entry.at < refreshMs) return entry.lines;\n      entry.inFlight = deps.terminal.screen(record, { lines });\n      try {\n        entry.lines = await entry.inFlight;\n      } finally {\n        // Stamped after the read, not before: the interval is a gap between\n        // reads, so a slow scrape must not immediately earn another one.\n        entry.at = deps.now();\n        entry.inFlight = undefined;\n      }\n      return entry.lines;\n    },\n    capabilities(record) {\n      return deps.terminal.capabilities(record);\n    },\n    takeControl(identity, token) {\n      const holder = heldBy(identity);\n      if (holder !== undefined && holder.token !== token) return false;\n      leases.set(identity, { token, expiresAt: deps.now() + leaseMs });\n      return true;\n    },\n    releaseControl(identity, token) {\n      if (heldBy(identity)?.token === token) leases.delete(identity);\n    },\n    async write(identity, record, token, data) {\n      const holder = heldBy(identity);\n      if (holder === undefined || holder.token !== token) throw new Error(NOT_HELD);\n      leases.set(identity, { token, expiresAt: deps.now() + leaseMs });\n      await deps.terminal.write(record, data);\n    },\n    async resize(identity, record, token, columns, rows) {\n      const holder = heldBy(identity);\n      if (holder === undefined || holder.token !== token) throw new Error(NOT_HELD);\n      return deps.terminal.resize(record, columns, rows);\n    },\n    forget(live) {\n      for (const identity of screens.keys()) {\n        if (!live.has(identity)) screens.delete(identity);\n      }\n      for (const identity of leases.keys()) {\n        if (!live.has(identity)) leases.delete(identity);\n      }\n    },\n  };\n}\n"],"mappings":";AAwDA,MAAM,qBAAqB;AAC3B,MAAM,mBAAmB;AACzB,MAAM,WAAW;AAsBjB,SAAgB,8BACd,MACiC;CACjC,MAAM,YAAY,KAAK,aAAa;CACpC,MAAM,UAAU,KAAK,WAAW;CAChC,MAAM,0BAAU,IAAI,IAAyB;CAC7C,MAAM,yBAAS,IAAI,IAAmB;CAEtC,MAAM,UAAU,aAAwC;EACtD,MAAM,QAAQ,OAAO,IAAI,QAAQ;EACjC,IAAI,UAAU,KAAA,GAAW,OAAO,KAAA;EAChC,IAAI,MAAM,YAAY,KAAK,IAAI,GAAG,OAAO;EACzC,OAAO,OAAO,QAAQ;CAExB;CAEA,OAAO;EACL,MAAM,OAAO,UAAU,QAAQ,OAAO;GACpC,MAAM,QAAQ,QAAQ,IAAI,QAAQ,KAAK,EAAE,OAAO,CAAC,EAAE;GACnD,QAAQ,IAAI,UAAU,KAAK;GAC3B,IAAI,MAAM,UAAU,OAAO,MAAM;GACjC,IAAI,MAAM,OAAO,KAAA,KAAa,KAAK,IAAI,IAAI,MAAM,KAAK,WAAW,OAAO,MAAM;GAC9E,MAAM,WAAW,KAAK,SAAS,OAAO,QAAQ,EAAE,MAAM,CAAC;GACvD,IAAI;IACF,MAAM,QAAQ,MAAM,MAAM;GAC5B,UAAU;IAGR,MAAM,KAAK,KAAK,IAAI;IACpB,MAAM,WAAW,KAAA;GACnB;GACA,OAAO,MAAM;EACf;EACA,aAAa,QAAQ;GACnB,OAAO,KAAK,SAAS,aAAa,MAAM;EAC1C;EACA,YAAY,UAAU,OAAO;GAC3B,MAAM,SAAS,OAAO,QAAQ;GAC9B,IAAI,WAAW,KAAA,KAAa,OAAO,UAAU,OAAO,OAAO;GAC3D,OAAO,IAAI,UAAU;IAAE;IAAO,WAAW,KAAK,IAAI,IAAI;GAAQ,CAAC;GAC/D,OAAO;EACT;EACA,eAAe,UAAU,OAAO;GAC9B,IAAI,OAAO,QAAQ,CAAC,EAAE,UAAU,OAAO,OAAO,OAAO,QAAQ;EAC/D;EACA,MAAM,MAAM,UAAU,QAAQ,OAAO,MAAM;GACzC,MAAM,SAAS,OAAO,QAAQ;GAC9B,IAAI,WAAW,KAAA,KAAa,OAAO,UAAU,OAAO,MAAM,IAAI,MAAM,QAAQ;GAC5E,OAAO,IAAI,UAAU;IAAE;IAAO,WAAW,KAAK,IAAI,IAAI;GAAQ,CAAC;GAC/D,MAAM,KAAK,SAAS,MAAM,QAAQ,IAAI;EACxC;EACA,MAAM,OAAO,UAAU,QAAQ,OAAO,SAAS,MAAM;GACnD,MAAM,SAAS,OAAO,QAAQ;GAC9B,IAAI,WAAW,KAAA,KAAa,OAAO,UAAU,OAAO,MAAM,IAAI,MAAM,QAAQ;GAC5E,OAAO,KAAK,SAAS,OAAO,QAAQ,SAAS,IAAI;EACnD;EACA,OAAO,MAAM;GACX,KAAK,MAAM,YAAY,QAAQ,KAAK,GAClC,IAAI,CAAC,KAAK,IAAI,QAAQ,GAAG,QAAQ,OAAO,QAAQ;GAElD,KAAK,MAAM,YAAY,OAAO,KAAK,GACjC,IAAI,CAAC,KAAK,IAAI,QAAQ,GAAG,OAAO,OAAO,QAAQ;EAEnD;CACF;AACF"}