@causyne/agent 1.10.21 → 1.11.0

package/src/tools/documentForge.js

@@ -0,0 +1,215 @@
+/*
+ * Copyright (c) 2026 Causyne.
+ * SPDX-License-Identifier: BUSL-1.1
+ *
+ * Causyne Document Forge Tool Wrapper.
+ * Bridges HTML/CSS-first publishing, headless PDF compilation, visual page QA,
+ * anti-slop compliance auditing, and Hollywood screenplay & shot list generation.
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+import { compileDocumentHtml, renderHtmlToPdf, inspectPdfPages } from '../documentEngine/documentForge.js';
+import { formatScreenplayHtml, formatShotListHtml, analyzeVoiceOverTiming } from '../documentEngine/screenplayFormatter.js';
+import { auditTextContent, auditBudgetArithmetic } from '../documentEngine/antiSlopAuditor.js';
+import { resolveUserPath } from '../utils/paths.js';
+export const documentForgeTool = {
+    schema: {
+        name: 'document_forge',
+        description: 'Causyne Document Forge: Professional document & media production harness. Generates pixel-perfect A4/Letter publications via HTML/CSS-First Paged Media and Headless Chrome, renders vector PDFs (<2MB compliant), extracts page images for visual QA ("Lihat Hasilnya"), audits anti-slop and math integrity, formats Hollywood Courier 12pt screenplays, creates production shot lists, and times VO narration.',
+        parameters: {
+            type: 'object',
+            properties: {
+                action: {
+                    type: 'string',
+                    enum: [
+                        'compile_document',
+                        'render_pdf',
+                        'inspect_pages',
+                        'audit_text',
+                        'audit_budget',
+                        'format_screenplay',
+                        'format_shotlist',
+                        'analyze_vo'
+                    ],
+                    description: 'Action to execute.'
+                },
+                documentSpec: {
+                    type: 'object',
+                    properties: {
+                        title: { type: 'string' },
+                        subtitle: { type: 'string' },
+                        categoryOrKicker: { type: 'string' },
+                        authorOrProposer: { type: 'string' },
+                        palette: { type: 'string', enum: ['corporate', 'editorial_dair', 'minimal_clean'] },
+                        includeCover: { type: 'boolean' }
+                    },
+                    description: 'Formal publication spec with sections, tables, and palette (corporate, editorial_dair, minimal_clean).'
+                },
+                screenplaySpec: {
+                    type: 'object',
+                    properties: {
+                        title: { type: 'string' },
+                        author: { type: 'string' },
+                        contact: { type: 'string' }
+                    },
+                    description: 'Hollywood screenplay spec with scene headings, action, characters, dialogue, and transitions.'
+                },
+                shotList: {
+                    type: 'object',
+                    properties: {
+                        title: { type: 'string' },
+                        shots: {
+                            type: 'array',
+                            items: {
+                                type: 'object',
+                                properties: {
+                                    shotNumber: { type: 'number' },
+                                    framing: { type: 'string' },
+                                    subject: { type: 'string' },
+                                    action: { type: 'string' },
+                                    durationSeconds: { type: 'number' }
+                                }
+                            }
+                        }
+                    },
+                    description: 'Director production shot list with framing, lenses, camera movements, and audio cues.'
+                },
+                voBlocks: {
+                    type: 'array',
+                    items: {
+                        type: 'object',
+                        properties: {
+                            id: { type: 'string' },
+                            timecode: { type: 'string' },
+                            text: { type: 'string' },
+                            targetDurationSeconds: { type: 'number' }
+                        }
+                    },
+                    description: 'Voiceover blocks with timecode and target durations for WPM pacing analysis.'
+                },
+                budgetSpec: {
+                    type: 'object',
+                    properties: {
+                        grossUpTaxRate: { type: 'number' },
+                        targetGross: { type: 'number' }
+                    },
+                    description: 'Budget specification for arithmetic validation and tax gross-up verification.'
+                },
+                textContent: {
+                    type: 'string',
+                    description: 'Raw text or HTML content to audit for AI tropes, long em-dashes, and placeholder brackets.'
+                },
+                sourceHtmlPath: {
+                    type: 'string',
+                    description: 'Path to HTML file to render into PDF via Headless Chrome.'
+                },
+                outputPdfPath: {
+                    type: 'string',
+                    description: 'Destination PDF file path.'
+                },
+                outputPath: {
+                    type: 'string',
+                    description: 'Destination HTML or JSON output file path.'
+                },
+                inspectImagesDir: {
+                    type: 'string',
+                    description: 'Directory to save extracted page images for visual inspection.'
+                }
+            }
+        }
+    },
+    async execute(args = {}, _context = {}) {
+        const action = args.action || 'compile_document';
+        switch (action) {
+            case 'compile_document': {
+                if (!args.documentSpec) {
+                    return { success: false, error: 'compile_document requires documentSpec.' };
+                }
+                const compiled = compileDocumentHtml(args.documentSpec);
+                if (args.outputPath) {
+                    const target = resolveUserPath(args.outputPath);
+                    fs.mkdirSync(path.dirname(target), { recursive: true });
+                    fs.writeFileSync(target, compiled.html, 'utf8');
+                }
+                return {
+                    success: true,
+                    html: compiled.html,
+                    outputPath: args.outputPath ? resolveUserPath(args.outputPath) : undefined
+                };
+            }
+            case 'render_pdf': {
+                if (!args.sourceHtmlPath || !args.outputPdfPath) {
+                    return { success: false, error: 'render_pdf requires sourceHtmlPath and outputPdfPath.' };
+                }
+                const src = resolveUserPath(args.sourceHtmlPath);
+                const out = resolveUserPath(args.outputPdfPath);
+                const res = await renderHtmlToPdf(src, out);
+                return res;
+            }
+            case 'inspect_pages': {
+                if (!args.outputPdfPath) {
+                    return { success: false, error: 'inspect_pages requires outputPdfPath.' };
+                }
+                const pdf = resolveUserPath(args.outputPdfPath);
+                const imgDir = args.inspectImagesDir ? resolveUserPath(args.inspectImagesDir) : undefined;
+                const res = await inspectPdfPages(pdf, imgDir);
+                return res;
+            }
+            case 'audit_text': {
+                if (!args.textContent) {
+                    return { success: false, error: 'audit_text requires textContent parameter.' };
+                }
+                const res = auditTextContent(args.textContent);
+                return { success: true, ...res };
+            }
+            case 'audit_budget': {
+                if (!args.budgetSpec) {
+                    return { success: false, error: 'audit_budget requires budgetSpec parameter.' };
+                }
+                const res = auditBudgetArithmetic(args.budgetSpec);
+                return { success: true, ...res };
+            }
+            case 'format_screenplay': {
+                if (!args.screenplaySpec) {
+                    return { success: false, error: 'format_screenplay requires screenplaySpec.' };
+                }
+                const formatted = formatScreenplayHtml(args.screenplaySpec);
+                if (args.outputPath) {
+                    const target = resolveUserPath(args.outputPath);
+                    fs.mkdirSync(path.dirname(target), { recursive: true });
+                    fs.writeFileSync(target, formatted.html, 'utf8');
+                }
+                return {
+                    success: true,
+                    html: formatted.html,
+                    outputPath: args.outputPath ? resolveUserPath(args.outputPath) : undefined
+                };
+            }
+            case 'format_shotlist': {
+                if (!args.shotList) {
+                    return { success: false, error: 'format_shotlist requires shotList parameter.' };
+                }
+                const formatted = formatShotListHtml(args.shotList.title, args.shotList.shots);
+                if (args.outputPath) {
+                    const target = resolveUserPath(args.outputPath);
+                    fs.mkdirSync(path.dirname(target), { recursive: true });
+                    fs.writeFileSync(target, formatted.html, 'utf8');
+                }
+                return {
+                    success: true,
+                    html: formatted.html,
+                    outputPath: args.outputPath ? resolveUserPath(args.outputPath) : undefined
+                };
+            }
+            case 'analyze_vo': {
+                if (!args.voBlocks || !Array.isArray(args.voBlocks)) {
+                    return { success: false, error: 'analyze_vo requires voBlocks array.' };
+                }
+                const res = analyzeVoiceOverTiming(args.voBlocks);
+                return { success: true, analysis: res };
+            }
+            default:
+                return { success: false, error: `Unsupported document_forge action: ${action}` };
+        }
+    }
+};

package/src/tools/documentForge.ts

@@ -0,0 +1,265 @@
+/*
+ * Copyright (c) 2026 Causyne.
+ * SPDX-License-Identifier: BUSL-1.1
+ *
+ * Causyne Document Forge Tool Wrapper.
+ * Bridges HTML/CSS-first publishing, headless PDF compilation, visual page QA,
+ * anti-slop compliance auditing, and Hollywood screenplay & shot list generation.
+ */
+
+import fs from 'node:fs';
+import path from 'node:path';
+import {
+  compileDocumentHtml,
+  renderHtmlToPdf,
+  inspectPdfPages,
+  type FormalDocumentSpec
+} from '../documentEngine/documentForge.js';
+import {
+  formatScreenplayHtml,
+  formatShotListHtml,
+  analyzeVoiceOverTiming,
+  type ScreenplaySpec,
+  type ProductionShot,
+  type VoBlock
+} from '../documentEngine/screenplayFormatter.js';
+import {
+  auditTextContent,
+  auditBudgetArithmetic,
+  type ArithmeticBudgetSpec
+} from '../documentEngine/antiSlopAuditor.js';
+import { resolveUserPath } from '../utils/paths.js';
+
+export interface DocumentForgeArgs {
+  action?:
+    | 'compile_document'
+    | 'render_pdf'
+    | 'inspect_pages'
+    | 'audit_text'
+    | 'audit_budget'
+    | 'format_screenplay'
+    | 'format_shotlist'
+    | 'analyze_vo';
+  documentSpec?: FormalDocumentSpec;
+  screenplaySpec?: ScreenplaySpec;
+  shotList?: { title: string; shots: ProductionShot[] };
+  voBlocks?: VoBlock[];
+  budgetSpec?: ArithmeticBudgetSpec;
+  textContent?: string;
+  sourceHtmlPath?: string;
+  outputPdfPath?: string;
+  outputPath?: string;
+  inspectImagesDir?: string;
+}
+
+export const documentForgeTool = {
+  schema: {
+    name: 'document_forge',
+    description: 'Causyne Document Forge: Professional document & media production harness. Generates pixel-perfect A4/Letter publications via HTML/CSS-First Paged Media and Headless Chrome, renders vector PDFs (<2MB compliant), extracts page images for visual QA ("Lihat Hasilnya"), audits anti-slop and math integrity, formats Hollywood Courier 12pt screenplays, creates production shot lists, and times VO narration.',
+    parameters: {
+      type: 'object',
+      properties: {
+        action: {
+          type: 'string',
+          enum: [
+            'compile_document',
+            'render_pdf',
+            'inspect_pages',
+            'audit_text',
+            'audit_budget',
+            'format_screenplay',
+            'format_shotlist',
+            'analyze_vo'
+          ],
+          description: 'Action to execute.'
+        },
+        documentSpec: {
+          type: 'object',
+          properties: {
+            title: { type: 'string' },
+            subtitle: { type: 'string' },
+            categoryOrKicker: { type: 'string' },
+            authorOrProposer: { type: 'string' },
+            palette: { type: 'string', enum: ['corporate', 'editorial_dair', 'minimal_clean'] },
+            includeCover: { type: 'boolean' }
+          },
+          description: 'Formal publication spec with sections, tables, and palette (corporate, editorial_dair, minimal_clean).'
+        },
+        screenplaySpec: {
+          type: 'object',
+          properties: {
+            title: { type: 'string' },
+            author: { type: 'string' },
+            contact: { type: 'string' }
+          },
+          description: 'Hollywood screenplay spec with scene headings, action, characters, dialogue, and transitions.'
+        },
+        shotList: {
+          type: 'object',
+          properties: {
+            title: { type: 'string' },
+            shots: {
+              type: 'array',
+              items: {
+                type: 'object',
+                properties: {
+                  shotNumber: { type: 'number' },
+                  framing: { type: 'string' },
+                  subject: { type: 'string' },
+                  action: { type: 'string' },
+                  durationSeconds: { type: 'number' }
+                }
+              }
+            }
+          },
+          description: 'Director production shot list with framing, lenses, camera movements, and audio cues.'
+        },
+        voBlocks: {
+          type: 'array',
+          items: {
+            type: 'object',
+            properties: {
+              id: { type: 'string' },
+              timecode: { type: 'string' },
+              text: { type: 'string' },
+              targetDurationSeconds: { type: 'number' }
+            }
+          },
+          description: 'Voiceover blocks with timecode and target durations for WPM pacing analysis.'
+        },
+        budgetSpec: {
+          type: 'object',
+          properties: {
+            grossUpTaxRate: { type: 'number' },
+            targetGross: { type: 'number' }
+          },
+          description: 'Budget specification for arithmetic validation and tax gross-up verification.'
+        },
+        textContent: {
+          type: 'string',
+          description: 'Raw text or HTML content to audit for AI tropes, long em-dashes, and placeholder brackets.'
+        },
+        sourceHtmlPath: {
+          type: 'string',
+          description: 'Path to HTML file to render into PDF via Headless Chrome.'
+        },
+        outputPdfPath: {
+          type: 'string',
+          description: 'Destination PDF file path.'
+        },
+        outputPath: {
+          type: 'string',
+          description: 'Destination HTML or JSON output file path.'
+        },
+        inspectImagesDir: {
+          type: 'string',
+          description: 'Directory to save extracted page images for visual inspection.'
+        }
+      }
+    }
+  },
+
+  async execute(args: DocumentForgeArgs = {}, _context: any = {}): Promise<{ success: boolean; [key: string]: any }> {
+    const action = args.action || 'compile_document';
+
+    switch (action) {
+      case 'compile_document': {
+        if (!args.documentSpec) {
+          return { success: false, error: 'compile_document requires documentSpec.' };
+        }
+        const compiled = compileDocumentHtml(args.documentSpec);
+        if (args.outputPath) {
+          const target = resolveUserPath(args.outputPath);
+          fs.mkdirSync(path.dirname(target), { recursive: true });
+          fs.writeFileSync(target, compiled.html, 'utf8');
+        }
+        return {
+          success: true,
+          html: compiled.html,
+          outputPath: args.outputPath ? resolveUserPath(args.outputPath) : undefined
+        };
+      }
+
+      case 'render_pdf': {
+        if (!args.sourceHtmlPath || !args.outputPdfPath) {
+          return { success: false, error: 'render_pdf requires sourceHtmlPath and outputPdfPath.' };
+        }
+        const src = resolveUserPath(args.sourceHtmlPath);
+        const out = resolveUserPath(args.outputPdfPath);
+        const res = await renderHtmlToPdf(src, out);
+        return res;
+      }
+
+      case 'inspect_pages': {
+        if (!args.outputPdfPath) {
+          return { success: false, error: 'inspect_pages requires outputPdfPath.' };
+        }
+        const pdf = resolveUserPath(args.outputPdfPath);
+        const imgDir = args.inspectImagesDir ? resolveUserPath(args.inspectImagesDir) : undefined;
+        const res = await inspectPdfPages(pdf, imgDir);
+        return res;
+      }
+
+      case 'audit_text': {
+        if (!args.textContent) {
+          return { success: false, error: 'audit_text requires textContent parameter.' };
+        }
+        const res = auditTextContent(args.textContent);
+        return { success: true, ...res };
+      }
+
+      case 'audit_budget': {
+        if (!args.budgetSpec) {
+          return { success: false, error: 'audit_budget requires budgetSpec parameter.' };
+        }
+        const res = auditBudgetArithmetic(args.budgetSpec);
+        return { success: true, ...res };
+      }
+
+      case 'format_screenplay': {
+        if (!args.screenplaySpec) {
+          return { success: false, error: 'format_screenplay requires screenplaySpec.' };
+        }
+        const formatted = formatScreenplayHtml(args.screenplaySpec);
+        if (args.outputPath) {
+          const target = resolveUserPath(args.outputPath);
+          fs.mkdirSync(path.dirname(target), { recursive: true });
+          fs.writeFileSync(target, formatted.html, 'utf8');
+        }
+        return {
+          success: true,
+          html: formatted.html,
+          outputPath: args.outputPath ? resolveUserPath(args.outputPath) : undefined
+        };
+      }
+
+      case 'format_shotlist': {
+        if (!args.shotList) {
+          return { success: false, error: 'format_shotlist requires shotList parameter.' };
+        }
+        const formatted = formatShotListHtml(args.shotList.title, args.shotList.shots);
+        if (args.outputPath) {
+          const target = resolveUserPath(args.outputPath);
+          fs.mkdirSync(path.dirname(target), { recursive: true });
+          fs.writeFileSync(target, formatted.html, 'utf8');
+        }
+        return {
+          success: true,
+          html: formatted.html,
+          outputPath: args.outputPath ? resolveUserPath(args.outputPath) : undefined
+        };
+      }
+
+      case 'analyze_vo': {
+        if (!args.voBlocks || !Array.isArray(args.voBlocks)) {
+          return { success: false, error: 'analyze_vo requires voBlocks array.' };
+        }
+        const res = analyzeVoiceOverTiming(args.voBlocks);
+        return { success: true, analysis: res };
+      }
+
+      default:
+        return { success: false, error: `Unsupported document_forge action: ${action}` };
+    }
+  }
+};

