@fpr1m3/opencode-pai-plugin 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 fprime
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,79 @@
+# OpenCode PAI Plugin
+
+A native OpenCode plugin that implements the **Personal AI Infrastructure (PAI)** logic, replacing legacy hook scripts with a cohesive, lifecycle-aware system.
+
+## Credits & Inspiration
+
+This project is an OpenCode-compatible clone of the hook system from **Dan Miessler's** [Personal AI Infrastructure (PAI)](https://github.com/danielmiessler/Personal_AI_Infrastructure) project. A massive shout out to Dan for the architectural vision and the original PAI patterns that this plugin brings to the OpenCode ecosystem.
+
+---
+
+**Disclaimer**: This project is independent and is **not** supported by, affiliated with, or endorsed by Dan Miessler or the OpenCode team.
+
+## Features
+
+### 1. Identity & Context Injection
+*   **Core Skill Loading**: Automatically injects your `skills/core/SKILL.md` (from `PAI_DIR`) into the system prompt.
+*   **Dynamic Substitution**: Supports placeholders like `{{DA}}`, `{{DA_COLOR}}`, and `{{ENGINEER_NAME}}` for personalized interactions.
+*   **Project Requirements**: Automatically detects and loads `.opencode/dynamic-requirements.md` from your current project, allowing for task-specific instructions.
+
+### 2. Intelligent History & Logging
+*   **Real-time Event Capture**: Logs all tool calls and SDK events to `PAI_DIR/history/raw-outputs` in an analytics-ready JSONL format.
+*   **Session Summaries**: Generates human-readable Markdown summaries in `PAI_DIR/history/sessions` at the end of every session, tracking files modified, tools used, and commands executed.
+*   **Agent Mapping**: Tracks session-to-agent relationships (e.g., mapping a subagent session to its specialized type).
+
+### 3. Security & Safety
+*   **Security Validator**: A built-in firewall that scans Bash commands for dangerous patterns (reverse shells, recursive deletions, prompt injections) via the `permission.ask` hook.
+*   **Safe Confirmations**: Automatically triggers a confirmation prompt for risky but potentially legitimate operations like forced Git pushes.
+
+### 4. Interactive Feedback
+*   **Real-time Tab Titles**: Updates your terminal tab title *instantly* when a tool starts (e.g., `Running bash...`, `Editing index.ts...`).
+*   **Post-Task Summaries**: Updates the tab title with a concise summary of what was accomplished when a task is completed.
+
+## Configuration
+
+The plugin centers around the `PAI_DIR` environment variable.
+
+| Variable | Description | Default |
+| :--- | :--- | :--- |
+| `PAI_DIR` | Root directory for PAI skills and history | `$XDG_CONFIG_HOME/opencode` |
+| `DA` | Name of your Digital Assistant | `PAI` |
+| `ENGINEER_NAME` | Your name/identity | `Operator` |
+| `DA_COLOR` | UI color theme for your DA | `blue` |
+
+## Quick Start
+
+Add the plugin to your global `opencode.json` configuration file (typically located at `~/.config/opencode/opencode.json`). OpenCode will automatically install the plugin from GitHub on its next startup.
+
+```json
+{
+  "plugins": [
+    "github:fpr1m3/opencode-pai-plugin"
+  ]
+}
+```
+
+Upon first run, the plugin will automatically:
+1. Detect or create your `PAI_DIR` (default: `$XDG_CONFIG_HOME/opencode`).
+2. Initialize the required directory structure for skills and history.
+3. Create a default `SKILL.md` core identity if one does not exist.
+
+## Development & Testing
+
+We provide scripts to verify the plugin in a pristine environment:
+
+*   `./scripts/create-test-env.sh`: Creates a fresh, isolated OpenCode project for testing.
+*   `./scripts/test-full-flow.sh`: Runs a complete E2E verification of the plugin lifecycle.
+
+## Roadmap / TODO
+
+- [ ] **Voice Server Integration**: Implementation of the PAI voice notification server to provide audible feedback on task completion.
+- [ ] **Enhanced Agent Mapping**: More granular tracking of subagent state transitions.
+
+---
+
+**Note**: This plugin is designed to work with the PAI ecosystem. While it auto-initializes a basic structure, you can customize your identity by editing `$PAI_DIR/skills/core/SKILL.md`.
+
+---
+
+Vibe coded with ❤️ by a mix of **Claude Code** and **OpenCode**.

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+import type { Plugin } from '@opencode-ai/plugin';
+export declare const PAIPlugin: Plugin;
+export default PAIPlugin;

package/dist/index.js

