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

15.9 KB
Raw Blame
// Creative Tool Registry + gated dispatch (#2183, CDO Phase 1).
//
// A single registry of creative-suite tools an orchestrating agent (the future
// Creative Director orchestrator, epic #2182) can call, plus the ONE dispatch
// chokepoint that makes autonomous use governable. Follows the voice-tools shape
// (server/services/voice/tools.js: {name, description, parameters, execute} +
// import-time integrity guards + a single dispatch fn) and the palette hydration
// pattern (server/routes/palette.js: reference existing schemas via
// getToolMetadata(), don't duplicate).
//
// Conductor, not re-implementation: every tool wraps an EXISTING service entry
// point (createUniverse, generateStep, startSeriesAutopilot, enqueueJob, …). The
// tools themselves stay UNGUARDED — direct user actions through the existing
// routes behave exactly as before. The gate lives ONLY here in
// dispatchCreativeTool: it enforces the `creative` autonomy mode, charges the
// daily action budget for llm/render tools, and appends to the calling project's
// run ledger. This is the governance point the AI Provider Usage Policy requires
// for autonomous creative work (the audit found only Series Autopilot and
// Writers-Room live mode self-gate today).

import { getCreativeAutonomyMode } from '../../lib/domainAutonomy.js';
import { getToolMetadata, getToolSpecs as getVoiceToolSpecs } from '../voice/tools.js';
import { loadState } from '../cosState.js';
import { getDomainBudgetStatus, recordDomainUsage } from '../domainUsage.js';
import { appendCreativeLedgerEntry, argsDigest } from './creativeRunLedger.js';
import { COST_CLASSES, BUDGETED_COST_CLASSES } from './tools/shared.js';
import { UNIVERSE_TOOLS } from './tools/universe.js';
import { STORY_BUILDER_TOOLS } from './tools/storyBuilder.js';
import { WRITERS_ROOM_TOOLS } from './tools/writersRoom.js';
import { PIPELINE_TOOLS } from './tools/pipeline.js';
import { MEDIA_TOOLS } from './tools/media.js';
import { CATALOG_TOOLS } from './tools/catalog.js';
import { CD_TOOLS } from './tools/cd.js';

// The daily action budget the creative gate charges against. Creative
// orchestration mirrors the cos autonomy posture (see getCreativeAutonomyMode),
// so it also shares the cos daily budget/usage ledger rather than introducing a
// parallel one — a single autonomous-work budget. A dedicated `creative` budget
// (and its settings UI) can arrive with CDO Phase 4.
const BUDGET_DOMAIN = 'cos';

// The registry. Order isn't load-bearing (consumers resolve by name).
export const CREATIVE_TOOLS = [
  ...UNIVERSE_TOOLS,
  ...STORY_BUILDER_TOOLS,
  ...WRITERS_ROOM_TOOLS,
  ...PIPELINE_TOOLS,
  ...MEDIA_TOOLS,
  ...CATALOG_TOOLS,
  ...CD_TOOLS,
];

const COST_SET = new Set(COST_CLASSES);

// OpenAI/compatible function-calling APIs only accept names matching this
// pattern — a dotted `domain.action` name would make the model request 400
// before the orchestrator could dispatch. Enforce it at load so a new tool
// can't reintroduce an unsafe name.
const SAFE_TOOL_NAME_RE = /^[a-zA-Z0-9_-]{1,64}$/;

/**
 * Fail-fast integrity check (navManifest / voice-tools precedent): every tool
 * must carry a unique name, a Zod schema, an execute fn, and a valid cost class;
 * a `hydrateFrom` must reference a real voice tool. Throws on the first offender.
 * Pure + exported so the guard is unit-tested directly against bad inputs, and
 * called at module load so a bad tool blocks boot loudly.
 *
 * @param {Array<object>} tools
 * @param {(id: string) => object|null} [resolveMeta] - voice metadata resolver
 */
