@ran-sh/dsh-crew 0.3.8 → 0.4.1

package/src/workflow-runtime.mjs

@@ -18,6 +18,7 @@ import { resolveModelPolicy, shouldAutoReview, getRoleState } from './policy.mjs
 import { buildOutcome, decideNextStep, JOB_PHASES, canTransition } from './workflow.mjs';
 import { parseDeliveryReport } from './delivery.mjs';
 import { classifyFailure } from './failure-classification.mjs';
+import { createCanonicalJobEvent } from './job-contracts.mjs';
 
 export const WORKFLOW_ERROR_CODES = {
   ISOLATION_UNAVAILABLE: 'ISOLATION_UNAVAILABLE',
@@ -111,6 +112,19 @@ export function createWorkflowRuntime(adapters, {
   const queue = [];
   let active = 0;
   let maxParallelLimit = normalizeMaxParallel(maxParallel);
+  let nestedIdFactory = null;
+
+  function nextWorkflowId() {
+    if (nestedIdFactory) return nestedIdFactory();
+    const generated = idFactory();
+    // A few embedders provide a factory-builder for deterministic tests.
+    // Normalize that legacy shape once while keeping the public id a string.
+    if (typeof generated === 'function') {
+      nestedIdFactory = generated;
+      return nestedIdFactory();
+    }
+    return generated;
+  }
 
   function log(msg) { logger?.debug?.(`workflow: ${msg}`); }
 
@@ -140,16 +154,38 @@ export function createWorkflowRuntime(adapters, {
     log(`${job.id} ${to}`);
   }
 
+  function recordCanonical(job, type, data = {}, attempt = null, at = clock()) {
+    job.canonical_event_sequence += 1;
+    job.canonical_events.push(createCanonicalJobEvent({
+      jobId: job.id,
+      type,
+      sequence: job.canonical_event_sequence,
+      at,
+      role: job.role,
+      attempt,
+      data,
+    }));
+  }
+
   function createJob(spec) {
     const now = clock();
-    return {
-      id: idFactory(),
+    const job = {
+      id: nextWorkflowId(),
+      client_job_id: spec.client_job_id ?? null,
       role: spec.role ?? 'worker',
       delivery: spec.delivery === 'review' ? 'review' : 'coding',
       model_class_hint: spec.model_class_hint === 'pro' ? 'pro' : spec.model_class_hint === 'flash' ? 'flash' : null,
       original_task: spec.task,
       source: spec.source ?? 'api',
       requested_cwd: spec.cwd,
+      requested_isolation: spec.requested_isolation ?? null,
+      workspace_branch: spec.workspace_branch ?? null,
+      timeout_seconds: spec.timeout_seconds ?? null,
+      profile_id: spec.profile_id ?? null,
+      allow_fallback: spec.allow_fallback !== false,
+      routing: spec.routing ?? 'auto',
+      review_strictness: spec.review_strictness ?? null,
+      workspace_context: spec.workspace_context ? { ...spec.workspace_context } : null,
       effort: spec.effort ?? 'max',
       phase: JOB_PHASES.CREATED,
       status: 'running',
@@ -170,12 +206,16 @@ export function createWorkflowRuntime(adapters, {
       retain_workspace: false,
       workspace_retained: false,
       events: [{ at: now, phase: JOB_PHASES.CREATED, type: 'created' }],
+      canonical_events: [],
+      canonical_event_sequence: 0,
       createdAt: now,
       startedAt: now,
       endedAt: null,
       workspaceHandle: null,
       waiters: [],
     };
+    recordCanonical(job, 'job.created', { client_job_id: job.client_job_id }, null, now);
+    return job;
   }
 
   function releaseSlot() {
@@ -227,6 +267,9 @@ export function createWorkflowRuntime(adapters, {
     job.error = err?.message ?? String(err);
     job.error_code = err?.code ?? err?.policyCode ?? job.error_code ?? null;
     job.phase = JOB_PHASES.FAILED;
+    recordCanonical(job, 'job.failed', {
+      error_code: job.error_code,
+    });
     setTerminal(job);
   }
 
@@ -259,10 +302,7 @@ export function createWorkflowRuntime(adapters, {
       config = adapters.getConfig?.() ?? {};
       const alloc = await adapters.allocateWorkspace?.(job);
       if (alloc && alloc.ok === false) {
-        job.error = alloc.error ?? alloc.reason;
-        job.phase = JOB_PHASES.FAILED;
-        if (alloc.reason) job.error_code = alloc.reason;
-        setTerminal(job);
+        failJob(job, Object.assign(new Error(alloc.error ?? alloc.reason), { code: alloc.reason }));
         return;
       }
       if (alloc && alloc.ok) {
@@ -272,12 +312,16 @@ export function createWorkflowRuntime(adapters, {
         job.base_revision = alloc.base_revision ?? null;
         job.primary_workspace_dirty = alloc.primary_workspace_dirty === true;
       }
+      recordCanonical(job, 'job.started', {
+        isolation: job.isolation,
+        base_revision: job.base_revision,
+      });
       transition(job, JOB_PHASES.RUNNING, 'start');
 
       if (isReviewJob) {
         transition(job, JOB_PHASES.REVIEWING, 'explicit reviewer');
         const before = alloc?.ok && alloc.isolation === 'worktree' ? await safeCapture(adapters, job.execution_cwd, job.base_revision) : null;
-        const reviewTask = adapters.buildReviewTask(job.original_task, null);
+        const reviewTask = adapters.buildReviewTask(job.original_task, null, { strictness: job.review_strictness ?? 'standard' });
         const review = await runReviewerAttempt(job, reviewTask, config, before);
         job.review = review;
         if (job.review) transition(job, JOB_PHASES.READY, 'review complete');
@@ -290,10 +334,20 @@ export function createWorkflowRuntime(adapters, {
       for (;;) {
         if (job.cancelling) { cancelWorkflow(job); return; }
         if (attempt > 0) transition(job, JOB_PHASES.RUNNING, `escalated attempt ${attempt}`);
-        const policy = resolveModelPolicy(config, 'worker', { attempt });
+        const resolvedPolicy = resolveModelPolicy(config, 'worker', { attempt });
+        const fallbackPolicy = job.allow_fallback === false
+          ? { ...resolvedPolicy, escalation: { ...resolvedPolicy.escalation, enabled: false } }
+          : resolvedPolicy;
+        const policy = job.routing === 'stable'
+          ? { ...fallbackPolicy, adaptive: { ...fallbackPolicy.adaptive, enabled: false } }
+          : fallbackPolicy;
         const attemptId = attemptIdFor(adapters, job.id, attempt === 0 ? '' : String(attempt));
         job.current_attempt_id = attemptId;
         job.events.push({ at: clock(), phase: job.phase, type: 'attempt/start', attempt, escalation_reason: escalationReason });
+        recordCanonical(job, 'worker.started', {
+          attempt_id: attemptId,
+          escalation_reason: escalationReason,
+        }, attempt);
         const ar = await adapters.executeAttempt({
           id: attemptId,
           workflowId: job.id,
@@ -302,6 +356,7 @@ export function createWorkflowRuntime(adapters, {
           task: job.original_task,
           cwd: job.execution_cwd,
           effort: job.effort,
+          timeout_seconds: job.timeout_seconds,
           policy,
           source: job.source,
           model_class_hint: job.model_class_hint,
@@ -314,6 +369,18 @@ export function createWorkflowRuntime(adapters, {
         if (job.cancelling) { cancelWorkflow(job); return; }
         const attemptView = attemptRecord(ar, attempt);
         job.attempts.push(attemptView);
+        recordCanonical(job, 'model.selected', {
+          provider: attemptView.provider,
+          model: attemptView.model,
+          source: attemptView.selection_source,
+          fallback_reason: attemptView.selection_trace?.fallback_reason ?? null,
+        }, attempt);
+        recordCanonical(job, 'worker.completed', {
+          attempt_id: attemptView.id,
+          status: attemptView.status,
+          stop_reason: attemptView.stopReason,
+          error_code: attemptView.error_code,
+        }, attempt);
         if (ar.infra === true) {
           failJob(job, Object.assign(new Error(ar.error ?? 'infrastructure failure'), { code: WORKFLOW_ERROR_CODES.ATTEMPT_INFRA_FAILURE }));
           return;
@@ -360,6 +427,11 @@ export function createWorkflowRuntime(adapters, {
           return;
         }
         if (decision.step === 'escalate') {
+          recordCanonical(job, 'model.fallback', {
+            reason: decision.reason,
+            from_attempt: attempt,
+            to_attempt: attempt + 1,
+          }, attempt);
           transition(job, JOB_PHASES.ESCALATING, decision.reason);
           escalationReason = decision.reason;
           attempt += 1;
@@ -368,7 +440,7 @@ export function createWorkflowRuntime(adapters, {
         if (decision.step === 'review') {
           transition(job, JOB_PHASES.REVIEWING, 'automatic review');
           const before = job.candidate;
-          const reviewTask = adapters.buildReviewTask(job.original_task, { outcome, candidate: job.candidate ?? null });
+          const reviewTask = adapters.buildReviewTask(job.original_task, { outcome, candidate: job.candidate ?? null }, { strictness: job.review_strictness ?? 'standard' });
           const review = await runReviewerAttempt(job, reviewTask, config, before, job.execution_cwd, job.base_revision);
           job.review = review;
           transition(job, JOB_PHASES.READY, decision.reason);
@@ -401,6 +473,7 @@ export function createWorkflowRuntime(adapters, {
     const attemptId = attemptIdFor(adapters, job.id, 'review');
     job.current_attempt_id = attemptId;
     job.events.push({ at: clock(), phase: job.phase, type: 'review/start' });
+    recordCanonical(job, 'review.started', { attempt_id: attemptId }, 0);
     const ar = await adapters.executeAttempt({
       id: attemptId,
       workflowId: job.id,
@@ -420,13 +493,30 @@ export function createWorkflowRuntime(adapters, {
     job.current_attempt_id = null;
     const attemptView = { ...attemptRecord(ar, 0), phase: 'review' };
     job.attempts.push(attemptView);
+    recordCanonical(job, 'model.selected', {
+      provider: attemptView.provider,
+      model: attemptView.model,
+      source: attemptView.selection_source,
+      fallback_reason: attemptView.selection_trace?.fallback_reason ?? null,
+    }, 0);
     if (ar.status === 'failed' && attemptView.error_code) job.error_code = attemptView.error_code;
     const afterCandidate = job.isolation === 'worktree' ? await safeCapture(adapters, cwd, baseRevision) : null;
-    return normalizeReview({ attemptResult: ar, beforeCandidate, afterCandidate });
+    const review = normalizeReview({ attemptResult: ar, beforeCandidate, afterCandidate });
+    recordCanonical(job, 'review.completed', {
+      attempt_id: attemptView.id,
+      status: review.status,
+      verdict: review.verdict,
+      error_code: attemptView.error_code,
+    }, 0);
+    return review;
   }
 
   function finalize(job) {
     transition(job, JOB_PHASES.COMPLETED, job.review ? 'reviewed' : 'verified');
+    recordCanonical(job, 'job.completed', {
+      reviewed: !!job.review,
+      task_status: job.outcome?.task_status ?? null,
+    });
     setTerminal(job);
   }
 
@@ -464,6 +554,7 @@ export function createWorkflowRuntime(adapters, {
     if (activeAttempt) adapters.cancelAttempt?.(activeAttempt).catch(() => {});
     job.phase = JOB_PHASES.CANCELLED;
     job.status = 'cancelled';
+    recordCanonical(job, 'job.cancelled', { active_attempt_id: activeAttempt ?? null });
     job.endedAt = clock();
     job.current_attempt_id = null;
     for (const w of job.waiters.splice(0)) w();
@@ -481,6 +572,7 @@ export function createWorkflowRuntime(adapters, {
     });
     const v = {
       id: job.id,
+      client_job_id: job.client_job_id,
       role: job.role,
       phase: job.phase,
       status: job.status,
@@ -488,6 +580,11 @@ export function createWorkflowRuntime(adapters, {
       current_model: job.attempts[job.attempts.length - 1]?.model ?? null,
       model_class_hint: job.model_class_hint,
       source: job.source,
+      profile_id: job.profile_id,
+      routing: job.routing,
+      workspace_context: job.workspace_context ? { ...job.workspace_context } : null,
+      workspace_branch: job.workspace_branch,
+      timeout_seconds: job.timeout_seconds,
       requested_cwd: job.requested_cwd,
       execution_cwd: job.execution_cwd,
       isolation: job.isolation,
@@ -505,6 +602,7 @@ export function createWorkflowRuntime(adapters, {
       decision: job.decision,
       candidate_available: !!job.candidate,
       review_status: job.review ? job.review.status ?? null : null,
+      event_cursor: job.canonical_events.at(-1)?.sequence ?? 0,
     };
     if (withResult) {
       v.child_attempts = job.attempts.map((a) => ({
@@ -520,6 +618,7 @@ export function createWorkflowRuntime(adapters, {
       v.candidate = job.candidate;
       v.review = job.review;
       v.events = job.events;
+      v.canonical_events = job.canonical_events.map((event) => ({ ...event, data: { ...event.data } }));
     }
     return v;
   }

package/src/workspace-context.mjs

@@ -0,0 +1,146 @@
+// Workspace Context carries stable project facts by reference. Instruction
+// file contents and validation output remain in the workspace and are never
+// copied into this registry or across Agent hand-offs.
+
+import { existsSync, mkdirSync, readFileSync, renameSync, rmSync, writeFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { dirname, isAbsolute, join, relative, resolve } from 'node:path';
+
+export const WORKSPACE_CONTEXT_SCHEMA_VERSION = 1;
+const ID = /^[a-z0-9][a-z0-9._-]{0,63}$/;
+
+export function isSafeBranchName(value) {
+  if (typeof value !== 'string' || value.length < 1 || value.length > 256) return false;
+  if (!/^[A-Za-z0-9][A-Za-z0-9._/-]*$/.test(value)) return false;
+  if (value.includes('..') || value.includes('@{') || value.includes('//')) return false;
+  if (value.endsWith('/') || value.endsWith('.') || value.endsWith('.lock')) return false;
+  return value.split('/').every((part) => part && !part.startsWith('.'));
+}
+
+function boundedStrings(value, { maxItems = 32, maxLength = 256 } = {}) {
+  if (value === undefined) return [];
+  if (!Array.isArray(value)) return null;
+  const result = [];
+  for (const item of value) {
+    if (typeof item !== 'string' || item.trim() === '' || item.length > maxLength) return null;
+    result.push(item.trim());
+    if (result.length > maxItems) return null;
+  }
+  return [...new Set(result)];
+}
+
+function safeReference(value) {
+  if (isAbsolute(value)) return false;
+  const normalized = value.replace(/\\/g, '/');
+  return normalized !== '..' && !normalized.startsWith('../') && !normalized.includes('/../');
+}
+
+function normalizeContext(id, raw) {
+  if (!ID.test(id) || !raw || typeof raw !== 'object' || Array.isArray(raw)) return null;
+  if (typeof raw.repo_root !== 'string' || !isAbsolute(raw.repo_root)) return null;
+  const instructionFiles = boundedStrings(raw.instruction_files);
+  const validationHints = boundedStrings(raw.validation_hints, { maxItems: 32, maxLength: 512 });
+  if (!instructionFiles || !validationHints || instructionFiles.some((entry) => !safeReference(entry))) return null;
+  if (raw.default_branch != null && !isSafeBranchName(raw.default_branch)) return null;
+  return {
+    workspace_id: id,
+    repo_root: resolve(raw.repo_root),
+    default_branch: raw.default_branch?.trim() || null,
+    instruction_files: instructionFiles,
+    validation_hints: validationHints,
+  };
+}
+
+export function workspaceContextsFile({ home = homedir() } = {}) {
+  return join(home, '.config', 'dsh-crew', 'workspaces.json');
+}
+
+export function loadWorkspaceContexts({ home = homedir(), file = workspaceContextsFile({ home }) } = {}) {
+  if (!existsSync(file)) {
+    return { schema_version: WORKSPACE_CONTEXT_SCHEMA_VERSION, ok: true, source: 'none', contexts: {}, errors: [] };
+  }
+  let raw;
+  try { raw = JSON.parse(readFileSync(file, 'utf8')); } catch {
+    return { schema_version: WORKSPACE_CONTEXT_SCHEMA_VERSION, ok: false, source: 'file', contexts: {}, errors: [{ code: 'WORKSPACE_CONTEXT_FILE_INVALID' }] };
+  }
+  return parseWorkspaceContexts(raw);
+}
+
+function parseWorkspaceContexts(raw) {
+  if (raw?.schema_version !== WORKSPACE_CONTEXT_SCHEMA_VERSION || !raw.workspaces || typeof raw.workspaces !== 'object' || Array.isArray(raw.workspaces)) {
+    return { schema_version: WORKSPACE_CONTEXT_SCHEMA_VERSION, ok: false, source: 'file', contexts: {}, errors: [{ code: 'WORKSPACE_CONTEXT_FILE_INVALID' }] };
+  }
+  const contexts = {};
+  const errors = [];
+  for (const [id, value] of Object.entries(raw.workspaces)) {
+    const context = normalizeContext(id, value);
+    if (!context) errors.push({ code: 'WORKSPACE_CONTEXT_INVALID', workspace_id: ID.test(id) ? id : '<invalid>' });
+    else contexts[id] = context;
+  }
+  return { schema_version: WORKSPACE_CONTEXT_SCHEMA_VERSION, ok: errors.length === 0, source: 'file', contexts, errors: errors.slice(0, 32) };
+}
+
+export function saveWorkspaceContexts(document, { home = homedir(), file = workspaceContextsFile({ home }) } = {}) {
+  const parsed = parseWorkspaceContexts(document);
+  if (!parsed.ok) return parsed;
+  const payload = { schema_version: WORKSPACE_CONTEXT_SCHEMA_VERSION, workspaces: parsed.contexts };
+  mkdirSync(dirname(file), { recursive: true });
+  const temp = `${file}.tmp-${process.pid}-${Date.now()}`;
+  try {
+    writeFileSync(temp, `${JSON.stringify(payload, null, 2)}\n`, { encoding: 'utf8', mode: 0o600 });
+    renameSync(temp, file);
+  } catch {
+    rmSync(temp, { force: true });
+    return { ...parsed, ok: false, errors: [{ code: 'WORKSPACE_CONTEXT_FILE_WRITE_FAILED' }], error_code: 'WORKSPACE_CONTEXT_FILE_WRITE_FAILED' };
+  }
+  return parsed;
+}
+
+function contains(root, target) {
+  const rel = relative(resolve(root), resolve(target));
+  return rel === '' || (rel !== '..' && !rel.startsWith(`..\\`) && !rel.startsWith('../') && !isAbsolute(rel));
+}
+
+export function resolveWorkspaceContext(registry, { workspace_id: workspaceId, cwd } = {}) {
+  if (!workspaceId) return { ok: true, context: null };
+  const context = registry?.contexts?.[workspaceId];
+  if (!context) return { ok: false, code: 'WORKSPACE_CONTEXT_NOT_FOUND', workspace_id: workspaceId };
+  if (cwd && !contains(context.repo_root, cwd)) {
+    return { ok: false, code: 'WORKSPACE_ROOT_MISMATCH', workspace_id: workspaceId };
+  }
+  return { ok: true, context: { ...context, instruction_files: [...context.instruction_files], validation_hints: [...context.validation_hints] } };
+}
+
+export function buildWorkspaceTask(objective, context) {
+  const task = String(objective ?? '').slice(0, 32_768);
+  if (!context) return task;
+  const lines = [
+    '[DSH Workspace Context — references only]',
+    `Workspace: ${context.workspace_id}`,
+    `Repository root: ${context.repo_root}`,
+  ];
+  if (context.default_branch) lines.push(`Default branch: ${context.default_branch}`);
+  if (context.instruction_files.length) lines.push(`Instruction references: ${context.instruction_files.join(', ')}`);
+  if (context.validation_hints.length) lines.push(`Validation hints: ${context.validation_hints.join(' | ')}`);
+  lines.push('Open referenced files in the workspace when needed; do not expect their contents in this hand-off.', '', '[Delegated objective]', task);
+  return lines.join('\n');
+}
+
+export function addContextReferences(context, references, { cwd } = {}) {
+  const refs = boundedStrings(references);
+  if (refs === null || refs.some((entry) => !safeReference(entry))) {
+    return { ok: false, code: 'WORKSPACE_CONTEXT_REFS_INVALID' };
+  }
+  if (refs.length === 0) return { ok: true, context };
+  const base = context ?? {
+    workspace_id: null,
+    repo_root: resolve(cwd ?? process.cwd()),
+    default_branch: null,
+    instruction_files: [],
+    validation_hints: [],
+  };
+  return {
+    ok: true,
+    context: { ...base, instruction_files: [...new Set([...base.instruction_files, ...refs])] },
+  };
+}

package/src/workspace-readiness.mjs

@@ -0,0 +1,32 @@
+// Read-only workspace preflight used by MCP and local HTTP readiness. It never
+// changes branches, creates worktrees, or touches user files.
+
+import { constants } from 'node:fs';
+import { access as fsAccess } from 'node:fs/promises';
+import { inspectRepository } from './workspace-isolation.mjs';
+
+export async function assessWorkspaceReadiness({ cwd, inspect = inspectRepository, access = fsAccess } = {}) {
+  if (!cwd) return { ok: true, status: 'READY', reason_code: 'WORKSPACE_NOT_REQUESTED', repo_root: null, base_revision: null };
+  const repository = await inspect({ cwd });
+  if (!repository?.ok) {
+    return { ok: false, status: 'UNAVAILABLE', reason_code: repository?.reason ?? 'WORKSPACE_UNAVAILABLE' };
+  }
+  try {
+    await access(repository.repoRoot, constants.W_OK);
+  } catch {
+    return {
+      ok: true, status: 'READ_ONLY', reason_code: 'WORKSPACE_READ_ONLY',
+      repo_root: repository.repoRoot, base_revision: repository.baseRevision,
+    };
+  }
+  if (repository.dirty === true) {
+    return {
+      ok: true, status: 'CONFLICT', reason_code: 'WORKSPACE_DIRTY',
+      repo_root: repository.repoRoot, base_revision: repository.baseRevision,
+    };
+  }
+  return {
+    ok: true, status: 'READY', reason_code: 'WORKSPACE_READY',
+    repo_root: repository.repoRoot, base_revision: repository.baseRevision,
+  };
+}