auggy 0.3.0

package/src/augments/org-context/skill/SKILL.md

@@ -0,0 +1,96 @@
+---
+name: org-context
+description: When and how to use org_fetch to retrieve knowledge from the operator's organization. Read this before answering questions about the org or its work.
+---
+
+# Org context
+
+You are connected to your operator's **organization knowledge base**. Your system context already includes a manifest — a list of endpoints the org exposes (paths like `/mission`, `/team`, `/projects`). Use `org_fetch` to pull the actual content from any of those endpoints when the conversation needs it.
+
+The manifest is small (~200 tokens, always loaded). The endpoint contents are larger and load only when you fetch them. This is progressive disclosure — you don't pay the token cost of every doc on every turn, only the ones the conversation calls for.
+
+## Tools
+
+| Tool | What it does |
+|------|--------------|
+| `org_fetch(endpoint)` | Retrieve the content of one endpoint listed in the org context manifest |
+
+Only `org_fetch` is exposed here. If you need to alert the operator out-of-band about something (escalate a request you can't handle, flag urgent input, ask for human approval), that's a separate capability — see the `notify` skill if it's mounted in this agent. Don't try to use `org_fetch` for it.
+
+## How to call it
+
+```
+org_fetch({ endpoint: "/mission" })
+```
+
+Or with an optional prompt that the tool can pass through to influence what comes back:
+
+```
+org_fetch({ endpoint: "/projects", prompt: "anything related to onboarding" })
+```
+
+**Parameters:**
+- `endpoint` — the path from the manifest (leading slash optional; the tool normalizes)
+- `prompt` (optional) — a hint about what you're looking for; passed through with the response for your own reference
+
+## What it returns
+
+A JSON envelope. For endpoints whose response is a structured `{ files: [...] }` payload, the tool flattens the files into a single combined-content string with section headers per file:
+
+```
+{
+  "endpoint": "/mission",
+  "fileCount": 1,
+  "content": "## mission.md\n\n<contents>\n\n---\n\n..."
+}
+```
+
+For other shapes, you get the raw body (up to ~20K chars) under `content`. Long responses are truncated with a `[truncated — N total chars]` marker so you know more exists.
+
+## When to call it
+
+| Situation | Endpoint to try |
+|-----------|-----------------|
+| Peer asks what your organization does | The manifest's `org` and `purpose` fields are already in context — you may already have enough |
+| Peer asks about a specific topic (mission, team, projects, decisions) | Find the matching endpoint in the manifest and `org_fetch` it |
+| Peer asks for details that the manifest summary doesn't cover | Fetch the relevant endpoint |
+| You're about to make a claim about the org and aren't sure | Fetch and verify before answering |
+
+The manifest in your system context lists the endpoints available — read it before calling `org_fetch` so you choose the right one. If the manifest doesn't list an endpoint covering what the peer wants, say so directly rather than guessing at paths that may not exist.
+
+## When NOT to call it
+
+- The peer asked something that has nothing to do with the operator's organization. Use other tools (or no tool) instead.
+- You already fetched the endpoint earlier in the same conversation and the content is still in context. Re-fetching doesn't add freshness — it just consumes tokens.
+- The manifest already contains everything the peer asked about (the org name, the purpose, the operator's name if exposed).
+- You're tempted to fetch every endpoint "just in case." Fetch only what's relevant to the current question.
+
+## What you cannot do
+
+- You cannot fetch endpoints not listed in the manifest. The org chose what to expose.
+- You cannot write to or modify org knowledge through this tool — it's read-only.
+- You cannot use `org_fetch` to reach arbitrary URLs on the public web — for that, use the `web_fetch` tool if it's mounted.
+
+## Common mistakes
+
+| Wrong | Correct |
+|-------|---------|
+| Saying "I don't know what this organization is" | Check the manifest already in your context; `org_fetch` a relevant endpoint if details are needed |
+| Fetching every endpoint at the start of a turn | Fetch only what the current question calls for |
+| Inventing endpoint paths the manifest doesn't list | Use only paths from the manifest; if nothing fits, say so |
+| Re-fetching the same endpoint multiple times in one turn | Fetch once; the content stays in your context for the rest of the turn |
+| Using `org_fetch` for general web pages | Use `web_fetch` for arbitrary URLs; `org_fetch` is scoped to the operator's org API |
+| Quoting fetched org docs verbatim back at the peer | Synthesize and answer in your own voice; cite the endpoint if the peer wants the source |
+
+## Workflow
+
+### Peer asks an org-specific question
+
+1. Glance at the manifest already in your context — does it cover the answer at the summary level?
+2. If yes, answer from the summary. If no, find the most relevant endpoint and `org_fetch` it.
+3. Read the returned content; answer in your own words.
+4. If the peer wants more detail than that endpoint provides, look for another endpoint in the manifest or be honest about the limit.
+
+### The org API is unreachable
+
+If the manifest is unavailable (boot-time fetch failed, or the manifest's contents are invalid), your system context will not include it and `org_fetch` calls will return an error envelope (typically `{"error": "Org context unavailable: no manifest loaded; cannot validate endpoint allowlist"}` or similar). Surface that honestly to the peer — say the org knowledge base is temporarily unavailable; don't fabricate answers about the org.

package/src/augments/skills/index.ts

@@ -0,0 +1,103 @@
+/**
+ * Skills augment — emits one context block listing the agent's mounted skills.
+ *
+ * Per ADR-030 (model-facing skill surface separation): identity stays
+ * identity; the kernel surfaces the skill manifest via this augment, sourced
+ * from each SKILL.md's YAML frontmatter (agentskills.io standard). Activation
+ * is `fs_read` via the filesystem augment; the full SKILL.md body is never
+ * boot-loaded.
+ *
+ * The augment is read-only and emits no tools. On every `context()` call it
+ * walks `options.dir`, reading frontmatter from `<dir>/<folder>/SKILL.md`.
+ * Subdirectories without a SKILL.md, with unparseable frontmatter, or with
+ * missing required fields are silently skipped — the boot-time skill
+ * validator (`src/cli/skill-validator.ts`) surfaces those operator-facing.
+ *
+ * The skill folder name (not the frontmatter `name` field) is the canonical
+ * model-facing identifier in the listing, because the model invokes the
+ * skill by file path (`fs_read skills/<folder>/SKILL.md`) — using the
+ * folder name keeps the listing entry and the read path aligned.
+ */
+
+import { readdirSync, statSync } from "node:fs";
+import { join } from "node:path";
+import type { Augment, ContextBlock } from "../../types";
+import { readSkillFrontmatter, type SkillFrontmatter } from "../../cli/skill-frontmatter";
+
+export interface SkillsOptions {
+  /**
+   * Absolute path to the directory containing skill subfolders. Each subfolder
+   * should contain a SKILL.md with `name` + `description` YAML frontmatter.
+   *
+   * The augment-resolver converts relative paths against the agent dir before
+   * construction (same pattern as orgContext's file:// scheme), so the
+   * augment factory only ever sees absolute paths.
+   */
+  dir: string;
+}
+
+interface DiscoveredSkill extends SkillFrontmatter {
+  folder: string;
+}
+
+function discoverSkills(dir: string): DiscoveredSkill[] {
+  let entries: string[];
+  try {
+    entries = readdirSync(dir);
+  } catch {
+    return [];
+  }
+
+  const out: DiscoveredSkill[] = [];
+  for (const folder of entries) {
+    const sub = join(dir, folder);
+    let isDir = false;
+    try {
+      isDir = statSync(sub).isDirectory();
+    } catch {
+      continue;
+    }
+    if (!isDir) continue;
+    const fm = readSkillFrontmatter(join(sub, "SKILL.md"));
+    if (fm === null) continue;
+    out.push({ folder, name: fm.name, description: fm.description });
+  }
+
+  out.sort((a, b) => a.folder.localeCompare(b.folder));
+  return out;
+}
+
+function buildBlockContent(discovered: DiscoveredSkill[]): string {
+  const lines = [
+    "# Skills",
+    "",
+    "Each skill is a guide stored on disk. Read a guide with `fs_read skills/<folder>/SKILL.md` before using its tools when you need usage detail.",
+    "",
+  ];
+  for (const s of discovered) {
+    lines.push(`- ${s.folder} — ${s.description}`);
+  }
+  return lines.join("\n");
+}
+
+export function skills(opts: SkillsOptions): Augment {
+  return {
+    name: "skills",
+    capabilities: ["context"],
+    context: async () => {
+      const discovered = discoverSkills(opts.dir);
+      if (discovered.length === 0) return [];
+      const block: ContextBlock = {
+        source: "skills",
+        content: buildBlockContent(discovered),
+        placement: "system",
+        priority: "required",
+        eviction: "never",
+        origin: "operator",
+        provenance: "augment",
+        ttl: "persistent",
+      };
+      return [block];
+    },
+  };
+}

package/src/augments/supabase-memory/index.ts

@@ -0,0 +1,151 @@
+import type {
+  Augment,
+  MemoryEntry,
+  ContextOrigin,
+  ContextPriority,
+  ContextPlacement,
+  EvictionPolicy,
+} from "../../types";
+
+/**
+ * Minimal Supabase client interface used by supabaseMemory. Compatible
+ * with @supabase/supabase-js and with the test mock.
+ *
+ * Terminal nodes in the chain return `PromiseLike` (not `Promise`) so
+ * thenable builders — like Supabase's PostgrestBuilder, and our mock —
+ * satisfy the type structurally.
+ */
+export interface SupabaseLikeClient {
+  from(table: string): {
+    insert(row: unknown): PromiseLike<{ error: Error | null }>;
+    select(columns?: string): {
+      eq(
+        column: string,
+        value: unknown,
+      ): {
+        maybeSingle(): PromiseLike<{ data: unknown; error: Error | null }>;
+      };
+      ilike(
+        column: string,
+        value: string,
+      ): {
+        order(
+          column: string,
+          opts?: { ascending?: boolean },
+        ): {
+          limit(n: number): PromiseLike<{ data: unknown[]; error: Error | null }>;
+        };
+      };
+    };
+  };
+}
+
+export interface SupabaseMemoryOptions {
+  namespace: string;
+  client: SupabaseLikeClient;
+  table: string;
+  mutable: boolean;
+  origin: ContextOrigin;
+  priority: ContextPriority;
+  placement: ContextPlacement;
+  eviction: EvictionPolicy;
+  searchLimit?: number;
+}
+
+/**
+ * Namespace-based memory provider backed by a Supabase table.
+ * Stores rows with { label, content, metadata?, created_at } and
+ * supports recent-or-relevant retrieval via ILIKE + ordering by
+ * created_at desc. Intended for episodic memory.
+ */
+export function supabaseMemory(opts: SupabaseMemoryOptions): Augment {
+  const prefix = opts.namespace.endsWith(":") ? opts.namespace : `${opts.namespace}:`;
+  const limit = opts.searchLimit ?? 10;
+
+  const search = async (query: string): Promise<MemoryEntry[]> => {
+    // Escape ILIKE wildcards (% and _) in user input so they're treated
+    // as literal characters, not pattern matchers.
+    const escaped = query.replace(/[%_]/g, (c) => `\\${c}`);
+    const { data, error } = await opts.client
+      .from(opts.table)
+      .select("label, content, metadata, created_at")
+      .ilike("content", `%${escaped}%`)
+      .order("created_at", { ascending: false })
+      .limit(limit);
+
+    if (error) throw error;
+    const rows = (data ?? []) as Array<{
+      label: string;
+      content: string;
+      metadata?: Record<string, unknown>;
+    }>;
+    // Defense-in-depth: even if the backing table holds rows from other
+    // namespaces (e.g. several providers sharing one table), this provider
+    // only returns rows it actually owns. Without this filter, the
+    // declared ownership of `${prefix}*` would be silently violated.
+    return rows
+      .filter((r) => r.label.startsWith(prefix))
+      .map((r) => ({
+        label: r.label,
+        content: r.content,
+        metadata: r.metadata,
+      }));
+  };
+
+  const read = async (label: string): Promise<MemoryEntry | null> => {
+    if (!label.startsWith(prefix)) return null;
+    const { data, error } = await opts.client
+      .from(opts.table)
+      .select("label, content, metadata")
+      .eq("label", label)
+      .maybeSingle();
+
+    if (error) throw error;
+    if (!data) return null;
+    const row = data as {
+      label: string;
+      content: string;
+      metadata?: Record<string, unknown>;
+    };
+    return {
+      label: row.label,
+      content: row.content,
+      metadata: row.metadata,
+    };
+  };
+
+  const write = opts.mutable
+    ? async (label: string, content: string): Promise<void> => {
+        if (!label.startsWith(prefix)) {
+          throw new Error(
+            `supabaseMemory: label "${label}" does not start with namespace prefix "${prefix}"`,
+          );
+        }
+        const { error } = await opts.client.from(opts.table).insert({
+          label,
+          content,
+          created_at: new Date().toISOString(),
+        });
+        if (error) throw error;
+      }
+    : undefined;
+
+  return {
+    name: `supabase-memory-${opts.namespace}`,
+    capabilities: ["context", "tools"],
+    memory: {
+      owns: { kind: "namespace", prefix },
+      defaults: {
+        mutable: opts.mutable,
+        origin: opts.origin,
+        priority: opts.priority,
+        placement: opts.placement,
+        eviction: opts.eviction,
+        ttl: "session",
+      },
+      search,
+      read,
+      write,
+    },
+  };
+}

package/src/augments/telegram-transport/index.ts

@@ -0,0 +1,312 @@
+/**
+ * Telegram transport augment — bidirectional Telegram I/O.
+ *
+ * Inbound: polling (T12) or webhook (T13) modes. Both feed updates through
+ * resolveTelegramIdentity to resolve peer identity per the four-path model
+ * from item 5's spec.
+ *
+ * Outbound: replies to the current peer's chat via sendMessage. Outbound to
+ * non-current-peer destinations is notify's job, not this transport's.
+ *
+ * Uses src/telegram-client.ts as a shared utility — no cross-augment coupling.
+ *
+ * Wiring: Implements the TransportSpec contract. The kernel calls
+ * `transport.register(kernel)` to plug in; the augment retains the kernel
+ * handle and calls `kernel.handleInbound(trigger, {onEvent})` for every
+ * inbound text update. The reply path is wired by registering an outbound
+ * callback via `kernel.onOutbound(cb)` once at register-time. Mirrors
+ * web-transport's pattern.
+ */
+
+import type {
+  Augment,
+  InboundMessage,
+  KernelEvent,
+  OutboundMessage,
+  Part,
+  PeerIdentity,
+  TelegramAuthOptions,
+  TelegramTransportOptions,
+  TransportKernel,
+  TransportSpec,
+  TurnTrigger,
+} from "../../types";
+import type { TelegramBotClient, TelegramUpdate } from "../../telegram-client";
+import { createTelegramBotClient } from "../../telegram-client";
+import { runPollLoop, type PollLoopHandle } from "./polling";
+import { startWebhookServer, type WebhookServerHandle } from "./webhook";
+
+// ---------------------------------------------------------------------------
+// Boot-time validation
+// ---------------------------------------------------------------------------
+
+export interface BootLogger {
+  info(msg: string): void;
+  warn(msg: string): void;
+}
+
+export async function validateAdmittedAgents(
+  admittedAgents: Array<{ id: string; telegramUserId: number }> | undefined,
+  client: TelegramBotClient,
+  log: BootLogger = console,
+): Promise<void> {
+  if (!admittedAgents || admittedAgents.length === 0) return;
+  for (const agent of admittedAgents) {
+    try {
+      await client.getChat(agent.telegramUserId);
+      log.info(
+        `[telegram-transport] admittedAgent "${agent.id}" (telegramUserId=${agent.telegramUserId}) resolved successfully`,
+      );
+    } catch (err) {
+      log.warn(
+        `[telegram-transport] admittedAgent "${agent.id}" (telegramUserId=${agent.telegramUserId}) failed boot-time validation: ${(err as Error).message}. Real agent traffic from this user_id will be silently demoted to public-anonymous. Verify the user_id is correct and the bot has access to message that user.`,
+      );
+    }
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Identity resolution
+// ---------------------------------------------------------------------------
+
+export interface ResolveIdentityInput {
+  userId: number;
+  threadId: string;
+}
+
+export function resolveTelegramIdentity(
+  input: ResolveIdentityInput,
+  auth: TelegramAuthOptions,
+): PeerIdentity {
+  const { userId, threadId } = input;
+  const mode = auth.anonymousIdentityMode ?? "ephemeral";
+
+  // Order matches item 5's web-transport: creator → agent → recognized → anonymous.
+  if (auth.creatorUserIds?.includes(userId)) {
+    return {
+      id: `tg_user_${userId}`,
+      kind: "human",
+      trustLevel: "creator",
+      sourceAugment: "telegram-transport",
+    };
+  }
+
+  const admitted = auth.admittedAgents?.find((a) => a.telegramUserId === userId);
+  if (admitted) {
+    return {
+      id: admitted.id,
+      kind: "agent",
+      trustLevel: "agent",
+      sourceAugment: "telegram-transport",
+    };
+  }
+
+  if (auth.recognizedUserIds?.includes(userId)) {
+    return {
+      id: `tg_user_${userId}`,
+      kind: "human",
+      trustLevel: "public",
+      publicSubstate: "recognized",
+      sourceAugment: "telegram-transport",
+    };
+  }
+
+  // Default: public-anonymous with mode-driven peer.id shape.
+  return {
+    id: mode === "durable" ? `tg_user_${userId}` : `tg_anon_${threadId}`,
+    kind: "human",
+    trustLevel: "public",
+    publicSubstate: "anonymous",
+    sourceAugment: "telegram-transport",
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Augment factory — full lifecycle (T14)
+// ---------------------------------------------------------------------------
+
+/**
+ * Internal extension of TelegramTransportOptions that adds test-only hooks.
+ * The public type does not include this field; tests use `as any` to pass it.
+ */
+interface InternalOptions extends TelegramTransportOptions {
+  /** Test-only: override the bot client factory. Useful for unit tests
+   *  that don't want to hit the real Telegram bot API. */
+  _clientFactory?: () => TelegramBotClient;
+}
+
+export function telegramTransport(opts: TelegramTransportOptions): Augment {
+  const internal = opts as InternalOptions;
+  const clientFactory =
+    internal._clientFactory ?? (() => createTelegramBotClient({ botToken: opts.botToken }));
+  const client = clientFactory();
+
+  let pollHandle: PollLoopHandle | null = null;
+  let webhookHandle: WebhookServerHandle | null = null;
+  let kernel: TransportKernel | null = null;
+  let registeredName: string | null = null;
+
+  /**
+   * Per-thread chat_id map. Populated when an inbound update arrives, read
+   * by the outbound callback so we know where to deliver the reply.
+   * Keyed by threadId (`tg-chat-<chatId>`) — same shape as the threadId we
+   * pass into resolveTelegramIdentity and into the TurnTrigger.
+   */
+  const threadChatIds = new Map<string, number | string>();
+
+  // ---------------------------------------------------------------------------
+  // Identity resolver (TransportSpec.identify)
+  // ---------------------------------------------------------------------------
+  //
+  // The kernel calls identify() with the raw inbound. For Telegram, the raw
+  // inbound is shaped `{ userId, threadId }` — we extract those before calling
+  // handleInbound so the kernel can pre-resolve peer identity if it wants to.
+
+  const identify = (raw: unknown): PeerIdentity | null => {
+    const r = raw as { userId?: number; threadId?: string };
+    if (typeof r?.userId !== "number" || typeof r?.threadId !== "string") return null;
+    return resolveTelegramIdentity({ userId: r.userId, threadId: r.threadId }, opts.auth);
+  };
+
+  const transport: TransportSpec = {
+    async register(k: TransportKernel, augmentName: string) {
+      kernel = k;
+      registeredName = augmentName;
+      // Wire the outbound callback once. The kernel invokes this for every
+      // outbound text message during a turn — we look up the chat_id by
+      // threadId (set when the inbound arrived) and call sendMessage.
+      kernel.onOutbound(async (_peer: PeerIdentity, message: OutboundMessage) => {
+        // Telegram replies are text-only in v0. Concatenate all text parts
+        // to mirror the AG-UI text_message kernel events.
+        const textParts = message.parts
+          .filter((p): p is Extract<Part, { kind: "text" }> => p.kind === "text")
+          .map((p) => p.text);
+        if (textParts.length === 0) return;
+        const text = textParts.join("");
+
+        // Find the chat_id. Prefer contextId/taskId-mapped threadId; fall
+        // back to message.targetPeer if the kernel relays it. The contract
+        // we set up at handleInbound time uses contextId === threadId.
+        const threadId = message.contextId;
+        if (!threadId) return;
+        const chatId = threadChatIds.get(threadId);
+        if (chatId === undefined) return;
+
+        try {
+          await client.sendMessage(chatId, text);
+        } catch (err) {
+          console.warn(
+            `[telegram-transport] sendMessage failed for chatId=${chatId}: ${(err as Error).message}`,
+          );
+        }
+      });
+    },
+    identify,
+  };
+
+  /**
+   * Convert a Telegram update to a TurnTrigger and dispatch via the kernel.
+   * Mirrors web-transport's handleAgentRun shape: build InboundMessage,
+   * wrap in TurnTrigger, call kernel.handleInbound.
+   */
+  async function handleUpdate(update: TelegramUpdate): Promise<void> {
+    if (!kernel) return; // Not yet registered — drop the update.
+    if (!update.message?.text || !update.message.from) return;
+
+    const userId = update.message.from.id;
+    const chatId = update.message.chat.id;
+    const threadId = `tg-chat-${chatId}`;
+    const peer = resolveTelegramIdentity({ userId, threadId }, opts.auth);
+
+    // Remember chat_id for the outbound callback.
+    threadChatIds.set(threadId, chatId);
+
+    const parts: Part[] = [{ kind: "text", text: update.message.text }];
+    const inbound: InboundMessage = {
+      parts,
+      sourceAugment: "telegram-transport",
+      peer,
+      timestamp: Date.now(),
+      contextId: threadId,
+    };
+    const trigger: TurnTrigger = {
+      type: "message",
+      turnId: crypto.randomUUID(),
+      threadId,
+      contextId: threadId,
+      timestamp: Date.now(),
+      source: registeredName ?? "telegram-transport",
+      peer,
+      payload: inbound,
+    };
+
+    // Drop kernelEvents on the floor for now (no streaming UI for Telegram
+    // in v0). The text replies arrive via the onOutbound callback wired in
+    // register(). If a streaming-edit (editMessageText) experience is added
+    // later, this is where text_message_delta would be intercepted.
+    const onEvent = (_e: KernelEvent): void => {};
+
+    try {
+      await kernel.handleInbound(trigger, { onEvent });
+    } catch (err) {
+      console.warn(
+        `[telegram-transport] kernel.handleInbound failed for threadId=${threadId}: ${(err as Error).message}`,
+      );
+    }
+  }
+
+  return {
+    name: "telegram-transport",
+    capabilities: ["transport"],
+    transport,
+
+    async onBoot(): Promise<void> {
+      await validateAdmittedAgents(opts.auth.admittedAgents, client);
+
+      if (opts.inbound.mode === "polling") {
+        pollHandle = runPollLoop({
+          client,
+          timeoutSec: opts.inbound.polling?.timeoutSec ?? 30,
+          onUpdate: (u) => handleUpdate(u),
+        });
+      } else if (opts.inbound.mode === "webhook") {
+        if (!opts.inbound.webhook) {
+          throw new Error(
+            "[telegram-transport] inbound.mode === 'webhook' requires inbound.webhook config",
+          );
+        }
+        await client.setWebhook(opts.inbound.webhook.publicUrl, opts.inbound.webhook.secretToken, {
+          allowedUpdates: opts.inbound.webhook.allowedUpdates,
+        });
+        webhookHandle = await startWebhookServer({
+          port: opts.inbound.webhook.port ?? 8081,
+          secretToken: opts.inbound.webhook.secretToken,
+          onUpdate: (u) => handleUpdate(u),
+        });
+      } else {
+        throw new Error(
+          `[telegram-transport] inbound.mode must be 'polling' or 'webhook' (got ${(opts.inbound as { mode: unknown }).mode})`,
+        );
+      }
+    },
+
+    async onShutdown(): Promise<void> {
+      if (pollHandle) {
+        pollHandle.stop();
+        await pollHandle.done;
+        pollHandle = null;
+      }
+      if (webhookHandle) {
+        webhookHandle.stop();
+        webhookHandle = null;
+        try {
+          await client.deleteWebhook();
+        } catch (err) {
+          console.warn(
+            `[telegram-transport] deleteWebhook on shutdown failed: ${(err as Error).message}`,
+          );
+        }
+      }
+    },
+  };
+}