@@ -0,0 +1,226 @@
+import { Logger } from './lib/logger';
+import { PAI_DIR } from './lib/paths';
+import { validateCommand } from './lib/security';
+import { join } from 'path';
+import { existsSync, readFileSync, mkdirSync, writeFileSync } from 'fs';
+/**
+ * Ensure the PAI directory structure exists.
+ */
+function ensurePAIStructure() {
+    const dirs = [
+        join(PAI_DIR, 'skills', 'core'),
+        join(PAI_DIR, 'history', 'raw-outputs'),
+        join(PAI_DIR, 'history', 'sessions'),
+        join(PAI_DIR, 'history', 'system-logs'),
+    ];
+    for (const dir of dirs) {
+        if (!existsSync(dir)) {
+            try {
+                mkdirSync(dir, { recursive: true });
+                console.log(`PAI: Created directory ${dir}`);
+            }
+            catch (e) {
+                console.error(`PAI: Failed to create directory ${dir}:`, e);
+            }
+        }
+    }
+    const coreSkillPath = join(PAI_DIR, 'skills', 'core', 'SKILL.md');
+    if (!existsSync(coreSkillPath)) {
+        const defaultSkill = `# PAI Core Identity
+You are {{DA}}, a Personal AI Infrastructure. 
+Your primary engineer is {{ENGINEER_NAME}}.
+`;
+        try {
+            writeFileSync(coreSkillPath, defaultSkill, 'utf-8');
+            console.log(`PAI: Created default SKILL.md at ${coreSkillPath}`);
+        }
+        catch (e) {
+            console.error(`PAI: Failed to create default SKILL.md:`, e);
+        }
+    }
+}
+/**
+ * Check if an event should be skipped to prevent recursive logging.
+ */
+function shouldSkipEvent(event, sessionId) {
+    // Skip file watcher events for raw-outputs directory or history directory
+    if (event.type === 'file.watcher.updated') {
+        const file = event.properties?.file;
+        if (typeof file === 'string' && (file.includes('raw-outputs/') || file.includes('history/'))) {
+            return true;
+        }
+    }
+    // Skip message.updated events with self-referencing diffs
+    if (sessionId && event.type === 'message.updated') {
+        const info = event.properties?.info;
+        const diffs = info?.summary?.diffs;
+        if (Array.isArray(diffs)) {
+            const hasSelfRef = diffs.some((diff) => typeof diff?.file === 'string' &&
+                diff.file.includes('history/') &&
+                diff.file.includes(sessionId));
+            if (hasSelfRef)
+                return true;
+        }
+    }
+    return false;
+}
+/**
+ * Generate a 4-word tab title summarizing what was done
+ */
+function generateTabTitle(completedLine) {
+    if (completedLine) {
+        const cleanCompleted = completedLine
+            .replace(/\*+/g, '')
+            .replace(/\[.*?\]/g, '')
+            .replace(/🎯\s*COMPLETED:\s*/gi, '')
+            .replace(/COMPLETED:\s*/gi, '')
+            .trim();
+        const words = cleanCompleted.split(/\s+/)
+            .filter(word => word.length > 2 && !['the', 'and', 'but', 'for', 'are', 'with', 'this', 'that'].includes(word.toLowerCase()))
+            .map(word => word.charAt(0).toUpperCase() + word.slice(1).toLowerCase());
+        if (words.length >= 2) {
+            return words.slice(0, 4).join(' ');
+        }
+    }
+    return 'PAI Task Done';
+}
+export const PAIPlugin = async ({ worktree }) => {
+    let logger = null;
+    let currentSessionId = null;
+    // Auto-initialize PAI infrastructure if needed
+    ensurePAIStructure();
+    // Load CORE skill content from $PAI_DIR/skills/core/SKILL.md
+    let coreSkillContent = '';
+    const coreSkillPath = join(PAI_DIR, 'skills', 'core', 'SKILL.md');
+    if (existsSync(coreSkillPath)) {
+        try {
+            coreSkillContent = readFileSync(coreSkillPath, 'utf-8');
+        }
+        catch (e) {
+            console.error('PAI: Failed to read CORE skill:', e);
+        }
+    }
+    // Dynamic Variable Substitution for System Prompt
+    const daName = process.env.DA || 'PAI';
+    const engineerName = process.env.ENGINEER_NAME || 'Operator';
+    const daColor = process.env.DA_COLOR || 'blue';
+    const personalizedSkillContent = coreSkillContent
+        .replace(/\{\{DA\}\}/g, daName)
+        .replace(/\{\{DA_COLOR\}\}/g, daColor)
+        .replace(/\{\{ENGINEER_NAME\}\}/g, engineerName);
+    // Load project-specific dynamic requirements if they exist
+    let projectRequirements = '';
+    const projectReqPath = join(worktree, '.opencode', 'dynamic-requirements.md');
+    if (existsSync(projectReqPath)) {
+        try {
+            projectRequirements = readFileSync(projectReqPath, 'utf-8');
+            console.log(`PAI: Loaded project requirements from ${projectReqPath}`);
+        }
+        catch (e) {
+            console.error('PAI: Failed to read project requirements:', e);
+        }
+    }
+    console.log(`PAI Plugin Initialized (Personalized for ${engineerName} & ${daName})`);
+    // Ready to serve
+    const hooks = {
+        event: async ({ event }) => {
+            const anyEvent = event;
+            // Initialize Logger on session creation
+            if (event.type === 'session.created') {
+                currentSessionId = anyEvent.properties.info.id;
+                logger = new Logger(currentSessionId);
+            }
+            // Handle generic event logging
+            if (logger &&
+                event.type !== 'message.part.updated' &&
+                !shouldSkipEvent(event, currentSessionId)) {
+                logger.logOpenCodeEvent(event);
+            }
+            // Handle real-time tab title updates (Pre-Tool Use)
+            if (anyEvent.type === 'tool.call') {
+                const props = anyEvent.properties;
+                if (props?.tool === 'Bash' || props?.tool === 'bash') {
+                    const cmd = props?.input?.command?.split(/\s+/)[0] || 'bash';
+                    process.stderr.write(`\x1b]0;Running ${cmd}...\x07`);
+                }
+                else if (props?.tool === 'Edit' || props?.tool === 'Write') {
+                    const file = props?.input?.file_path?.split('/').pop() || 'file';
+                    process.stderr.write(`\x1b]0;Editing ${file}...\x07`);
+                }
+                else if (props?.tool === 'Task') {
+                    const type = props?.input?.subagent_type || 'agent';
+                    process.stderr.write(`\x1b]0;Agent: ${type}...\x07`);
+                }
+            }
+            // Handle assistant completion (Tab Titles)
+            if (event.type === 'message.updated') {
+                const info = anyEvent.properties?.info;
+                if (info?.author === 'assistant' && info?.content) {
+                    const content = typeof info.content === 'string' ? info.content : '';
+                    // Look for COMPLETED: line (can be prefaced by 🎯 or just text)
+                    const completedMatch = content.match(/(?:🎯\s*)?COMPLETED:\s*(.+?)(?:\n|$)/i);
+                    if (completedMatch) {
+                        const completedLine = completedMatch[1].trim();
+                        // Set Tab Title
+                        const tabTitle = generateTabTitle(completedLine);
+                        process.stderr.write(`\x1b]0;${tabTitle}\x07`);
+                    }
+                }
+            }
+            // Handle session deletion / end
+            if (event.type === 'session.deleted') {
+                if (logger) {
+                    await logger.generateSessionSummary();
+                    logger.flush();
+                }
+            }
+        },
+        "tool.execute.after": async (input, output) => {
+            if (logger) {
+                logger.logToolExecution(input, output);
+            }
+        },
+        "permission.ask": async (permission) => {
+            if (permission.tool === 'Bash' || permission.tool === 'bash') {
+                const command = permission.arguments?.command || '';
+                const result = validateCommand(command);
+                if (result.status === 'deny') {
+                    return {
+                        status: 'deny',
+                        feedback: result.feedback
+                    };
+                }
+                if (result.status === 'ask') {
+                    return { status: 'ask' };
+                }
+            }
+            return { status: 'allow' };
+        },
+        /**
+         * Experimental: Inject PAI Core identity into the system prompt
+         */
+        ...{
+            "experimental.chat.system.transform": async (input, output) => {
+                const skipAgents = ['title', 'summary', 'compaction'];
+                if (input.agent && skipAgents.includes(input.agent.name)) {
+                    return;
+                }
+                if (personalizedSkillContent && output.system && output.system.length > 0) {
+                    // system[0] is typically the caching-sensitive header, so we inject into system[1] or push
+                    let injection = `\n\n--- PAI CORE IDENTITY ---\n${personalizedSkillContent}\n--- END PAI CORE IDENTITY ---\n\n`;
+                    if (projectRequirements) {
+                        injection += `\n\n--- PROJECT DYNAMIC REQUIREMENTS ---\n${projectRequirements}\n--- END PROJECT DYNAMIC REQUIREMENTS ---\n\n`;
+                    }
+                    if (output.system.length >= 2) {
+                        output.system[1] = injection + output.system[1];
+                    }
+                    else {
+                        output.system.push(injection);
+                    }
+                }
+            }
+        }
+    };
+    return hooks;
+};
+export default PAIPlugin;

