Skip to content

Self-hosted, Self-Improving, Federated Everything App — dev management, agent orchestration, persistent mind, digital twin, second brain, and creative pipeline from a single dashboard over Tailscale to port the user into the OS

9.8 KB
Raw Blame
/**
 * Orchestration profiles for CoS agent runs (issue #5992).
 *
 * A CoS task normally resolves ONE provider and ONE model for its whole run, so
 * a user who wants strong reasoning for the planning also pays that model's rate
 * for the mechanical editing. An orchestration profile splits the run into three
 * ROLES — architect (plans and writes specs), implementer (executes one spec at
 * a time), reviewer (checks the result) — each with its own provider/model, plus
 * a per-step reasoning rung the architect names in the spec it hands down.
 *
 * This module is the pure vocabulary + normalizer + spec-directive grammar. The
 * Zod surface lives in `cosValidation.js`, model selection in
 * `services/agentModelSelection.js`, and the prompt doctrine in
 * `services/promptSections/orchestrationDoctrine.js` — all of them read the
 * definitions HERE so the four cannot drift.
 *
 * Opt-in by construction: `direct` is the default mode and every accessor
 * returns null for a task that carries no profile, so an install that never
 * configures one behaves exactly as it did before.
 */

import { EFFORT_LEVELS } from './providerModels.js';
import { isPlainObject } from './objects.js';

/** Execution modes a CoS task can run under. `direct` is today's behavior. */
export const ORCHESTRATION_MODES = Object.freeze(['direct', 'orchestrated']);
export const DEFAULT_ORCHESTRATION_MODE = 'direct';

/**
 * The roles a run is split into. Ordered plan → build → check, which is also the
 * order the doctrine section renders them in.
 */
export const ORCHESTRATION_ROLES = Object.freeze(['architect', 'implementer', 'reviewer']);

/**
 * The role a `direct`-mode run — and the top-level agent of an orchestrated run
 * — is dispatched as. Naming it keeps `selectModelForTask`'s delegation honest:
 * with no profile the architect assignment is empty and selection is unchanged.
 */
export const PRIMARY_ORCHESTRATION_ROLE = 'architect';

/**
 * Starter orchestration profiles shipped by default. Each configures distinct
 * reasoning effort per role while leaving provider and model selection to the
 * install/task defaults. User-defined profiles can override or extend these.
 */
export const BUILT_IN_ORCHESTRATION_PROFILES = Object.freeze([
  Object.freeze({
    id: 'heavy-planner',
    name: 'Heavy Planning / Lean Execution',
    description: 'High reasoning effort for the architect pass, standard effort for implementer and reviewer.',
    profile: Object.freeze({
      architect: Object.freeze({ effort: 'high' }),
      implementer: Object.freeze({ effort: 'low' }),
      reviewer: Object.freeze({ effort: 'medium' }),
    }),
    isBuiltin: true,
  }),
  Object.freeze({
    id: 'max-deliberation',
    name: 'Max Deliberation',
    description: 'Maximum reasoning effort across all roles for complex architectural tasks.',
    profile: Object.freeze({
      architect: Object.freeze({ effort: 'max' }),
      implementer: Object.freeze({ effort: 'high' }),
      reviewer: Object.freeze({ effort: 'high' }),
    }),
    isBuiltin: true,
  }),
]);

const MAX_PROVIDER_ID_LENGTH = 120;
const MAX_MODEL_ID_LENGTH = 300;

/**
 * The six parts every delegated unit of work must carry. A delegated lane shares
 * NONE of the architect's context — it sees only the spec — so a spec missing
 * any of these is a lane that has to guess. Rendered into the doctrine section
 * so the architect prompt and any later spec check read one definition.
 */
export const SPEC_PARTS = Object.freeze([
  Object.freeze({ key: 'objective', label: 'OBJECTIVE', description: 'the single outcome this unit delivers, stated so it can be judged done or not' }),
  Object.freeze({ key: 'files', label: 'FILES', description: 'every path the unit may read or write, absolute or repo-relative' }),
  Object.freeze({ key: 'interfaces', label: 'INTERFACES', description: 'the exact signatures, schemas, and event names it must produce or consume' }),
  Object.freeze({ key: 'constraints', label: 'CONSTRAINTS', description: 'what it must not touch, plus the conventions it inherits' }),
  Object.freeze({ key: 'verification', label: 'VERIFICATION', description: 'one runnable command that proves the unit landed' }),
  Object.freeze({ key: 'reasoning', label: 'REASONING', description: `the effort rung for this step — one of ${EFFORT_LEVELS.join(', ')}` }),
]);

/** Directive line the architect writes to pin one step's reasoning effort. */
export const REASONING_DIRECTIVE_LABEL = 'REASONING';

const trimmedString = (value, maxLength) => {
  if (typeof value !== 'string') return null;
  const trimmed = value.trim();
  if (!trimmed || trimmed.length > maxLength) return null;
  return trimmed;
};

/**
 * Normalize ONE role's assignment. Every field is optional — a role that pins
 * only a model inherits the run's provider, and a role that pins nothing at all
 * normalizes away entirely (null) rather than persisting an empty object that
 * would read as a configured-but-blank override.
 */
