software-defence-factory 0.4.7 → 0.5.0

package/factory/definition.mjs

@@ -0,0 +1,56 @@
+import { readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { ROOT, digest, harnessOf } from './lib.mjs';
+
+// Execution order is shared with the queue; presentation cannot invent phases.
+export const WORKFLOWS = Object.freeze({
+  software: Object.freeze(['build', 'verify', 'review', 'handoff']),
+  defence: Object.freeze(['defence']),
+});
+const phaseInfo = {
+  build: { title: 'Implement', owner: 'agent', skills: ['factory-implement'], description: 'Implement the accepted scope in an isolated checkout. Produce a candidate and evidence.' },
+  verify: { title: 'Check', owner: 'factory', skills: [], description: 'Run the project check command against the candidate. A failure stops delivery.' },
+  review: { title: 'Review', owner: 'agent', skills: ['factory-review', 'factory-security'], description: 'Review the candidate and evidence in a separate agent invocation. Security review applies when required by the accepted scope.' },
+  handoff: { title: 'Accept & hand off', owner: 'operator', skills: [], description: 'Wait for operator approval, then confirm the candidate and policy still match the checks and review. Record acceptance; do not push, merge or deploy.' },
+  defence: { title: 'Investigate', owner: 'agent', skills: ['factory-security'], description: 'Investigate supplied incident evidence within the accepted scope. Produce a private draft with findings and unknowns. No production access or recovery action is granted.' },
+};
+const skillRoles = {
+  triage: 'Prepare incoming work before admission', spec: 'Define scope and acceptance before admission',
+  implement: 'Implement an accepted software task', review: 'Independently assess a candidate',
+  security: 'Assess security within the authorized scope', evaluate: 'Compare configurations in a separately scoped evaluation',
+};
+export function factoryDefinition(config) {
+  const harness = harnessOf(config);
+  const skills = Object.entries(skillRoles).map(([role, purpose]) => {
+    const id = `factory-${role}`, path = `.agents/skills/${id}/SKILL.md`;
+    const content = readFileSync(join(ROOT, path), 'utf8');
+    return { id, purpose, path, content, sha256: digest(content) };
+  });
+  const workflows = Object.fromEntries(Object.entries(WORKFLOWS).map(([name, phases]) => [name, phases.map(name => ({ name, approval: name === 'handoff' }))]));
+  return {
+    version: 1, workflows, terminology: JSON.parse(readFileSync(join(ROOT, 'factory/terminology.json'), 'utf8')),
+    agents: Object.entries(phaseInfo).filter(([, info]) => info.owner === 'agent').map(([phase, info]) => ({
+      id: phase === 'build' ? 'implement' : phase === 'defence' ? 'investigate' : phase,
+      phase, title: info.title, responsibility: info.description, harness, model: config.model || null, skills: info.skills,
+    })),
+    operator_skills: [foundationSkill()],
+    automations: { supported: false, items: [] },
+    commands: Object.entries(phaseInfo).map(([name, info]) => ({ name, ...info, prompt: info.description,
+      executor: info.owner === 'agent' ? harnessOf(config) : 'factory', timeout: `${config.timeoutSeconds}s` })),
+    skills,
+    configuration: { harness, agent: harness, // agent is a v1 compatibility alias
+      model: config.model || null, check: config.check, timeoutSeconds: config.timeoutSeconds,
+      memoryMiB: config.memoryMiB, cpus: config.cpus || 2 },
+    method: {
+      preparation: ['factory-triage', 'factory-spec'], evaluation: ['factory-evaluate'],
+      instructions: 'All six skills are available read-only to agent phases. A skill is an instruction set, not a separate agent or an automatic workflow step.',
+      customization: 'Choose the harness, model, project check and resource limits in the installation’s private factory.json while stopped, then restart. Task scope belongs in the issue or work instructions. Phase order, gates and packaged skills change through a reviewed Factory release; they are not editable prompt templates.',
+    },
+  };
+}
+
+export function foundationSkill() {
+  const path = 'operator-skills/factory-foundation/SKILL.md';
+  const content = readFileSync(join(ROOT, path), 'utf8');
+  return { id: 'factory-foundation', purpose: 'Prepare a repository and host for bounded Factory work', path, content, sha256: digest(content) };
+}

package/factory/execution-profile.mjs

@@ -1,3 +1,4 @@
+import { harnessOf } from './lib.mjs';
 import { hostname } from 'node:os';
 import { digest } from './lib.mjs';
 import { VERSION } from './updates.mjs';
@@ -6,11 +7,11 @@ import { usageFields } from './usage.mjs';
 export function withRequestedModel(configuration, requestedModel) {
   const config = structuredClone(configuration);
   if (requestedModel && requestedModel !== config.model) {
-    if (!['codex', 'pi'].includes(config.agent)) throw new Error('Task model overrides require codex or pi');
+    if (!['codex', 'pi'].includes(harnessOf(config))) throw new Error('Task model overrides require codex or pi');
     config.model = requestedModel;
     const index = config.command.indexOf('--model');
     if (index >= 0) config.command[index + 1] = requestedModel;
-    else config.command.splice(config.agent === 'codex' ? config.command.length - 1 : config.command.length, 0, '--model', requestedModel);
+    else config.command.splice(harnessOf(config) === 'codex' ? config.command.length - 1 : config.command.length, 0, '--model', requestedModel);
   }
   return config;
 }
@@ -18,15 +19,15 @@ export function withRequestedModel(configuration, requestedModel) {
 // Public facts only. The complete admitted configuration stays in private state.
 export function executionProfile(config, phase) {
   const deterministic = ['verify', 'handoff'].includes(phase);
-  const applicable = !deterministic && config.agent !== 'mock';
-  const provider = applicable && ['codex', 'pi'].includes(config.agent);
+  const applicable = !deterministic && harnessOf(config) !== 'mock';
+  const provider = applicable && ['codex', 'pi'].includes(harnessOf(config));
   const requestedModel = provider ? config.model || null : null;
   return {
-    version: 1, phase, executor: deterministic ? 'deterministic' : config.agent,
+    version: 1, phase, executor: deterministic ? 'deterministic' : harnessOf(config),
     requestedModel,
     modelSelection: !applicable ? 'not_applicable' : !provider ? 'unknown' : requestedModel ? 'explicit' : 'provider_default',
     runtimeVersion: VERSION, image: phase === 'handoff' ? null : config.image,
-    policyHash: digest(JSON.stringify(config)), workerName: hostname(),
+    policyHash: digest(JSON.stringify(config)), hostName: hostname(),
   };
 }
 
@@ -38,7 +39,8 @@ export function attemptPresentation(attempt, recoveredUsage) {
   return {
     ...attempt, executor: profile?.executor ?? 'unknown',
     ...usage,
-    model: profile?.requestedModel ?? null, worker_name: profile?.workerName ?? null,
+    model: profile?.requestedModel ?? null, host_name: profile?.hostName ?? profile?.workerName ?? null,
+    worker_name: profile?.hostName ?? profile?.workerName ?? null, // v1 presentation alias
     provenance_status: profile ? 'recorded' : attempt.started_at ? 'unknown' : 'not_started',
   };
 }

package/factory/executor.mjs

@@ -1,3 +1,4 @@
+import { harnessOf } from './lib.mjs';
 import { existsSync, mkdirSync, readFileSync, writeFileSync, rmSync, lstatSync, chmodSync, readdirSync } from 'node:fs';
 import { join } from 'node:path';
 import { spawn } from 'node:child_process';
@@ -73,7 +74,7 @@ async function container(mode, input, command, writable = false, credentials = f
   if (mode === 'verify') args.push('--env',`FACTORY_BASE_REVISION=${git('rev-parse',`${metadata().base}^{commit}`)}`);
   if (credentials) args.push('--env-file', join(state,'model.env'));
   args.push('-i',config.image,'timeout','--signal=KILL',`${config.timeoutSeconds}s`,'sh','-c','mkdir -p "$HOME" && exec "$@"','factory',...command);
-  console.log(JSON.stringify({ phase: mode, event: 'started', synthetic: config.agent === 'mock' }));
+  console.log(JSON.stringify({ phase: mode, event: 'started', synthetic: harnessOf(config) === 'mock' }));
   const logPath = join(folder, attempt, `${mode}.log`);
   const log = new BoundedLog(), usageParser = execution.executor === 'codex' ? new CodexUsageParser() : null; let exitSignal;
   const code = await new Promise((ok, fail) => {
@@ -109,7 +110,7 @@ try {
     if (existsSync(workspace)) throw new Error('Workspace already exists; preserve evidence and create a new task for a fresh build');
     run('git',['-c','core.hooksPath=/dev/null','-c','core.fsmonitor=false','clone','--no-hardlinks','--',config.repo,workspace], { env: gitEnv });
     git('remote','remove','origin');
-    save(join(folder,'candidate.json'), { base: git('rev-parse','HEAD'), head: git('rev-parse','HEAD'), synthetic: config.agent === 'mock' });
+    save(join(folder,'candidate.json'), { base: git('rev-parse','HEAD'), head: git('rev-parse','HEAD'), synthetic: harnessOf(config) === 'mock' });
   }
   if (phase === 'build') {
     const reports = await container('build', brief('Implement the requested bounded change. Save /output/agent-report.md with actual changes and remaining uncertainty.'), config.command, true, true);
@@ -155,13 +156,13 @@ try {
     save(incident.path,{...incident.entry,report:validated});candidate();
   }
   completed=true;
-  save(result,{ outcome:'complete', ...usageFields(observedUsage, execution, phase), ...(reviewVerdict ? {review_verdict:reviewVerdict} : {}), summary: phase === 'defence' ? 'Unverified private incident draft ready; recovery has not been verified.' : `${phase} complete; ${config.agent === 'mock' ? 'synthetic fixture' : 'see revision and evidence'}.` });
+  save(result,{ outcome:'complete', ...usageFields(observedUsage, execution, phase), ...(reviewVerdict ? {review_verdict:reviewVerdict} : {}), summary: phase === 'defence' ? 'Unverified private incident draft ready; recovery has not been verified.' : `${phase} complete; ${harnessOf(config) === 'mock' ? 'synthetic fixture' : 'see revision and evidence'}.` });
 } catch (error) {
   console.error(error.message);
   save(result,{outcome:'blocked', ...usageFields(observedUsage, execution, phase), ...(reviewVerdict ? {review_verdict:reviewVerdict} : {}), summary:error.message});
   process.exitCode=1;
 } finally {
-  const measurement = { job, attempt, phase, policyHash, execution, ...usageFields(observedUsage, execution, phase), completed, durationMs: Date.now()-started, requestedModel: execution.requestedModel, directCost: null, humanTime: null, synthetic: config.agent === 'mock' };
+  const measurement = { job, attempt, phase, policyHash, execution, ...usageFields(observedUsage, execution, phase), completed, durationMs: Date.now()-started, requestedModel: execution.requestedModel, directCost: null, humanTime: null, synthetic: harnessOf(config) === 'mock' };
   save(join(folder,`measurement-${attempt}.json`),measurement);save(join(output,`measurement-${attempt}.json`),measurement);
   // If cleanup cannot be confirmed, retain the lock and require explicit recovery.
   stopContainers(state,job);

package/factory/lib.mjs

@@ -26,9 +26,17 @@ export function stream(command, args, options = {}) {
 }
 export const digest = value => createHash('sha256').update(value).digest('hex');
 export const sleep = ms => new Promise(resolve => setTimeout(resolve, ms));
+export function harnessOf(config) {
+  if (config.harness !== undefined && config.agent !== undefined && config.harness !== config.agent)
+    throw new Error('harness conflicts with legacy agent; keep one harness setting');
+  const harness = config.harness ?? config.agent;
+  if (!['mock', 'codex', 'pi', 'custom'].includes(harness)) throw new Error('Unsupported harness');
+  return harness;
+}
 export function configAt(state) {
   const config = json(join(state, 'factory.json'));
-  if (config.version !== 1 || !['mock','codex','pi','custom'].includes(config.agent)) throw new Error('Unsupported configuration');
+  if (config.version !== 1) throw new Error('Unsupported configuration');
+  harnessOf(config);
   if (!Array.isArray(config.command) || !config.command.length || !config.command.every(v => typeof v === 'string' && v && !v.includes('\0'))) throw new Error('command must be an argument array');
   if (!Number.isInteger(config.port) || config.port < 1024 || config.port > 65535) throw new Error('Invalid port');
   if (!Number.isInteger(config.timeoutSeconds) || config.timeoutSeconds < 1 || config.timeoutSeconds > 7200) throw new Error('timeoutSeconds must be 1–7200');

package/factory/queue.mjs

@@ -4,7 +4,7 @@ import { join } from 'node:path';
 import { existsSync, writeFileSync, rmSync } from 'node:fs';
 import { usageFields } from './usage.mjs';
 
-import { WORKFLOWS as workflows } from './workflows.mjs';
+import { WORKFLOWS as workflows } from './definition.mjs';
 const id = prefix => prefix + '_' + randomBytes(12).toString('hex');
 const now = () => new Date().toISOString();
 export class QueueError extends Error { constructor(message, status = 409) { super(message); this.status = status; } }

package/factory/server.mjs

@@ -1,10 +1,11 @@
+import { harnessOf } from './lib.mjs';
 import http from 'node:http';
 import { randomBytes, timingSafeEqual } from 'node:crypto';
 import { existsSync, readFileSync, readdirSync, lstatSync, realpathSync } from 'node:fs';
 import { join, resolve, sep } from 'node:path';
 import { readIssue } from './issue-intake.mjs';
 import { machineInfo } from './machine.mjs';
-import { workflowDefinitions } from './workflows.mjs';
+import { factoryDefinition } from './definition.mjs';
 import { JobQueue, QueueError } from './queue.mjs';
 import { executors } from './processes.mjs';
 import { configAt, ROOT } from './lib.mjs';
@@ -32,7 +33,7 @@ export function createController(state, adapter = executors(state)) {
   const token = readFileSync(join(state, 'worker.token'), 'utf8').trim();
   const queue = new JobQueue(state, adapter);
   const projectLinks = readProjectLinks(config.repo);
-  const definitions = workflowDefinitions(config), machine = machineInfo();
+  const definitions = factoryDefinition(config), host = machineInfo();
   const server = http.createServer(async (request, response) => {
     const send = (status, value, type = 'application/json; charset=utf-8') => { response.writeHead(status, { 'Content-Type': type }); response.end(type.startsWith('application/json') ? JSON.stringify(value) : value); };
     response.setHeader('Cache-Control', 'no-store'); response.setHeader('X-Content-Type-Options', 'nosniff'); response.setHeader('Referrer-Policy', 'no-referrer');
@@ -48,8 +49,10 @@ export function createController(state, adapter = executors(state)) {
         const jobs = queue.all().map(job => ({ ...job, can_request_changes: queue.canRequestChanges(job), runs: job.runs.map(attempt => attemptPresentation({ ...attempt,
           outcome: attempt.outcome || (attempt.state === 'succeeded' ? 'complete' : undefined) }, adapter.usage?.(job, attempt))) }));
         return send(200, { version: 1, runtime_version: VERSION, maintenance: queue.maintenance, workflows: Object.keys(definitions.workflows), commands: [], triggers: [], jobs, csrf_token: csrf,
-          workers: [{ name: machine.hardware || machine.hostname, machine, instance_id: 'local-executor', repositories: ['app'], connected: !queue.closing, last_seen_at: new Date().toISOString() }],
-          repositories: ['app'], repo: config.repo, project_links: projectLinks, agent: config.agent });
+          infrastructure: { host, controller: { connected: !queue.closing }, workers: [{ id: 'local-executor', name: 'Local worker', host: host.hostname, connected: !queue.closing }] },
+          automations: [],
+          workers: [{ name: 'Local worker', machine: host, instance_id: 'local-executor', repositories: ['app'], connected: !queue.closing, last_seen_at: new Date().toISOString() }], // v1 compatibility view
+          repositories: ['app'], repo: config.repo, project_links: projectLinks, harness: harnessOf(config), agent: harnessOf(config) });
       }
       if (request.method === 'GET' && url.pathname === '/api/v1/definitions') {
         return send(200, definitions);
@@ -79,7 +82,7 @@ export function createController(state, adapter = executors(state)) {
           catch (error) { throw new QueueError(error.message, 400); }
         }
         if (url.pathname === '/api/v1/jobs') {
-          if (input.model && input.model !== config.model && !['codex','pi'].includes(config.agent)) throw new QueueError('Model overrides require a codex or pi executor', 400);
+          if (input.model && input.model !== config.model && !['codex','pi'].includes(harnessOf(config))) throw new QueueError('Model overrides require a codex or pi executor', 400);
           return send(201, queue.submit(input));
         }
         const action = url.pathname.match(/^\/api\/v1\/jobs\/(job_[a-f0-9]+)\/(approve|cancel|retry|request_changes)$/);

package/factory/terminology.json

@@ -0,0 +1,12 @@
+{
+  "host": "The machine that provides CPU, memory, storage and networking.",
+  "controller": "The service that owns one project's queue, policy, API and dashboard.",
+  "worker": "The execution process that runs isolated jobs on a host; not the host or an agent role.",
+  "harness": "The program that runs an agent, such as Codex, Pi or a custom command.",
+  "agent": "A configured work role with a responsibility and instructions, executed through a harness.",
+  "skill": "Reusable instructions available to an agent or operator; not a process or an access grant.",
+  "workflow": "The ordered agent steps, deterministic checks and approval gates for a work type.",
+  "task": "A bounded work request admitted to the controller; stored as a job with retained run attempts.",
+  "automation": "A trigger, filters and target that admits work automatically. Not yet implemented.",
+  "definition": "The effective work roles, workflows, skills and installation settings, separate from runtime records."
+}