@causyne/agent 1.10.21 → 1.11.0

package/native-skills/media/professional-document-publishing/SKILL.md

@@ -0,0 +1,44 @@
+---
+name: professional-document-publishing
+description: Generate publication-grade PDF documents, grant proposals, financial sheets, and technical reports using HTML/CSS Paged Media and Headless Chrome. Enforces visual quality inspection, under 2MB compliance, and mathematical integrity.
+---
+
+# Professional Document Publishing & Harness
+
+Frontier LLMs and efficient models produce equally stunning, publication-ready documents when guided by this harness methodology.
+
+Never assemble print layouts through raw Python scripts. Always author in semantic HTML5 plus CSS Paged Media, compile via Headless Chrome, and visually inspect the rendered output.
+
+## Workflow
+
+1. Prepare structured data and schemas.
+   - Keep numeric budget and scheduling data in structured JSON format.
+   - Run math validation with `document_forge` (`action: "audit_budget"`).
+   - **Done when:** all numbers are validated against the single source of truth.
+
+2. Compile document markup and styles.
+   - Author page layouts in HTML using standard CSS `@page` rules (`size: A4 portrait; margin: 20mm 18mm 18mm 18mm;`).
+   - Use `@page cover { margin: 0; }` for full-bleed cover banners without white borders.
+   - Force `-webkit-print-color-adjust: exact; print-color-adjust: exact;` so backgrounds and gradients render faithfully.
+   - Prevent mid-table row cuts with `tr { page-break-inside: avoid; }`.
+   - Prevent orphan headers with `h1, h2, h3 { page-break-after: avoid; }`.
+   - Compile via `document_forge` (`action: "compile_document"`).
+   - **Done when:** HTML markup and CSS paged styles are written to disk.
+
+3. Render to vector PDF via Headless Chrome.
+   - Invoke `document_forge` (`action: "render_pdf"`, `sourceHtmlPath`, `outputPdfPath`).
+   - **Done when:** vector PDF file exists on disk with non-zero size.
+
+4. Inspect pages visually and audit compliance.
+   - Extract page images via `document_forge` (`action: "inspect_pages"`).
+   - Verify page fill density: flag and repair any pages with less than 25% text coverage.
+   - Confirm PDF file size is below 2,048 KB for portal compliance.
+   - Audit text content for long em-dashes and AI clichés with `document_forge` (`action: "audit_text"`).
+   - **Done when:** all pages pass visual density check and size constraints.
+
+## Verification
+
+- `document_forge` returns `success: true`.
+- Output PDF file size is non-zero and under 2,048 KB.
+- Extracted page images show no clipped text or orphaned headers.
+- Mathematical totals match across all sections.

package/native-skills/media/screenplay-and-shotlist-forge/SKILL.md

@@ -0,0 +1,42 @@
+---
+name: screenplay-and-shotlist-forge
+description: Format professional Hollywood screenplays in Courier 12pt, create director production shot lists, and build voiceover timing cue sheets with Words-Per-Minute pacing analysis. Use for movie scripts, video storytelling, documentary shotlists, and audio dubbing timelines.
+---
+
+# Screenplay & Production Shot List Forge
+
+High-end cinematic storytelling and video production require standardized industry formatting so that directors, cinematographers, and editors can immediately execute on set and in the edit suite.
+
+## Specifications
+
+- **Screenplay Typography:** Courier 12pt monospaced font, exactly 6 lines per inch vertical rhythm.
+- **Screenplay Margins:** Left margin 1.5 inches; right, top, and bottom margins 1.0 inch.
+- **Pacing Standard:** Voiceover narration moves at 130 to 155 Words-Per-Minute for natural documentary cadence.
+
+## Workflow
+
+1. Format screenplay elements and layout.
+   - Author scenes using `document_forge` (`action: "format_screenplay"`, `screenplaySpec`).
+   - Format scene headings in uppercase, character cues indented 2.2 inches, and dialogue width constrained to 3.5 inches.
+   - **Done when:** script HTML and CSS with Courier 12pt specifications are generated.
+
+2. Build director's production shot list.
+   - Generate production shot lists with `document_forge` (`action: "format_shotlist"`, `shotList`).
+   - Assign camera framing (EWS, WS, MS, CU, ECU), lenses, movement, and audio cues.
+   - **Done when:** structured shot list grid is compiled with cumulative duration estimates.
+
+3. Analyze voiceover timing and narration pacing.
+   - Audit narration pacing with `document_forge` (`action: "analyze_vo"`, `voBlocks`).
+   - Ensure word density stays within 130 to 155 WPM for optimal documentary pacing.
+   - **Done when:** pacing status is confirmed as optimal across all audio blocks.
+
+4. Render and verify publication files.
+   - Render scripts or shot lists to vector PDF via `document_forge` (`action: "render_pdf"`).
+   - **Done when:** output PDF files exist and are verified visually.
+
+## Verification
+
+- `document_forge` returns `success: true`.
+- Screenplay HTML contains Courier 12pt typography and 1.5-inch left margin.
+- Shot list table summarizes total shots and total runtime.
+- Voiceover analysis confirms pacing within target WPM limits.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@causyne/agent",
-  "version": "1.10.21",
+  "version": "1.11.0",
   "description": "Agentic AI for software, tools, and computer workflows",
   "main": "bin/causyne.js",
   "type": "module",