package/dist/lib/context-loader.d.ts

@@ -0,0 +1 @@
+export declare function getCoreContext(baseDir: string, env: NodeJS.ProcessEnv): string;

package/dist/lib/context-loader.js

@@ -0,0 +1,21 @@
+import { readFileSync, existsSync } from 'fs';
+import { join } from 'path';
+import { getSkillsDir } from './paths';
+export function getCoreContext(baseDir, env) {
+    const skillsDir = getSkillsDir(baseDir);
+    const coreSkillPath = join(skillsDir, 'core', 'SKILL.md');
+    if (!existsSync(coreSkillPath)) {
+        console.warn(`Core skill file not found at ${coreSkillPath}`);
+        return '';
+    }
+    let content = readFileSync(coreSkillPath, 'utf-8');
+    // Variable replacement
+    const replacements = {
+        '{{DA}}': env.DA_NAME || 'PAI',
+        '{{ENGINEER_NAME}}': env.USER_NAME || env.USER || 'Engineer',
+    };
+    for (const [key, value] of Object.entries(replacements)) {
+        content = content.replaceAll(key, value);
+    }
+    return content;
+}

package/dist/lib/logger.d.ts

@@ -0,0 +1,35 @@
+import type { Event } from '@opencode-ai/sdk';
+export declare class Logger {
+    private sessionId;
+    private toolsUsed;
+    private filesChanged;
+    private commandsExecuted;
+    private startTime;
+    constructor(sessionId: string);
+    private getPSTTimestamp;
+    private getEventsFilePath;
+    private getSessionMappingFile;
+    private getAgentForSession;
+    private setAgentForSession;
+    logEvent(event: Event): void;
+    logOpenCodeEvent(event: Event): void;
+    /**
+     * Log tool execution from tool.execute.after hook
+     *
+     * Input structure: { tool: string; sessionID: string; callID: string }
+     * Output structure: { title: string; output: string; metadata: any }
+     */
+    logToolExecution(input: {
+        tool: string;
+        sessionID: string;
+        callID: string;
+    }, output: {
+        title: string;
+        output: string;
+        metadata: any;
+    }): void;
+    generateSessionSummary(): Promise<string | null>;
+    logError(context: string, error: any): void;
+    private writeEvent;
+    flush(): void;
+}

package/dist/lib/logger.js

