@causyne/agent 1.10.21 → 1.11.0

package/src/documentEngine/screenplayFormatter.ts

@@ -0,0 +1,407 @@
+/*
+ * Copyright (c) 2026 Causyne.
+ * SPDX-License-Identifier: BUSL-1.1
+ *
+ * Hollywood Standard Screenplay & Production Shot List Formatter.
+ * Enforces industry Courier 12pt specifications, 1-page-per-minute timing,
+ * director's shot list grids, and voice-over (VO) timing synchronization.
+ */
+
+export type ScreenplayElementType =
+  | 'scene_heading'
+  | 'action'
+  | 'character'
+  | 'parenthetical'
+  | 'dialogue'
+  | 'transition';
+
+export interface ScreenplayElement {
+  type: ScreenplayElementType;
+  text: string;
+}
+
+export interface ScreenplaySpec {
+  title: string;
+  author?: string;
+  contact?: string;
+  elements: ScreenplayElement[];
+}
+
+export interface ProductionShot {
+  shotNumber: number | string;
+  scene?: string;
+  framing: 'EWS' | 'WS' | 'MWS' | 'MS' | 'MCU' | 'CU' | 'ECU' | 'AERIAL' | 'MACRO';
+  angle?: 'Eye-level' | 'Low-angle' | 'High-angle' | 'Dutch' | 'Over-the-shoulder' | 'POV';
+  movement?: 'Static' | 'Pan' | 'Tilt' | 'Dolly' | 'Tracking' | 'Crane' | 'Handheld';
+  lens?: string; // e.g. "24mm", "35mm", "50mm", "85mm"
+  subject: string;
+  action: string;
+  audioOrSfx?: string;
+  durationSeconds: number;
+}
+
+export interface VoBlock {
+  id: string;
+  timecode: string; // e.g. "00-10s"
+  text: string;
+  targetDurationSeconds: number;
+}
+
+export interface VoAnalysisResult {
+  blocks: Array<{
+    id: string;
+    timecode: string;
+    text: string;
+    wordCount: number;
+    targetDurationSeconds: number;
+    wpm: number;
+    status: 'optimal' | 'too_fast' | 'too_slow';
+  }>;
+  totalWords: number;
+  totalDurationSeconds: number;
+  averageWpm: number;
+}
+
+/**
+ * Generate industry-standard Hollywood Screenplay HTML + CSS.
+ * Courier 12pt, 1.5in left margin, centered character cues, constrained dialogue width.
+ */
+export function formatScreenplayHtml(spec: ScreenplaySpec): { html: string; css: string } {
+  const css = `
+/* Hollywood Industry Standard Screenplay Layout */
+@page {
+  size: letter portrait;
+  margin: 1.0in 1.0in 1.0in 1.5in;
+  @top-right {
+    content: counter(page) ".";
+    font-family: "Courier Prime", "Courier Final Draft", Courier, monospace;
+    font-size: 10pt;
+  }
+}
+@page :first {
+  @top-right { content: normal; }
+}
+
+html {
+  -webkit-print-color-adjust: exact;
+  print-color-adjust: exact;
+}
+
+body {
+  margin: 0;
+  padding: 0;
+  font-family: "Courier Prime", "Courier Final Draft", Courier, monospace;
+  font-size: 12pt;
+  line-height: 1.0;
+  color: #000000;
+  background: #ffffff;
+}
+
+.script-title-page {
+  page-break-after: always;
+  height: 9.0in;
+  display: flex;
+  flex-direction: column;
+  justify-content: center;
+  align-items: center;
+  text-align: center;
+}
+.script-title {
+  font-size: 18pt;
+  font-weight: bold;
+  letter-spacing: 0.1em;
+  text-transform: uppercase;
+  margin-bottom: 24pt;
+}
+.script-by {
+  font-size: 12pt;
+  margin-bottom: 12pt;
+}
+.script-author {
+  font-size: 12pt;
+  text-transform: uppercase;
+  margin-bottom: 48pt;
+}
+
+.element-scene_heading {
+  font-weight: bold;
+  text-transform: uppercase;
+  margin-top: 18pt;
+  margin-bottom: 10pt;
+  page-break-after: avoid;
+}
+
+.element-action {
+  margin-bottom: 12pt;
+  line-height: 1.25;
+  text-align: left;
+}
+
+.element-character {
+  text-transform: uppercase;
+  margin-left: 2.2in;
+  margin-top: 14pt;
+  margin-bottom: 0;
+  page-break-after: avoid;
+}
+
+.element-parenthetical {
+  margin-left: 1.6in;
+  width: 2.5in;
+  margin-top: 0;
+  margin-bottom: 0;
+  page-break-after: avoid;
+}
+
+.element-dialogue {
+  margin-left: 1.0in;
+  width: 3.5in;
+  line-height: 1.2;
+  margin-top: 2pt;
+  margin-bottom: 12pt;
+}
+
+.element-transition {
+  text-transform: uppercase;
+  text-align: right;
+  margin-top: 14pt;
+  margin-bottom: 14pt;
+  page-break-after: avoid;
+}
+`.trim();
+
+  let bodyContent = '';
+
+  if (spec.title) {
+    bodyContent += `
+<div class="script-title-page">
+  <div class="script-title">${escapeHtml(spec.title)}</div>
+  <div class="script-by">written by</div>
+  <div class="script-author">${escapeHtml(spec.author || 'Anonymous')}</div>
+  ${spec.contact ? `<div style="margin-top: auto; font-size: 10pt;">${escapeHtml(spec.contact)}</div>` : ''}
+</div>`;
+  }
+
+  bodyContent += '<div class="script-body">';
+  for (const el of spec.elements) {
+    const escaped = escapeHtml(el.text);
+    switch (el.type) {
+      case 'scene_heading':
+        bodyContent += `\n<div class="element-scene_heading">${escaped}</div>`;
+        break;
+      case 'action':
+        bodyContent += `\n<div class="element-action">${escaped}</div>`;
+        break;
+      case 'character':
+        bodyContent += `\n<div class="element-character">${escaped}</div>`;
+        break;
+      case 'parenthetical':
+        bodyContent += `\n<div class="element-parenthetical">(${escaped.replace(/^\(|\)$/g, '')})</div>`;
+        break;
+      case 'dialogue':
+        bodyContent += `\n<div class="element-dialogue">${escaped}</div>`;
+        break;
+      case 'transition':
+        bodyContent += `\n<div class="element-transition">${escaped}</div>`;
+        break;
+    }
+  }
+  bodyContent += '\n</div>';
+
+  const html = `<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="UTF-8">
+  <title>${escapeHtml(spec.title)}</title>
+  <style>
+${css}
+  </style>
+</head>
+<body>
+${bodyContent}
+</body>
+</html>`;
+
+  return { html, css };
+}
+
+/**
+ * Format Production Shot List as print-ready HTML table.
+ */
+export function formatShotListHtml(title: string, shots: ProductionShot[]): { html: string; css: string } {
+  const css = `
+@page {
+  size: A4 landscape;
+  margin: 15mm;
+  @bottom-right {
+    content: "Page " counter(page) " of " counter(pages);
+    font-size: 9pt;
+    font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, sans-serif;
+  }
+}
+body {
+  font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, Helvetica, Arial, sans-serif;
+  font-size: 9.5pt;
+  color: #111827;
+  margin: 0;
+  padding: 0;
+}
+.header {
+  margin-bottom: 16px;
+  border-bottom: 2px solid #0f172a;
+  padding-bottom: 8px;
+  display: flex;
+  justify-content: space-between;
+  align-items: baseline;
+}
+.title {
+  font-size: 16pt;
+  font-weight: 700;
+  letter-spacing: -0.02em;
+}
+.subtitle {
+  font-size: 10pt;
+  color: #4b5563;
+}
+table {
+  width: 100%;
+  border-collapse: collapse;
+  margin-top: 8px;
+}
+th {
+  background: #0f172a;
+  color: #ffffff;
+  font-weight: 600;
+  text-align: left;
+  padding: 8px 10px;
+  font-size: 8.5pt;
+  text-transform: uppercase;
+  letter-spacing: 0.05em;
+}
+td {
+  padding: 8px 10px;
+  border-bottom: 1px solid #e2e8f0;
+  vertical-align: top;
+  line-height: 1.4;
+}
+tr:nth-child(even) td {
+  background: #f8fafc;
+}
+tr {
+  page-break-inside: avoid;
+}
+.badge {
+  display: inline-block;
+  padding: 2px 6px;
+  border-radius: 4px;
+  font-size: 7.5pt;
+  font-weight: 600;
+  background: #e0e7ff;
+  color: #3730a3;
+}
+`.trim();
+
+  let totalDuration = 0;
+  const rows = shots
+    .map((s) => {
+      totalDuration += s.durationSeconds;
+      return `
+    <tr>
+      <td style="font-weight: bold; width: 40px;">${escapeHtml(String(s.shotNumber))}</td>
+      <td style="width: 70px;">${escapeHtml(s.scene || '-')}</td>
+      <td style="width: 70px;"><span class="badge">${escapeHtml(s.framing)}</span></td>
+      <td style="width: 90px;">${escapeHtml(s.angle || 'Eye-level')}</td>
+      <td style="width: 90px;">${escapeHtml(s.movement || 'Static')}</td>
+      <td style="width: 60px;">${escapeHtml(s.lens || '-')}</td>
+      <td><strong>${escapeHtml(s.subject)}</strong> — ${escapeHtml(s.action)}</td>
+      <td style="width: 160px; font-size: 8.5pt; color: #475569;">${escapeHtml(s.audioOrSfx || '-')}</td>
+      <td style="text-align: right; font-weight: 600; width: 50px;">${s.durationSeconds}s</td>
+    </tr>`;
+    })
+    .join('');
+
+  const html = `<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="UTF-8">
+  <title>${escapeHtml(title)} - Shot List</title>
+  <style>${css}</style>
+</head>
+<body>
+  <div class="header">
+    <div class="title">${escapeHtml(title)} — Production Shot List</div>
+    <div class="subtitle">Total Shots: ${shots.length} | Est. Duration: ${totalDuration}s (${(totalDuration / 60).toFixed(1)} min)</div>
+  </div>
+  <table>
+    <thead>
+      <tr>
+        <th>Shot</th>
+        <th>Scene</th>
+        <th>Framing</th>
+        <th>Angle</th>
+        <th>Movement</th>
+        <th>Lens</th>
+        <th>Subject & Action Description</th>
+        <th>Audio / SFX Cue</th>
+        <th style="text-align: right;">Dur</th>
+      </tr>
+    </thead>
+    <tbody>
+      ${rows}
+    </tbody>
+  </table>
+</body>
+</html>`;
+
+  return { html, css };
+}
+
+/**
+ * Analyze Voice-Over / Dubbing blocks for Word-Per-Minute (WPM) cadence.
+ * Target: 130-155 WPM for natural documentary/commercial narration.
+ */
+export function analyzeVoiceOverTiming(blocks: VoBlock[]): VoAnalysisResult {
+  let totalWords = 0;
+  let totalDuration = 0;
+
+  const analyzed = blocks.map((b) => {
+    const words = b.text.trim().split(/\s+/).filter(Boolean).length;
+    totalWords += words;
+    totalDuration += b.targetDurationSeconds;
+
+    const minutes = b.targetDurationSeconds / 60;
+    const wpm = minutes > 0 ? Math.round(words / minutes) : 0;
+
+    let status: 'optimal' | 'too_fast' | 'too_slow' = 'optimal';
+    if (wpm > 165) status = 'too_fast';
+    else if (wpm < 115) status = 'too_slow';
+
+    return {
+      id: b.id,
+      timecode: b.timecode,
+      text: b.text,
+      wordCount: words,
+      targetDurationSeconds: b.targetDurationSeconds,
+      wpm,
+      status
+    };
+  });
+
+  const avgMinutes = totalDuration / 60;
+  const averageWpm = avgMinutes > 0 ? Math.round(totalWords / avgMinutes) : 0;
+
+  return {
+    blocks: analyzed,
+    totalWords,
+    totalDurationSeconds: totalDuration,
+    averageWpm
+  };
+}
+
+function escapeHtml(str: string): string {
+  return String(str || '')
+    .replace(/&/g, '&amp;')
+    .replace(/</g, '&lt;')
+    .replace(/>/g, '&gt;')
+    .replace(/"/g, '&quot;');
+}

package/src/entrypoint.js

@@ -194,6 +194,19 @@ program
     await execCommand(command);
   });
 