export function assertCreativeToolIntegrity(tools, resolveMeta = getToolMetadata) {
  const seen = new Set();
  for (const t of tools) {
    if (!t || typeof t.name !== 'string' || !t.name) {
      throw new Error('creative tools: a tool is missing its name');
    }
    if (!SAFE_TOOL_NAME_RE.test(t.name)) {
      throw new Error(`creative tools: "${t.name}" is not a function-calling-safe name (letters/digits/_/-, ≤64 chars)`);
    }
    if (seen.has(t.name)) {
      throw new Error(`creative tools: duplicate tool name "${t.name}"`);
    }
    seen.add(t.name);
    if (typeof t.execute !== 'function') {
      throw new Error(`creative tools: "${t.name}" is missing execute()`);
    }
    if (!t.schema || typeof t.schema.parse !== 'function') {
      throw new Error(`creative tools: "${t.name}" is missing a Zod schema`);
    }
    if (!COST_SET.has(t.costClass)) {
      throw new Error(`creative tools: "${t.name}" has invalid costClass "${t.costClass}"`);
    }
    if (t.hydrateFrom && !resolveMeta(t.hydrateFrom)) {
      throw new Error(`creative tools: "${t.name}" hydrateFrom "${t.hydrateFrom}" is not a known voice tool`);
    }
  }
}

assertCreativeToolIntegrity(CREATIVE_TOOLS);

const byName = new Map(CREATIVE_TOOLS.map((t) => [t.name, t]));

// Resolve a tool's advertised description + parameters. When a tool declares
// `hydrateFrom`, pull them from the voice tool's fully-RESOLVED spec of that name
// (single source of schemas — the palette pattern) instead of the tool's own
// authored fallback. It reads the resolved `getToolSpecs()` output rather than
// the static `getToolMetadata()` so any spec-build-time widening survives — e.g.
// `catalog_lookup` widens its `type` enum to the user's active custom catalog
// types, which the static metadata doesn't carry; hydrating from the metadata
// would advertise only the built-in types to the orchestrator.
function resolveDisplay(t) {
  if (t.hydrateFrom) {
    const spec = getVoiceToolSpecs().find((s) => s.function?.name === t.hydrateFrom);
    if (spec) return { description: spec.function.description, parameters: spec.function.parameters };
  }
  return { description: t.description, parameters: t.parameters };
}

const toSpec = (t) => {
  const { description, parameters } = resolveDisplay(t);
  return { type: 'function', function: { name: t.name, description, parameters } };
};

/**
 * OpenAI-function-style specs for the registry, suitable for inclusion in a CoS
 * agent prompt. Destructive tools (delete/overwrite) are excluded by default so
 * an orchestrator prompt can't casually invoke them; pass `includeDestructive`
 * to surface them for an explicitly-approved flow.
 *
 * @param {{includeDestructive?: boolean}} [opts]
 */
// Pure (exported for the destructive-exclusion test): the tools that belong in
// the default spec set. Destructive tools are dropped unless explicitly included.
export const filterDestructive = (tools, includeDestructive) =>
  tools.filter((t) => includeDestructive || !t.destructive);

// A commission has already chosen its output type in the UI. Give its planner
// only the tools capable of producing that output, instead of asking the LLM to
// rediscover the choice from prose while staring at the entire creative suite.
// Hand-created/general Creative Director projects have no targetAbility and
// retain the full registry.
const ABILITY_TOOL_NAMES = Object.freeze({
  video: new Set(['media_enqueueVideoJob']),
  image: new Set(['media_enqueueImageJob']),
  music: new Set(['media_enqueueAudioJob']),
  'music-video': new Set(['media_enqueueAudioJob', 'media_enqueueImageJob', 'media_enqueueVideoJob']),
});

export const filterForTargetAbility = (tools, targetAbility) => {
  return tools.filter((tool) => isToolAllowedForTargetAbility(tool.name, targetAbility));
};

export function isToolAllowedForTargetAbility(toolName, targetAbility) {
  if (!targetAbility) return true;
  if (targetAbility === 'series') {
    return toolName.startsWith('pipeline_') || toolName.startsWith('universe_');
  }
  const allowed = ABILITY_TOOL_NAMES[targetAbility];
  return allowed ? allowed.has(toolName) : true;
}

/**
 * Validate the production shape selected by the commission form. Tool schemas
 * still validate each step's args at dispatch; this guard locks the output lane
 * and requested artifact count before any autonomous work starts.
 */
