auggy 0.3.0

package/src/index.ts

@@ -0,0 +1,165 @@
+// === Core types ===
+export type {
+  // Context
+  Augment,
+  AugmentCapability,
+  AugmentConstraints,
+  AgentConfig,
+  AgentHandle,
+  AgentHealth,
+  ContextBlock,
+  ContextPlacement,
+  ContextProvenance,
+  ContextPriority,
+  EvictionPolicy,
+  ContextOrigin,
+  // A2A-compatible content
+  Part,
+  TaskState,
+  // Memory
+  MemoryDefaults,
+  MemoryEntry,
+  MemoryProviderSpec,
+  StaticMemoryProvider,
+  NamespaceMemoryProvider,
+  // Tools
+  Tool,
+  ToolCategory,
+  ToolDefinition,
+  // Peers
+  PeerIdentity,
+  PeerKind,
+  TrustLevel,
+  // Turns
+  TurnTrigger,
+  TurnTriggerType,
+  TurnState,
+  TurnResult,
+  OutboundMessage,
+  InboundMessage,
+  Message,
+  MessageRole,
+  ToolCallRecord,
+  // ADR-027 — post-turn background work
+  Transcript,
+  SchedulerContext,
+  // Kernel events
+  KernelEvent,
+  KernelEventHandler,
+  // Model
+  ModelClient,
+  ModelResponse,
+  AssembledPrompt,
+  // Storage
+  Storage,
+  // Transport
+  TransportSpec,
+  TransportKernel,
+  // Agent Card
+  AgentCard,
+  AgentCardProvider,
+  AgentCardCapabilities,
+  AgentCardSkill,
+  // Traces
+  TurnTrace,
+  // History
+  CompactionStrategy,
+} from "./types";
+
+// === Agent definition ===
+export { defineAgent } from "./agent";
+
+// === Agent Card ===
+export { generateAgentCard } from "./agent-card";
+
+// === Helpers ===
+export { defineAugment, defineTool } from "./helpers";
+export { extractText, textPart, dataPart } from "./parts";
+
+// === Tokenizer (for augment authors who need token counting) ===
+export { createTokenizer } from "./tokenizer";
+
+// === Built-in augments ===
+export { fileMemory } from "./augments/file-memory";
+export type { FileMemoryOptions } from "./augments/file-memory";
+export { supabaseMemory } from "./augments/supabase-memory";
+export type { SupabaseMemoryOptions } from "./augments/supabase-memory";
+export { filesystem } from "./augments/filesystem";
+export type { FilesystemOptions, FsMount } from "./augments/filesystem";
+
+// === Built-in augments (org) ===
+export { orgContext } from "./augments/org-context";
+export type { OrgContextOptions } from "./augments/org-context";
+
+// === Built-in augments (web) ===
+export { webFetch } from "./augments/web-fetch";
+export type { WebFetchOptions, WebFetchResult } from "./augments/web-fetch";
+
+export { bash } from "./augments/bash";
+export type {
+  BashAugmentOptions,
+  BashRiskLevel,
+  BashScript,
+} from "./augments/bash";
+
+// === HTTP client (for augment authors who need HTTP) ===
+export { createHttpClient } from "./http";
+export type {
+  HttpClient,
+  HttpClientOptions,
+  HttpRequestInit,
+  HttpResponse,
+} from "./http";
+
+// === Built-in transports ===
+export { webTransport } from "./transports/web-transport";
+export type { WebTransportOptions } from "./transports/web-transport";
+
+// === Engines (model client adapters) ===
+export { createAnthropicEngine } from "./engines/anthropic";
+export type { AnthropicEngineOptions } from "./engines/anthropic";
+export { createOpenAIEngine } from "./engines/openai";
+export type { OpenAIEngineOptions } from "./engines/openai";
+export {
+  assembleOpenAISystemMessage,
+  buildOpenAIModelResponse,
+  convertOpenAIMessages,
+  convertOpenAITools,
+  safeParseJson as openaiSafeParseJson,
+  safeParseToolCall as openaiSafeParseToolCall,
+} from "./engines/openai";
+export { createOpenRouterEngine } from "./engines/openrouter";
+export type {
+  OpenRouterEngineOptions,
+  OpenRouterProviderRouting,
+} from "./engines/openrouter";
+
+// === AG-UI event protocol (for custom transports or advanced consumers) ===
+export {
+  runStarted,
+  runFinished,
+  runError,
+  textMessageStart,
+  textMessageContent,
+  textMessageEnd,
+  toolCallStart,
+  toolCallArgs,
+  toolCallEnd,
+  toolCallResult,
+  translateKernelEvent,
+  serializeSSE,
+} from "./transports/ag-ui-events";
+export type {
+  AGUIEvent,
+  AGUIBaseEvent,
+  AGUIRunStarted,
+  AGUIRunFinished,
+  AGUIRunError,
+  AGUITextMessageStart,
+  AGUITextMessageContent,
+  AGUITextMessageEnd,
+  AGUIToolCallStart,
+  AGUIToolCallArgs,
+  AGUIToolCallEnd,
+  AGUIToolCallResult,
+} from "./transports/ag-ui-events";