+program
+  .command('acp')
+  .description('Start Causyne as an Agent Client Protocol (ACP) server over stdio')
+  .action(async () => {
+    const { AcpServer } = await import('./acp/server.js');
+    const server = new AcpServer({
+      input: process.stdin,
+      output: process.stdout,
+      agentVersion: getPackageVersion()
+    });
+    server.start();
+  });
+
 // Setup fallback for missing commands
 program.on('command:*', function () {
   console.error('Invalid command: %s\nSee --help for a list of available commands.', program.args.join(' '));

package/src/execSafe.js

@@ -1,21 +1,18 @@
 import { exec, execSync as nodeExecSync } from 'node:child_process';
-
 // Compatibility wrapper, NOT a security boundary. These APIs invoke a shell.
 // Callers must enforce approval and validate input; prefer execFile with argv.
 export function execSync(command, options) {
-  return nodeExecSync(command, options);
+    return nodeExecSync(command, options);
 }
-
 export function execAsync(command, options = {}) {
-  return new Promise((resolve, reject) => {
-    exec(command, options, (error, stdout, stderr) => {
-      if (error) {
-        error.stdout = stdout;
-        error.stderr = stderr;
-        reject(error);
-        return;
-      }
-      resolve(typeof stdout === 'string' ? stdout : String(stdout ?? ''));
+    return new Promise((resolve, reject) => {
+        exec(command, options, (error, stdout, stderr) => {
+            if (error) {
+                Object.assign(error, { stdout, stderr });
+                reject(error);
+                return;
+            }
+            resolve(typeof stdout === 'string' ? stdout : String(stdout ?? ''));
+        });
     });
-  });
 }

package/src/execSafe.ts

@@ -0,0 +1,25 @@
+import {
+  exec,
+  execSync as nodeExecSync,
+  type ExecOptions,
+  type ExecSyncOptions
+} from 'node:child_process';
+
+// Compatibility wrapper, NOT a security boundary. These APIs invoke a shell.
+// Callers must enforce approval and validate input; prefer execFile with argv.
+export function execSync(command: string, options?: ExecSyncOptions): Buffer | string {
+  return nodeExecSync(command, options);
+}
+
+export function execAsync(command: string, options: ExecOptions = {}): Promise<string> {
+  return new Promise((resolve, reject) => {
+    exec(command, options, (error, stdout, stderr) => {
+      if (error) {
+        Object.assign(error, { stdout, stderr });
+        reject(error);
+        return;
+      }
+      resolve(typeof stdout === 'string' ? stdout : String(stdout ?? ''));
+    });
+  });
+}

package/src/modelRouter.js

@@ -1,145 +1,78 @@
 import { UTILITY_MODEL_BY_PROVIDER } from './modelCatalogue.js';
-
-// Hybrid model routing.
-//
-// Not every call an agent makes is reasoning. Condensing a dropped transcript,
-// classifying an intent, filtering a log, extracting keywords — these are
-// utility work, and paying a flagship rate for them is pure waste. The research
-// spec puts the saving at the difference between the two rate cards, which for
-// OpenAI is $5/$30 against $0.75/$4.50: roughly 6x on work that never needed
-// the better model.
-//
-// THREE RULES THIS MODULE EXISTS TO ENFORCE, all of them things a naive router
-// gets wrong:
-//
-//   1. NEVER CHANGE PROVIDER. Causyne is BYOK. The user holds one key. A router
-//      that sends utility work to "whatever is cheapest on the market" calls an
-//      endpoint there is no credential for and the task fails — having spent
-//      the tokens that got it there.
-//
-//   2. NEVER CHANGE THE PRIVACY POSTURE. Muse's cheap tier is `-contributor`,
-//      discounted because the vendor trains on the content. Routing into it to
-//      save money would opt the user into training silently. Cost is not a
-//      reason to make that choice for someone.
-//
-//   3. NEVER GUESS. A provider with no published second tier routes to nothing
-//      and pays full rate. An invented model id becomes a 404 mid-task, or
-//      worse, a real model at a price nobody predicted.
-//
-// The router returns a DESCRIPTION of where a call should go. It never
-// constructs a provider and never performs a call, so it stays trivially
-// testable and cannot become a second place where credentials are handled.
-
-/**
- * What a call is for.
- *
- * `reasoning` — planning, code, architecture, tool selection, anything the
- * user's result quality depends on. Always the configured model.
- * `utility`   — mechanical text work whose output is consumed by the machine
- * rather than by the user's judgement.
- *
- * @typedef {'reasoning' | 'utility'} RouteClass
- */
-
-/**
- * @typedef {Object} Route
- * @property {string}  provider  The provider to call. Always the configured one.
- * @property {string}  model     The model id to request.
- * @property {boolean} routed    True when this differs from the configured model.
- * @property {string}  reason    Why, in one line. Written to the audit trail.
- */
-
 /**
  * Utility work that is cheap to get wrong and expensive to run on a flagship.
  * Anything not listed is treated as reasoning — the safe default is to spend
  * more, never to silently downgrade work the user is judging.
- *
- * @type {ReadonlySet<string>}
  */
 export const UTILITY_KINDS = new Set([
-  'condense',        // cortex/autoCondenser semantic pass
-  'keywords',        // plan-cache intent extraction
-  'classify',        // intent / archetype disambiguation
-  'filter',          // log and output filtering
-  'summarise'        // non-decision summaries
+    'condense', // cortex/autoCondenser semantic pass
+    'keywords', // plan-cache intent extraction
+    'classify', // intent / archetype disambiguation
+    'filter', // log and output filtering
+    'summarise' // non-decision summaries
 ]);
-
 /**
  * Decide where a call of a given kind should go.
  *
- * @param   {{provider?: string, model?: string, modelRouting?: Record<string, string>, disableModelRouting?: boolean}} config
- *          The live agent config, as loaded from `~/.causyne/config.json`.
- * @param   {RouteClass|string} kind
- *          Either a RouteClass or one of UTILITY_KINDS.
- * @returns {Route}
+ * @param config The live agent config, as loaded from `~/.causyne/config.json`.
+ * @param kind Either a RouteClass or one of UTILITY_KINDS.
+ * @returns The resolved route description.
  */
 export function resolveRoute(config, kind) {
-  const provider = String(config?.provider || '').toLowerCase();
-  const configured = String(config?.model || '');
-
-  /** @type {Route} */
-  const stay = {
-    provider,
-    model: configured,
-    routed: false,
-    reason: 'reasoning work runs on the configured model'
-  };
-
-  if (!provider || !configured) {
-    return { ...stay, reason: 'no provider or model configured' };
-  }
-
-  const isUtility = kind === 'utility' || UTILITY_KINDS.has(String(kind));
-  if (!isUtility) return stay;
-
-  if (config?.disableModelRouting === true) {
-    return { ...stay, reason: 'model routing disabled by config' };
-  }
-
-  // An explicit choice by the user outranks the table, including a deliberate
-  // choice of a training tier — they made it, we did not make it for them.
-  const override = config?.modelRouting?.utility;
-  if (override) {
+    const provider = String(config?.provider || '').toLowerCase();
+    const configured = String(config?.model || '');
+    const stay = {
+        provider,
+        model: configured,
+        routed: false,
+        reason: 'reasoning work runs on the configured model'
+    };
+    if (!provider || !configured) {
+        return { ...stay, reason: 'no provider or model configured' };
+    }
+    const isUtility = kind === 'utility' || UTILITY_KINDS.has(String(kind));
+    if (!isUtility)
+        return stay;
+    if (config?.disableModelRouting === true) {
+        return { ...stay, reason: 'model routing disabled by config' };
+    }
+    // An explicit choice by the user outranks the table, including a deliberate
+    // choice of a training tier — they made it, we did not make it for them.
+    const override = config?.modelRouting?.['utility'];
+    if (override) {
+        return {
+            provider,
+            model: String(override),
+            routed: String(override) !== configured,
+            reason: 'utility route set explicitly in config'
+        };
+    }
+    const cheap = UTILITY_MODEL_BY_PROVIDER[provider];
+    if (!cheap) {
+        return { ...stay, reason: `no published utility tier for ${provider}; paying full rate` };
+    }
+    if (cheap === configured) {
+        return { ...stay, reason: 'already on this provider\'s utility tier' };
+    }
+    // Rule 2. The configured model already carries a privacy posture; a route may
+    // not alter it in either direction.
+    if (/-contributor$/.test(configured) !== /-contributor$/.test(cheap)) {
+        return { ...stay, reason: 'a route may not change the training-data posture' };
+    }
     return {
-      provider,
-      model: String(override),
-      routed: String(override) !== configured,
-      reason: 'utility route set explicitly in config'
+        provider,
+        model: cheap,
+        routed: true,
+        reason: `utility work routed to ${provider}'s cheaper tier`
     };
-  }
-
-  const cheap = UTILITY_MODEL_BY_PROVIDER[provider];
-  if (!cheap) {
-    return { ...stay, reason: `no published utility tier for ${provider}; paying full rate` };
-  }
-  if (cheap === configured) {
-    return { ...stay, reason: 'already on this provider\'s utility tier' };
-  }
-
-  // Rule 2. The configured model already carries a privacy posture; a route may
-  // not alter it in either direction.
-  if (/-contributor$/.test(configured) !== /-contributor$/.test(cheap)) {
-    return { ...stay, reason: 'a route may not change the training-data posture' };
-  }
-
-  return {
-    provider,
-    model: cheap,
-    routed: true,
-    reason: `utility work routed to ${provider}'s cheaper tier`
-  };
 }
-
 /**
  * A config object for the routed call, leaving everything except the model
  * untouched — same provider, same key, same base URL.
- *
- * @param   {Record<string, any>} config
- * @param   {RouteClass|string}   kind
- * @returns {{config: Record<string, any>, route: Route}}
  */
 export function routedConfig(config, kind) {
-  const route = resolveRoute(config, kind);
-  if (!route.routed) return { config, route };
-  return { config: { ...config, model: route.model }, route };
+    const route = resolveRoute(config, kind);
+    if (!route.routed)
+        return { config, route };
+    return { config: { ...config, model: route.model }, route };
 }