package/src/acp/client.js

@@ -0,0 +1,235 @@
+import { spawn } from 'node:child_process';
+import { ACP_ERROR_CODES, ACP_METHODS, ACP_PROTOCOL_VERSION, isJsonRpcRequest, isJsonRpcResponse } from './protocol.js';
+const MAX_STDERR_CHARS = 4000;
+const MAX_UPDATE_CHARS = 200_000;
+export class AcpClient {
+    options;
+    child = null;
+    buffer = '';
+    stderrTail = '';
+    pending = new Map();
+    nextId = 1;
+    closed = false;
+    exitError = null;
+    constructor(options) {
+        this.options = options;
+    }
+    get command() {
+        return this.options.command;
+    }
+    async start() {
+        if (this.child)
+            throw new Error('client already started');
+        const args = this.options.args ?? [];
+        const child = spawn(this.options.command, args, {
+            cwd: this.options.cwd,
+            env: this.options.env ?? process.env,
+            stdio: ['pipe', 'pipe', 'pipe'],
+            windowsHide: true
+        });
+        this.child = child;
+        child.stdout.setEncoding('utf8');
+        child.stdout.on('data', (chunk) => {
+            this.buffer += chunk;
+            void this.drain();
+        });
+        child.stderr.setEncoding('utf8');
+        child.stderr.on('data', (chunk) => {
+            this.stderrTail = `${this.stderrTail}${chunk}`.slice(-MAX_STDERR_CHARS);
+        });
+        child.on('error', (error) => this.failAll(new Error(`agent process failed: ${error.message}`)));
+        child.on('exit', (code, signal) => {
+            const detail = this.stderrTail.trim() || `exit code ${code ?? 'null'}${signal ? ` signal ${signal}` : ''}`;
+            this.failAll(new Error(`agent process exited: ${detail}`));
+        });
+        const params = {
+            protocolVersion: ACP_PROTOCOL_VERSION,
+            clientCapabilities: {
+                fs: { readTextFile: false, writeTextFile: false },
+                terminal: false,
+                session: { notices: false }
+            },
+            clientInfo: { name: 'Causyne Agent', version: this.options.clientVersion ?? '0.0.0' }
+        };
+        return await this.request(ACP_METHODS.INITIALIZE, params, 30_000);
+    }
+    async newSession(cwd, mcpServers = []) {
+        const result = await this.request(ACP_METHODS.NEW_SESSION, {
+            cwd,
+            mcpServers
+        }, 30_000);
+        if (!result || typeof result.sessionId !== 'string' || !result.sessionId) {
+            throw new Error('agent did not return a session id');
+        }
+        return result.sessionId;
+    }
+    async prompt(sessionId, text) {
+        const blocks = [{ type: 'text', text }];
+        let collected = '';
+        const collector = (update) => {
+            if (update.sessionUpdate === 'agent_message_chunk' && update.content.type === 'text') {
+                collected = `${collected}${update.content.text}`.slice(0, MAX_UPDATE_CHARS);
+            }
+        };
+        const previous = this.updateListener;
+        this.updateListener = (sessionIdFromEvent, update) => {
+            previous?.(sessionIdFromEvent, update);
+            if (sessionIdFromEvent === sessionId)
+                collector(update);
+        };
+        try {
+            const response = await this.request(ACP_METHODS.PROMPT, {
+                sessionId,
+                prompt: blocks
+            }, this.options.promptTimeoutMs ?? 15 * 60 * 1000);
+            return {
+                stopReason: response?.stopReason ?? 'end_turn',
+                text: collected
+            };
+        }
+        finally {
+            this.updateListener = previous;
+        }
+    }
+    notifyCancel(sessionId) {
+        this.write({
+            jsonrpc: '2.0',
+            method: ACP_METHODS.CANCEL,
+            params: { sessionId }
+        });
+    }
+    async close() {
+        if (this.closed)
+            return;
+        this.closed = true;
+        const child = this.child;
+        this.failAll(new Error('client closed'));
+        if (!child)
+            return;
+        await new Promise((resolve) => {
+            const timer = setTimeout(() => {
+                child.kill('SIGKILL');
+                resolve();
+            }, 1500);
+            child.once('exit', () => {
+                clearTimeout(timer);
+                resolve();
+            });
+            child.kill('SIGTERM');
+        });
+        this.child = null;
+    }
+    updateListener = null;
+    write(message) {
+        if (!this.child || this.closed)
+            return;
+        try {
+            this.child.stdin.write(`${JSON.stringify(message)}\n`);
+        }
+        catch {
+            // A dead pipe surfaces through the exit handler.
+        }
+    }
+    async drain() {
+        let index = this.buffer.indexOf('\n');
+        while (index >= 0) {
+            const line = this.buffer.slice(0, index).trim();
+            this.buffer = this.buffer.slice(index + 1);
+            if (line)
+                await this.handleLine(line);
+            index = this.buffer.indexOf('\n');
+        }
+    }
+    async handleLine(line) {
+        let parsed;
+        try {
+            parsed = JSON.parse(line);
+        }
+        catch {
+            return;
+        }
+        if (isJsonRpcResponse(parsed)) {
+            this.settle(parsed);
+            return;
+        }
+        if (isJsonRpcRequest(parsed)) {
+            await this.handleServerRequest(parsed);
+            return;
+        }
+        const method = parsed.method;
+        if (method === ACP_METHODS.UPDATE) {
+            const params = parsed.params;
+            if (params && typeof params.sessionId === 'string' && params.update) {
+                this.updateListener?.(params.sessionId, params.update);
+            }
+        }
+    }
+    async handleServerRequest(request) {
+        if (request.method === ACP_METHODS.REQUEST_PERMISSION) {
+            const handler = this.options.permissionHandler;
+            if (!handler) {
+                this.write({
+                    jsonrpc: '2.0',
+                    id: request.id,
+                    result: { outcome: { outcome: 'cancelled' } }
+                });
+                return;
+            }
+            try {
+                const outcome = await handler(request.params);
+                this.write({ jsonrpc: '2.0', id: request.id, result: { outcome } });
+            }
+            catch {
+                this.write({ jsonrpc: '2.0', id: request.id, result: { outcome: { outcome: 'cancelled' } } });
+            }
+            return;
+        }
+        this.write({
+            jsonrpc: '2.0',
+            id: request.id,
+            error: { code: ACP_ERROR_CODES.METHOD_NOT_FOUND, message: `Unsupported client method: ${request.method}` }
+        });
+    }
+    settle(response) {
+        if (response.id === null || response.id === undefined)
+            return;
+        const pending = this.pending.get(response.id);
+        if (!pending)
+            return;
+        clearTimeout(pending.timer);
+        this.pending.delete(response.id);
+        if (response.error) {
+            pending.reject(new Error(`${pending.method} failed: ${response.error.message}`));
+            return;
+        }
+        pending.resolve(response.result);
+    }
+    request(method, params, timeoutMs) {
+        if (!this.child || this.closed)
+            return Promise.reject(new Error('agent process is not running'));
+        if (this.exitError)
+            return Promise.reject(this.exitError);
+        const id = this.nextId++;
+        return new Promise((resolve, reject) => {
+            const timer = setTimeout(() => {
+                this.pending.delete(id);
+                reject(new Error(`${method} timed out after ${timeoutMs}ms`));
+            }, timeoutMs);
+            this.pending.set(id, {
+                resolve: (value) => resolve(value),
+                reject,
+                timer,
+                method
+            });
+            this.write({ jsonrpc: '2.0', id, method, params });
+        });
+    }
+    failAll(error) {
+        this.exitError = error;
+        for (const [id, pending] of this.pending) {
+            clearTimeout(pending.timer);
+            pending.reject(error);
+            this.pending.delete(id);
+        }
+    }
+}

