portable-agent-layer 0.1.0

package/src/targets/opencode/plugin.ts

@@ -0,0 +1,328 @@
+/**
+ * PAL plugin for opencode — thin adapter over shared hooks/lib/ modules.
+ *
+ * All business logic lives in hooks/lib/ so it stays in sync with Claude Code hooks.
+ * This plugin just wires opencode's hook API to those shared functions.
+ */
+
+import { writeFileSync } from "node:fs";
+import { resolve } from "node:path";
+import type { Plugin, PluginInput } from "@opencode-ai/plugin";
+
+const PAL_DIR = process.env.PAL_DIR || resolve(import.meta.dir, "../../..");
+
+// Dynamic imports from shared lib — resolved at runtime via PAL_DIR
+async function lib<T>(mod: string): Promise<T> {
+  return await import(resolve(PAL_DIR, "src", "hooks", "lib", mod));
+}
+
+type TranscriptMessage = { role: string; content: string };
+
+const PALPlugin: Plugin = async ({ directory, client }: PluginInput) => {
+  // Pre-load shared modules
+  const { buildGreeting, buildSystemReminder } =
+    await lib<typeof import("../../hooks/lib/context")>("context.ts");
+  const { checkBashCommand, checkFilePath } =
+    await lib<typeof import("../../hooks/lib/security")>("security.ts");
+  const { paths, ensureDir } =
+    await lib<typeof import("../../hooks/lib/paths")>("paths.ts");
+  const { emitRating } =
+    await lib<typeof import("../../hooks/lib/signals")>("signals.ts");
+  const { now } = await lib<typeof import("../../hooks/lib/time")>("time.ts");
+  const { monthPath, fileTimestamp } =
+    await lib<typeof import("../../hooks/lib/time")>("time.ts");
+  const { logDebug, logError } =
+    await lib<typeof import("../../hooks/lib/log")>("log.ts");
+
+  // Load shared stop-orchestrator handler
+  const { runStopHandlers } = await lib<typeof import("../../hooks/lib/stop")>("stop.ts");
+  const { captureSessionName } = await lib<
+    typeof import("../../hooks/handlers/session-name")
+  >("../handlers/session-name.ts");
+
+  function partsToText(parts: Array<Record<string, unknown>>): string {
+    return parts
+      .filter((p) => p?.type === "text" && !p.ignored && !p.synthetic)
+      .map((p) => (typeof p.text === "string" ? p.text : ""))
+      .join(" ")
+      .trim();
+  }
+
+  async function buildSessionTranscript(sessionID: string): Promise<TranscriptMessage[]> {
+    const result = await client.session.messages({
+      path: { id: sessionID },
+      query: { directory },
+    });
+
+    if (result.error || !result.data) {
+      logDebug(
+        "opencode:session.messages",
+        `Failed to fetch messages (error=${Boolean(result.error)})`
+      );
+      return [];
+    }
+
+    const rows = result.data as Array<{
+      info: { role?: string };
+      parts: Array<Record<string, unknown>>;
+    }>;
+
+    return rows
+      .map((row) => {
+        const role = row?.info?.role ?? "unknown";
+        const content = partsToText(row?.parts ?? []);
+        return { role, content };
+      })
+      .filter((m) => m.content.length > 0);
+  }
+
+  const { categorizeLearning } =
+    await lib<typeof import("../../hooks/lib/learning-category")>("learning-category.ts");
+
+  // Local helpers for rating (thin wrappers around shared signals)
+  function handleRating(
+    rating: number,
+    context: string,
+    source: string,
+    detailedContext?: string,
+    userMessage?: string
+  ): void {
+    emitRating(rating, context, source);
+
+    if (rating < 5) {
+      const category = categorizeLearning(context, detailedContext ?? "");
+      const dir = ensureDir(resolve(paths.sessionLearning(), monthPath()));
+      const filename = `${fileTimestamp()}_${source}-rating-${rating}_${category}.md`;
+      writeFileSync(
+        resolve(dir, filename),
+        [
+          `# ${source === "explicit" ? "Low Rating" : "Implicit Low Rating"}: ${rating}/10`,
+          `**Title:** ${context.slice(0, 100) || "(low rating)"}`,
+          `**Date:** ${new Date().toISOString().slice(0, 10)}`,
+          `**Rating:** ${rating}/10`,
+          `**Source:** ${source}`,
+          `**Category:** ${category.toUpperCase()}`,
+          "",
+          "## Context",
+          context || "*(unavailable)*",
+          "",
+          ...(detailedContext ? ["## Analysis", detailedContext, ""] : []),
+        ].join("\n")
+      );
+    }
+
+    if (rating <= 3) {
+      const userPreview = userMessage?.slice(0, 400);
+      writeFileSync(
+        resolve(paths.state(), "pending-failure.json"),
+        JSON.stringify(
+          { rating, context, source, detailedContext, userPreview, ts: now() },
+          null,
+          2
+        ),
+        "utf-8"
+      );
+    }
+  }
+
+  const PRAISE_PATTERNS =
+    /^(great\s*job|nice|perfect|awesome|excellent|thanks|thank\s*you|well\s*done|good\s*job|love\s*it|amazing|brilliant|fantastic|wonderful|superb|nailed\s*it)[.!?]?$/i;
+
+  return {
+    // --- Per-message: Inject dynamic system reminder ---
+    "experimental.chat.system.transform": async (_input, output) => {
+      const reminder = buildSystemReminder();
+      if (reminder) output.system.push(reminder);
+    },
+
+    // --- Session events: start and stop handling ---
+    event: async ({ event }) => {
+      logDebug("opencode:event", `Event: ${event.type}`);
+
+      if (event.type === "session.created" || event.type === "session.updated") {
+        const { regenerateIfNeeded } =
+          await lib<typeof import("../../hooks/lib/claude-md")>("claude-md.ts");
+        regenerateIfNeeded();
+        console.log(buildGreeting().join("\n"));
+      }
+
+      if (event.type === "session.idle" || event.type === "session.diff") {
+        logDebug("opencode:event", "Running stop handlers...");
+        try {
+          const sessionID = (event as { properties?: { sessionID?: string } })?.properties
+            ?.sessionID;
+          if (!sessionID) {
+            logDebug("opencode:event", "Skipping stop handlers: missing sessionID");
+            return;
+          }
+
+          const messages = await buildSessionTranscript(sessionID);
+          logDebug("opencode:event", `Got ${messages.length} transcript messages`);
+          if (messages.length < 2) return;
+
+          // Name session from first user message (if not already named)
+          const firstUser = messages.find((m: TranscriptMessage) => m.role === "user");
+          if (firstUser) {
+            await captureSessionName(firstUser.content, sessionID);
+          }
+
+          await runStopHandlers(JSON.stringify(messages), { sessionId: sessionID });
+          logDebug("opencode:event", "Stop handlers complete");
+        } catch (err) {
+          logError("opencode:session.stop", err);
+        }
+      }
+    },
+
+    // --- Capture ratings from user messages ---
+    "chat.message": async (_input, output) => {
+      const text =
+        output.parts
+          ?.filter((p) => p.type === "text")
+          .map((p) => p.text || "")
+          .join(" ") ?? "";
+
+      // Explicit rating
+      const match = text.match(
+        /(?:^|rating:?\s*|score:?\s*)(\d|10)(?:\s*(?:\/10|[-.])|$|\s)/i
+      );
+      if (match) {
+        const rating = parseInt(match[1], 10);
+        if (rating >= 1 && rating <= 10) {
+          handleRating(rating, text.slice(0, 200), "explicit", undefined, text);
+          return;
+        }
+      }
+
+      // Implicit sentiment: auto-enabled when ANTHROPIC_API_KEY is set
+      if (process.env.ANTHROPIC_API_KEY) {
+        const trimmed = text.trim();
+        if (PRAISE_PATTERNS.test(trimmed)) {
+          handleRating(8, trimmed, "implicit", undefined, trimmed);
+          return;
+        }
+
+        // Full implicit via API — only for medium-length messages
+        if (
+          trimmed.length >= 5 &&
+          trimmed.length <= 500 &&
+          !/^[/$`{]/.test(trimmed) &&
+          !trimmed.includes("\n\n")
+        ) {
+          const apiKey = process.env.ANTHROPIC_API_KEY;
+          if (apiKey) {
+            try {
+              const response = await fetch("https://api.anthropic.com/v1/messages", {
+                method: "POST",
+                headers: {
+                  "x-api-key": apiKey,
+                  "anthropic-version": "2023-06-01",
+                  "content-type": "application/json",
+                },
+                body: JSON.stringify({
+                  model: (await lib<{ HAIKU_MODEL: string }>("models")).HAIKU_MODEL,
+                  max_tokens: 100,
+                  messages: [
+                    {
+                      role: "user",
+                      content: `Rate the sentiment of this user message toward an AI assistant on a 1-10 scale (1=very negative, 5=neutral, 10=very positive). If the message has no clear sentiment toward the assistant, respond with just "neutral". Otherwise respond with just a JSON object: {"rating": N, "sentiment": "one-word"}\n\nMessage: "${trimmed.slice(0, 300)}"`,
+                    },
+                  ],
+                }),
+              });
+
+              if (response.ok) {
+                const data = (await response.json()) as {
+                  content?: Array<{ text?: string }>;
+                };
+                const rText = data?.content?.[0]?.text?.trim();
+                if (rText && rText !== "neutral") {
+                  try {
+                    const parsed = JSON.parse(rText) as {
+                      rating?: number;
+                      sentiment?: string;
+                    };
+                    if (
+                      typeof parsed.rating === "number" &&
+                      parsed.rating >= 1 &&
+                      parsed.rating <= 10 &&
+                      parsed.rating !== 5
+                    ) {
+                      handleRating(
+                        parsed.rating,
+                        `${parsed.sentiment || "inferred"}: ${trimmed.slice(0, 150)}`,
+                        "implicit",
+                        undefined,
+                        trimmed
+                      );
+                    }
+                  } catch {
+                    // Ignore parse errors
+                  }
+                }
+              }
+            } catch {
+              // Ignore API errors
+            }
+          }
+        }
+      }
+    },
+
+    // --- Security: block dangerous tool executions ---
+    "tool.execute.before": async (
+      _input: { tool: string; sessionID: string; callID: string },
+      output: { args: Record<string, unknown> | string }
+    ) => {
+      const toolName = _input.tool;
+
+      if (toolName === "shell" || toolName === "bash") {
+        const cmd =
+          typeof output.args === "string"
+            ? output.args
+            : ((output.args?.command as string) ?? "");
+        const reason = checkBashCommand(cmd);
+        if (reason) {
+          throw new Error(`PAL Security: Blocked — ${reason}`);
+        }
+      }
+
+      if (toolName === "write" || toolName === "edit" || toolName === "patch") {
+        const args = output.args as Record<string, string>;
+        const filePath = args?.file_path ?? args?.filePath ?? args?.path ?? "";
+        const fileReason = checkFilePath(filePath);
+        if (fileReason) {
+          throw new Error(`PAL Security: ${fileReason}`);
+        }
+      }
+    },
+
+    // --- Capture work state after tool use ---
+    "tool.execute.after": async (
+      input: { tool: string; sessionID: string; callID: string; args: unknown },
+      _output: { title: string; output: string; metadata: unknown }
+    ) => {
+      try {
+        writeFileSync(
+          resolve(ensureDir(paths.state()), "current-work.json"),
+          JSON.stringify({ ts: now(), tool: input.tool, cwd: directory }, null, 2)
+        );
+      } catch {
+        // Ignore write errors
+      }
+    },
+
+    // --- Inject PAL_DIR into shell environment ---
+    "shell.env": async (
+      _input: { cwd: string; sessionID?: string; callID?: string },
+      output: { env: Record<string, string> }
+    ) => {
+      output.env.PAL_DIR = PAL_DIR;
+      if (process.env.PAL_DEBUG) {
+        output.env.PAL_DEBUG = process.env.PAL_DEBUG;
+      }
+    },
+  };
+};
+
+export default PALPlugin;

package/src/targets/opencode/uninstall.ts

@@ -0,0 +1,57 @@
+/**
+ * PAL — opencode uninstaller (TypeScript)
+ * Removes plugin and AGENTS.md.
+ */
+
+import { unlinkSync } from "node:fs";
+import { resolve } from "node:path";
+import { platform } from "../../hooks/lib/paths";
+import { log, removeAgentsFromOpencode, removeSkills } from "../lib";
+
+const OC_GLOBAL_DIR = platform.opencodeDir() || "";
+
+const PAL_CLAUDE_DIR = platform.claudeDir() || "";
+
+if (!OC_GLOBAL_DIR || !PAL_CLAUDE_DIR) {
+  log.error("PAL_OPENCODE_DIR or PAL_CLAUDE_DIR not set");
+  process.exit(1);
+}
+
+// --- Remove plugin ---
+const pluginPath = resolve(OC_GLOBAL_DIR, "plugins", "pal-plugin.ts");
+try {
+  unlinkSync(pluginPath);
+  log.success("Removed PAL plugin");
+} catch {
+  log.info("No PAL plugin found");
+}
+
+// --- Remove skills ---
+const removed = removeSkills(resolve(PAL_CLAUDE_DIR, "skills"));
+if (removed.length > 0)
+  log.success(`Removed ${removed.length} skill(s): ${removed.join(", ")}`);
+
+// --- Remove agents ---
+const removedAgents = removeAgentsFromOpencode(resolve(OC_GLOBAL_DIR, "agents"));
+if (removedAgents.length > 0)
+  log.success(
+    `Removed ${removedAgents.length} opencode agent(s): ${removedAgents.join(", ")}`
+  );
+
+// --- Remove AGENTS.md and CLAUDE.md symlink ---
+const agentsMd = resolve(OC_GLOBAL_DIR, "AGENTS.md");
+const claudeMd = resolve(PAL_CLAUDE_DIR, "CLAUDE.md");
+try {
+  unlinkSync(claudeMd);
+  log.success("Removed ~/.claude/CLAUDE.md");
+} catch {
+  /* gone */
+}
+try {
+  unlinkSync(agentsMd);
+  log.success("Removed ~/.config/opencode/AGENTS.md");
+} catch {
+  /* gone */
+}
+
+log.success("opencode uninstall complete");

package/src/tools/entity-save.ts

@@ -0,0 +1,110 @@
+#!/usr/bin/env bun
+/**
+ * Entity Save — Deduplicate and persist extracted entities.
+ *
+ * Accepts extracted people/companies JSON via stdin or --file,
+ * deduplicates against the entity index, and saves.
+ *
+ * Usage:
+ *   echo '{"people":[...],"companies":[...]}' | bun run ai:entity-save -- --source "https://example.com"
+ *   bun run ai:entity-save -- --file /path/to/extracted.json --source "https://example.com"
+ */
+
+import { readFileSync } from "node:fs";
+import { parseArgs } from "node:util";
+import { loadEntityIndex, processEntities } from "../hooks/lib/entities";
+
+const { values } = parseArgs({
+  args: Bun.argv.slice(2),
+  options: {
+    source: { type: "string", short: "s", default: "manual" },
+    file: { type: "string", short: "f" },
+  },
+  strict: true,
+});
+
+const sourceId = values.source ?? "manual";
+
+let raw: string;
+if (values.file) {
+  raw = readFileSync(values.file, "utf-8");
+} else {
+  raw = await Bun.stdin.text();
+}
+
+if (!raw.trim()) {
+  console.error("Error: No input provided. Pipe JSON via stdin or use --file.");
+  process.exit(1);
+}
+
+let data: {
+  people: Array<Record<string, unknown>>;
+  companies: Array<Record<string, unknown>>;
+  links?: Array<Record<string, unknown>>;
+  sources?: Array<Record<string, unknown>>;
+};
+try {
+  data = JSON.parse(raw);
+} catch {
+  console.error("Error: Invalid JSON input.");
+  process.exit(1);
+}
+
+if (!Array.isArray(data.people) || !Array.isArray(data.companies)) {
+  console.error('Error: JSON must have "people" and "companies" arrays.');
+  process.exit(1);
+}
+data.links ??= [];
+data.sources ??= [];
+
+const before = loadEntityIndex();
+const counts = (idx: ReturnType<typeof loadEntityIndex>) => ({
+  people: Object.keys(idx.people).length,
+  companies: Object.keys(idx.companies).length,
+  links: Object.keys(idx.links).length,
+  sources: Object.keys(idx.sources).length,
+});
+const cb = counts(before);
+
+const result = processEntities(
+  {
+    people: data.people as Array<{ name: string; [key: string]: unknown }>,
+    companies: data.companies as Array<{
+      name: string;
+      domain: string | null;
+      [key: string]: unknown;
+    }>,
+    links: data.links as Array<{ url: string; [key: string]: unknown }>,
+    sources: data.sources as Array<{
+      url: string | null;
+      author: string | null;
+      publication: string | null;
+      [key: string]: unknown;
+    }>,
+  },
+  sourceId
+);
+
+const ca = counts(loadEntityIndex());
+
+console.log(
+  JSON.stringify(
+    {
+      saved: {
+        people: result.people.length,
+        companies: result.companies.length,
+        links: result.links.length,
+        sources: result.sources.length,
+      },
+      new: {
+        people: ca.people - cb.people,
+        companies: ca.companies - cb.companies,
+        links: ca.links - cb.links,
+        sources: ca.sources - cb.sources,
+      },
+      total: ca,
+    },
+    null,
+    2
+  )
+);

package/src/tools/export.ts

@@ -0,0 +1,34 @@
+/**
+ * PAL Export — Zips all gitignored personal files (memory, telos, state)
+ * into a portable archive for transfer between machines.
+ *
+ * Usage: bun run tool:export [output-path] [--dry-run]
+ * Default output: pal-export-YYYYMMDD-HHmmss.zip in the repo root.
+ */
+
+import { resolve } from "node:path";
+import { collectExportFiles, exportZip, timestamp } from "../hooks/lib/export";
+import { palHome } from "../hooks/lib/paths";
+
+const args = process.argv.slice(2);
+const dryRun = args.includes("--dry-run");
+const pathArg = args.find((a) => a !== "--dry-run");
+
+const outputPath = pathArg || resolve(palHome(), `pal-export-${timestamp()}.zip`);
+
+if (dryRun) {
+  const files = collectExportFiles();
+  if (files.length === 0) {
+    console.log("Nothing to export — no gitignored personal files found.");
+  } else {
+    console.log(`Would export ${files.length} files → ${outputPath}\n`);
+    for (const f of files) console.log(`  ${f}`);
+  }
+} else {
+  const count = exportZip(outputPath);
+  if (count === 0) {
+    console.log("Nothing to export — no gitignored personal files found.");
+  } else {
+    console.log(`Exported ${count} files → ${outputPath}`);
+  }
+}

package/src/tools/fyzz-api.ts

@@ -0,0 +1,104 @@
+#!/usr/bin/env bun
+/**
+ * Fyzz Chat API — CLI wrapper for programmatic conversation access.
+ *
+ * Reads the API key from FYZZ_API_KEY env var (never printed to stdout).
+ * Returns JSON responses from the Fyzz Chat REST API.
+ *
+ * Usage:
+ *   bun run ai:fyzz-api -- conversations [--limit 20] [--search "query"] [--project-id <id>] [--cursor <cursor>]
+ *   bun run ai:fyzz-api -- conversations <id>
+ *   bun run ai:fyzz-api -- projects
+ */
+
+import { parseArgs } from "node:util";
+
+function loadApiKey(): string {
+  const key = process.env.FYZZ_API_KEY;
+  if (!key) {
+    console.error("Error: FYZZ_API_KEY environment variable is not set.");
+    console.error("Set it in your shell profile or PAL settings.json env section.");
+    process.exit(1);
+  }
+  return key;
+}
+
+async function apiFetch(path: string, params?: Record<string, string>): Promise<unknown> {
+  const apiKey = loadApiKey();
+  const baseUrl = process.env.FYZZ_BASE_URL ?? "http://localhost:3000";
+
+  const url = new URL(`/api/v1${path}`, baseUrl);
+  if (params) {
+    for (const [k, v] of Object.entries(params)) {
+      if (v !== undefined && v !== "") url.searchParams.set(k, v);
+    }
+  }
+
+  const response = await fetch(url.toString(), {
+    headers: { Authorization: `Bearer ${apiKey}` },
+  });
+
+  if (!response.ok) {
+    console.error(`Error: ${response.status} ${response.statusText}`);
+    const body = await response.text();
+    if (body) console.error(body);
+    process.exit(1);
+  }
+
+  return response.json();
+}
+
+const args = process.argv.slice(2);
+const command = args[0];
+
+if (!command || command === "--help" || command === "-h") {
+  console.log("Usage:");
+  console.log("  bun run ai:fyzz-api -- conversations                List conversations");
+  console.log(
+    "  bun run ai:fyzz-api -- conversations <id>           Get conversation with messages"
+  );
+  console.log("  bun run ai:fyzz-api -- projects                     List projects");
+  console.log("");
+  console.log("Options for 'conversations' (list mode):");
+  console.log("  --limit <n>          Max results (default 20)");
+  console.log("  --search <query>     Search in titles and messages");
+  console.log("  --project-id <id>    Filter by project");
+  console.log("  --cursor <cursor>    Pagination cursor");
+  process.exit(0);
+}
+
+if (command === "conversations") {
+  const secondArg = args[1];
+
+  if (secondArg && !secondArg.startsWith("--")) {
+    const result = await apiFetch(`/conversations/${secondArg}`);
+    console.log(JSON.stringify(result, null, 2));
+  } else {
+    const { values } = parseArgs({
+      args: args.slice(1),
+      options: {
+        limit: { type: "string", short: "l", default: "20" },
+        search: { type: "string", short: "s" },
+        "project-id": { type: "string", short: "p" },
+        cursor: { type: "string", short: "c" },
+      },
+      strict: true,
+    });
+
+    const params: Record<string, string> = {};
+    if (values.limit) params.limit = values.limit;
+    if (values.search) params.search = values.search;
+    if (values["project-id"]) params.projectId = values["project-id"];
+    if (values.cursor) params.cursor = values.cursor;
+
+    const result = await apiFetch("/conversations", params);
+    console.log(JSON.stringify(result, null, 2));
+  }
+} else if (command === "projects") {
+  const result = await apiFetch("/projects");
+  console.log(JSON.stringify(result, null, 2));
+} else {
+  console.error(`Unknown command: ${command}`);
+  console.error("Run with --help for usage.");
+  process.exit(1);
+}