@bryti/agent 0.0.1 → 0.1.0

package/dist/defaults/extensions/EXTENSIONS.md

@@ -0,0 +1,158 @@
+# Writing Extensions for Bryti
+
+Extensions add new tools to the agent. They are TypeScript files in
+`data/files/extensions/`. The agent loads them on startup and the tools
+become available immediately.
+
+## The one thing you need to know
+
+Bryti runs headlessly — no terminal, no TUI. Extensions work through
+`pi.registerTool()` only. Everything else in the pi extension API
+(commands, UI, TUI components, session navigation) requires an interactive
+terminal and does nothing here.
+
+**Use:** `pi.registerTool()`  
+**Ignore:** `pi.registerCommand()`, `pi.registerShortcut()`, `ctx.ui.*`,
+`ctx.sessionManager`, `pi.on()` events — these are no-ops or unavailable.
+
+## Minimal template
+
+```typescript
+import type { ExtensionAPI } from "@mariozechner/pi-coding-agent";
+import { Type } from "@sinclair/typebox";
+
+export default function (pi: ExtensionAPI) {
+  pi.registerTool({
+    name: "tool_name",           // snake_case, unique across all extensions
+    label: "tool_name",          // same as name
+    description: "What this tool does and when to use it.",
+    parameters: Type.Object({
+      input: Type.String({ description: "What this parameter is" }),
+    }),
+    async execute(_toolCallId, { input }) {
+      // Do work here
+      return {
+        content: [{ type: "text", text: JSON.stringify({ result: input }) }],
+      };
+    },
+  });
+}
+```
+
+## What you can do inside execute()
+
+Anything Node.js supports:
+
+- `fetch()` for HTTP requests
+- `process.env.MY_VAR` for secrets and config (set in .env)
+- `node:fs`, `node:path`, `node:child_process` for local system access
+- Any npm package if you install it in `data/files/extensions/`
+
+## Returning results
+
+Always return JSON-stringified text so the agent can parse the result:
+
+```typescript
+// Success
+return {
+  content: [{ type: "text", text: JSON.stringify({ key: "value" }) }],
+};
+
+// Error
+return {
+  content: [{ type: "text", text: JSON.stringify({ error: "What went wrong" }) }],
+};
+```
+
+## Using environment variables
+
+Non-secret config (URLs, feature flags) goes in `config.yml` under `integrations`.
+Secrets (API keys, tokens) go in `.env` and are referenced from config.yml via `${VAR}`.
+
+Bryti injects `integrations.<name>.<key>` as `NAME_KEY` (uppercased) into `process.env`
+at startup, so extensions read them the same way regardless of where they came from.
+
+```yaml
+# config.yml
+integrations:
+  my_service:
+    url: "https://api.example.com"
+    api_key: "${MY_SERVICE_API_KEY}"   # secret stays in .env
+```
+
+```typescript
+// extension reads it the same way either way
+const url = process.env.MY_SERVICE_URL;
+const apiKey = process.env.MY_SERVICE_API_KEY;
+
+if (!url) {
+  return {
+    content: [{ type: "text", text: JSON.stringify({
+      error: "MY_SERVICE_URL not set. Add integrations.my_service.url to config.yml and restart."
+    })}],
+  };
+}
+```
+
+## Optional tools (register only when configured)
+
+If a tool requires env vars to work, check at registration time and skip
+if they're missing. This keeps the tool list clean:
+
+```typescript
+export default function (pi: ExtensionAPI) {
+  const apiKey = process.env.MY_SERVICE_API_KEY;
+  if (!apiKey) return;  // Not configured — skip registration
+
+  pi.registerTool({ ... });
+}
+```
+
+## Multiple tools in one file
+
+Group related tools in a single file:
+
+```typescript
+export default function (pi: ExtensionAPI) {
+  pi.registerTool({ name: "thing_get", ... });
+  pi.registerTool({ name: "thing_set", ... });
+  pi.registerTool({ name: "thing_list", ... });
+}
+```
+
+## Parameter types
+
+```typescript
+Type.String()                              // text
+Type.Number()                              // number
+Type.Boolean()                             // true/false
+Type.Integer()                             // whole number
+Type.Optional(Type.String())               // optional field
+Type.Array(Type.String())                  // list of strings
+Type.Union([                               // one of several string values
+  Type.Literal("option_a"),
+  Type.Literal("option_b"),
+])
+```
+
+## Disabling an extension
+
+Write an empty file over it. An empty file is a permanent tombstone —
+the extension will not be restored on restart, even if it was a default.
+
+```
+file_write("extensions/some-extension.ts", "")
+```
+
+Do not delete extension files. Always overwrite with empty content.
+
+## Real examples
+
+Read the existing extensions in `data/files/extensions/` for patterns.
+The bundled default:
+
+- `extensions/documents-hedgedoc.ts` — optional tool (skips if env var missing), fetch API, multiple tools
+
+The agent can also write its own extensions at runtime (shell access,
+API integrations, etc.). Check `data/files/extensions/` for any that
+already exist.

