auggy 0.3.0

package/src/augments/filesystem/skill/references/mount-permissions.md

@@ -0,0 +1,81 @@
+# Mount Permissions Reference
+
+## Permission matrix
+
+| Operation | Read-only | Writable | Writable + Deletable |
+|-----------|-----------|----------|---------------------|
+| `fs_read` | ✓ | ✓ | ✓ |
+| `fs_list` | ✓ | ✓ | ✓ |
+| `fs_search` | ✓ | ✓ | ✓ |
+| `fs_write` | ✗ | ✓ | ✓ |
+| `fs_mkdir` | ✗ | ✓ | ✓ |
+| `fs_remove` | ✗ | ✗ | ✓ |
+
+## Mount configuration shape
+
+```typescript
+{
+  name: string;           // logical name — first path segment
+  path: string;           // physical path on disk
+  writable?: boolean;     // default false
+  deletable?: boolean;    // default false (requires writable: true)
+  maxReadSize?: number;   // default 256KB (262144 bytes)
+  maxWriteSize?: number;  // default 1MB (1048576 bytes)
+  searchExcludes?: string[]; // default [".git", "node_modules", ".next", "__pycache__", ".DS_Store"]
+}
+```
+
+## Typical mount configurations
+
+### Skills (read-only)
+```typescript
+{ name: "skills", path: "./augments", writable: false }
+```
+For reading SKILL.md files, references, and examples. NEVER writable — prevents the agent from modifying its own behavioral teaching.
+
+### Workspace (writable + deletable)
+```typescript
+{ name: "workspace", path: "./workspace", writable: true, deletable: true }
+```
+Agent's personal working directory. Full read/write/delete access. Used for notes, drafts, intermediate work products, scratch files.
+
+### Repository (read-only)
+```typescript
+{ name: "repo", path: "/repos/platform", writable: false }
+```
+External code repository mounted for review or analysis. Read-only to prevent accidental modification.
+
+### Output (writable, not deletable)
+```typescript
+{ name: "output", path: "/shared/reports", writable: true, deletable: false }
+```
+Shared directory for publishing reports. The agent can create and update files but cannot delete published output.
+
+## Size limits
+
+| Limit | Default | What it protects |
+|-------|---------|-----------------|
+| `maxReadSize` | 256KB | Prevents large files from consuming the context window. Files over this limit are truncated with a `[truncated]` marker. |
+| `maxWriteSize` | 1MB | Prevents the agent from writing arbitrarily large files to disk. |
+| `fs_search` max results | 100 (configurable up to 1000) | Prevents glob expansion on huge directories from returning overwhelming results. |
+
+## Binary file handling
+
+The following extensions are detected as binary and rejected by `fs_read`:
+
+**Images:** .png, .jpg, .jpeg, .gif, .bmp, .ico, .webp, .svg
+**Documents:** .pdf
+**Archives:** .zip, .gz, .tar, .bz2, .7z, .rar
+**Media:** .mp3, .mp4, .avi, .mov, .wav, .flac
+**Fonts:** .woff, .woff2, .ttf, .otf, .eot
+**Compiled:** .exe, .dll, .so, .dylib, .o, .a, .wasm, .pyc, .class
+
+Binary files return: `Error: Binary file (.ext, size). Use fs_list to see metadata.`
+
+## Security boundaries
+
+1. **Path traversal**: All paths are resolved via `fs.realpath()` (follows symlinks) and checked against the mount root using a `path.relative()`-based containment helper. Paths that escape the mount (relative result of `..` or absolute path for cross-drive) are rejected. The `relative()`-based check handles both prefix-collision siblings (`/var/data/work` does not accept `/var/data/workspace/...`) and root-level mounts (`/` on POSIX accepts nested children correctly).
+2. **Symlink escape**: Symlinks that point outside the mount boundary are detected and rejected before the file is read, using the same containment check.
+3. **Mount isolation**: Each mount is an independent security boundary. No cross-mount path references are possible.
+4. **No absolute paths**: The agent always uses logical paths (`mount-name/...`). Physical paths are never exposed.
+5. **Trust-level tool gating**: Mutation tools (`fs_write`, `fs_mkdir`, `fs_remove`) are structurally hidden from untrusted peers by the kernel's capability table before the model sees them. The authenticated level loses `fs_remove`. Operator and facility peers see all tools. This runs at tool-selection time; mount-level `writable` / `deletable` flags are a complementary check that runs inside the tool.

package/src/augments/layered-memory/extractor/buffer.ts