package/src/kernel/capability-table.ts

@@ -0,0 +1,172 @@
+import type { Augment, PeerIdentity, TrustLevel, TurnState } from "../types";
+
+const KERNEL_DEFAULT_MAX_TOOL_CALLS = 5;
+
+/**
+ * Null peer means "no external initiator" — an internal/scheduled trigger
+ * fired by the agent's own configuration. Treated as operator for capability
+ * checks: if the operator scheduled it, the operator authorized it.
+ */
+export function effectiveTrustLevel(peer: PeerIdentity | null): TrustLevel {
+  return peer?.trustLevel ?? "creator";
+}
+
+export interface CapabilityTable {
+  canExpose(toolName: string, turn: TurnState): boolean;
+  canExecute(
+    toolName: string,
+    input: unknown,
+    turn: TurnState,
+  ): { allowed: true } | { needsApproval: true; reason: string } | { denied: true; reason: string };
+  recordToolCall(toolName: string): void;
+  resetTurn(): void;
+}
+
+export function createCapabilityTable(augments: Augment[]): CapabilityTable {
+  const neverExpose = new Set<string>();
+  const requiresApproval = new Set<string>();
+  // Per-trust-level additive constraints. Applied on top of the global sets.
+  const perLevelNeverExpose = new Map<TrustLevel, Set<string>>();
+  const perLevelRequiresApproval = new Map<TrustLevel, Set<string>>();
+
+  // Map tool name → augment name
+  const toolOwner = new Map<string, string>();
+  // Map augment name → max tool calls (kernel default if unset)
+  const augmentLimits = new Map<string, number>();
+  // Per-turn counters: augment name → calls this turn
+  const augmentCallCounts = new Map<string, number>();
+  // Global limit (sum of all augment limits or kernel default * augment count)
+  let globalLimit = 0;
+  let globalCalls = 0;
+
+  for (const aug of augments) {
+    const c = aug.constraints;
+    if (c) {
+      for (const tool of c.neverExpose ?? []) neverExpose.add(tool);
+      for (const tool of c.requiresHumanApproval ?? []) requiresApproval.add(tool);
+
+      if (c.perTrustLevel) {
+        for (const [level, rules] of Object.entries(c.perTrustLevel) as [
+          TrustLevel,
+          { neverExpose?: string[]; requiresHumanApproval?: string[] },
+        ][]) {
+          if (!rules) continue;
+          for (const tool of rules.neverExpose ?? []) {
+            let set = perLevelNeverExpose.get(level);
+            if (!set) {
+              set = new Set<string>();
+              perLevelNeverExpose.set(level, set);
+            }
+            set.add(tool);
+          }
+          for (const tool of rules.requiresHumanApproval ?? []) {
+            let set = perLevelRequiresApproval.get(level);
+            if (!set) {
+              set = new Set<string>();
+              perLevelRequiresApproval.set(level, set);
+            }
+            set.add(tool);
+          }
+        }
+      }
+    }
+
+    const limit = c?.maxToolCallsPerTurn ?? KERNEL_DEFAULT_MAX_TOOL_CALLS;
+    augmentLimits.set(aug.name, limit);
+    globalLimit += limit;
+
+    for (const tool of aug.tools ?? []) {
+      toolOwner.set(tool.name, aug.name);
+    }
+  }
+
+  // If no augments have tools, use kernel default as global limit
+  if (globalLimit === 0) globalLimit = KERNEL_DEFAULT_MAX_TOOL_CALLS;
+
+  return {
+    canExpose(toolName: string, turn: TurnState): boolean {
+      // Global block (applies to every trust level, no escape).
+      if (neverExpose.has(toolName)) return false;
+      // Per-trust-level block (applies only to that level).
+      const level = effectiveTrustLevel(turn.peer);
+      if (perLevelNeverExpose.get(level)?.has(toolName)) return false;
+      return true;
+    },
+
+    canExecute(toolName: string, _input: unknown, turn: TurnState) {
+      const level = effectiveTrustLevel(turn.peer);
+
+      // Structural denial: tools in neverExpose cannot execute, regardless
+      // of whether they appeared in the model's tool list. canExpose is a
+      // pre-flight filter that shapes the catalog shown to the model;
+      // canExecute must re-enforce the same rule here because the turn
+      // loop resolves tool calls against the full tool registry — if the
+      // model fabricates a tool name that happens to match a withheld
+      // tool, without this check the call would run.
+      if (neverExpose.has(toolName)) {
+        return {
+          denied: true,
+          reason: `Tool "${toolName}" is blocked (neverExpose)`,
+        };
+      }
+      if (perLevelNeverExpose.get(level)?.has(toolName)) {
+        return {
+          denied: true,
+          reason: `Tool "${toolName}" is not available at trust level "${level}"`,
+        };
+      }
+
+      // Global limit
+      if (globalCalls >= globalLimit) {
+        return {
+          denied: true,
+          reason: `Global max tool calls per turn (${globalLimit}) exceeded`,
+        };
+      }
+
+      // Per-augment limit
+      const owner = toolOwner.get(toolName);
+      if (owner) {
+        const limit = augmentLimits.get(owner) ?? KERNEL_DEFAULT_MAX_TOOL_CALLS;
+        const count = augmentCallCounts.get(owner) ?? 0;
+        if (count >= limit) {
+          return {
+            denied: true,
+            reason: `Max tool calls for augment "${owner}" (${limit}) exceeded`,
+          };
+        }
+      }
+
+      // Global approval gate (applies to every trust level).
+      if (requiresApproval.has(toolName)) {
+        return {
+          needsApproval: true,
+          reason: `Tool "${toolName}" requires human approval`,
+        };
+      }
+
+      // Per-trust-level approval gate (applies only to that level).
+      if (perLevelRequiresApproval.get(level)?.has(toolName)) {
+        return {
+          needsApproval: true,
+          reason: `Tool "${toolName}" requires human approval for peer trust level "${level}"`,
+        };
+      }
+
+      return { allowed: true };
+    },
+
+    recordToolCall(toolName: string) {
+      globalCalls++;
+      const owner = toolOwner.get(toolName);
+      if (owner) {
+        augmentCallCounts.set(owner, (augmentCallCounts.get(owner) ?? 0) + 1);
+      }
+    },
+
+    resetTurn() {
+      globalCalls = 0;
+      augmentCallCounts.clear();
+    },
+  };
+}