package/dist/defaults/extensions/documents-hedgedoc.ts

@@ -0,0 +1,153 @@
+/**
+ * Document tools — HedgeDoc backend.
+ *
+ * Registers three tools: document_create, document_update, document_read.
+ *
+ * These tools are the stable interface for collaborative note editing.
+ * The tool NAMES are what the agent and users refer to. If you replace
+ * this backend (Notion, Google Docs, plain files, anything), keep the
+ * same tool names so the agent's behaviour and memory stay consistent.
+ *
+ * To replace this backend:
+ *   1. Rewrite this file (or write a new one and delete this)
+ *   2. Implement the same three tools against your preferred API
+ *   3. The agent will pick up the new tools on next restart
+ *
+ * Requirements for HedgeDoc:
+ *   - HEDGEDOC_URL env var: internal URL pibot uses (e.g. http://hedgedoc:3000)
+ *   - HEDGEDOC_PUBLIC_URL env var: user-facing URL for shared links (optional, defaults to HEDGEDOC_URL)
+ *   - HedgeDoc must be started with CMD_ALLOW_FREEURL=true for document_update to work
+ *   - See docker-compose.yml for the service definition
+ */
+
+import type { ExtensionAPI } from "@mariozechner/pi-coding-agent";
+import { Type } from "@sinclair/typebox";
+
+export default function (pi: ExtensionAPI) {
+  const baseUrl = (process.env.HEDGEDOC_URL ?? "").replace(/\/$/, "");
+  const publicUrl = (process.env.HEDGEDOC_PUBLIC_URL ?? baseUrl).replace(/\/$/, "");
+
+  if (!baseUrl) {
+    // HedgeDoc not configured — tools are not registered.
+    // Set HEDGEDOC_URL in .env to activate document_create/update/read.
+    console.log("[documents-hedgedoc] HEDGEDOC_URL not set — document tools not registered");
+    return;
+  }
+
+  // ---------------------------------------------------------------------------
+  // Helpers
+  // ---------------------------------------------------------------------------
+
+  function extractNoteId(location: string): string {
+    const parts = location.split("/");
+    return parts[parts.length - 1];
+  }
+
+  function buildMarkdown(title: string, content: string): string {
+    const trimmed = content.trimStart();
+    if (trimmed.startsWith("# ")) return trimmed;
+    return `# ${title}\n\n${trimmed}`;
+  }
+
+  async function hedgedocPost(path: string, body: string): Promise<Response> {
+    const response = await fetch(`${baseUrl}${path}`, {
+      method: "POST",
+      headers: { "Content-Type": "text/markdown" },
+      body,
+      redirect: "manual", // capture 302 Location header ourselves
+    });
+    if (!response.ok && response.status !== 302) {
+      throw new Error(`HedgeDoc returned ${response.status} for ${path}`);
+    }
+    return response;
+  }
+
+  // ---------------------------------------------------------------------------
+  // document_create
+  // ---------------------------------------------------------------------------
+
+  pi.registerTool({
+    name: "document_create",
+    label: "document_create",
+    description:
+      "Create a new collaborative document and return a shareable link. " +
+      "Use this whenever the conversation produces content the user should be able to view, " +
+      "edit, or share: drafts, plans, research notes, code documents, etc. " +
+      "Send the returned url to the user so they can open it in their browser.",
+    parameters: Type.Object({
+      title: Type.String({ description: "Title for the document (written as the first H1 heading)" }),
+      content: Type.String({ description: "Initial markdown content of the document" }),
+    }),
+    async execute(_toolCallId, { title, content }) {
+      try {
+        const response = await hedgedocPost("/new", buildMarkdown(title, content));
+        const location = response.headers.get("location") ?? "";
+
+        if (!location) {
+          return { content: [{ type: "text", text: JSON.stringify({ error: "HedgeDoc did not return a note location" }) }] };
+        }
+
+        const noteId = extractNoteId(location);
+        const url = `${publicUrl}/${noteId}`;
+
+        return { content: [{ type: "text", text: JSON.stringify({ note_id: noteId, url, title }) }] };
+      } catch (error) {
+        return { content: [{ type: "text", text: JSON.stringify({ error: `Failed to create document: ${error instanceof Error ? error.message : String(error)}` }) }] };
+      }
+    },
+  });
+
+  // ---------------------------------------------------------------------------
+  // document_update
+  //
+  // Uses POST /new/<alias> which overwrites the note when CMD_ALLOW_FREEURL=true.
+  // ---------------------------------------------------------------------------
+
+  pi.registerTool({
+    name: "document_update",
+    label: "document_update",
+    description:
+      "Replace the full content of an existing document. " +
+      "Provide the complete new markdown — this is a full overwrite, not a patch. " +
+      "Read the document first with document_read if you need to preserve existing content.",
+    parameters: Type.Object({
+      note_id: Type.String({ description: "Note ID returned by document_create" }),
+      content: Type.String({ description: "Full new markdown content (replaces existing content)" }),
+    }),
+    async execute(_toolCallId, { note_id, content }) {
+      try {
+        await hedgedocPost(`/new/${note_id}`, content);
+        return { content: [{ type: "text", text: JSON.stringify({ note_id, updated: true }) }] };
+      } catch (error) {
+        return { content: [{ type: "text", text: JSON.stringify({ error: `Failed to update document: ${error instanceof Error ? error.message : String(error)}` }) }] };
+      }
+    },
+  });
+
+  // ---------------------------------------------------------------------------
+  // document_read
+  // ---------------------------------------------------------------------------
+
+  pi.registerTool({
+    name: "document_read",
+    label: "document_read",
+    description:
+      "Read the current markdown content of a document. " +
+      "Use this before updating so you can preserve content the user may have edited.",
+    parameters: Type.Object({
+      note_id: Type.String({ description: "Note ID returned by document_create" }),
+    }),
+    async execute(_toolCallId, { note_id }) {
+      try {
+        const response = await fetch(`${baseUrl}/${note_id}/download`);
+        if (!response.ok) {
+          throw new Error(`HedgeDoc returned ${response.status}`);
+        }
+        const content = await response.text();
+        return { content: [{ type: "text", text: JSON.stringify({ note_id, content }) }] };
+      } catch (error) {
+        return { content: [{ type: "text", text: JSON.stringify({ error: `Failed to read document: ${error instanceof Error ? error.message : String(error)}` }) }] };
+      }
+    },
+  });
+}

