auggy 0.3.0

package/src/agent.ts

@@ -0,0 +1,283 @@
+import type {
+  AgentCard,
+  AgentConfig,
+  AgentHandle,
+  AgentHealth,
+  ModelClient,
+  TurnTrigger,
+  TurnResult,
+  TransportKernel,
+  PeerIdentity,
+  OutboundMessage,
+  SchedulerContext,
+} from "./types";
+import { createTokenizer } from "./tokenizer";
+import { generateAgentCard } from "./agent-card";
+import { wireMemoryBus } from "./memory/memory-bus";
+import { createTurnLoop } from "./kernel/turn-loop";
+import { createLifecycleManager } from "./kernel/lifecycle-manager";
+import { createTransportQueue } from "./kernel/transport-queue";
+import { collectAugmentRoutes } from "./kernel/route-collector";
+import type { CollectedRoute } from "./kernel/route-collector";
+
+export function defineAgent(config: AgentConfig, model: ModelClient): AgentHandle {
+  const tokenizer = createTokenizer();
+
+  // Wire the memory bus BEFORE constructing other kernel components.
+  // This synthesizes context() for memory providers and adds a synthetic
+  // augment carrying the generic memory tools.
+  const wiring = wireMemoryBus(config.augments);
+  const effectiveAugments = wiring.syntheticToolsAugment
+    ? [...wiring.augmentsWithSynthesizedContext, wiring.syntheticToolsAugment]
+    : wiring.augmentsWithSynthesizedContext;
+
+  const effectiveConfig: AgentConfig = {
+    ...config,
+    augments: effectiveAugments,
+  };
+
+  // Agent card is generated from the effective config (includes memory
+  // capability if any augment has a memory field).
+  const agentCard: AgentCard = generateAgentCard(effectiveConfig);
+
+  const lifecycle = createLifecycleManager({
+    name: effectiveConfig.name,
+    augments: effectiveAugments,
+    model,
+  });
+  const turnLoop = createTurnLoop({
+    augments: effectiveAugments,
+    model,
+    tokenizer,
+    config: effectiveConfig,
+  });
+
+  const outboundHandlers = new Map<
+    string,
+    (peer: PeerIdentity, message: OutboundMessage) => Promise<void>
+  >();
+
+  let started = false;
+
+  async function dispatchOutbound(result: TurnResult, trigger: TurnTrigger) {
+    // Collect all messages to dispatch: single response + multi-destination responses
+    const messages: OutboundMessage[] = [];
+    if (result.response) messages.push(result.response);
+    if (result.responses) messages.push(...result.responses);
+    if (messages.length === 0) return;
+
+    for (const msg of messages) {
+      const targetAugment = msg.targetAugment ?? trigger.source;
+      const peer = trigger.peer;
+      if (!targetAugment || !peer) continue;
+      const handler = outboundHandlers.get(targetAugment);
+      if (handler) {
+        await handler(peer, msg);
+      }
+    }
+  }
+
+  const handle: AgentHandle = {
+    async start() {
+      if (started) throw new Error("Agent already started. Call stop() first.");
+      await lifecycle.boot();
+
+      // PR γ.1 — collect augment-registered HTTP routes AFTER boot so
+      // onBoot-populated route lists are visible, BEFORE any transport
+      // binds a port so a collision can't leave the agent half-bound.
+      const collected = collectAugmentRoutes(effectiveAugments);
+      if (collected.errors.length > 0) {
+        // Run shutdown to undo the boot side-effects we just performed
+        // (otherwise SQLite handles, file watchers, etc. leak).
+        try {
+          await lifecycle.shutdown();
+        } catch {
+          // best-effort; the original validation error wins
+        }
+        throw new Error(
+          `Cannot start agent — augment HTTP route validation failed:\n  ` +
+            collected.errors.join("\n  "),
+        );
+      }
+      const augmentRoutes: readonly CollectedRoute[] = collected.routes;
+
+      // Register transport augments
+      for (const aug of effectiveAugments) {
+        if (aug.transport) {
+          const queue = createTransportQueue({
+            concurrency: aug.transport.concurrency ?? 1,
+            maxQueueDepth: aug.transport.maxQueueDepth ?? 50,
+            rateLimitPerPeer: aug.transport.rateLimitPerPeer,
+          });
+
+          const transportKernel: TransportKernel = {
+            async handleInbound(
+              trigger: TurnTrigger,
+              opts?: { onEvent?: import("./types").KernelEventHandler },
+            ): Promise<TurnResult> {
+              return queue.enqueue(trigger, async (t) => {
+                lifecycle.resetIdleTimer();
+                const threadId = t.threadId ?? t.turnId;
+                const result = await turnLoop.executeTurn(t, threadId, {
+                  onEvent: opts?.onEvent,
+                });
+
+                await dispatchOutbound(result, t);
+
+                // Eager compaction
+                const historyBudget = Math.floor(
+                  model.maxContextTokens * ((config.contextBudget?.historyPercent ?? 40) / 100),
+                );
+                turnLoop
+                  .getHistoryManager(threadId)
+                  .compact(historyBudget, config.compactionStrategy ?? "truncate");
+
+                // Run onTurnEnd hooks. Awaited sequentially in declaration
+                // order so ADR-027's lifecycle ordering guarantee holds —
+                // scheduleAfterTurn must observe a fully-settled onTurnEnd.
+                for (const a of effectiveAugments) {
+                  if (a.onTurnEnd) {
+                    try {
+                      await a.onTurnEnd(result);
+                    } catch (err) {
+                      console.warn(`onTurnEnd hook "${a.name}" failed: ${err}`);
+                    }
+                  }
+                }
+
+                // ADR-027: dispatch scheduleAfterTurn (same semantics as the
+                // inject() path) — sequential, error-isolated, transcript
+                // closure-bound to the just-completed turn. The hook runs
+                // here as well as in inject() so transport-driven turns
+                // (web/Telegram) get the same post-turn surface as kernel-
+                // injected ones; PR β's auto-save depends on both paths
+                // firing identically.
+                const completedTurnIdT = result.turnId;
+                const completedThreadIdT = threadId;
+                const ctxT: SchedulerContext = {
+                  inject: (next) => handle.inject(next),
+                  getCompletedTranscript: async () =>
+                    turnLoop.getHistoryManager(completedThreadIdT).getTranscript(completedTurnIdT),
+                };
+                for (const a of effectiveAugments) {
+                  if (a.scheduleAfterTurn) {
+                    try {
+                      await a.scheduleAfterTurn(result, ctxT);
+                    } catch (err) {
+                      console.warn(
+                        `scheduleAfterTurn hook "${a.name}" threw: ${(err as Error).message}`,
+                      );
+                    }
+                  }
+                }
+
+                return result;
+              });
+            },
+            onOutbound(callback) {
+              outboundHandlers.set(aug.name, callback);
+            },
+            getAgentCard() {
+              return agentCard;
+            },
+            getAugmentRoutes() {
+              return augmentRoutes;
+            },
+          };
+          await aug.transport.register(transportKernel, aug.name);
+        }
+      }
+
+      // Start idle timer
+      lifecycle.startIdleTimer(async () => {
+        for (const aug of effectiveAugments) {
+          if (aug.onIdle) {
+            try {
+              await aug.onIdle();
+            } catch {
+              // Log and continue
+            }
+          }
+        }
+      });
+
+      started = true;
+    },
+
+    async stop() {
+      if (!started) return; // no-op if not started
+      lifecycle.stopIdleTimer();
+      await lifecycle.shutdown();
+      started = false;
+    },
+
+    async ready() {
+      if (!started) throw new Error("Agent not started");
+    },
+
+    health(): AgentHealth {
+      return lifecycle.health();
+    },
+
+    card(): AgentCard {
+      return agentCard;
+    },
+
+    async inject(trigger: TurnTrigger): Promise<TurnResult> {
+      lifecycle.resetIdleTimer();
+      const threadId = trigger.threadId ?? trigger.turnId;
+      const result = await turnLoop.executeTurn(trigger, threadId);
+
+      await dispatchOutbound(result, trigger);
+
+      // Eager compaction
+      const historyBudget = Math.floor(
+        model.maxContextTokens * ((config.contextBudget?.historyPercent ?? 40) / 100),
+      );
+      turnLoop
+        .getHistoryManager(threadId)
+        .compact(historyBudget, config.compactionStrategy ?? "truncate");
+
+      // Run onTurnEnd hooks. Awaited sequentially in declaration order so
+      // that ADR-027's lifecycle ordering guarantee holds — scheduleAfterTurn
+      // must observe a fully-settled onTurnEnd. Errors are caught/logged so
+      // a single failing hook never propagates out of the inject path.
+      for (const a of effectiveAugments) {
+        if (a.onTurnEnd) {
+          try {
+            await a.onTurnEnd(result);
+          } catch (err) {
+            console.warn(`onTurnEnd hook "${a.name}" failed: ${err}`);
+          }
+        }
+      }
+
+      // ADR-027: dispatch scheduleAfterTurn for augments that registered it.
+      // SchedulerContext closes over inject (this handle's method) +
+      // getCompletedTranscript (closure-bound to the just-completed turn id;
+      // arbitrary-turnId reads stay kernel-internal at v1.0). Sequential
+      // execution in declaration order per ADR-027 Decision 2; errors are
+      // caught + logged, never propagated — background work is best-effort.
+      const completedTurnId = result.turnId;
+      const completedThreadId = threadId;
+      const ctx: SchedulerContext = {
+        inject: (t) => handle.inject(t),
+        getCompletedTranscript: async () =>
+          turnLoop.getHistoryManager(completedThreadId).getTranscript(completedTurnId),
+      };
+      for (const a of effectiveAugments) {
+        if (a.scheduleAfterTurn) {
+          try {
+            await a.scheduleAfterTurn(result, ctx);
+          } catch (err) {
+            console.warn(`scheduleAfterTurn hook "${a.name}" threw: ${(err as Error).message}`);
+          }
+        }
+      }
+
+      return result;
+    },
+  };
+
+  return handle;
+}