package/src/acp/client.ts

@@ -0,0 +1,282 @@
+import { spawn } from 'node:child_process';
+import type { ChildProcessWithoutNullStreams } from 'node:child_process';
+import {
+  ACP_ERROR_CODES,
+  ACP_METHODS,
+  ACP_PROTOCOL_VERSION,
+  isJsonRpcRequest,
+  isJsonRpcResponse
+} from './protocol.js';
+import type {
+  ContentBlock,
+  InitializeRequest,
+  InitializeResult,
+  JsonRpcNotification,
+  JsonRpcRequest,
+  JsonRpcResponse,
+  PromptResponse,
+  RequestPermissionRequest,
+  RequestPermissionResponse,
+  SessionNotification,
+  SessionUpdate
+} from './protocol.js';
+
+export interface AcpClientOptions {
+  command: string;
+  args?: string[];
+  cwd: string;
+  env?: NodeJS.ProcessEnv;
+  clientVersion?: string;
+  promptTimeoutMs?: number;
+  permissionHandler?: (request: RequestPermissionRequest) => Promise<RequestPermissionResponse['outcome']>;
+}
+
+export interface AcpPromptResult {
+  stopReason: PromptResponse['stopReason'];
+  text: string;
+}
+
+interface PendingRequest {
+  resolve: (value: unknown) => void;
+  reject: (error: Error) => void;
+  timer: NodeJS.Timeout;
+  method: string;
+}
+
+const MAX_STDERR_CHARS = 4000;
+const MAX_UPDATE_CHARS = 200_000;
+
+export class AcpClient {
+  private readonly options: AcpClientOptions;
+  private child: ChildProcessWithoutNullStreams | null = null;
+  private buffer = '';
+  private stderrTail = '';
+  private readonly pending = new Map<string | number, PendingRequest>();
+  private nextId = 1;
+  private closed = false;
+  private exitError: Error | null = null;
+
+  constructor(options: AcpClientOptions) {
+    this.options = options;
+  }
+
+  get command(): string {
+    return this.options.command;
+  }
+
+  async start(): Promise<InitializeResult> {
+    if (this.child) throw new Error('client already started');
+    const args = this.options.args ?? [];
+    const child = spawn(this.options.command, args, {
+      cwd: this.options.cwd,
+      env: this.options.env ?? process.env,
+      stdio: ['pipe', 'pipe', 'pipe'],
+      windowsHide: true
+    });
+    this.child = child;
+
+    child.stdout.setEncoding('utf8');
+    child.stdout.on('data', (chunk: string) => {
+      this.buffer += chunk;
+      void this.drain();
+    });
+    child.stderr.setEncoding('utf8');
+    child.stderr.on('data', (chunk: string) => {
+      this.stderrTail = `${this.stderrTail}${chunk}`.slice(-MAX_STDERR_CHARS);
+    });
+    child.on('error', (error) => this.failAll(new Error(`agent process failed: ${error.message}`)));
+    child.on('exit', (code, signal) => {
+      const detail = this.stderrTail.trim() || `exit code ${code ?? 'null'}${signal ? ` signal ${signal}` : ''}`;
+      this.failAll(new Error(`agent process exited: ${detail}`));
+    });
+
+    const params: InitializeRequest = {
+      protocolVersion: ACP_PROTOCOL_VERSION,
+      clientCapabilities: {
+        fs: { readTextFile: false, writeTextFile: false },
+        terminal: false,
+        session: { notices: false }
+      },
+      clientInfo: { name: 'Causyne Agent', version: this.options.clientVersion ?? '0.0.0' }
+    };
+    return await this.request<InitializeResult>(ACP_METHODS.INITIALIZE, params, 30_000);
+  }
+
+  async newSession(cwd: string, mcpServers: unknown[] = []): Promise<string> {
+    const result = await this.request<{ sessionId?: unknown }>(ACP_METHODS.NEW_SESSION, {
+      cwd,
+      mcpServers
+    }, 30_000);
+    if (!result || typeof result.sessionId !== 'string' || !result.sessionId) {
+      throw new Error('agent did not return a session id');
+    }
+    return result.sessionId;
+  }
+
+  async prompt(sessionId: string, text: string): Promise<AcpPromptResult> {
+    const blocks: ContentBlock[] = [{ type: 'text', text }];
+    let collected = '';
+    const collector = (update: SessionUpdate): void => {
+      if (update.sessionUpdate === 'agent_message_chunk' && update.content.type === 'text') {
+        collected = `${collected}${update.content.text}`.slice(0, MAX_UPDATE_CHARS);
+      }
+    };
+    const previous = this.updateListener;
+    this.updateListener = (sessionIdFromEvent, update) => {
+      previous?.(sessionIdFromEvent, update);
+      if (sessionIdFromEvent === sessionId) collector(update);
+    };
+    try {
+      const response = await this.request<PromptResponse>(ACP_METHODS.PROMPT, {
+        sessionId,
+        prompt: blocks
+      }, this.options.promptTimeoutMs ?? 15 * 60 * 1000);
+      return {
+        stopReason: response?.stopReason ?? 'end_turn',
+        text: collected
+      };
+    } finally {
+      this.updateListener = previous;
+    }
+  }
+
+  notifyCancel(sessionId: string): void {
+    this.write({
+      jsonrpc: '2.0',
+      method: ACP_METHODS.CANCEL,
+      params: { sessionId }
+    });
+  }
+
+  async close(): Promise<void> {
+    if (this.closed) return;
+    this.closed = true;
+    const child = this.child;
+    this.failAll(new Error('client closed'));
+    if (!child) return;
+    await new Promise<void>((resolve) => {
+      const timer = setTimeout(() => {
+        child.kill('SIGKILL');
+        resolve();
+      }, 1500);
+      child.once('exit', () => {
+        clearTimeout(timer);
+        resolve();
+      });
+      child.kill('SIGTERM');
+    });
+    this.child = null;
+  }
+
+  private updateListener: ((sessionId: string, update: SessionUpdate) => void) | null = null;
+
+  private write(message: JsonRpcRequest<unknown> | JsonRpcResponse | JsonRpcNotification<unknown>): void {
+    if (!this.child || this.closed) return;
+    try {
+      this.child.stdin.write(`${JSON.stringify(message)}\n`);
+    } catch {
+      // A dead pipe surfaces through the exit handler.
+    }
+  }
+
+  private async drain(): Promise<void> {
+    let index = this.buffer.indexOf('\n');
+    while (index >= 0) {
+      const line = this.buffer.slice(0, index).trim();
+      this.buffer = this.buffer.slice(index + 1);
+      if (line) await this.handleLine(line);
+      index = this.buffer.indexOf('\n');
+    }
+  }
+
+  private async handleLine(line: string): Promise<void> {
+    let parsed: unknown;
+    try {
+      parsed = JSON.parse(line);
+    } catch {
+      return;
+    }
+    if (isJsonRpcResponse(parsed)) {
+      this.settle(parsed);
+      return;
+    }
+    if (isJsonRpcRequest(parsed)) {
+      await this.handleServerRequest(parsed);
+      return;
+    }
+    const method = (parsed as { method?: unknown }).method;
+    if (method === ACP_METHODS.UPDATE) {
+      const params = (parsed as { params?: SessionNotification }).params;
+      if (params && typeof params.sessionId === 'string' && params.update) {
+        this.updateListener?.(params.sessionId, params.update);
+      }
+    }
+  }
+
+  private async handleServerRequest(request: JsonRpcRequest): Promise<void> {
+    if (request.method === ACP_METHODS.REQUEST_PERMISSION) {
+      const handler = this.options.permissionHandler;
+      if (!handler) {
+        this.write({
+          jsonrpc: '2.0',
+          id: request.id,
+          result: { outcome: { outcome: 'cancelled' } } satisfies RequestPermissionResponse
+        });
+        return;
+      }
+      try {
+        const outcome = await handler(request.params as unknown as RequestPermissionRequest);
+        this.write({ jsonrpc: '2.0', id: request.id, result: { outcome } });
+      } catch {
+        this.write({ jsonrpc: '2.0', id: request.id, result: { outcome: { outcome: 'cancelled' } } });
+      }
+      return;
+    }
+    this.write({
+      jsonrpc: '2.0',
+      id: request.id,
+      error: { code: ACP_ERROR_CODES.METHOD_NOT_FOUND, message: `Unsupported client method: ${request.method}` }
+    });
+  }
+
+  private settle(response: JsonRpcResponse): void {
+    if (response.id === null || response.id === undefined) return;
+    const pending = this.pending.get(response.id);
+    if (!pending) return;
+    clearTimeout(pending.timer);
+    this.pending.delete(response.id);
+    if (response.error) {
+      pending.reject(new Error(`${pending.method} failed: ${response.error.message}`));
+      return;
+    }
+    pending.resolve(response.result);
+  }
+
+  private request<T>(method: string, params: unknown, timeoutMs: number): Promise<T> {
+    if (!this.child || this.closed) return Promise.reject(new Error('agent process is not running'));
+    if (this.exitError) return Promise.reject(this.exitError);
+    const id = this.nextId++;
+    return new Promise<T>((resolve, reject) => {
+      const timer = setTimeout(() => {
+        this.pending.delete(id);
+        reject(new Error(`${method} timed out after ${timeoutMs}ms`));
+      }, timeoutMs);
+      this.pending.set(id, {
+        resolve: (value) => resolve(value as T),
+        reject,
+        timer,
+        method
+      });
+      this.write({ jsonrpc: '2.0', id, method, params });
+    });
+  }
+
+  private failAll(error: Error): void {
+    this.exitError = error;
+    for (const [id, pending] of this.pending) {
+      clearTimeout(pending.timer);
+      pending.reject(error);
+      this.pending.delete(id);
+    }
+  }
+}