package/dist/history.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Conversation history as JSONL files, rotated by day. Used as an audit log;
+ * conversation_search reads these directly. Persistent pi sessions are the
+ * source of truth for agent context.
+ */
+export interface ChatMessage {
+    role: "user" | "assistant" | "system" | "tool";
+    content: string;
+    tool_calls?: Array<{
+        id: string;
+        type: "function";
+        function: {
+            name: string;
+            arguments: string;
+        };
+    }>;
+    tool_call_id?: string;
+    name?: string;
+    timestamp: string;
+}
+export interface HistoryManager {
+    /** Append a message to today's history file. */
+    append(message: Omit<ChatMessage, "timestamp">): Promise<void>;
+    /** Clear all history. */
+    clear(): Promise<void>;
+}
+/**
+ * Create a file-based history manager.
+ */
+export declare function createHistoryManager(dataDir: string): HistoryManager;
+//# sourceMappingURL=history.d.ts.map

package/dist/history.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"history.d.ts","sourceRoot":"","sources":["../src/history.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAKH,MAAM,WAAW,WAAW;IAC1B,IAAI,EAAE,MAAM,GAAG,WAAW,GAAG,QAAQ,GAAG,MAAM,CAAC;IAC/C,OAAO,EAAE,MAAM,CAAC;IAChB,UAAU,CAAC,EAAE,KAAK,CAAC;QACjB,EAAE,EAAE,MAAM,CAAC;QACX,IAAI,EAAE,UAAU,CAAC;QACjB,QAAQ,EAAE;YACR,IAAI,EAAE,MAAM,CAAC;YACb,SAAS,EAAE,MAAM,CAAC;SACnB,CAAC;KACH,CAAC,CAAC;IACH,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,SAAS,EAAE,MAAM,CAAC;CACnB;AAED,MAAM,WAAW,cAAc;IAC7B,gDAAgD;IAChD,MAAM,CAAC,OAAO,EAAE,IAAI,CAAC,WAAW,EAAE,WAAW,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAE/D,yBAAyB;IACzB,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CACxB;AAED;;GAEG;AACH,wBAAgB,oBAAoB,CAAC,OAAO,EAAE,MAAM,GAAG,cAAc,CA2CpE"}

package/dist/history.js