@@ -0,0 +1,264 @@
+import { existsSync, mkdirSync, appendFileSync, readFileSync, writeFileSync } from 'fs';
+import { dirname, join } from 'path';
+import { PAI_DIR, getHistoryFilePath, HISTORY_DIR } from './paths';
+import { enrichEventWithAgentMetadata, isAgentSpawningCall } from './metadata-extraction';
+import { redactString, redactObject } from './redaction';
+export class Logger {
+    sessionId;
+    toolsUsed = new Set();
+    filesChanged = new Set();
+    commandsExecuted = [];
+    startTime = Date.now();
+    constructor(sessionId) {
+        this.sessionId = sessionId;
+    }
+    // Get PST timestamp
+    getPSTTimestamp() {
+        const date = new Date();
+        const pstDate = new Date(date.toLocaleString('en-US', { timeZone: process.env.TIME_ZONE || 'America/Los_Angeles' }));
+        const year = pstDate.getFullYear();
+        const month = String(pstDate.getMonth() + 1).padStart(2, '0');
+        const day = String(pstDate.getDate()).padStart(2, '0');
+        const hours = String(pstDate.getHours()).padStart(2, '0');
+        const minutes = String(pstDate.getMinutes()).padStart(2, '0');
+        const seconds = String(pstDate.getSeconds()).padStart(2, '0');
+        return `${year}-${month}-${day} ${hours}:${minutes}:${seconds} PST`;
+    }
+    getEventsFilePath() {
+        const now = new Date();
+        const pstDate = new Date(now.toLocaleString('en-US', { timeZone: process.env.TIME_ZONE || 'America/Los_Angeles' }));
+        const year = pstDate.getFullYear();
+        const month = String(pstDate.getMonth() + 1).padStart(2, '0');
+        const day = String(pstDate.getDate()).padStart(2, '0');
+        const filename = `${year}-${month}-${day}_all-events.jsonl`;
+        const filePath = getHistoryFilePath('raw-outputs', filename);
+        const dir = dirname(filePath);
+        if (!existsSync(dir)) {
+            mkdirSync(dir, { recursive: true });
+        }
+        return filePath;
+    }
+    getSessionMappingFile() {
+        return join(PAI_DIR, 'agent-sessions.json');
+    }
+    getAgentForSession(sessionId) {
+        try {
+            const mappingFile = this.getSessionMappingFile();
+            if (existsSync(mappingFile)) {
+                const mappings = JSON.parse(readFileSync(mappingFile, 'utf-8'));
+                return mappings[sessionId] || 'pai';
+            }
+        }
+        catch (error) {
+            // Ignore errors, default to pai
+        }
+        return 'pai';
+    }
+    setAgentForSession(sessionId, agentName) {
+        try {
+            const mappingFile = this.getSessionMappingFile();
+            let mappings = {};
+            if (existsSync(mappingFile)) {
+                mappings = JSON.parse(readFileSync(mappingFile, 'utf-8'));
+            }
+            mappings[sessionId] = agentName;
+            writeFileSync(mappingFile, JSON.stringify(mappings, null, 2), 'utf-8');
+        }
+        catch (error) {
+            // Silently fail - don't block
+        }
+    }
+    logEvent(event) {
+        // Legacy method, not used much as we use logOpenCodeEvent
+        // But might be called from index.ts if I didn't update all calls
+        this.logOpenCodeEvent(event);
+    }
+    // Method to log generic OpenCode event
+    logOpenCodeEvent(event) {
+        const anyEvent = event;
+        const timestamp = anyEvent.timestamp || Date.now();
+        const payload = {
+            ...anyEvent.properties,
+            timestamp: timestamp
+        };
+        // Track stats for summary
+        if (anyEvent.type === 'tool.call' || anyEvent.type === 'tool.execute.before') {
+            const props = anyEvent.properties;
+            const tool = props?.tool || props?.tool_name;
+            if (tool) {
+                this.toolsUsed.add(tool);
+                if (tool === 'Bash' || tool === 'bash') {
+                    const command = props?.input?.command || props?.tool_input?.command;
+                    if (command)
+                        this.commandsExecuted.push(redactString(command));
+                }
+                if (['Edit', 'Write', 'edit', 'write'].includes(tool)) {
+                    const path = props?.input?.file_path || props?.input?.path ||
+                        props?.tool_input?.file_path || props?.tool_input?.path;
+                    if (path)
+                        this.filesChanged.add(path);
+                }
+            }
+        }
+        this.writeEvent(anyEvent.type, redactObject(payload));
+    }
+    /**
+     * Log tool execution from tool.execute.after hook
+     *
+     * Input structure: { tool: string; sessionID: string; callID: string }
+     * Output structure: { title: string; output: string; metadata: any }
+     */
+    logToolExecution(input, output) {
+        const toolName = input.tool;
+        const sessionId = this.sessionId;
+        this.toolsUsed.add(toolName);
+        // Extract metadata - may contain additional tool info
+        const metadata = output.metadata || {};
+        // Logic to update agent mapping based on Task tool spawning subagents
+        if (toolName === 'Task' && metadata?.subagent_type) {
+            this.setAgentForSession(sessionId, metadata.subagent_type);
+        }
+        else if (toolName === 'subagent_stop' || toolName === 'stop') {
+            this.setAgentForSession(sessionId, 'pai');
+        }
+        const payload = {
+            tool_name: toolName,
+            tool_title: output.title,
+            tool_output: output.output,
+            tool_metadata: metadata,
+            call_id: input.callID,
+        };
+        this.writeEvent('ToolUse', redactObject(payload), toolName, metadata);
+    }
+    async generateSessionSummary() {
+        try {
+            const now = new Date();
+            const timestamp = now.toISOString()
+                .replace(/:/g, '')
+                .replace(/\..+/, '')
+                .replace('T', '-'); // YYYY-MM-DD-HHMMSS
+            const yearMonth = timestamp.substring(0, 7);
+            const date = timestamp.substring(0, 10);
+            const time = timestamp.substring(11).replace(/-/g, ':');
+            const duration = Math.round((Date.now() - this.startTime) / 60000);
+            const sessionDir = join(HISTORY_DIR, 'sessions', yearMonth);
+            if (!existsSync(sessionDir)) {
+                mkdirSync(sessionDir, { recursive: true });
+            }
+            const focus = this.filesChanged.size > 0 ? 'development' : 'research';
+            const filename = `${timestamp}_SESSION_${focus}.md`;
+            const filePath = join(sessionDir, filename);
+            const summary = `---
+capture_type: SESSION
+timestamp: ${new Date().toISOString()}
+session_id: ${this.sessionId}
+duration_minutes: ${duration}
+executor: pai
+---
+
+# Session: ${focus}
+
+**Date:** ${date}
+**Time:** ${time}
+**Session ID:** ${this.sessionId}
+
+---
+
+## Session Overview
+
+**Focus:** ${focus === 'development' ? 'Software development and code modification' : 'Research and general assistance'}
+**Duration:** ${duration} minutes
+
+---
+
+## Tools Used
+
+${this.toolsUsed.size > 0 ? Array.from(this.toolsUsed).map(t => `- ${t}`).sort().join('\n') : '- None recorded'}
+
+---
+
+## Files Modified
+
+${this.filesChanged.size > 0 ? Array.from(this.filesChanged).map(f => `- \`${f}\``).sort().join('\n') : '- None recorded'}
+
+**Total Files Changed:** ${this.filesChanged.size}
+
+---
+
+## Commands Executed
+
+${this.commandsExecuted.length > 0 ? '```bash\n' + this.commandsExecuted.slice(0, 20).join('\n') + '\n```' : 'None recorded'}
+
+---
+
+## Notes
+
+This session summary was automatically generated by the PAI OpenCode Plugin.
+
+---
+
+**Session Outcome:** Completed
+**Generated:** ${new Date().toISOString()}
+`;
+            writeFileSync(filePath, summary);
+            return filePath;
+        }
+        catch (error) {
+            this.logError('SessionSummary', error);
+            return null;
+        }
+    }
+    logError(context, error) {
+        try {
+            const now = new Date();
+            const pstDate = new Date(now.toLocaleString('en-US', { timeZone: process.env.TIME_ZONE || 'America/Los_Angeles' }));
+            const year = pstDate.getFullYear();
+            const month = String(pstDate.getMonth() + 1).padStart(2, '0');
+            const day = String(pstDate.getDate()).padStart(2, '0');
+            const filename = `${year}-${month}-${day}_errors.log`;
+            const filePath = getHistoryFilePath('system-logs', filename);
+            const dir = dirname(filePath);
+            if (!existsSync(dir)) {
+                mkdirSync(dir, { recursive: true });
+            }
+            const timestamp = this.getPSTTimestamp();
+            const errorMessage = error instanceof Error ? error.message : String(error);
+            const stack = error instanceof Error ? error.stack : '';
+            const logEntry = `[${timestamp}] [${context}] ${errorMessage}\n${stack}\n-------------------\n`;
+            appendFileSync(filePath, logEntry, 'utf-8');
+        }
+        catch (e) {
+            // Intentionally silent - TUI protection
+        }
+    }
+    // Core write method
+    writeEvent(eventType, payload, toolName, toolInput) {
+        const sessionId = this.sessionId;
+        let agentName = this.getAgentForSession(sessionId);
+        // Create base event object
+        let hookEvent = {
+            source_app: agentName,
+            session_id: sessionId,
+            hook_event_type: eventType,
+            payload: payload,
+            timestamp: Date.now(),
+            timestamp_pst: this.getPSTTimestamp()
+        };
+        // Enrich with agent instance metadata if this is a Task tool call
+        if (toolName && toolInput && isAgentSpawningCall(toolName, toolInput)) {
+            hookEvent = enrichEventWithAgentMetadata(hookEvent, toolInput, payload.description // Assuming description is available in payload if passed
+            );
+        }
+        try {
+            const eventsFile = this.getEventsFilePath();
+            const jsonLine = JSON.stringify(hookEvent) + '\n';
+            appendFileSync(eventsFile, jsonLine, 'utf-8');
+        }
+        catch (error) {
+            this.logError('EventCapture', error);
+        }
+    }
+    flush() {
+        // No-op for now as we append synchronously
+    }
+}

package/dist/lib/metadata-extraction.d.ts

@@ -0,0 +1,51 @@
+/**
+ * Metadata Extraction Library for UOCS Enhancement
+ *
+ * Extracts agent instance IDs, parent-child relationships, and session info
+ * from Task tool calls and other tool inputs.
+ *
+ * Design Philosophy: Optional extraction with graceful fallbacks
+ * - If instance IDs are present in descriptions/prompts, extract them
+ * - If not present, fall back to agent type only
+ * - Never fail - always return usable metadata
+ */
+export interface AgentInstanceMetadata {
+    agent_instance_id?: string;
+    agent_type?: string;
+    instance_number?: number;
+    parent_session_id?: string;
+    parent_task_id?: string;
+}
+/**
+ * Extract agent instance ID from Task tool input
+ *
+ * Looks for patterns in priority order:
+ * 1. [agent-type-N] in description (e.g., "Research topic [perplexity-researcher-1]")
+ * 2. [AGENT_INSTANCE: agent-type-N] in prompt
+ * 3. subagent_type field (fallback to just type, no instance number)
+ *
+ * @param toolInput The tool input object from PreToolUse/PostToolUse hooks
+ * @param description Optional description field from tool input
+ * @returns Metadata object with extracted information
+ */
+export declare function extractAgentInstanceId(toolInput: any, description?: string): AgentInstanceMetadata;
+/**
+ * Enrich event with agent metadata
+ *
+ * Takes a base event object and adds agent instance metadata to it.
+ * Returns a new object with merged metadata.
+ *
+ * @param event Base event object (from PreToolUse/PostToolUse)
+ * @param toolInput Tool input object
+ * @param description Optional description field
+ * @returns Enriched event with agent metadata
+ */
+export declare function enrichEventWithAgentMetadata(event: any, toolInput: any, description?: string): any;
+/**
+ * Check if a tool call is spawning a subagent
+ *
+ * @param toolName Name of the tool being called
+ * @param toolInput Tool input object
+ * @returns true if this is a Task tool call spawning an agent
+ */
+export declare function isAgentSpawningCall(toolName: string, toolInput: any): boolean;

package/dist/lib/metadata-extraction.js

@@ -0,0 +1,130 @@
+/**
+ * Metadata Extraction Library for UOCS Enhancement
+ *
+ * Extracts agent instance IDs, parent-child relationships, and session info
+ * from Task tool calls and other tool inputs.
+ *
+ * Design Philosophy: Optional extraction with graceful fallbacks
+ * - If instance IDs are present in descriptions/prompts, extract them
+ * - If not present, fall back to agent type only
+ * - Never fail - always return usable metadata
+ */
+/**
+ * Validate that an ID string contains only safe characters
+ * Allows alphanumeric, hyphens, and underscores.
+ * Prevents path traversal and injection attacks.
+ */
+function isValidId(id) {
+    return /^[a-zA-Z0-9\-_]+$/.test(id);
+}
+/**
+ * Extract agent instance ID from Task tool input
+ *
+ * Looks for patterns in priority order:
+ * 1. [agent-type-N] in description (e.g., "Research topic [perplexity-researcher-1]")
+ * 2. [AGENT_INSTANCE: agent-type-N] in prompt
+ * 3. subagent_type field (fallback to just type, no instance number)
+ *
+ * @param toolInput The tool input object from PreToolUse/PostToolUse hooks
+ * @param description Optional description field from tool input
+ * @returns Metadata object with extracted information
+ */
+export function extractAgentInstanceId(toolInput, description) {
+    const result = {};
+    // Strategy 1: Extract from description [agent-type-N]
+    // Example: "Research consumer complaints [perplexity-researcher-1]"
+    if (description) {
+        const descMatch = description.match(/\[([a-z-]+-researcher)-(\d+)\]/);
+        if (descMatch) {
+            result.agent_type = descMatch[1];
+            result.instance_number = parseInt(descMatch[2], 10);
+            result.agent_instance_id = `${result.agent_type}-${result.instance_number}`;
+        }
+    }
+    // Strategy 2: Extract from prompt [AGENT_INSTANCE: ...]
+    // Example: "[AGENT_INSTANCE: perplexity-researcher-1]"
+    if (!result.agent_instance_id && toolInput?.prompt && typeof toolInput.prompt === 'string') {
+        const promptMatch = toolInput.prompt.match(/\[AGENT_INSTANCE:\s*([^\]]+)\]/);
+        if (promptMatch) {
+            const extractedId = promptMatch[1].trim();
+            // Security: Validate ID format to prevent injection
+            if (isValidId(extractedId)) {
+                result.agent_instance_id = extractedId;
+                // Parse agent type and instance number from ID
+                const parts = result.agent_instance_id.match(/^([a-z-]+)-(\d+)$/);
+                if (parts) {
+                    result.agent_type = parts[1];
+                    result.instance_number = parseInt(parts[2], 10);
+                }
+            }
+        }
+    }
+    // Strategy 3: Extract parent session from prompt
+    // Example: "[PARENT_SESSION: b7062b5a-03d3-4168-9555-a748e0b2efa3]"
+    if (toolInput?.prompt && typeof toolInput.prompt === 'string') {
+        const parentSessionMatch = toolInput.prompt.match(/\[PARENT_SESSION:\s*([^\]]+)\]/);
+        if (parentSessionMatch) {
+            const extractedId = parentSessionMatch[1].trim();
+            if (isValidId(extractedId)) {
+                result.parent_session_id = extractedId;
+            }
+        }
+        // Extract parent task from prompt
+        // Example: "[PARENT_TASK: research_1731445892345]"
+        const parentTaskMatch = toolInput.prompt.match(/\[PARENT_TASK:\s*([^\]]+)\]/);
+        if (parentTaskMatch) {
+            const extractedId = parentTaskMatch[1].trim();
+            if (isValidId(extractedId)) {
+                result.parent_task_id = extractedId;
+            }
+        }
+    }
+    // Strategy 4: Fallback to subagent_type if available (no instance number)
+    // This ensures we at least capture the agent type even without instance IDs
+    if (!result.agent_type && toolInput?.subagent_type) {
+        result.agent_type = toolInput.subagent_type;
+    }
+    return result;
+}
+/**
+ * Enrich event with agent metadata
+ *
+ * Takes a base event object and adds agent instance metadata to it.
+ * Returns a new object with merged metadata.
+ *
+ * @param event Base event object (from PreToolUse/PostToolUse)
+ * @param toolInput Tool input object
+ * @param description Optional description field
+ * @returns Enriched event with agent metadata
+ */
+export function enrichEventWithAgentMetadata(event, toolInput, description) {
+    const metadata = extractAgentInstanceId(toolInput, description);
+    // Only add fields that have values (keep events clean)
+    const enrichedEvent = { ...event };
+    if (metadata.agent_instance_id) {
+        enrichedEvent.agent_instance_id = metadata.agent_instance_id;
+    }
+    if (metadata.agent_type) {
+        enrichedEvent.agent_type = metadata.agent_type;
+    }
+    if (metadata.instance_number !== undefined) {
+        enrichedEvent.instance_number = metadata.instance_number;
+    }
+    if (metadata.parent_session_id) {
+        enrichedEvent.parent_session_id = metadata.parent_session_id;
+    }
+    if (metadata.parent_task_id) {
+        enrichedEvent.parent_task_id = metadata.parent_task_id;
+    }
+    return enrichedEvent;
+}
+/**
+ * Check if a tool call is spawning a subagent
+ *
+ * @param toolName Name of the tool being called
+ * @param toolInput Tool input object
+ * @returns true if this is a Task tool call spawning an agent
+ */
+export function isAgentSpawningCall(toolName, toolInput) {
+    return toolName === 'Task' && toolInput?.subagent_type !== undefined;
+}

package/dist/lib/notifier.d.ts

@@ -0,0 +1 @@
+export declare function notifyVoiceServer(message: string): Promise<void>;

package/dist/lib/notifier.js

@@ -0,0 +1,12 @@
+export async function notifyVoiceServer(message) {
+    try {
+        await fetch('http://localhost:8888/notify', {
+            method: 'POST',
+            headers: { 'Content-Type': 'application/json' },
+            body: JSON.stringify({ message }),
+        });
+    }
+    catch (error) {
+        // Ignore errors if server is not running
+    }
+}

package/dist/lib/paths.d.ts

@@ -0,0 +1,22 @@
+/**
+ * PAI Path Resolution - Single Source of Truth
+ *
+ * This module provides consistent path resolution across all PAI hooks.
+ * It handles PAI_DIR detection whether set explicitly or defaulting to ~/.claude
+ *
+ * Usage in hooks:
+ *   import { PAI_DIR, HOOKS_DIR, SKILLS_DIR } from './lib/paths';
+ */
+export declare const PAI_DIR: string;
+/**
+ * Common PAI directories
+ */
+export declare const HOOKS_DIR: string;
+export declare const SKILLS_DIR: string;
+export declare const AGENTS_DIR: string;
+export declare const HISTORY_DIR: string;
+export declare const COMMANDS_DIR: string;
+/**
+ * Helper to get history file path with date-based organization
+ */
+export declare function getHistoryFilePath(subdir: string, filename: string): string;

package/dist/lib/paths.js

@@ -0,0 +1,55 @@
+/**
+ * PAI Path Resolution - Single Source of Truth
+ *
+ * This module provides consistent path resolution across all PAI hooks.
+ * It handles PAI_DIR detection whether set explicitly or defaulting to ~/.claude
+ *
+ * Usage in hooks:
+ *   import { PAI_DIR, HOOKS_DIR, SKILLS_DIR } from './lib/paths';
+ */
+import { homedir } from 'os';
+import { resolve, join } from 'path';
+import { existsSync } from 'fs';
+/**
+ * Smart PAI_DIR detection with fallback
+ * Priority:
+ * 1. PAI_DIR environment variable (if set)
+ * 2. $XDG_CONFIG_HOME/opencode (standard XDG location)
+ * 3. ~/.config/opencode (fallback if XDG_CONFIG_HOME is not set)
+ */
+const XDG_CONFIG_HOME = process.env.XDG_CONFIG_HOME || join(homedir(), '.config');
+export const PAI_DIR = process.env.PAI_DIR
+    ? resolve(process.env.PAI_DIR)
+    : resolve(XDG_CONFIG_HOME, 'opencode');
+/**
+ * Common PAI directories
+ */
+export const HOOKS_DIR = join(PAI_DIR, 'hooks');
+export const SKILLS_DIR = join(PAI_DIR, 'skills');
+export const AGENTS_DIR = join(PAI_DIR, 'agents');
+export const HISTORY_DIR = join(PAI_DIR, 'history');
+export const COMMANDS_DIR = join(PAI_DIR, 'commands');
+/**
+ * Validate PAI directory structure on first import
+ * This fails fast with a clear error if PAI is misconfigured
+ */
+function validatePAIStructure() {
+    // Only validate if we are actually in a context where we expect PAI to exist.
+    // For the plugin, we might not want to hard crash if the user hasn't set it up yet,
+    // but PAI plugin implies PAI usage.
+    // We will log a warning instead of exit(1) to be safer in a plugin environment.
+    if (!existsSync(PAI_DIR)) {
+        // console.warn(`⚠️ PAI_DIR does not exist: ${PAI_DIR}`);
+    }
+}
+validatePAIStructure();
+/**
+ * Helper to get history file path with date-based organization
+ */
+export function getHistoryFilePath(subdir, filename) {
+    const now = new Date();
+    const pstDate = new Date(now.toLocaleString('en-US', { timeZone: process.env.TIME_ZONE || 'America/Los_Angeles' }));
+    const year = pstDate.getFullYear();
+    const month = String(pstDate.getMonth() + 1).padStart(2, '0');
+    return join(HISTORY_DIR, subdir, `${year}-${month}`, filename);
+}

package/dist/lib/redaction.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Redaction utility to scrub sensitive data from logs
+ */
+export declare function redactString(str: string): string;
+export declare function redactObject(obj: any, visited?: WeakSet<any>): any;

package/dist/lib/redaction.js

@@ -0,0 +1,75 @@
+/**
+ * Redaction utility to scrub sensitive data from logs
+ */
+const SENSITIVE_KEYS = [
+    'api_key', 'apikey', 'secret', 'token', 'password', 'passwd', 'pwd',
+    'auth', 'credential', 'private_key', 'client_secret', 'access_key'
+];
+const SECRET_PATTERNS = [
+    // AWS Access Key ID
+    /\b(AKIA|ASIA)[0-9A-Z]{16}\b/g,
+    // GitHub Personal Access Token (classic)
+    /\bghp_[a-zA-Z0-9]{36}\b/g,
+    // Generic Private Key
+    /-----BEGIN [A-Z ]+ PRIVATE KEY-----/g,
+    // Bearer Token (simple heuristic - starts with Bearer, followed by base64-ish chars)
+    /\bBearer\s+[a-zA-Z0-9\-\._~+/]+=*/g,
+];
+// Regex for Key-Value assignments like "key=value" or "key: value" where key is sensitive
+// This catches "export AWS_SECRET_KEY=..." or JSON "password": "..."
+// We construct this dynamically from SENSITIVE_KEYS
+const SENSITIVE_KEY_PATTERN = new RegExp(`\\b([a-zA-Z0-9_]*(${SENSITIVE_KEYS.join('|')})[a-zA-Z0-9_]*)\\s*[:=]\\s*['"]?([^\\s'"]{8,})['"]?`, 'gi');
+export function redactString(str) {
+    if (!str)
+        return str;
+    let redacted = str;
+    // 1. Redact specific patterns (like AWS keys)
+    for (const pattern of SECRET_PATTERNS) {
+        redacted = redacted.replace(pattern, '[REDACTED]');
+    }
+    // 2. Redact key-value pairs where key suggests sensitivity
+    // We use a callback to preserve the key and redact the value
+    redacted = redacted.replace(SENSITIVE_KEY_PATTERN, (match, key, keyword, value) => {
+        // If value is already redacted, skip
+        if (value === '[REDACTED]')
+            return match;
+        // Replace the value part with [REDACTED]
+        return match.replace(value, '[REDACTED]');
+    });
+    return redacted;
+}
+export function redactObject(obj, visited = new WeakSet()) {
+    if (obj === null || obj === undefined)
+        return obj;
+    if (typeof obj === 'string') {
+        return redactString(obj);
+    }
+    if (typeof obj !== 'object') {
+        return obj;
+    }
+    if (obj instanceof Date) {
+        return obj;
+    }
+    if (visited.has(obj)) {
+        return '[CIRCULAR]';
+    }
+    visited.add(obj);
+    if (Array.isArray(obj)) {
+        return obj.map(item => redactObject(item, visited));
+    }
+    if (typeof obj === 'object') {
+        const newObj = {};
+        for (const [key, value] of Object.entries(obj)) {
+            // If the key itself is sensitive, redact the value blindly if it's a string/number
+            const isSensitiveKey = SENSITIVE_KEYS.some(k => key.toLowerCase().includes(k));
+            if (isSensitiveKey && (typeof value === 'string' || typeof value === 'number')) {
+                newObj[key] = '[REDACTED]';
+            }
+            else {
+                newObj[key] = redactObject(value, visited);
+            }
+        }
+        return newObj;
+    }
+    return obj;
+}

package/dist/lib/security.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Security Library for PAI Plugin
+ * Ported from legacy security-validator.ts
+ */
+export interface SecurityResult {
+    status: 'allow' | 'deny' | 'ask';
+    category?: string;
+    feedback?: string;
+}
+export declare function validateCommand(command: string): SecurityResult;

package/dist/lib/security.js

@@ -0,0 +1,57 @@
+import { redactString } from './redaction';
+const REVERSE_SHELL_PATTERNS = [
+    /\/dev\/(tcp|udp)\/[0-9]/,
+    /bash\s+-i\s+>&?\s*\/dev\//,
+];
+const INSTRUCTION_OVERRIDE_PATTERNS = [
+    /ignore\s+(all\s+)?previous\s+instructions?/i,
+    /disregard\s+(all\s+)?(prior|previous)\s+(instructions?|rules?)/i,
+];
+const CATASTROPHIC_DELETION_PATTERNS = [
+    /\s+~\/?(\s*$|\s+)/,
+    /\brm\s+(-[rfivd]+\s+)*\S+\s+~\/?/,
+    /\brm\s+(-[rfivd]+\s+)*\.\/\s*$/,
+    /\brm\s+(-[rfivd]+\s+)*\.\.\/\s*$/,
+    /\brm\s+(-[rfivd]+\s+)*\/\s*$/,
+];
+const DANGEROUS_FILE_OPS_PATTERNS = [
+    /\bchmod\s+(-R\s+)?0{3,}/,
+];
+const DANGEROUS_GIT_PATTERNS = [
+    /\bgit\s+push\s+.*(-f\b|--force)/i,
+    /\bgit\s+reset\s+--hard/i,
+];
+const BLOCK_CATEGORIES = [
+    { category: 'reverse_shell', patterns: REVERSE_SHELL_PATTERNS },
+    { category: 'instruction_override', patterns: INSTRUCTION_OVERRIDE_PATTERNS },
+    { category: 'catastrophic_deletion', patterns: CATASTROPHIC_DELETION_PATTERNS },
+    { category: 'dangerous_file_ops', patterns: DANGEROUS_FILE_OPS_PATTERNS },
+];
+const ASK_CATEGORIES = [
+    { category: 'dangerous_git', patterns: DANGEROUS_GIT_PATTERNS },
+];
+export function validateCommand(command) {
+    for (const { category, patterns } of BLOCK_CATEGORIES) {
+        for (const pattern of patterns) {
+            if (pattern.test(command)) {
+                return {
+                    status: 'deny',
+                    category,
+                    feedback: `🚨 SECURITY: Blocked ${category} pattern. Command: ${redactString(command).slice(0, 50)}...`,
+                };
+            }
+        }
+    }
+    for (const { category, patterns } of ASK_CATEGORIES) {
+        for (const pattern of patterns) {
+            if (pattern.test(command)) {
+                return {
+                    status: 'ask',
+                    category,
+                    feedback: `⚠️ DANGEROUS: ${category} operation requires confirmation.`,
+                };
+            }
+        }
+    }
+    return { status: 'allow' };
+}

package/package.json

@@ -0,0 +1,33 @@
+{
+  "name": "@fpr1m3/opencode-pai-plugin",
+  "version": "1.0.0",
+  "type": "module",
+  "description": "Personal AI Infrastructure (PAI) plugin for OpenCode",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "files": [
+    "dist"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/fpr1m3/opencode-pai-plugin.git"
+  },
+  "scripts": {
+    "build": "tsc",
+    "test": "bun test",
+    "dev": "tsc --watch",
+    "prepare": "bun run build"
+  },
+  "dependencies": {
+    "@opencode-ai/plugin": "^1.0.180",
+    "@opencode-ai/sdk": "^1.0.180",
+    "glob": "^13.0.0"
+  },
+  "devDependencies": {
+    "@types/bun": "latest",
+    "typescript": "^5.0.0"
+  }
+}