@@ -0,0 +1,56 @@
+import type { Transcript } from "../../../types";
+
+/**
+ * Per-peer in-memory buffer used by the `session-end-only` extraction
+ * mode (Decision 3 of the memorist design). When the frequency
+ * dispatcher returns "buffer" for a turn, the auto-save handler
+ * appends that turn's `Transcript` here. At a configured boundary —
+ * session end, idle threshold, or operator-triggered flush — the
+ * augment calls `flush(peerId)` and runs extraction on the accumulated
+ * snapshot.
+ *
+ * Process-local: a restart drops all buffered transcripts. That's the
+ * intended trade-off — buffered visitor traffic is operationally
+ * low-stakes (anonymous public peers), and persistence would require
+ * its own retention/compaction story disproportionate to the value.
+ */
+export interface ExtractionBuffer {
+  /** Append a completed turn's transcript to the peer's buffer. */
+  append(peerId: string, transcript: Transcript): void;
+  /**
+   * Drain and return the peer's buffered transcripts. Subsequent
+   * `peek` returns an empty array until the next `append`.
+   */
+  flush(peerId: string): Transcript[];
+  /** Read-only view of currently buffered transcripts for a peer. */
+  peek(peerId: string): readonly Transcript[];
+  /** Drop the peer's buffer without returning it (e.g. on `forget`). */
+  clear(peerId: string): void;
+  /** Number of distinct peers with at least one buffered transcript. */
+  size(): number;
+}
+
+export function createBuffer(): ExtractionBuffer {
+  const store = new Map<string, Transcript[]>();
+  return {
+    append(peerId, transcript) {
+      const list = store.get(peerId) ?? [];
+      list.push(transcript);
+      store.set(peerId, list);
+    },
+    flush(peerId) {
+      const list = store.get(peerId) ?? [];
+      store.delete(peerId);
+      return list;
+    },
+    peek(peerId) {
+      return store.get(peerId) ?? [];
+    },
+    clear(peerId) {
+      store.delete(peerId);
+    },
+    size() {
+      return store.size;
+    },
+  };
+}

package/src/augments/layered-memory/extractor/frequency.ts

@@ -0,0 +1,79 @@
+import type { TrustLevel } from "../../../types";
+
+/**
+ * Per-trust-level extraction frequency knobs (Decision 3 of the memorist
+ * design). Operators choose how aggressively auto-save extracts per cohort:
+ *
+ *   - "every-turn": extract after every completed turn
+ *   - "every-N-turns": extract after turns where turnIndex % N === 0
+ *   - "session-end-only": buffer transcripts; flush at session boundary
+ *   - "never": skip extraction entirely for this cohort
+ */
+export type ExtractionFrequency = "every-turn" | "every-N-turns" | "session-end-only" | "never";
+
+/**
+ * Outcome of the frequency check for a single completed turn:
+ *
+ *   - "extract": run extraction now (immediate write path)
+ *   - "buffer": append the transcript to the per-peer buffer (deferred)
+ *   - "skip": do nothing for this turn
+ */
+export type ExtractionDecision = "extract" | "buffer" | "skip";
+
+/**
+ * Nested configuration shape consumed by the dispatcher. `public` splits
+ * into `recognized` (visitor-token holders) and `anonymous` (no token /
+ * fresh visitor) so operators can be more aggressive with returning
+ * recognized visitors than with first-touch traffic.
+ */
+export interface ExtractionFrequencyConfig {
+  creator?: ExtractionFrequency;
+  agent?: ExtractionFrequency;
+  public?: {
+    recognized?: ExtractionFrequency;
+    anonymous?: ExtractionFrequency;
+  };
+}
+
+/**
+ * Minimal peer descriptor used by the dispatcher. The full PeerIdentity
+ * carries more fields, but only trust + public substate matter for
+ * frequency selection.
+ */
+export interface PeerInput {
+  trustLevel: TrustLevel;
+  publicSubstate?: "recognized" | "anonymous";
+}
+
+/**
+ * Pure dispatch: given a peer, the current turn index for that peer, and
+ * the operator's frequency config, return whether to extract immediately,
+ * buffer, or skip. No side effects, no I/O.
+ */
+export function shouldExtract(
+  peer: PeerInput,
+  turnIndex: number,
+  config: ExtractionFrequencyConfig,
+  everyNTurns: number,
+): ExtractionDecision {
+  const freq = resolveFrequency(peer, config);
+  if (freq === "never") return "skip";
+  if (freq === "every-turn") return "extract";
+  if (freq === "session-end-only") return "buffer";
+  if (freq === "every-N-turns") return turnIndex % everyNTurns === 0 ? "extract" : "skip";
+  return "skip";
+}
+
+function resolveFrequency(peer: PeerInput, config: ExtractionFrequencyConfig): ExtractionFrequency {
+  if (peer.trustLevel === "creator") return config.creator ?? "every-turn";
+  if (peer.trustLevel === "agent") return config.agent ?? "every-N-turns";
+  if (peer.trustLevel === "public") {
+    const sub = peer.publicSubstate ?? "anonymous";
+    return config.public?.[sub] ?? (sub === "recognized" ? "every-turn" : "session-end-only");
+  }
+  // Defensive — unknown trust levels (shouldn't happen given the union)
+  // skip extraction rather than fall through to a default that might
+  // accidentally write under an unintended peer cohort.
+  console.warn(`[layered-memory] unknown trust level: ${peer.trustLevel}; skipping extraction`);
+  return "never";
+}