package/src/kernel/context-allocator.ts

@@ -0,0 +1,161 @@
+import type {
+  AssembledPrompt,
+  ContextBlock,
+  ContextPriority,
+  Message,
+  ToolDefinition,
+} from "../types";
+import type { Tokenizer } from "../tokenizer";
+
+const PRIORITY_ORDER: ContextPriority[] = ["required", "high", "normal", "low", "evictable"];
+
+/**
+ * Phase 1b Task 8: per-entry origin → provenance marker mapping.
+ *
+ * synthesizeContextFor stamps each ContextBlock with the per-entry
+ * origin (or the provider's defaults.origin when an entry has none).
+ * Each block represents one memory entry — multiple blocks from the
+ * same provider may carry different origin values when entries were
+ * written by different write paths (e.g. memory_write from the model
+ * vs. auto-save from the layered-memory extractor).
+ *
+ * The marker map honors the canonical OriginValue union from the
+ * storage layer ("operator" | "peer-derived" | "agent-derived" |
+ * "agent") plus the kernel's ContextOrigin ("system" + the above).
+ * Both "agent" (model wrote it) and "agent-derived" (auto-save
+ * extractor wrote it) render as [AGENT-DERIVED] — the skill teaches
+ * the model to treat both as paraphrase / self-note. Operator and
+ * system origins remain unmarked at v1.0; the preamble already
+ * teaches behavioral guidance for [PEER-DERIVED] and [AGENT-DERIVED]
+ * only, so introducing [OPERATOR] / [SYSTEM] without paired preamble
+ * guidance would just be noise to the model.
+ *
+ * Unknown origin values render unmarked (forward-compat: a future
+ * OriginValue extension ships marker + preamble guidance together).
+ */
+function originMarker(origin: ContextBlock["origin"] | string | undefined): string {
+  switch (origin) {
+    case "peer-derived":
+      return "[PEER-DERIVED]";
+    case "agent":
+    case "agent-derived":
+      return "[AGENT-DERIVED]";
+    default:
+      return "";
+  }
+}
+
+export interface ContextAllocatorConfig {
+  maxTokens: number;
+  historyPercent: number;
+  toolSchemaPercent: number;
+  tokenizer: Tokenizer;
+  preamble: string;
+}
+
+export function createContextAllocator(config: ContextAllocatorConfig) {
+  const preambleTokens = config.tokenizer.count(config.preamble);
+
+  return {
+    assemble(
+      augmentBlocks: ContextBlock[],
+      history: Message[],
+      tools: ToolDefinition[],
+      opts?: { toolChoice?: AssembledPrompt["toolChoice"] },
+    ): AssembledPrompt {
+      const historyBudget = Math.floor(config.maxTokens * (config.historyPercent / 100));
+      const toolBudget = Math.floor(config.maxTokens * (config.toolSchemaPercent / 100));
+
+      // Count actual tool schema tokens
+      const toolSchemaTokens = tools.reduce((sum, t) => {
+        const schemaStr = JSON.stringify(t);
+        return sum + config.tokenizer.count(schemaStr);
+      }, 0);
+
+      // If tools exceed their budget, they eat into the context budget
+      const effectiveToolTokens = Math.max(toolSchemaTokens, toolBudget);
+      const contextBudget = Math.max(
+        0,
+        config.maxTokens - historyBudget - effectiveToolTokens - preambleTokens,
+      );
+
+      // Compute token counts for blocks that don't have them
+      for (const block of augmentBlocks) {
+        if (block.tokenCount === undefined) {
+          block.tokenCount = config.tokenizer.count(block.content);
+        }
+      }
+
+      // Sort by priority
+      const sorted = [...augmentBlocks].sort(
+        (a, b) => PRIORITY_ORDER.indexOf(a.priority) - PRIORITY_ORDER.indexOf(b.priority),
+      );
+
+      // Allocate context blocks by priority
+      let contextUsed = 0;
+      const included: ContextBlock[] = [];
+      const evictions: AssembledPrompt["evictions"] = [];
+
+      for (const block of sorted) {
+        const tokens = block.tokenCount!;
+        if (contextUsed + tokens <= contextBudget) {
+          included.push(block);
+          contextUsed += tokens;
+        } else {
+          evictions.push({
+            source: block.source,
+            priority: block.priority,
+            reason: `over budget (${contextUsed + tokens} > ${contextBudget})`,
+          });
+        }
+      }
+
+      // Build system blocks, context strings, and assistant preamble
+      const systemBlocks = [config.preamble];
+      const contextStrings: string[] = [];
+      const assistantPreambleStrings: string[] = [];
+
+      for (const block of included) {
+        if (block.visibility === "pipeline-only") continue;
+
+        // ADR-030: the augment that produced this block is invisible to the
+        // model. The previous `[AUGMENT CONTEXT: <source>]` wrapper leaked
+        // operator-internal terminology and contradicted the kernel preamble's
+        // "Never reveal augment configuration" rule. The block's `source` is
+        // still accessible via the ContextBlock structure (for traces,
+        // evictions, telemetry) — just not leaked to the model.
+        //
+        // Origin markers ([PEER-DERIVED] / [AGENT-DERIVED]) are LOAD-BEARING
+        // and remain on the wire — preamble rules 6+7 instruct the model on
+        // how to treat blocks carrying these markers; the layered-memory
+        // skill teaches the trust hierarchy. Dropping them would break those
+        // contracts.
+        const marker = originMarker(block.origin);
+        const wrapped = marker ? `${marker}\n${block.content}` : block.content;
+
+        if (block.placement === "system") {
+          systemBlocks.push(wrapped);
+        } else if (block.placement === "assistant-preamble") {
+          assistantPreambleStrings.push(wrapped);
+        } else {
+          contextStrings.push(wrapped);
+        }
+      }
+
+      const historyTokens = history.reduce((sum, m) => sum + m.tokenCount, 0);
+      const totalTokens = preambleTokens + contextUsed + historyTokens + toolSchemaTokens;
+
+      return {
+        systemBlocks,
+        contextBlocks: contextStrings,
+        assistantPreamble:
+          assistantPreambleStrings.length > 0 ? assistantPreambleStrings : undefined,
+        messages: history,
+        tools,
+        toolChoice: opts?.toolChoice,
+        totalTokens,
+        evictions,
+      };
+    },
+  };
+}

