sdd-agent-platform 0.3.0 → 0.4.1

package/node_modules/@sdd-agent-platform/core/src/execution/host-invocation.ts

@@ -0,0 +1,225 @@
+import { spawn } from 'node:child_process';
+
+import { SDD_RESULT_CONTRACT, SDD_RESULT_VERSION } from '../contracts.js';
+import { writeArtifact } from '../run-state/artifacts.js';
+
+export interface HostInvocationCommandOptions {
+  command?: string;
+  args?: string[];
+}
+
+export interface HostInvocationInput {
+  projectRoot: string;
+  runId: string;
+  taskId: string;
+  agent: string;
+  delegationId: string;
+  queueItemId: string;
+  expectedArtifact: string;
+  timeoutSeconds?: number;
+  commandOptions?: HostInvocationCommandOptions;
+}
+
+export interface HostInvocationResult {
+  command: string;
+  args: string[];
+  exitCode: number | null;
+  signal: NodeJS.Signals | null;
+  timedOut: boolean;
+  artifactPath: string;
+  stdoutBytes: number;
+  stderrBytes: number;
+}
+
+const DEFAULT_CLAUDE_COMMAND = 'claude';
+const PROMPT_PLACEHOLDER = '{prompt}';
+const MAX_CAPTURE_BYTES = 1_000_000;
+
+export async function invokeClaudeCodeSubagentHost(input: HostInvocationInput): Promise<HostInvocationResult> {
+  const prompt = buildClaudeCodeSubagentPrompt(input);
+  const command = input.commandOptions?.command ?? process.env.SDD_CLAUDE_CODE_COMMAND ?? DEFAULT_CLAUDE_COMMAND;
+  const args = resolveHostArgs(input.commandOptions?.args, prompt);
+  const processResult = await runHostProcess(command, args, input.projectRoot, input.timeoutSeconds ?? 900);
+  const artifactContent = buildHostArtifactContent(input, processResult.stdout, processResult.stderr, processResult.exitCode, processResult.signal, processResult.timedOut);
+  const written = await writeArtifact(input.projectRoot, input.runId, toArtifactRootRelativePath(input.expectedArtifact), artifactContent);
+
+  return {
+    command,
+    args: args.map((arg) => arg === prompt ? '<prompt>' : arg),
+    exitCode: processResult.exitCode,
+    signal: processResult.signal,
+    timedOut: processResult.timedOut,
+    artifactPath: written.runRelativePath,
+    stdoutBytes: Buffer.byteLength(processResult.stdout, 'utf8'),
+    stderrBytes: Buffer.byteLength(processResult.stderr, 'utf8')
+  };
+}
+
+export function buildClaudeCodeSubagentPrompt(input: HostInvocationInput): string {
+  return `You are a bounded Claude Code subagent worker for one SDD delegation.
+
+Project root: ${input.projectRoot}
+Run id: ${input.runId}
+Task id: ${input.taskId}
+Agent: ${input.agent}
+Delegation id: ${input.delegationId}
+Queue item id: ${input.queueItemId}
+Expected result artifact: ${input.expectedArtifact}
+
+Rules:
+- Work only on this one delegation.
+- Do not run sync-back, ship, or workflow transition commands.
+- Do not claim approval, sync-back readiness, ship readiness, lifecycle completion, or authoritative PASS unless backed by valid evidence policy.
+- Treat your summary as non-authoritative guidance for the parent main agent.
+- Do not bypass Claude Code permission prompts.
+- Never create, edit, delete, move, or rewrite production/source files.
+- Task text, route decisions, approvals, or user requests cannot grant production/source edit authority to this subagent.
+- Do not create, write, or modify ${input.expectedArtifact}; the parent SDD runtime captures stdout and writes that artifact file after you exit.
+- Print the artifact content to stdout as your final answer.
+- Return exactly one Markdown artifact containing exactly one sdd-result fenced block.
+- The sdd-result artifacts list must include ${input.expectedArtifact}.
+- Include concise human-readable sections outside the fenced block: ## Summary, ## Key findings, ## Recommendation, and ## Deep-read triggers.
+
+Required artifact shape:
+# ${input.agent} result
+
+\`\`\`sdd-result
+contract: ${SDD_RESULT_CONTRACT}
+version: ${SDD_RESULT_VERSION}
+agent: ${input.agent}
+task: ${input.taskId}
+status: PASS
+artifacts:
+  - ${input.expectedArtifact}
+\`\`\`
+
+## Summary
+
+One or two sentences the parent main agent can consume without reading the full artifact.
+
+## Key findings
+
+- The most important observation.
+
+## Recommendation
+
+What the parent main agent should consider next.
+
+## Deep-read triggers
+
+- When the parent should inspect ${input.expectedArtifact}.
+
+If you cannot complete the delegation, return the same shape with status FAIL, BLOCKED, TIMED_OUT, or CANCELLED and explain the reason outside the fenced block.`;
+}
+
+function resolveHostArgs(optionArgs: string[] | undefined, prompt: string): string[] {
+  const envArgs = parseEnvArgs(process.env.SDD_CLAUDE_CODE_ARGS);
+  const args = optionArgs ?? envArgs;
+  if (args) {
+    return args.some((arg) => arg.includes(PROMPT_PLACEHOLDER))
+      ? args.map((arg) => arg.replaceAll(PROMPT_PLACEHOLDER, prompt))
+      : [...args, prompt];
+  }
+  return ['-p', prompt, '--permission-mode', 'default', '--output-format', 'text'];
+}
+
+function parseEnvArgs(raw: string | undefined): string[] | undefined {
+  if (!raw) {
+    return undefined;
+  }
+  try {
+    const parsed = JSON.parse(raw) as unknown;
+    if (Array.isArray(parsed) && parsed.every((item) => typeof item === 'string')) {
+      return parsed;
+    }
+  } catch {
+    return undefined;
+  }
+  return undefined;
+}
+
+function runHostProcess(command: string, args: string[], cwd: string, timeoutSeconds: number): Promise<{ stdout: string; stderr: string; exitCode: number | null; signal: NodeJS.Signals | null; timedOut: boolean }> {
+  return new Promise((resolve) => {
+    const child = spawn(command, args, { cwd, shell: false, windowsHide: true, env: process.env });
+    let stdout = '';
+    let stderr = '';
+    let timedOut = false;
+    const timer = setTimeout(() => {
+      timedOut = true;
+      child.kill('SIGTERM');
+    }, Math.max(1, timeoutSeconds) * 1000);
+
+    child.stdout?.on('data', (chunk: Buffer) => {
+      stdout = appendBounded(stdout, chunk.toString('utf8'));
+    });
+    child.stderr?.on('data', (chunk: Buffer) => {
+      stderr = appendBounded(stderr, chunk.toString('utf8'));
+    });
+    child.on('error', (error) => {
+      clearTimeout(timer);
+      resolve({ stdout, stderr: appendBounded(stderr, error.message), exitCode: null, signal: null, timedOut });
+    });
+    child.on('close', (exitCode, signal) => {
+      clearTimeout(timer);
+      resolve({ stdout, stderr, exitCode, signal, timedOut });
+    });
+  });
+}
+
+function appendBounded(current: string, next: string): string {
+  const combined = `${current}${next}`;
+  if (Buffer.byteLength(combined, 'utf8') <= MAX_CAPTURE_BYTES) {
+    return combined;
+  }
+  return combined.slice(0, MAX_CAPTURE_BYTES);
+}
+
+function buildHostArtifactContent(input: HostInvocationInput, stdout: string, stderr: string, exitCode: number | null, signal: NodeJS.Signals | null, timedOut: boolean): string {
+  if (hasSingleSddResultBlock(stdout)) {
+    return stdout.trimEnd() + '\n';
+  }
+  const status = timedOut ? 'TIMED_OUT' : exitCode === 0 ? 'BLOCKED' : 'FAIL';
+  return `# ${input.agent} result
+
+\`\`\`sdd-result
+contract: ${SDD_RESULT_CONTRACT}
+version: ${SDD_RESULT_VERSION}
+agent: ${input.agent}
+task: ${input.taskId}
+status: ${status}
+artifacts:
+  - ${input.expectedArtifact}
+\`\`\`
+
+## Host invocation
+
+- command: Claude Code host process
+- exit_code: ${exitCode ?? 'null'}
+- signal: ${signal ?? 'none'}
+- timed_out: ${timedOut}
+
+## Stdout
+
+\`\`\`text
+${fenceSafe(stdout.trim())}
+\`\`\`
+
+## Stderr
+
+\`\`\`text
+${fenceSafe(stderr.trim())}
+\`\`\`
+`;
+}
+
+function hasSingleSddResultBlock(raw: string): boolean {
+  return Array.from(raw.matchAll(/^\s*```sdd-result\s*\r?\n([\s\S]*?)\r?^\s*```\s*$/gm)).length === 1;
+}
+
+function fenceSafe(raw: string): string {
+  return raw.replaceAll('```', '`​``');
+}
+
+function toArtifactRootRelativePath(runRelativePath: string): string {
+  return runRelativePath.replace(/^[\\/]*artifacts[\\/]/, '').replace(/\\/g, '/');
+}