function normalizeRoleAssignment(raw) {
  if (!isPlainObject(raw)) return null;
  const provider = trimmedString(raw.provider, MAX_PROVIDER_ID_LENGTH);
  const model = trimmedString(raw.model, MAX_MODEL_ID_LENGTH);
  const effort = EFFORT_LEVELS.includes(raw.effort) ? raw.effort : null;
  if (!provider && !model && !effort) return null;
  return Object.freeze({
    ...(provider ? { provider } : {}),
    ...(model ? { model } : {}),
    ...(effort ? { effort } : {}),
  });
}

/**
 * Normalize a whole profile to the persisted shape, or null when nothing usable
 * survives. Unknown roles are dropped rather than carried: the role vocabulary
 * is what the prompt doctrine and model selection can actually act on, so a typo
 * must not persist as a silently-inert assignment.
 */
export function normalizeOrchestrationProfile(raw) {
  if (!isPlainObject(raw)) return null;
  const profile = {};
  for (const role of ORCHESTRATION_ROLES) {
    const assignment = normalizeRoleAssignment(raw[role]);
    if (assignment) profile[role] = assignment;
  }
  return Object.keys(profile).length > 0 ? Object.freeze(profile) : null;
}

/** Normalize a mode string, falling back to `direct` for anything unrecognized. */
export function normalizeOrchestrationMode(raw) {
  return ORCHESTRATION_MODES.includes(raw) ? raw : DEFAULT_ORCHESTRATION_MODE;
}

/**
 * Is this task running under the orchestrated contract? Requires BOTH the mode
 * flag and a usable profile — an orchestrated task with no role assignments has
 * nothing to delegate differently, and telling its agent to emit specs for lanes
 * that all resolve to the same model buys context loss for nothing.
 */
export function isOrchestratedTask(task) {
  return normalizeOrchestrationMode(task?.metadata?.orchestrationMode) === 'orchestrated'
    && normalizeOrchestrationProfile(task?.metadata?.orchestrationProfile) !== null;
}

/**
 * The assignment for one role on a task, or null. Returns null for every role
 * on a `direct`-mode task, so callers do not need to check the mode themselves
 * — this is the single gate that keeps a stored-but-disabled profile inert.
 */
export function roleAssignment(task, role) {
  if (!ORCHESTRATION_ROLES.includes(role)) return null;
  if (!isOrchestratedTask(task)) return null;
  return normalizeOrchestrationProfile(task?.metadata?.orchestrationProfile)?.[role] ?? null;
}

/**
 * Parse a `REASONING: <rung>` directive out of spec text.
 *
 * NEVER rounds. An unsupported rung is an error, not a downgrade: the whole
 * point of a per-step rung is that the architect chose it deliberately, and
 * silently substituting the nearest supported level would run the step at an
 * effort nobody asked for while reporting success. Callers decide whether to
 * reject the spec or surface the error; this only refuses to guess.
 *
 * @param {string} text - spec text (a full spec or a single directive line)
 * @returns {{ rung: string }|{ error: string }|null} null when no directive is present
 */
export function parseReasoningDirective(text) {
  if (typeof text !== 'string') return null;
  const match = text.match(new RegExp(`^\\s*${REASONING_DIRECTIVE_LABEL}\\s*:\\s*(\\S+)\\s*$`, 'mi'));
  if (!match) return null;
  const rung = match[1];
  if (!EFFORT_LEVELS.includes(rung)) {
    return { error: `Unsupported reasoning rung "${rung}" — expected one of ${EFFORT_LEVELS.join(', ')}` };
  }
  return { rung };
}

/**
 * Resolve the reasoning effort for ONE DELEGATED STEP of an orchestrated run
 * (#5992), rather than one effort for the whole run.
 *
 * Precedence: the `REASONING: <rung>` directive the architect wrote into this
 * step's spec → the role's configured default from the orchestration profile →
 * the run-level effort already resolved for the task.
 *
 * NEVER rounds. An unsupported rung returns `{ error }` so the caller can refuse
 * the spec: silently substituting the nearest supported level would run the step
 * at an effort nobody chose while still reporting success — and the architect
 * naming a rung deliberately is the entire point of the per-step contract.
 *
 * @param {object} options
 * @param {string} [options.spec] - the delegated step's spec text
 * @param {object} [options.task] - the task carrying the orchestration profile
 * @param {string} [options.role] - the role executing this step
 * @param {string|null} [options.runEffort] - the run-level effort already resolved
 * @returns {{ effort: string|null, source: string }|{ error: string }}
 */
export function resolveStepEffort({ spec = '', task = null, role = PRIMARY_ORCHESTRATION_ROLE, runEffort = null } = {}) {
  const directive = parseReasoningDirective(spec);
  if (directive?.error) return { error: directive.error };
  if (directive?.rung) return { effort: directive.rung, source: 'spec' };

  const roleDefault = roleAssignment(task, role)?.effort;
  if (roleDefault) return { effort: roleDefault, source: 'role' };

  return { effort: runEffort || null, source: runEffort ? 'run' : 'default' };
}