package/src/augments/layered-memory/extractor/inject-handler.ts

@@ -0,0 +1,103 @@
+import type { Transcript } from "../../../types";
+import { type ExtractedFact, parseExtractionResponse } from "./parse";
+
+/**
+ * Minimal extraction-engine surface. The auto-save handler does NOT need
+ * the full `ModelClient` shape (assembled prompts, tool definitions, token
+ * counters). It needs a single string-in / string-out completion paired
+ * with a USD cost so callers can roll the spend into budgets.
+ *
+ * Decoupling here lets the augment swap in either:
+ *  - a thin adapter wrapping the agent's primary engine (Phase 2c+), or
+ *  - a dedicated cheaper extraction model (per Decision 6 of the
+ *    memorist design — extraction can ride a Haiku-priced engine while
+ *    the user-facing agent runs Sonnet).
+ *
+ * The shape is intentionally narrow: no streaming, no tool calls. The
+ * extraction LLM emits a JSON array; the handler parses it via parse.ts.
+ */
+export interface ExtractionEngine {
+  complete(prompt: string): Promise<{ text: string; costUsd: number }>;
+}
+
+export interface ExtractionInput {
+  transcript: Transcript;
+  engine: ExtractionEngine;
+  /**
+   * Prompt template containing the literal token `{{TRANSCRIPT}}` which
+   * the handler replaces with a rendered transcript string. Operators
+   * may override the bundled `prompt.md` via
+   * `layeredMemory.options.autoSave.promptTemplate`.
+   */
+  promptTemplate: string;
+}
+
+/**
+ * Outcome of one extraction call. `costUsd` always carries the engine's
+ * reported spend even on failure, so the augment can attribute it to the
+ * originating turn's budget when integration ships in Phase 2c.
+ *
+ * Engine-call failures (network, rate limit) report `costUsd: 0` because
+ * no completion happened; parse failures keep the engine's costUsd
+ * because the model already billed for the (malformed) response.
+ */
+export type ExtractionResult =
+  | { success: true; facts: ExtractedFact[]; costUsd: number }
+  | { success: false; error: string; costUsd: number };
+
+/**
+ * Run a single extraction turn: render prompt → call engine → parse JSON.
+ *
+ * Never throws. Engine errors and parse errors map to
+ * `{ success: false, error, costUsd }` so the calling
+ * `scheduleAfterTurn` hook can log and skip without poisoning the
+ * background-work path. Per ADR-027, extraction failures are explicitly
+ * best-effort — they never affect the user-facing turn.
+ */
+export async function handleExtractionTurn(input: ExtractionInput): Promise<ExtractionResult> {
+  const transcriptText = renderTranscript(input.transcript);
+  const prompt = input.promptTemplate.replace("{{TRANSCRIPT}}", transcriptText);
+
+  let response: { text: string; costUsd: number };
+  try {
+    response = await input.engine.complete(prompt);
+  } catch (err) {
+    return {
+      success: false,
+      error: (err as Error).message,
+      costUsd: 0,
+    };
+  }
+
+  const parsed = parseExtractionResponse(response.text);
+  if (!parsed.success) {
+    return {
+      success: false,
+      error: parsed.error,
+      costUsd: response.costUsd,
+    };
+  }
+
+  return {
+    success: true,
+    facts: parsed.facts,
+    costUsd: response.costUsd,
+  };
+}
+
+/**
+ * Flatten the transcript into a plain-text rendering suitable for the
+ * extraction prompt. Currently only emits text parts — file/data parts
+ * carry binary or structured payloads the extraction model can't reason
+ * about uniformly. Keeping this minimal also avoids accidentally leaking
+ * tool-call internals into the prompt body.
+ */
+function renderTranscript(t: Transcript): string {
+  const lines: string[] = [];
+  for (const part of t.parts) {
+    if (part.kind === "text") {
+      lines.push(part.text);
+    }
+  }
+  return lines.join("\n");
+}