export function getCommissionPlanError(plan, directive) {
  const targetAbility = directive?.constraints?.targetAbility;
  if (!targetAbility) return null;
  const steps = Array.isArray(plan?.steps) ? plan.steps : [];
  const disallowed = steps.find((step) => !isToolAllowedForTargetAbility(step.toolName, targetAbility));
  if (disallowed) {
    return `Tool "${disallowed.toolName}" is not allowed for commission type ${targetAbility}`;
  }
  const count = (name) => steps.filter((step) => step.toolName === name && step.status !== 'skipped').length;
  const requiredCounts = {
    video: [['media_enqueueVideoJob', 1]],
    image: [['media_enqueueImageJob', Number(directive.constraints.generation?.imageCount) || 1]],
    music: [['media_enqueueAudioJob', 1]],
    'music-video': [['media_enqueueAudioJob', 1], ['media_enqueueVideoJob', 1]],
  }[targetAbility] || [];
  for (const [toolName, expected] of requiredCounts) {
    const actual = count(toolName);
    if (actual !== expected) {
      return `${targetAbility} commission requires exactly ${expected} ${toolName} step${expected === 1 ? '' : 's'}; received ${actual}`;
    }
  }
  return null;
}

export const getToolSpecs = ({ includeDestructive = false, targetAbility = null } = {}) =>
  filterForTargetAbility(filterDestructive(CREATIVE_TOOLS, includeDestructive), targetAbility).map(toSpec);

export const getAllCreativeToolNames = () => CREATIVE_TOOLS.map((t) => t.name);

/**
 * Plain metadata for EVERY registered tool (id, description, costClass,
 * longRunning, destructive) — the plan-board / directive-composer consumers
 * (CDO Phase 4) hydrate cost-class badges + approval affordances from this
 * without pulling the LLM-shaped `getToolSpecs()`. Destructive tools ARE
 * included here (unlike the default spec set) so a hand-authored or bridged plan
 * step naming one still renders with its real cost/approval flags.
 */
export const getAllCreativeToolMetadata = () => CREATIVE_TOOLS.map((t) => getCreativeToolMetadata(t.name));

/**
 * Plain metadata for one tool (for non-LLM consumers, e.g. a plan board or the
 * command palette). Shape-independent from getToolSpecs.
 *
 * @param {string} name
 */
export const getCreativeToolMetadata = (name) => {
  const t = byName.get(name);
  if (!t) return null;
  const { description, parameters } = resolveDisplay(t);
  return {
    id: t.name,
    description,
    parameters,
    costClass: t.costClass,
    longRunning: Boolean(t.longRunning),
    destructive: Boolean(t.destructive),
  };
};

// Best-effort audit append — a ledger write failure must never break the tool
// run. Injected `ctx.appendLedger` wins (Phase 2 will route entries onto the CD
// project record); otherwise a project-scoped file ledger is used when a
// projectId is present. A project-less dispatch simply isn't audited.
async function recordLedger(ctx, entry) {
  try {
    if (typeof ctx?.appendLedger === 'function') {
      await ctx.appendLedger(entry);
      return;
    }
    if (ctx?.projectId) {
      await appendCreativeLedgerEntry(ctx.projectId, entry);
    }
  } catch (err) {
    console.error(`❌ creative ledger append failed for ${entry.tool}: ${err.message}`);
  }
}

/**
 * The single governed dispatch chokepoint for orchestrator tool calls.
 *
 * Flow: validate args (Zod) → resolve the `creative` autonomy mode → gate →
 * (execute mode only) charge budget for llm/render → run → append to the run
 * ledger. Modes:
 *   - `off`      → reject without executing or charging.
 *   - `dry-run`  → return a plan frame describing what WOULD run; no side effects.
 *   - `execute`  → charge budget (llm/render) then run the wrapped entry point.
 *
 * @param {string} name - registered tool name
 * @param {object} args - tool arguments (validated against the tool's schema)
 * @param {{projectId?: string, appendLedger?: Function, [k: string]: unknown}} ctx
 * @returns {Promise<object>}
 */
