@agilno-tech/rivet 0.1.0-alpha.0

package/src/feature/planner.js

@@ -0,0 +1,253 @@
+import { AgentContractError, immutableJson } from '../clients/contract.js';
+import { validateProjectConfiguration } from '../config/validate.js';
+import { validateWorkRequest } from '../work-request/contract.js';
+import {
+  FeatureDecompositionError,
+  createFeatureDecomposition,
+} from './decomposition-contract.js';
+import {
+  FeaturePlanError,
+  createFeaturePlan,
+  featurePlanDigest,
+} from './plan-contract.js';
+import { clientProfileFor, workerExecutionFor } from './client-profile.js';
+
+const MAX_PLANNING_ATTEMPTS = 2;
+const REPAIRABLE_PATH_VIOLATIONS = new Set(['owned-path-invalid', 'owned-path-protected', 'owned-path-duplicate']);
+
+function fail(reason) { throw new FeaturePlanError(reason); }
+
+function slug(value, fallback = 'feature') {
+  const normalized = value.normalize('NFKD').replace(/\p{M}/gu, '').toLowerCase()
+    .replace(/[^a-z0-9]+/g, '-').replace(/^-+|-+$/g, '');
+  const candidate = /^[a-z]/.test(normalized) ? normalized : `${fallback}-${normalized}`;
+  return (candidate || fallback).slice(0, 64).replace(/-+$/g, '') || fallback;
+}
+
+function uniqueNodeId(objective, used) {
+  const base = slug(objective, 'work-item');
+  let candidate = base;
+  let suffix = 2;
+  while (used.has(candidate)) {
+    const tail = `-${suffix}`;
+    candidate = `${base.slice(0, 64 - tail.length).replace(/-+$/g, '')}${tail}`;
+    suffix += 1;
+  }
+  used.add(candidate);
+  return candidate;
+}
+
+function intersect(...values) {
+  const [first = [], ...rest] = values;
+  return first.filter(value => rest.every(items => items.includes(value)));
+}
+
+function boundedBudget(...roles) {
+  return Object.freeze(Object.fromEntries(
+    ['timeMinutes', 'tokenLimit', 'costUsd', 'taskLimit']
+      .map(name => [name, Math.min(...roles.map(role => role.budget[name]))]),
+  ));
+}
+
+function roleChain(config) {
+  for (const boss of config.orchestration.roles.filter(role => role.kind === 'boss' && role.delegatesTo.includes('manager'))) {
+    for (const manager of config.orchestration.roles.filter(role => role.kind === 'manager'
+      && role.delegatesTo.includes('worker'))) {
+      const worker = config.orchestration.roles.find(role => role.kind === 'worker');
+      if (worker) return { boss, manager, worker };
+    }
+  }
+  fail('compiled-plan-invalid');
+}
+
+function requiredEvidence(config, role, { humanApproval = false } = {}) {
+  const profile = config.orchestration.completionProfiles.find(value => value.id === role.completionProfile);
+  if (!profile) fail('compiled-plan-invalid');
+  return [...new Set([...profile.requiredEvidence, ...(humanApproval ? ['human-approval'] : [])])];
+}
+
+function compileFeaturePlan({ decomposition, config, workRequest, baselineCommit, client }) {
+  if (client === 'host' && config.orchestration.roles.some(role => role.harness !== undefined)) fail('compiled-plan-invalid');
+  const { boss, manager, worker } = roleChain(config);
+  const execution = workerExecutionFor(worker);
+  const managerScopes = intersect(manager.authorityScopes, boss.authorityScopes);
+  const workerScopes = intersect(worker.authorityScopes, managerScopes);
+  if (managerScopes.length === 0 || workerScopes.length === 0) fail('compiled-plan-invalid');
+  const configuredProviders = new Set(config.providers.providers.map(provider => provider.id));
+  const providerRefs = intersect(boss.providerRefs, manager.providerRefs, worker.providerRefs)
+    .filter(provider => configuredProviders.has(provider));
+  const commandIds = config.quality.commandGates.filter(gate => gate.required).map(gate => gate.command);
+  const used = new Set(['activation', 'management', 'final-delivery']);
+  const workers = decomposition.workItems.map(item => ({
+    id: uniqueNodeId(item.objective, used),
+    parentId: 'management',
+    role: 'worker',
+    roleId: worker.id,
+    ...(execution === undefined ? {} : { execution }),
+    objective: item.objective,
+    dependencies: ['management'],
+    ownedPaths: item.ownedPaths,
+    authorityScopes: workerScopes,
+    commandIds,
+    budget: boundedBudget(boss, manager, worker),
+    requiredEvidenceTypes: requiredEvidence(config, worker),
+    acceptanceCriteria: item.acceptanceCriterionIndexes.map(criterionIndex => (
+      workRequest.acceptanceCriteria[criterionIndex - 1]
+    )),
+    status: 'proposed',
+  }));
+  for (let index = 1; index < workers.length; index += 1) {
+    workers[index].dependencies = [workers[index - 1].id];
+  }
+  const finalScopes = boss.authorityScopes.includes('verify') ? ['verify'] : [boss.authorityScopes[0]];
+  const clientProfile = clientProfileFor(client);
+  return {
+    schemaVersion: 1,
+    id: slug(workRequest.title),
+    baselineCommit,
+    workRequestDigest: workRequest.digest,
+    client,
+    ...(clientProfile === undefined ? {} : { clientProfile }),
+    providerRefs,
+    nodes: [
+      {
+        id: 'activation', role: 'boss', roleId: boss.id, objective: 'Approve the exact feature plan.',
+        dependencies: [], ownedPaths: [], authorityScopes: boss.authorityScopes, commandIds: [],
+        budget: boundedBudget(boss), requiredEvidenceTypes: requiredEvidence(config, boss, { humanApproval: true }),
+        acceptanceCriteria: [], status: 'proposed', approvalGate: 'activation',
+      },
+      {
+        id: 'management', parentId: 'activation', role: 'manager', roleId: manager.id,
+        objective: 'Coordinate implementation and verification.', dependencies: ['activation'], ownedPaths: [],
+        authorityScopes: managerScopes, commandIds: [], budget: boundedBudget(boss, manager),
+        requiredEvidenceTypes: requiredEvidence(config, manager), acceptanceCriteria: [], status: 'proposed',
+      },
+      ...workers,
+      {
+        id: 'final-delivery', parentId: 'activation', role: 'boss', roleId: boss.id,
+        objective: 'Review evidence and approve final delivery.', dependencies: workers.map(node => node.id),
+        ownedPaths: [], authorityScopes: finalScopes, commandIds,
+        budget: boundedBudget(boss), requiredEvidenceTypes: requiredEvidence(config, boss, { humanApproval: true }),
+        acceptanceCriteria: [], status: 'proposed', approvalGate: 'final-delivery',
+      },
+    ],
+  };
+}
+
+export function createHostFeaturePlan(input) {
+  try {
+    if (!input || typeof input !== 'object' || Array.isArray(input)
+      || Reflect.ownKeys(input).length !== 4
+      || !['config', 'workRequest', 'baselineCommit', 'decomposition'].every(key => Object.hasOwn(input, key))) fail();
+    validateProjectConfiguration(input.config);
+    validateWorkRequest(input.workRequest);
+    const decomposition = createFeatureDecomposition(
+      input.decomposition,
+      input.workRequest.acceptanceCriteria.length,
+    );
+    const bindings = {
+      config: input.config,
+      workRequest: input.workRequest,
+      baselineCommit: input.baselineCommit,
+      client: 'host',
+    };
+    return createFeaturePlan({
+      proposal: compileFeaturePlan({ decomposition, ...bindings }),
+      ...bindings,
+    });
+  } catch (error) {
+    if (error instanceof FeaturePlanError) throw error;
+    if (error instanceof FeatureDecompositionError) fail('decomposition-invalid');
+    fail();
+  }
+}
+
+function planningContract({ config, workRequest, baselineCommit, client }) {
+  return immutableJson({
+    schemaVersion: 1,
+    baselineCommit,
+    client,
+    workRequest,
+    policy: {
+      projectId: config.project.id,
+      defaultBranch: config.project.repository.defaultBranch,
+      branchPattern: config.project.repository.branchPattern,
+      sensitivePaths: config.project.repository.sensitivePaths ?? [],
+      commands: config.project.commands,
+      providers: config.providers.providers.map(provider => ({
+        id: provider.id, kind: provider.kind, mode: provider.mode, capabilities: provider.capabilities,
+      })),
+      roles: config.orchestration.roles.map(role => ({
+        id: role.id, kind: role.kind, delegatesTo: role.delegatesTo, providerRefs: role.providerRefs,
+        authorityScopes: role.authorityScopes, permissions: role.permissions, budget: role.budget,
+        completionProfile: role.completionProfile,
+      })),
+      approvalGates: config.orchestration.approvalGates,
+      completionProfiles: config.orchestration.completionProfiles,
+      quality: {
+        commandGates: config.quality.commandGates,
+        evidence: config.quality.evidence,
+      },
+    },
+  });
+}
+
+function parseProposal(value) {
+  if (typeof value !== 'string') return value;
+  if (Buffer.byteLength(value) > 512 * 1024) fail();
+  try { return JSON.parse(value); } catch { fail(); }
+}
+
+export function createFeaturePlanner(input) {
+  try {
+    if (!input || typeof input !== 'object' || Array.isArray(input)
+      || Reflect.ownKeys(input).length !== 1 || !Object.hasOwn(input, 'planningClient')
+      || !input.planningClient || typeof input.planningClient !== 'object'
+      || typeof input.planningClient.propose !== 'function') fail();
+  } catch (error) {
+    if (error instanceof FeaturePlanError) throw error;
+    fail();
+  }
+  const planningClient = input.planningClient;
+  return Object.freeze({
+    async propose(request) {
+      try {
+        if (!request || typeof request !== 'object' || Array.isArray(request)
+          || Reflect.ownKeys(request).length !== 4
+          || !['config', 'workRequest', 'baselineCommit', 'client'].every(key => Object.hasOwn(request, key))) fail();
+        validateProjectConfiguration(request.config);
+        validateWorkRequest(request.workRequest);
+        const contract = planningContract(request);
+        let repair;
+        // At most two read-only provider calls; never retry provider or policy failures.
+        for (let attempt = 1; attempt <= MAX_PLANNING_ATTEMPTS; attempt += 1) {
+          const payload = repair ? immutableJson({ ...contract, repair }) : contract;
+          const proposal = parseProposal(await planningClient.propose(payload));
+          let decomposition;
+          try {
+            decomposition = createFeatureDecomposition(proposal, request.workRequest.acceptanceCriteria.length);
+          } catch (error) {
+            if (error instanceof FeatureDecompositionError) fail('decomposition-invalid');
+            throw error;
+          }
+          const compiled = compileFeaturePlan({ decomposition, ...request });
+          try { return createFeaturePlan({ proposal: compiled, ...request }); }
+          catch (error) {
+            if (!(error instanceof FeaturePlanError)) throw error;
+            const violation = error.details.violation;
+            if (attempt < MAX_PLANNING_ATTEMPTS && REPAIRABLE_PATH_VIOLATIONS.has(violation)) {
+              repair = { attempt: attempt + 1, reason: violation };
+              continue;
+            }
+            throw new FeaturePlanError('compiled-plan-invalid', violation);
+          }
+        }
+      } catch (error) {
+        if (error instanceof FeaturePlanError || error instanceof AgentContractError) throw error;
+        fail();
+      }
+    },
+  });
+}
+
+export { FeaturePlanError, featurePlanDigest };