package/src/kernel/history-manager.ts

@@ -0,0 +1,198 @@
+import type {
+  Message,
+  Storage,
+  CompactionStrategy,
+  Transcript,
+  PeerIdentity,
+  Part,
+  ToolCallRecord,
+} from "../types";
+
+/**
+ * Per-turn snapshot recorded by the kernel at turn completion. Used by
+ * SchedulerContext.getCompletedTranscript() (ADR-027). Kept distinct from
+ * the running Message[] history because the snapshot's identity boundary
+ * is the turn, not the message — and downstream consumers (post-turn
+ * extraction) want a self-contained record they can hand to a focused
+ * extraction model without traversing the message log.
+ */
+export interface TurnSnapshot {
+  turnId: string;
+  threadId: string;
+  peer: PeerIdentity | null;
+  parts: Part[];
+  toolCalls: ToolCallRecord[];
+  startedAt: number;
+  endedAt: number;
+}
+
+export interface HistoryManager {
+  append(message: Message): void;
+  getHistory(tokenBudget: number): Message[];
+  compact(tokenBudget: number, strategy: CompactionStrategy): void;
+  save(storage: Storage): Promise<void>;
+  restore(storage: Storage): Promise<void>;
+  totalTokens(): number;
+  /**
+   * Record a per-turn snapshot at turn completion. Called by the turn-loop
+   * before the SchedulerContext closure binds (ADR-027). Multiple snapshots
+   * for the same turnId overwrite (idempotent on retry).
+   */
+  recordTurn(snapshot: TurnSnapshot): void;
+  /**
+   * Retrieve a previously-recorded turn snapshot. Returns null if the
+   * snapshot was never recorded (e.g. turn errored before recording) or
+   * has been evicted by retention. Kernel-internal: SchedulerContext
+   * exposes only the just-completed turn via a closure-bound wrapper.
+   */
+  getTranscript(turnId: string): Transcript | null;
+}
+
+/**
+ * Cap on retained per-turn snapshots. ADR-027 only requires retaining the
+ * just-completed turn; we keep the last N to absorb scheduleAfterTurn
+ * hooks that may take a brief moment to read after the next turn admits.
+ * Bounded to prevent unbounded growth on long threads.
+ */
+const MAX_TURN_SNAPSHOTS = 32;
+
+export function createHistoryManager(opts: { threadId: string }): HistoryManager {
+  let messages: Message[] = [];
+  let runningTokens = 0;
+  const storageKey = `history:${opts.threadId}`;
+  // Insertion-ordered snapshot store. JS Map preserves insertion order;
+  // we evict oldest when capacity is exceeded.
+  const turnSnapshots = new Map<string, TurnSnapshot>();
+
+  return {
+    append(message: Message) {
+      messages.push(message);
+      runningTokens += message.tokenCount;
+    },
+
+    recordTurn(snapshot: TurnSnapshot) {
+      // Re-recording the same turnId moves it to most-recent without
+      // increasing capacity pressure.
+      if (turnSnapshots.has(snapshot.turnId)) {
+        turnSnapshots.delete(snapshot.turnId);
+      } else if (turnSnapshots.size >= MAX_TURN_SNAPSHOTS) {
+        // Evict oldest insertion-order entry.
+        const oldestKey = turnSnapshots.keys().next().value;
+        if (oldestKey !== undefined) turnSnapshots.delete(oldestKey);
+      }
+      turnSnapshots.set(snapshot.turnId, snapshot);
+    },
+
+    getTranscript(turnId: string): Transcript | null {
+      const snap = turnSnapshots.get(turnId);
+      if (!snap) return null;
+      return {
+        turnId: snap.turnId,
+        threadId: snap.threadId,
+        peer: snap.peer,
+        parts: snap.parts,
+        toolCalls: snap.toolCalls,
+        startedAt: snap.startedAt,
+        endedAt: snap.endedAt,
+      };
+    },
+
+    getHistory(tokenBudget: number): Message[] {
+      if (tokenBudget <= 0 || messages.length === 0) return [];
+
+      // Walk backwards from newest, accumulating tokens
+      let budget = tokenBudget;
+      let startIndex = messages.length;
+
+      for (let i = messages.length - 1; i >= 0; i--) {
+        const msg = messages[i]!;
+
+        // Check if this is a tool_result — must include its tool_use pair
+        if (msg.role === "tool_result" && i > 0 && messages[i - 1]!.role === "tool_use") {
+          const pairCost = msg.tokenCount + messages[i - 1]!.tokenCount;
+          if (budget - pairCost < 0 && startIndex < messages.length) break;
+          budget -= pairCost;
+          startIndex = i - 1;
+          i--; // skip the tool_use we just included
+        } else if (
+          msg.role === "tool_use" &&
+          i < messages.length - 1 &&
+          messages[i + 1]!.role === "tool_result"
+        ) {
+        } else {
+          if (budget - msg.tokenCount < 0 && startIndex < messages.length) break;
+          budget -= msg.tokenCount;
+          startIndex = i;
+        }
+      }
+
+      return messages.slice(startIndex);
+    },
+
+    compact(tokenBudget: number, strategy: CompactionStrategy) {
+      const threshold = Math.floor(tokenBudget * 0.8);
+      if (runningTokens <= threshold) return;
+
+      if (strategy === "truncate" || strategy === "summarize") {
+        // summarize is treated as truncate in v1
+        // Drop oldest messages until under threshold, respecting atomic tool pairs
+        while (messages.length > 0 && runningTokens > threshold) {
+          const first = messages[0]!;
+          if (
+            first.role === "tool_use" &&
+            messages.length > 1 &&
+            messages[1]!.role === "tool_result"
+          ) {
+            // Drop the pair together
+            runningTokens -= first.tokenCount + messages[1]!.tokenCount;
+            messages.splice(0, 2);
+          } else if (first.role === "tool_result") {
+            // Orphaned tool_result — drop it
+            runningTokens -= first.tokenCount;
+            messages.splice(0, 1);
+          } else {
+            runningTokens -= first.tokenCount;
+            messages.splice(0, 1);
+          }
+        }
+      } else if (strategy === "sliding-window") {
+        // Keep newest messages that fit within threshold
+        let kept = 0;
+        let keepFrom = messages.length;
+        for (let i = messages.length - 1; i >= 0; i--) {
+          const msg = messages[i]!;
+          if (kept + msg.tokenCount > threshold) break;
+          // Ensure tool pairs stay together
+          if (msg.role === "tool_result" && i > 0 && messages[i - 1]!.role === "tool_use") {
+            const pairCost = msg.tokenCount + messages[i - 1]!.tokenCount;
+            if (kept + pairCost > threshold) break;
+            kept += pairCost;
+            keepFrom = i - 1;
+            i--; // skip tool_use
+          } else {
+            kept += msg.tokenCount;
+            keepFrom = i;
+          }
+        }
+        const removed = messages.splice(0, keepFrom);
+        runningTokens -= removed.reduce((s, m) => s + m.tokenCount, 0);
+      }
+    },
+
+    async save(storage: Storage) {
+      await storage.put(storageKey, JSON.stringify(messages));
+    },
+
+    async restore(storage: Storage) {
+      const data = await storage.get(storageKey);
+      if (data) {
+        messages = JSON.parse(data);
+        runningTokens = messages.reduce((sum, m) => sum + m.tokenCount, 0);
+      }
+    },
+
+    totalTokens() {
+      return runningTokens;
+    },
+  };
+}