package/src/tools/peerAgent.js

@@ -0,0 +1,102 @@
+/**
+ * Causyne Peer Agent Tool
+ *
+ * Delegates a bounded task to an external ACP agent that the user configured
+ * in `~/.causyne/peers.json`. The model chooses a profile and writes a prompt;
+ * it never chooses the executable, arguments, working directory, or
+ * environment. Those come from the user's file and nowhere else.
+ */
+import { AcpClient } from '../acp/client.js';
+import { getPeerProfile, loadPeerProfiles, peerEnvironment } from '../acp/peerProfiles.js';
+const MAX_PROMPT_CHARS = 100_000;
+const READ_ONLY_KINDS = new Set(['read', 'search', 'fetch', 'think']);
+function selectPermission(profile, request) {
+    const kind = request.toolCall.kind;
+    const readLike = typeof kind === 'string' && READ_ONLY_KINDS.has(kind);
+    if (profile.policy === 'read-only' && !readLike) {
+        const reject = request.options.find((option) => option.kind === 'reject_once' || option.kind === 'reject_always');
+        return reject ? { outcome: 'selected', optionId: reject.optionId } : { outcome: 'cancelled' };
+    }
+    const allow = request.options.find((option) => option.kind === 'allow_once' || option.kind === 'allow_always');
+    return allow ? { outcome: 'selected', optionId: allow.optionId } : { outcome: 'cancelled' };
+}
+export const peerAgentTool = {
+    schema: {
+        name: 'peer_agent_delegate',
+        description: 'Delegate a bounded task to a peer ACP agent that the user configured in the peers file. The model supplies the peer id and the prompt only; the executable, arguments, working directory, environment, and permission policy come from the user configuration. Peers default to rejecting mutating permission requests; the external agent decides how to honor that policy.',
+        parameters: {
+            type: 'object',
+            properties: {
+                peer: {
+                    type: 'string',
+                    description: 'Id of a configured peer profile from the peers file.'
+                },
+                prompt: {
+                    type: 'string',
+                    description: 'Task instructions and context for the peer agent.'
+                },
+                timeoutSeconds: {
+                    type: 'number',
+                    description: 'Optional shorter timeout in seconds, bounded by the profile timeout.'
+                }
+            },
+            required: ['peer', 'prompt']
+        }
+    },
+    async execute(args) {
+        const peerId = String(args.peer || '').trim();
+        const prompt = String(args.prompt || '').trim().slice(0, MAX_PROMPT_CHARS);
+        if (!peerId) {
+            const configured = loadPeerProfiles().map((profile) => profile.id);
+            return {
+                success: false,
+                error: configured.length > 0
+                    ? `A peer id is required. Configured peers: ${configured.join(', ')}.`
+                    : 'No peer profiles are configured. Add one to the peers file first.'
+            };
+        }
+        if (!prompt) {
+            return { success: false, error: 'A prompt is required for peer delegation.' };
+        }
+        const profile = getPeerProfile(peerId);
+        if (!profile) {
+            return { success: false, error: `Unknown peer profile: ${peerId}.` };
+        }
+        const requested = typeof args.timeoutSeconds === 'number' && Number.isFinite(args.timeoutSeconds)
+            ? Math.round(args.timeoutSeconds)
+            : profile.timeoutSeconds;
+        const timeoutSeconds = Math.max(5, Math.min(Math.min(profile.timeoutSeconds, requested), 1800));
+        const client = new AcpClient({
+            command: profile.command,
+            args: profile.args,
+            cwd: profile.cwd ?? process.cwd(),
+            env: peerEnvironment(profile),
+            promptTimeoutMs: timeoutSeconds * 1000,
+            permissionHandler: async (request) => selectPermission(profile, request)
+        });
+        try {
+            await client.start();
+            const sessionId = await client.newSession(profile.cwd ?? process.cwd());
+            const result = await client.prompt(sessionId, prompt);
+            if (result.stopReason === 'cancelled') {
+                return { success: false, error: 'The peer agent cancelled the task.' };
+            }
+            if (result.stopReason === 'refusal') {
+                return { success: false, error: 'The peer agent refused the task.' };
+            }
+            return {
+                success: true,
+                output: result.text.trim() || 'Peer agent completed the task without a written summary.'
+            };
+        }
+        catch (error) {
+            return {
+                success: false,
+                error: error instanceof Error ? error.message : 'Peer agent delegation failed.'
+            };
+        }
+        finally {
+            await client.close();
+        }
+    }
+};