package/src/augments/layered-memory/extractor/parse.ts

@@ -0,0 +1,75 @@
+/**
+ * Parsed shape of a single extracted fact. Mirrors the JSON schema the
+ * extraction prompt instructs the model to emit. The parser strips any
+ * fields not in this list — forward compatibility for prompt revisions
+ * that introduce new fields without coordinating with downstream code.
+ */
+export interface ExtractedFact {
+  subject: string;
+  predicate: string;
+  object: string;
+  confidence: number;
+  isVerbatim: boolean;
+}
+
+export type ParseResult =
+  | { success: true; facts: ExtractedFact[] }
+  | { success: false; error: string };
+
+/**
+ * Defensive JSON parser for the extraction LLM's response. The model
+ * should emit a top-level JSON array of fact objects per `prompt.md`,
+ * but real models occasionally drift (extra prose, missing fields,
+ * type mismatches). This parser:
+ *
+ *   - Returns `{ success: false, error }` on any failure mode rather
+ *     than throwing, so the auto-save handler can log and skip without
+ *     killing the injected turn's tool-call execution.
+ *   - Validates each entry's shape strictly: all five required fields
+ *     must be present and the right primitive type. One bad entry
+ *     fails the whole batch — partial writes would leave inconsistent
+ *     storage, and the cost of a re-extraction is bounded.
+ *   - Strips unknown keys to keep the storage schema clean across
+ *     prompt-template revisions.
+ */
+export function parseExtractionResponse(raw: string): ParseResult {
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(raw);
+  } catch (err) {
+    return { success: false, error: `failed to parse JSON: ${(err as Error).message}` };
+  }
+  if (!Array.isArray(parsed)) {
+    return { success: false, error: "extraction output is not a JSON array" };
+  }
+  const facts: ExtractedFact[] = [];
+  for (const [i, item] of parsed.entries()) {
+    if (item === null || typeof item !== "object") {
+      return { success: false, error: `entry ${i} is not an object` };
+    }
+    const e = item as Record<string, unknown>;
+    if (typeof e.subject !== "string") {
+      return { success: false, error: `entry ${i} missing/invalid subject` };
+    }
+    if (typeof e.predicate !== "string") {
+      return { success: false, error: `entry ${i} missing/invalid predicate` };
+    }
+    if (typeof e.object !== "string") {
+      return { success: false, error: `entry ${i} missing/invalid object` };
+    }
+    if (typeof e.confidence !== "number") {
+      return { success: false, error: `entry ${i} missing/invalid confidence` };
+    }
+    if (typeof e.isVerbatim !== "boolean") {
+      return { success: false, error: `entry ${i} missing/invalid isVerbatim` };
+    }
+    facts.push({
+      subject: e.subject,
+      predicate: e.predicate,
+      object: e.object,
+      confidence: e.confidence,
+      isVerbatim: e.isVerbatim,
+    });
+  }
+  return { success: true, facts };
+}

package/src/augments/layered-memory/extractor/prompt.md

@@ -0,0 +1,26 @@
+You are a memory extractor. Given a conversation transcript between an agent and a peer, identify durable facts about THE PEER (not about the agent or other entities) that would be useful in future conversations.
+
+# Transcript
+{{TRANSCRIPT}}
+
+# Output
+
+Return a JSON array of fact objects. Each fact has these REQUIRED fields:
+- subject: typically "peer", may be more specific
+- predicate: a short verb-phrase (e.g. "name", "prefers", "works_at", "team", "asked_to_remember")
+- object: the value
+- confidence: a number 0-1, your confidence the fact is durable + accurate
+- isVerbatim: true ONLY if the peer's exact phrasing matters and is captured exactly; otherwise false
+
+Example:
+[
+  {"subject": "peer", "predicate": "name", "object": "Sam", "confidence": 0.95, "isVerbatim": true},
+  {"subject": "peer", "predicate": "prefers", "object": "dark mode", "confidence": 0.8, "isVerbatim": false}
+]
+
+# Rules
+
+- Extract durable facts only — preferences, names, commitments, recurring topics. Skip transient ("today I'm tired"), agent-side facts ("the agent said hi"), or third-party gossip.
+- DO NOT extract secrets, API keys, passwords, or anything the peer explicitly marked confidential. Skip credentials and sensitive PII entirely.
+- If the conversation has nothing extractable, return [].
+- Output ONLY the JSON array. No prose, no markdown, no explanation.