export async function dispatchCreativeTool(name, args = {}, ctx = {}) {
  const tool = byName.get(name);
  if (!tool) throw new Error(`Unknown creative tool: ${name}`);
  if (!isToolAllowedForTargetAbility(name, ctx.targetAbility)) {
    throw new Error(`Creative tool "${name}" is not allowed for commission type ${ctx.targetAbility}`);
  }

  // Validate up front — a Zod parse failure throws before any gating/side effect.
  const parsed = tool.schema.parse(args ?? {});

  const state = await loadState().catch(() => ({ config: {} }));
  const mode = getCreativeAutonomyMode(state.config);
  const base = { tool: name, argsDigest: argsDigest(parsed), costClass: tool.costClass, mode };

  if (mode === 'off') {
    console.log(`🚫 creative dispatch ${name} rejected (creative autonomy: off)`);
    await recordLedger(ctx, { ...base, outcome: 'rejected', timingMs: 0 });
    return { ok: false, rejected: true, reason: 'autonomy-off', mode, tool: name };
  }

  if (mode === 'dry-run') {
    console.log(`📝 creative dispatch ${name} planned (dry-run)`);
    await recordLedger(ctx, { ...base, outcome: 'planned', timingMs: 0 });
    return {
      ok: true,
      planned: true,
      mode,
      tool: name,
      costClass: tool.costClass,
      longRunning: Boolean(tool.longRunning),
      destructive: Boolean(tool.destructive),
      args: parsed,
    };
  }

  // execute mode — charge the daily action budget for llm/render tools first,
  // EXCEPT self-budgeting tools: a long-running coordinator (Series Autopilot)
  // budget-gates and records each of its own LLM/render steps against the same
  // cos budget internally, so charging one action here would double-count and,
  // under a tight cap, consume the last action before the run does any work.
  let charged = false;
  if (BUDGETED_COST_CLASSES.has(tool.costClass) && !tool.selfBudgeted) {
    const status = await getDomainBudgetStatus(BUDGET_DOMAIN);
    if (!status.withinBudget) {
      console.warn(`⛔ creative dispatch ${name} over budget (${BUDGET_DOMAIN} ${status.exceeded})`);
      await recordLedger(ctx, { ...base, outcome: 'budget-exceeded', timingMs: 0, exceeded: status.exceeded });
      return { ok: false, rejected: true, reason: 'budget', exceeded: status.exceeded, mode, tool: name };
    }
    await recordDomainUsage(BUDGET_DOMAIN, { actions: 1 });
    charged = true;
  }

  const startedAt = Date.now();
  // Outside the Express request lifecycle (called by the orchestrator / CoS
  // agent) — catch so a thrown tool records an `error` ledger entry, then rethrow.
  try {
    const result = await tool.execute(parsed, ctx);
    const timingMs = Date.now() - startedAt;
    // A wrapped service that self-gates returns `{ rejected: true, ... }` instead
    // of throwing (e.g. Series Autopilot when cos autonomy is `off`, reachable
    // when creative is explicitly overridden to `execute` over an `off` cos).
    // Surface that honestly through the one chokepoint rather than reporting a
    // clean `executed` — otherwise the ledger and orchestrator record a
    // successful start for a run the inner gate refused.
    if (result && result.rejected === true) {
      console.log(`🚫 creative dispatch ${name} rejected by wrapped service (${result.mode ?? 'gate'})`);
      // The tool did no work — refund the action charged before execute so a
      // self-gated (non-selfBudgeted) tool doesn't burn budget on a no-op. Today
      // only the selfBudgeted autopilot self-rejects (never charged), so this is
      // defensive for future self-gating tools that keep the registry charge.
      if (charged) await recordDomainUsage(BUDGET_DOMAIN, { actions: -1 });
      await recordLedger(ctx, { ...base, outcome: 'rejected', timingMs });
      return { ok: false, rejected: true, reason: result.reason || 'tool-rejected', mode, tool: name, result, timingMs };
    }
    console.log(`✅ creative dispatch ${name} executed in ${timingMs}ms`);
    await recordLedger(ctx, { ...base, outcome: 'executed', timingMs });
    return { ok: true, mode, tool: name, longRunning: Boolean(tool.longRunning), result, timingMs };
  } catch (err) {
    const timingMs = Date.now() - startedAt;
    console.error(`❌ creative dispatch ${name} failed: ${err.message}`);
    await recordLedger(ctx, { ...base, outcome: 'error', timingMs, error: err.message });
    throw err;
  }
}