@@ -0,0 +1,49 @@
+/**
+ * Conversation history as JSONL files, rotated by day. Used as an audit log;
+ * conversation_search reads these directly. Persistent pi sessions are the
+ * source of truth for agent context.
+ */
+import fs from "node:fs";
+import path from "node:path";
+/**
+ * Create a file-based history manager.
+ */
+export function createHistoryManager(dataDir) {
+    const historyDir = path.join(dataDir, "history");
+    // Ensure directory exists
+    fs.mkdirSync(historyDir, { recursive: true });
+    function getTodayFilename() {
+        const today = new Date().toISOString().split("T")[0];
+        return `${today}.jsonl`;
+    }
+    function getHistoryFilePath(filename) {
+        return path.join(historyDir, filename);
+    }
+    function listHistoryFiles() {
+        if (!fs.existsSync(historyDir)) {
+            return [];
+        }
+        return fs.readdirSync(historyDir)
+            .filter((f) => f.endsWith(".jsonl"))
+            .sort()
+            .reverse(); // Most recent first
+    }
+    return {
+        async append(message) {
+            const fullMessage = {
+                ...message,
+                timestamp: new Date().toISOString(),
+            };
+            const filePath = getHistoryFilePath(getTodayFilename());
+            const line = JSON.stringify(fullMessage) + "\n";
+            fs.appendFileSync(filePath, line, "utf-8");
+        },
+        async clear() {
+            const files = listHistoryFiles();
+            for (const file of files) {
+                fs.unlinkSync(getHistoryFilePath(file));
+            }
+        },
+    };
+}
+//# sourceMappingURL=history.js.map

package/dist/history.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"history.js","sourceRoot":"","sources":["../src/history.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EAAE,MAAM,SAAS,CAAC;AACzB,OAAO,IAAI,MAAM,WAAW,CAAC;AA0B7B;;GAEG;AACH,MAAM,UAAU,oBAAoB,CAAC,OAAe;IAClD,MAAM,UAAU,GAAG,IAAI,CAAC,IAAI,CAAC,OAAO,EAAE,SAAS,CAAC,CAAC;IAEjD,0BAA0B;IAC1B,EAAE,CAAC,SAAS,CAAC,UAAU,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;IAE9C,SAAS,gBAAgB;QACvB,MAAM,KAAK,GAAG,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC;QACrD,OAAO,GAAG,KAAK,QAAQ,CAAC;IAC1B,CAAC;IAED,SAAS,kBAAkB,CAAC,QAAgB;QAC1C,OAAO,IAAI,CAAC,IAAI,CAAC,UAAU,EAAE,QAAQ,CAAC,CAAC;IACzC,CAAC;IAED,SAAS,gBAAgB;QACvB,IAAI,CAAC,EAAE,CAAC,UAAU,CAAC,UAAU,CAAC,EAAE,CAAC;YAC/B,OAAO,EAAE,CAAC;QACZ,CAAC;QACD,OAAO,EAAE,CAAC,WAAW,CAAC,UAAU,CAAC;aAC9B,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,QAAQ,CAAC,QAAQ,CAAC,CAAC;aACnC,IAAI,EAAE;aACN,OAAO,EAAE,CAAC,CAAC,oBAAoB;IACpC,CAAC;IAED,OAAO;QACL,KAAK,CAAC,MAAM,CAAC,OAAuC;YAClD,MAAM,WAAW,GAAgB;gBAC/B,GAAG,OAAO;gBACV,SAAS,EAAE,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE;aACpC,CAAC;YACF,MAAM,QAAQ,GAAG,kBAAkB,CAAC,gBAAgB,EAAE,CAAC,CAAC;YACxD,MAAM,IAAI,GAAG,IAAI,CAAC,SAAS,CAAC,WAAW,CAAC,GAAG,IAAI,CAAC;YAChD,EAAE,CAAC,cAAc,CAAC,QAAQ,EAAE,IAAI,EAAE,OAAO,CAAC,CAAC;QAC7C,CAAC;QAED,KAAK,CAAC,KAAK;YACT,MAAM,KAAK,GAAG,gBAAgB,EAAE,CAAC;YACjC,KAAK,MAAM,IAAI,IAAI,KAAK,EAAE,CAAC;gBACzB,EAAE,CAAC,UAAU,CAAC,kBAAkB,CAAC,IAAI,CAAC,CAAC,CAAC;YAC1C,CAAC;QACH,CAAC;KACF,CAAC;AACJ,CAAC"}

package/dist/index.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Bryti entry point.
+ *
+ * Wires config, persistent pi sessions (one per user), channel bridges
+ * (Telegram, WhatsApp), cron scheduler, and the message queue together.
+ *
+ * Startup: load config, ensure data dirs, warm up embedding model, start
+ * bridges, start scheduler, begin processing messages.
+ *
+ * Each message: load (or reuse) the user's persistent session, run
+ * transcript repair, prompt the model with fallback, persist the
+ * response to the JSONL audit log.
+ */
+/**
+ * Exit code that signals an intentional restart to the run.sh supervisor loop.
+ * The loop checks for this code and restarts immediately without delay.
+ */
+export declare const RESTART_EXIT_CODE = 42;
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AA+CH;;;GAGG;AACH,eAAO,MAAM,iBAAiB,KAAK,CAAC"}