package/src/feature/run-store.js

@@ -0,0 +1,241 @@
+import { createHash } from 'node:crypto';
+
+import { immutableJson } from '../clients/contract.js';
+import { createSnapshotStore, readSnapshotWithoutLock } from '../state/snapshot-store.js';
+import { assertResolvedStatePaths } from '../state/paths.js';
+import { validateWorkRequest } from '../work-request/contract.js';
+import { featurePlanDigest, validateFeaturePlan } from './plan-contract.js';
+
+const STATUSES = new Set(['proposed', 'approved', 'running', 'blocked', 'awaiting-final-approval', 'completed', 'cancelled']);
+const TRANSITIONS = Object.freeze({
+  proposed: new Set(['approved', 'cancelled']),
+  approved: new Set(['running', 'cancelled']),
+  running: new Set(['blocked', 'awaiting-final-approval', 'completed', 'cancelled']),
+  blocked: new Set(['running', 'cancelled']),
+  'awaiting-final-approval': new Set(['completed', 'cancelled']),
+  completed: new Set(),
+  cancelled: new Set(),
+});
+const DIGEST = /^[a-f0-9]{64}$/;
+const REF = /^[a-z][a-z0-9-]{0,63}:[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$/;
+const ID = /^[a-z][a-z0-9]*(?:-[a-z0-9]+)*$/;
+const RECORD_KEYS = new Set([
+  'schemaVersion', 'runId', 'status', 'workRequest', 'featurePlan', 'proposalDigest',
+  'tracker', 'activation', 'runtimeRefs', 'evidenceRefs', 'createdAt', 'updatedAt',
+]);
+
+export class FeatureRunStoreError extends Error {
+  constructor() {
+    super('Feature run state is invalid.');
+    this.name = 'FeatureRunStoreError';
+    this.code = 'ERR_INVALID_FEATURE_RUN';
+    this.safeMessage = this.message;
+  }
+}
+
+export class FeatureRunVersionConflictError extends Error {
+  constructor() {
+    super('Feature run version conflict.');
+    this.name = 'FeatureRunVersionConflictError';
+    this.code = 'ERR_FEATURE_RUN_VERSION_CONFLICT';
+    this.safeMessage = this.message;
+  }
+}
+
+function fail() { throw new FeatureRunStoreError(); }
+
+function canonical(value) {
+  if (value === null || typeof value !== 'object') return JSON.stringify(value);
+  if (Array.isArray(value)) return `[${value.map(canonical).join(',')}]`;
+  return `{${Object.keys(value).sort().map(key => `${JSON.stringify(key)}:${canonical(value[key])}`).join(',')}}`;
+}
+
+function contentDigest(value) {
+  return createHash('sha256').update(canonical(value)).digest('hex');
+}
+
+function timestamp(value) {
+  if (typeof value !== 'string' || value.length > 64) fail();
+  let normalized;
+  try { normalized = new Date(value).toISOString(); } catch { fail(); }
+  if (normalized !== value) fail();
+  return value;
+}
+
+function exactRecord(value, keys, required = keys) {
+  if (!value || typeof value !== 'object' || Array.isArray(value)) fail();
+  const ownKeys = Reflect.ownKeys(value);
+  if (ownKeys.length > keys.size || ownKeys.some(key => typeof key !== 'string' || !keys.has(key))
+    || [...required].some(key => !ownKeys.includes(key))) fail();
+  return value;
+}
+
+function refs(value) {
+  if (!Array.isArray(value) || Object.getPrototypeOf(value) !== Array.prototype || value.length > 256
+    || value.some(ref => typeof ref !== 'string' || !REF.test(ref)) || new Set(value).size !== value.length) fail();
+  return value;
+}
+
+function tracker(value, request) {
+  if (value === null) {
+    if (request.source.kind === 'jira' || request.source.kind === 'linear') fail();
+    return null;
+  }
+  exactRecord(value, new Set(['provider', 'ticketId', 'capturedRevision', 'currentRevision', 'drifted', 'checkedAt']));
+  if (value.provider !== request.source.kind || value.ticketId !== request.source.ref
+    || value.capturedRevision !== request.source.revision || typeof value.currentRevision !== 'string'
+    || value.currentRevision.length < 1 || value.currentRevision.length > 256
+    || typeof value.drifted !== 'boolean' || value.drifted !== (value.currentRevision !== value.capturedRevision)) fail();
+  timestamp(value.checkedAt);
+  return value;
+}
+
+function activation(value, record) {
+  if (value === null) return null;
+  exactRecord(value, new Set(['approverId', 'approvedAt', 'requestDigest', 'proposalDigest']));
+  if (typeof value.approverId !== 'string' || !ID.test(value.approverId)
+    || value.requestDigest !== record.workRequest.digest || value.proposalDigest !== record.proposalDigest) fail();
+  timestamp(value.approvedAt);
+  return value;
+}
+
+function validateRecord(value, runId) {
+  exactRecord(value, RECORD_KEYS);
+  if (value.schemaVersion !== 1 || value.runId !== runId || !STATUSES.has(value.status)) fail();
+  try { validateWorkRequest(value.workRequest); } catch { fail(); }
+  if (!value.featurePlan || typeof value.featurePlan !== 'object' || Array.isArray(value.featurePlan)
+    || typeof value.proposalDigest !== 'string' || !DIGEST.test(value.proposalDigest)
+    || contentDigest(value.featurePlan) !== value.proposalDigest
+    || value.featurePlan.workRequestDigest !== value.workRequest.digest) fail();
+  tracker(value.tracker, value.workRequest);
+  activation(value.activation, value);
+  refs(value.runtimeRefs);
+  refs(value.evidenceRefs);
+  const created = timestamp(value.createdAt);
+  const updated = timestamp(value.updatedAt);
+  if (Date.parse(updated) < Date.parse(created) || value.status !== 'proposed' && value.activation === null) fail();
+  return value;
+}
+
+function hydrate(snapshot, runId) {
+  if (!snapshot || !Number.isSafeInteger(snapshot.version) || snapshot.version < 1) fail();
+  const record = immutableJson({ ...snapshot.data, version: snapshot.version });
+  const data = { ...record };
+  delete data.version;
+  validateRecord(data, runId);
+  return record;
+}
+
+function createTracker(request, at) {
+  if (request.source.kind !== 'jira' && request.source.kind !== 'linear') return null;
+  if (!request.source.revision) fail();
+  return {
+    provider: request.source.kind,
+    ticketId: request.source.ref,
+    capturedRevision: request.source.revision,
+    currentRevision: request.source.revision,
+    drifted: false,
+    checkedAt: at,
+  };
+}
+
+function mapVersionConflict(error) {
+  if (error?.code === 'ERR_STATE_VERSION_CONFLICT' || /state version conflict/i.test(error?.message ?? '')) {
+    throw new FeatureRunVersionConflictError();
+  }
+  throw error;
+}
+
+export function createFeatureRunStore(paths) {
+  assertResolvedStatePaths(paths);
+  if (typeof paths.runId !== 'string' || !ID.test(paths.runId) || paths.runDir !== paths.instanceDir) fail();
+  const snapshots = createSnapshotStore(paths, { environment: {} });
+
+  async function read() {
+    const snapshot = await snapshots.read();
+    return snapshot === null ? null : hydrate(snapshot, paths.runId);
+  }
+
+  return Object.freeze({
+    read,
+    async readOnly() {
+      const snapshot = await readSnapshotWithoutLock(paths);
+      return snapshot === null ? null : hydrate(snapshot, paths.runId);
+    },
+    async create(input) {
+      try {
+        exactRecord(input, new Set(['workRequest', 'featurePlan', 'createdAt']));
+        validateWorkRequest(input.workRequest);
+        validateFeaturePlan(input.featurePlan);
+        if (input.featurePlan.workRequestDigest !== input.workRequest.digest) fail();
+        const createdAt = timestamp(input.createdAt);
+        const record = {
+          schemaVersion: 1,
+          runId: paths.runId,
+          status: 'proposed',
+          workRequest: input.workRequest,
+          featurePlan: input.featurePlan,
+          proposalDigest: featurePlanDigest(input.featurePlan),
+          tracker: createTracker(input.workRequest, createdAt),
+          activation: null,
+          runtimeRefs: [],
+          evidenceRefs: [],
+          createdAt,
+          updatedAt: createdAt,
+        };
+        validateRecord(record, paths.runId);
+        return hydrate(await snapshots.write(record, { expectedVersion: 0 }), paths.runId);
+      } catch (error) {
+        if (error instanceof FeatureRunStoreError || error instanceof FeatureRunVersionConflictError) throw error;
+        try { mapVersionConflict(error); } catch (mapped) {
+          if (mapped instanceof FeatureRunVersionConflictError) throw mapped;
+        }
+        fail();
+      }
+    },
+    async update(input, options = {}) {
+      try {
+        const allowed = new Set(['status', 'updatedAt', 'activation', 'trackerRevision', 'runtimeRefs', 'evidenceRefs']);
+        exactRecord(input, allowed, new Set(['status', 'updatedAt', 'runtimeRefs', 'evidenceRefs']));
+        if (!Number.isSafeInteger(options.expectedVersion) || options.expectedVersion < 1) fail();
+        const current = await read();
+        if (!current || current.version !== options.expectedVersion) throw new FeatureRunVersionConflictError();
+        if (!STATUSES.has(input.status) || !TRANSITIONS[current.status].has(input.status)) fail();
+        const updatedAt = timestamp(input.updatedAt);
+        if (Date.parse(updatedAt) < Date.parse(current.updatedAt)) fail();
+        refs(input.runtimeRefs);
+        refs(input.evidenceRefs);
+        if (current.runtimeRefs.some(ref => !input.runtimeRefs.includes(ref))
+          || current.evidenceRefs.some(ref => !input.evidenceRefs.includes(ref))) fail();
+        const next = {
+          ...current,
+          status: input.status,
+          updatedAt,
+          runtimeRefs: input.runtimeRefs,
+          evidenceRefs: input.evidenceRefs,
+          activation: input.activation ?? current.activation,
+        };
+        delete next.version;
+        if (current.activation && input.activation && canonical(current.activation) !== canonical(input.activation)) fail();
+        if (input.trackerRevision !== undefined) {
+          if (!current.tracker || typeof input.trackerRevision !== 'string' || input.trackerRevision.length < 1
+            || input.trackerRevision.length > 256) fail();
+          next.tracker = {
+            ...current.tracker,
+            currentRevision: input.trackerRevision,
+            drifted: input.trackerRevision !== current.tracker.capturedRevision,
+            checkedAt: updatedAt,
+          };
+        }
+        validateRecord(next, paths.runId);
+        return hydrate(await snapshots.write(next, { expectedVersion: options.expectedVersion }), paths.runId);
+      } catch (error) {
+        if (error instanceof FeatureRunStoreError || error instanceof FeatureRunVersionConflictError) throw error;
+        try { mapVersionConflict(error); } catch (mapped) {
+          if (mapped instanceof FeatureRunVersionConflictError) throw mapped;
+        }
+        fail();
+      }
+    },
+  });
+}