@ran-sh/dsh-crew 0.3.8 → 0.4.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ran-sh/dsh-crew",
-  "version": "0.3.8",
+  "version": "0.4.0",
   "type": "module",
   "main": "./src/hub/entry.mjs",
   "bin": {
@@ -124,6 +124,9 @@
     ".mcp.json",
     "README.md",
     "README.*.md",
+    "docs/job-contracts.md",
+    "docs/readiness-matrix.md",
+    "docs/gpt-relay-extension.md",
     "docs/images/dsh-crew-logo.png",
     "docs/images/dsh-crew-overview.png",
     "docs/images/dsh-crew-host.png",

package/scripts/verify-official-bridge-e2e.mjs

@@ -3,7 +3,6 @@
 
 import { spawn, spawnSync } from 'node:child_process';
 import {
-  copyFileSync,
   existsSync,
   mkdirSync,
   mkdtempSync,
@@ -14,11 +13,14 @@ import {
   writeFileSync,
 } from 'node:fs';
 import { homedir, tmpdir } from 'node:os';
+import { createServer } from 'node:net';
 import { dirname, join, resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { npxInstall, npxIntegrate } from '../src/install/npx-lifecycle.mjs';
 
 const root = resolve(dirname(fileURLToPath(import.meta.url)), '..');
+const candidateVersion = JSON.parse(readFileSync(join(root, 'package.json'), 'utf8')).version;
+if (typeof candidateVersion !== 'string' || candidateVersion === '') throw new Error('candidate package version is unavailable');
 const realHome = homedir();
 const runtimeRoot = join(realHome, '.config', 'dsh-crew', 'harness', 'runtime');
 const runtimeModule = join(runtimeRoot, 'node_modules', '@deepseek-ai', 'dsh', 'lib', 'bin.js');
@@ -32,6 +34,22 @@ const profileRoot = join(officialHome, 'profiles', 'web');
 const logs = [];
 let official;
 
+async function reservePort() {
+  const server = createServer();
+  await new Promise((resolveListen, reject) => {
+    server.once('error', reject);
+    server.listen(0, '127.0.0.1', resolveListen);
+  });
+  const port = server.address().port;
+  await new Promise((resolveClose) => server.close(resolveClose));
+  return port;
+}
+
+const officialPort = await reservePort();
+const crewPort = await reservePort();
+const officialUrl = `http://127.0.0.1:${officialPort}`;
+const crewUrl = `http://127.0.0.1:${crewPort}`;
+
 function assert(condition, message) {
   if (!condition) throw new Error(message);
 }
@@ -88,10 +106,13 @@ try {
   writeFileSync(join(profileRoot, 'pnpm-workspace.yaml'), 'packages:\n  - .\n\nnodeLinker: hoisted\nautoInstallPeers: false\n');
 
   const currentConfig = join(realHome, '.config', 'dsh-crew', 'config.json');
+  let sandboxConfig = {};
   if (existsSync(currentConfig)) {
     mkdirSync(crewRoot, { recursive: true });
-    copyFileSync(currentConfig, join(crewRoot, 'config.json'));
+    sandboxConfig = JSON.parse(readFileSync(currentConfig, 'utf8'));
   }
+  mkdirSync(crewRoot, { recursive: true });
+  writeFileSync(join(crewRoot, 'config.json'), JSON.stringify({ ...sandboxConfig, hub_url: crewUrl }, null, 2));
 
   const installer = {
     installCodex: () => ({ ok: true, actions: [] }),
@@ -115,9 +136,9 @@ try {
   assert(integrated.ok, `disposable integrate failed: ${logs.join(' | ')}`);
 
   official = spawn(process.execPath, [
-    runtimeModule, '--profile', 'web', '--host', '127.0.0.1', '--port', '3080', '--no-open',
+    runtimeModule, '--profile', 'web', '--host', '127.0.0.1', '--port', String(officialPort), '--no-open',
   ], {
-    env: { ...process.env, HOME: sandbox, USERPROFILE: sandbox, DSH_HOME: officialHome },
+    env: { ...process.env, HOME: sandbox, USERPROFILE: sandbox, DSH_HOME: officialHome, DSH_CREW_BRIDGE_TARGET: crewUrl },
     stdio: ['ignore', 'pipe', 'pipe'],
     windowsHide: true,
   });
@@ -125,20 +146,20 @@ try {
   official.stdout.on('data', capture);
   official.stderr.on('data', capture);
 
-  await waitForPageMarker('http://127.0.0.1:3080/', '@ran-sh/dsh-crew-web-bridge');
-  const bridgeStatus = await (await waitFor('http://127.0.0.1:3080/_dsh/dsh-crew/bridge-status')).json();
+  await waitForPageMarker(`${officialUrl}/`, '@ran-sh/dsh-crew-web-bridge');
+  const bridgeStatus = await (await waitFor(`${officialUrl}/_dsh/dsh-crew/bridge-status`)).json();
   assert(bridgeStatus.mode === 'official-3080-isolated-3210', 'bridge status mode mismatch');
-  const proxiedRuntime = await (await waitFor('http://127.0.0.1:3080/_dsh/dsh-crew/runtime', { timeout: 45_000 })).json();
-  assert(proxiedRuntime.runtime_version === '0.3.8', 'proxied runtime version mismatch');
-  const directRuntime = await (await waitFor('http://127.0.0.1:3210/_dsh/dsh-crew/runtime')).json();
-  assert(directRuntime.runtime_version === '0.3.8', 'direct runtime version mismatch');
-  const models = await (await waitFor('http://127.0.0.1:3080/_dsh/dsh-crew/models')).json();
+  const proxiedRuntime = await (await waitFor(`${officialUrl}/_dsh/dsh-crew/runtime`, { timeout: 45_000 })).json();
+  assert(proxiedRuntime.runtime_version === candidateVersion, `proxied runtime version mismatch (${proxiedRuntime.runtime_version} != ${candidateVersion})`);
+  const directRuntime = await (await waitFor(`${crewUrl}/_dsh/dsh-crew/runtime`)).json();
+  assert(directRuntime.runtime_version === candidateVersion, `direct runtime version mismatch (${directRuntime.runtime_version} != ${candidateVersion})`);
+  const models = await (await waitFor(`${officialUrl}/_dsh/dsh-crew/models`)).json();
   assert(Array.isArray(models.providers), 'proxied model catalog missing providers');
 
   console.log(JSON.stringify({
     ok: true,
-    official_ui: 'http://127.0.0.1:3080',
-    isolated_backend: 'http://127.0.0.1:3210',
+    official_ui: officialUrl,
+    isolated_backend: crewUrl,
     runtime_version: proxiedRuntime.runtime_version,
     provider_count: models.providers.length,
     official_profile: profileRoot,

package/src/extension-contract.mjs

@@ -0,0 +1,78 @@
+// Stable extension-capability projection for GPT-first orchestrators. It
+// describes only DSH Crew and deliberately never advertises itself as a top-
+// level Executor or control plane.
+
+export const EXTENSION_CONTRACT_SCHEMA_VERSION = 1;
+
+function row(matrix, id) {
+  return Array.isArray(matrix?.rows) ? matrix.rows.find((entry) => entry?.id === id) : undefined;
+}
+
+function component(status, reasonCode, evidence = null) {
+  return { status, reason_code: reasonCode, ...(evidence ? { evidence } : {}) };
+}
+
+function workspaceComponent(workspace) {
+  if (workspace?.status === 'CONFLICT' || workspace?.status === 'READ_ONLY') {
+    return { ...component('DEGRADED', workspace.reason_code ?? `WORKSPACE_${workspace.status}`), state: workspace.status };
+  }
+  if (workspace?.status === 'UNAVAILABLE') {
+    return { ...component('UNAVAILABLE', workspace.reason_code ?? 'WORKSPACE_UNAVAILABLE'), state: 'UNAVAILABLE' };
+  }
+  if (workspace?.status === 'READY') {
+    return { ...component('READY', workspace.reason_code ?? 'WORKSPACE_READY'), state: 'READY' };
+  }
+  return workspace?.ok === true
+    ? { ...component('READY', workspace.context ? 'WORKSPACE_CONTEXT_RESOLVED' : 'WORKSPACE_CONTEXT_NOT_REQUESTED'), state: 'READY' }
+    : { ...component('UNAVAILABLE', workspace?.code ?? 'WORKSPACE_NOT_CHECKED'), state: 'UNAVAILABLE' };
+}
+
+function readinessFromRow(entry, { pass = 'READY', notRun = 'DEGRADED' } = {}) {
+  if (!entry) return component('UNAVAILABLE', 'NO_EVIDENCE');
+  if (entry.status === 'PASS') return component(pass, entry.reason_code ?? 'CHECK_PASSED');
+  if (entry.status === 'NOT_RUN' || entry.status === 'SKIP') return component(notRun, entry.reason_code ?? 'CHECK_NOT_RUN');
+  return component('UNAVAILABLE', entry.reason_code ?? 'CHECK_FAILED');
+}
+
+export function buildExtensionContract({ config = {}, readinessMatrix = {}, workspace = null, profiles = null, runtime = null } = {}) {
+  const workerEnabled = config.subagents_enabled !== false && config.worker_state !== 'disabled';
+  const reviewerEnabled = config.subagents_enabled !== false && config.review_state !== 'disabled';
+  const realModelEvidence = ['model_execution', 'deepseek_flash', 'deepseek_pro', 'opencode_go_mimo_qwen']
+    .map((id) => row(readinessMatrix, id))
+    .find((entry) => entry?.status === 'PASS');
+  const catalogEvidence = row(readinessMatrix, 'provider_catalog');
+  const modelReadiness = realModelEvidence
+    ? component('READY', realModelEvidence.reason_code ?? 'MODEL_EXECUTION_PASSED')
+    : catalogEvidence?.status === 'PASS' || catalogEvidence?.status === 'SKIP'
+      ? component('DEGRADED', 'MODEL_CATALOG_ONLY')
+      : component('UNAVAILABLE', catalogEvidence?.reason_code ?? 'NO_EVIDENCE');
+  const components = {
+    harness: readinessFromRow(row(readinessMatrix, 'hub_compatibility')),
+    model: modelReadiness,
+    workspace: workspaceComponent(workspace),
+    reviewer: reviewerEnabled
+      ? readinessFromRow(row(readinessMatrix, 'reviewer_pipeline'))
+      : component('DEGRADED', 'REVIEWER_DISABLED'),
+  };
+  const states = Object.values(components).map((entry) => entry.status);
+  const readiness = states.includes('UNAVAILABLE') ? 'UNAVAILABLE' : states.includes('DEGRADED') ? 'DEGRADED' : 'READY';
+  return {
+    schema_version: EXTENSION_CONTRACT_SCHEMA_VERSION,
+    kind: 'dsh-crew-extension',
+    runtime: runtime ?? null,
+    capabilities: {
+      'deepseek.worker': workerEnabled,
+      'deepseek.reviewer': reviewerEnabled,
+      'worktree.isolation': true,
+      'model.fallback': config.escalate_on_failure === true,
+      'job.cancel': true,
+      'job.watch': true,
+      'job.resume': false,
+      'result.evidence': true,
+      'events.canonical': true,
+      'profiles.roles': profiles?.ok === true,
+      'workspace.context': true,
+    },
+    readiness: { status: readiness, components },
+  };
+}

package/src/failure-classification.mjs

@@ -69,6 +69,11 @@ const RUNTIME_CODES = new Set([
   'GIT_ERROR',
   'WORKTREE_LOCKED',
   'WORKTREE_CREATE_FAILED',
+  'PROFILE_NOT_FOUND',
+  'PROFILE_ROLE_MISMATCH',
+  'WORKSPACE_CONTEXT_NOT_FOUND',
+  'WORKSPACE_ROOT_MISMATCH',
+  'WORKSPACE_CONTEXT_REFS_INVALID',
   'CANDIDATE_CAPTURE_FAILED',
   'ATTEMPT_INFRA_FAILURE',
   'HUB_REQUEST_FAILED',
@@ -78,13 +83,37 @@ function normalizedCode(value) {
   return typeof value === 'string' && value.trim() ? value.trim() : null;
 }
 
+function failureFamily(category, reasonCode, sourceCode) {
+  const code = sourceCode ?? reasonCode ?? '';
+  if (category === 'none') return 'NONE';
+  if (category === 'compatibility' || code.startsWith('HUB_')) return 'HARNESS';
+  if (category === 'provider' || code.startsWith('MODEL_') || code.startsWith('PROVIDER_')) return 'MODEL';
+  if (/^(WORK|GIT_|ISOLATION_|CANDIDATE_|PROFILE_)/.test(code)) return 'WORKSPACE';
+  if (String(reasonCode).startsWith('REVIEW_')) return 'REVIEW';
+  if (category === 'policy') return 'POLICY';
+  return 'JOB';
+}
+
+function failureDisposition(category, family) {
+  if (category === 'none') return 'none';
+  if (category === 'cancelled') return 'terminal';
+  if (category === 'compatibility') return 'retry';
+  if (category === 'provider') return 'fallback';
+  if (category === 'policy' || family === 'WORKSPACE' || family === 'REVIEW') return 'human';
+  if (category === 'runtime') return 'retry';
+  return 'terminal';
+}
+
 function result(category, reasonCode, { sourceCode = null, terminalReason = null } = {}) {
+  const family = failureFamily(category, reasonCode, sourceCode);
   return {
     schema_version: 1,
     category,
     reason_code: reasonCode,
     ...(sourceCode ? { source_code: sourceCode } : {}),
     ...(terminalReason ? { terminal_reason: terminalReason } : {}),
+    family,
+    disposition: failureDisposition(category, family),
   };
 }