package/src/agentmail-client.ts

@@ -0,0 +1,138 @@
+/**
+ * AgentMail HTTP client — stateless infrastructure shared by the notify
+ * agentmail adapter and (future) the agentMail augment.
+ *
+ * Pattern matches src/telegram-client.ts: env-var or constructor-arg keyed,
+ * no SQLite state, no augment-system coupling.
+ */
+
+import { createHttpClient } from "./http";
+import type { HttpClient } from "./http";
+
+const DEFAULT_BASE_URL = "https://api.agentmail.to/v0";
+
+export interface AgentMailClientOptions {
+  apiKey: string;
+  /** Override AgentMail API base URL (testing/sandbox). */
+  apiBaseUrl?: string;
+  /** Timeout per request. Default 15s. */
+  timeoutMs?: number;
+  /** Test-only HTTP client override. */
+  http?: Pick<HttpClient, "post" | "get">;
+}
+
+export interface AgentMailInboxInfo {
+  inboxId: string;
+  /** Echoed back when the inbox exists. */
+  status: "ok";
+}
+
+export interface AgentMailInboxError {
+  status: "failed";
+  detail: string;
+  /** HTTP status if the failure originated from AgentMail (vs. network). */
+  httpStatus?: number;
+}
+
+export interface SendMessageInput {
+  inboxId: string;
+  to: string[];
+  subject: string;
+  text: string;
+  html?: string;
+  labels?: string[];
+}
+
+export interface SendMessageResult {
+  status: "sent";
+  messageId: string;
+  threadId: string;
+}
+
+export interface SendMessageError {
+  status: "failed";
+  detail: string;
+  /** HTTP status if the failure originated from AgentMail (vs. network). */
+  httpStatus?: number;
+  /** AgentMail-returned Retry-After if 429. */
+  retryAfterSec?: number;
+}
+
+export interface AgentMailClient {
+  send(input: SendMessageInput): Promise<SendMessageResult | SendMessageError>;
+  /**
+   * Best-effort healthcheck. Pings AgentMail's `inboxes.get` endpoint to
+   * confirm the inbox exists and the API key has access. Used by visitorAuth
+   * onBoot. Caller should warn-and-continue on failure: a transient AgentMail
+   * outage shouldn't block agent startup; the first real send will surface
+   * the same error.
+   */
+  getInbox(inboxId: string): Promise<AgentMailInboxInfo | AgentMailInboxError>;
+}
+
+export function createAgentMailClient(opts: AgentMailClientOptions): AgentMailClient {
+  const baseUrl = opts.apiBaseUrl ?? DEFAULT_BASE_URL;
+  const http =
+    opts.http ??
+    createHttpClient({
+      timeoutMs: opts.timeoutMs ?? 15_000,
+      userAgent: "auggy-agentmail-client/0.1",
+    });
+  return {
+    async send(input) {
+      const url = `${baseUrl}/inboxes/${input.inboxId}/messages`;
+      const body = JSON.stringify({
+        to: input.to,
+        subject: input.subject,
+        text: input.text,
+        ...(input.html ? { html: input.html } : {}),
+        ...(input.labels && input.labels.length > 0 ? { labels: input.labels } : {}),
+      });
+      try {
+        const res = await http.post(url, {
+          headers: {
+            "content-type": "application/json",
+            authorization: `Bearer ${opts.apiKey}`,
+          },
+          body,
+        });
+        if (res.status < 200 || res.status >= 300) {
+          const result: SendMessageError = {
+            status: "failed",
+            detail: `agentmail returned ${res.status}: ${res.body.slice(0, 200)}`,
+            httpStatus: res.status,
+          };
+          if (res.status === 429) {
+            const retry = res.headers.get("retry-after");
+            if (retry) result.retryAfterSec = Number(retry) || undefined;
+          }
+          return result;
+        }
+        const parsed = JSON.parse(res.body) as { message_id: string; thread_id: string };
+        return { status: "sent", messageId: parsed.message_id, threadId: parsed.thread_id };
+      } catch (err) {
+        return { status: "failed", detail: `agentmail error: ${(err as Error).message}` };
+      }
+    },
+    async getInbox(inboxId: string) {
+      const url = `${baseUrl}/inboxes/${inboxId}`;
+      try {
+        const res = await http.get(url, {
+          headers: {
+            authorization: `Bearer ${opts.apiKey}`,
+          },
+        });
+        if (res.status < 200 || res.status >= 300) {
+          return {
+            status: "failed" as const,
+            detail: `agentmail returned ${res.status}: ${res.body.slice(0, 200)}`,
+            httpStatus: res.status,
+          };
+        }
+        return { inboxId, status: "ok" as const };
+      } catch (err) {
+        return { status: "failed" as const, detail: `agentmail error: ${(err as Error).message}` };
+      }
+    },
+  };
+}