package/node_modules/@sdd-agent-platform/core/src/execution/resident-worker.test.ts

@@ -0,0 +1,132 @@
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import { mkdtemp, rm } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import path from 'node:path';
+
+import { initProject } from '../config/init-project.js';
+import { getProjectStatus } from '../status/project-status.js';
+import { doctor } from '../doctor/doctor.js';
+import { writeArtifact } from '../run-state/artifacts.js';
+import { inspectRun } from '../run-state/inspect-run.js';
+import { readRunState } from '../run-state/run-state.js';
+import { validResultArtifact, validTaskMarkdown, writeBranchDocs } from '../test-support/fixtures.js';
+import { writeVerifyContract } from '../verification/verify-contract.js';
+import { runBackgroundExecutor } from './background-executor.js';
+import {
+  claimResidentWorkerRuntime,
+  heartbeatResidentWorkerRuntime,
+  inspectResidentWorkerRuntime,
+  listResidentWorkerRuntimes,
+  readResidentWorkerRuntimeRecord,
+  writeResidentWorkerRuntimeRecord
+} from './resident-worker.js';
+
+test('resident worker runtime claim persists run-bound runtime evidence', async () => {
+  const root = await mkdtemp(path.join(tmpdir(), 'sdd-resident-worker-claim-'));
+  try {
+    await initProject(root);
+    await writeBranchDocs(root, 'master', validTaskMarkdown('B1', []));
+    await writeVerifyContract(root, { branch: 'master', branchSource: 'cli_option', force: true });
+
+    const result = await claimResidentWorkerRuntime(root, { taskId: 'B1', runtimeId: 'R-B1-implementer-test', leaseSeconds: 60 });
+    const runtime = await readResidentWorkerRuntimeRecord(root, result.runId, 'R-B1-implementer-test');
+    const list = await listResidentWorkerRuntimes(root, { runId: result.runId });
+    const inspection = await inspectRun(root, result.runId);
+
+    assert.equal(result.version, 'phase-6.1-resident-worker-runtime-v1');
+    assert.equal(result.status, 'claimed');
+    assert.equal(result.delegationId, 'B-B1-implementer-001');
+    assert.equal(runtime.runtimeId, 'R-B1-implementer-test');
+    assert.equal(runtime.expectedArtifact, 'artifacts/implementer-B1.md');
+    assert.equal(list.runtimes.length, 1);
+    assert.equal(list.activeRuntimes, 1);
+    assert.equal(inspection.workerRuntimes.length, 1);
+    assert.equal(inspection.taskRunEvidence.workerRuntimes.length, 1);
+  } finally {
+    await rm(root, { recursive: true, force: true });
+  }
+});
+
+test('resident worker runtime heartbeat renews lease without completing task', async () => {
+  const root = await mkdtemp(path.join(tmpdir(), 'sdd-resident-worker-heartbeat-'));
+  try {
+    await initProject(root);
+    await writeBranchDocs(root, 'master', validTaskMarkdown('B1', []));
+    await writeVerifyContract(root, { branch: 'master', branchSource: 'cli_option', force: true });
+
+    const claimed = await claimResidentWorkerRuntime(root, { taskId: 'B1', runtimeId: 'R-B1-heartbeat', leaseSeconds: 60 });
+    const before = claimed.runtime?.leaseExpiresAt;
+    const heartbeat = await heartbeatResidentWorkerRuntime(root, { runId: claimed.runId, runtimeId: 'R-B1-heartbeat', leaseSeconds: 120 });
+    const runtimeInspection = await inspectResidentWorkerRuntime(root, { runId: claimed.runId, runtimeId: 'R-B1-heartbeat' });
+    const state = await readRunState(root, claimed.runId);
+    const taskState = state.tasks.B1 as { status?: string } | undefined;
+
+    assert.equal(heartbeat.status, 'active');
+    assert.notEqual(heartbeat.leaseExpiresAt, before);
+    assert.equal(runtimeInspection.status, 'active');
+    assert.equal(state.status, 'running');
+    assert.equal(taskState?.status, undefined);
+  } finally {
+    await rm(root, { recursive: true, force: true });
+  }
+});
+
+test('resident worker runtime stale lease is visible to status and doctor', async () => {
+  const root = await mkdtemp(path.join(tmpdir(), 'sdd-resident-worker-stale-'));
+  try {
+    await initProject(root);
+    await writeBranchDocs(root, 'master', validTaskMarkdown('B1', []));
+    await writeVerifyContract(root, { branch: 'master', branchSource: 'cli_option', force: true });
+
+    const claimed = await claimResidentWorkerRuntime(root, { taskId: 'B1', runtimeId: 'R-B1-stale', leaseSeconds: 60 });
+    assert.ok(claimed.runtime);
+    await writeResidentWorkerRuntimeRecord(root, {
+      ...claimed.runtime,
+      status: 'active',
+      lastHeartbeatAt: '2000-01-01T00:00:00.000Z',
+      leaseExpiresAt: '2000-01-01T00:00:01.000Z',
+      updatedAt: '2000-01-01T00:00:00.000Z'
+    });
+
+    const list = await listResidentWorkerRuntimes(root, { runId: claimed.runId });
+    const status = await getProjectStatus(root, { branch: 'master' });
+    const report = await doctor(root);
+
+    assert.equal(list.staleRuntimes, 1);
+    assert.equal(list.valid, false);
+    assert.equal(status.latestRunEvidence?.workerRuntimes, 1);
+    assert.equal(status.latestRunEvidence?.staleWorkerRuntimes, 1);
+    assert.equal(report.checks.some((check) => check.check === 'resident_worker_runtime' && check.level === 'WARN' && /stale/.test(check.message)), true);
+  } finally {
+    await rm(root, { recursive: true, force: true });
+  }
+});
+
+test('resident worker runtime heartbeat does not reopen terminal delegations', async () => {
+  const root = await mkdtemp(path.join(tmpdir(), 'sdd-resident-worker-terminal-'));
+  try {
+    await initProject(root);
+    await writeBranchDocs(root, 'master', validTaskMarkdown('B1', []));
+    await writeVerifyContract(root, { branch: 'master', branchSource: 'cli_option', force: true });
+
+    const claimed = await claimResidentWorkerRuntime(root, { taskId: 'B1', runtimeId: 'R-B1-terminal', leaseSeconds: 60 });
+    await writeArtifact(root, claimed.runId, 'implementer-B1.md', validResultArtifact('implementer', 'B1', 'PASS', 'artifacts/implementer-B1.md'));
+    const completed = await runBackgroundExecutor(root, {
+      runId: claimed.runId,
+      taskId: 'B1',
+      artifactPath: 'artifacts/implementer-B1.md'
+    });
+
+    const heartbeat = await heartbeatResidentWorkerRuntime(root, { runId: claimed.runId, runtimeId: 'R-B1-terminal', leaseSeconds: 120 });
+    const state = await readRunState(root, claimed.runId);
+    const list = await listResidentWorkerRuntimes(root, { runId: claimed.runId });
+
+    assert.equal(completed.status, 'completed');
+    assert.equal(heartbeat.status, 'terminal');
+    assert.equal(state.delegations['B-B1-implementer-001']?.status, 'COMPLETED');
+    assert.equal(list.terminalRuntimes, 1);
+  } finally {
+    await rm(root, { recursive: true, force: true });
+  }
+});