@agenr/openclaw-plugin 0.10.1

package/README.md

@@ -0,0 +1,321 @@
+```text
+ █████╗  ██████╗ ███████╗███╗   ██╗██████╗
+██╔══██╗██╔════╝ ██╔════╝████╗  ██║██╔══██╗
+███████║██║  ███╗█████╗  ██╔██╗ ██║██████╔╝
+██╔══██║██║   ██║██╔══╝  ██║╚██╗██║██╔══██╗
+██║  ██║╚██████╔╝███████╗██║ ╚████║██║  ██║
+╚═╝  ╚═╝ ╚═════╝ ╚══════╝╚═╝  ╚═══╝╚═╝  ╚═╝
+  AGENt memoRy
+```
+
+# AGENR
+
+**AY-JEN-ER** - Human memory for AI agents.
+
+This README is the overview and quick start. Canonical mechanism docs live in [docs/ARCHITECTURE.md](./docs/ARCHITECTURE.md) and [docs/OPENCLAW.md](./docs/OPENCLAW.md).
+
+AGENR is a local, structured, universal, living memory layer for AI agents. It tackles session amnesia, multi-surface fragmentation, and vendor lock-in together so you get one person, many agents, one brain.
+
+It extracts structured knowledge from conversation transcripts - facts, decisions, preferences, todos, relationships, events, lessons - and stores them in a local database with semantic search. Entries strengthen when reinforced, decay when stale, and resolve contradictions. Your memory stays on your machine.
+
+More: [Vision](./docs/vision.md) | [Roadmap](./docs/roadmap.md) | [Architecture](./docs/ARCHITECTURE.md) | [OpenClaw guide](./docs/OPENCLAW.md)
+
+## Quick Start
+
+```bash
+pnpm install -g agenr
+agenr init
+```
+
+That's it. The interactive wizard handles everything: auth setup, platform detection, plugin installation, session ingestion, and watcher configuration. Run `agenr init` again anytime to reconfigure.
+
+## What It Does
+
+- **Extract** - An LLM reads your transcripts and pulls out structured entries. Smart filtering removes noise (tool calls, file contents, boilerplate - about 80% of a typical session) before the LLM sees it. Hedged or unverified agent claims are capped at importance 5 with an `unverified` tag.
+- **Store** - Entries get embedded and compared against existing knowledge. Near-duplicates reinforce existing entries. New information gets inserted. Online dedup catches copies in real-time.
+- **Recall** - Semantic search plus memory-aware ranking. Entries you recall often score higher. Stale entries decay. Contradicted entries get penalized.
+- **Consolidate** - Periodic cleanup: rule-based expiry first, then optional LLM-assisted merging for entries that say the same thing differently.
+
+```text
+Transcript -> Filter -> Extract -> Store -> Recall
+               80%       LLM      dedup    semantic
+               noise     typed    + embed  + memory-
+               removed   entries  + dedup    aware
+```
+
+## What You Need
+
+An **OpenAI API key** for embeddings (`text-embedding-3-small`). Embeddings cost fractions of a penny per operation - a full ingestion of 100+ session transcripts runs about $0.10 total.
+
+For the LLM extraction step, AGENR supports:
+- **OpenAI API key** (recommended) - `gpt-4.1` is highly recommended for best extraction quality; `gpt-4.1-mini` is the default and works well if cost is a concern; `gpt-4.1-nano` is the budget option
+- **OpenAI Pro subscription** - no API key needed
+- **Anthropic Claude subscription** - no API key needed
+
+The `agenr init` wizard walks you through all of this.
+
+```bash
+export OPENAI_API_KEY=sk-...  # for embeddings + extraction
+```
+
+## Platform Setup
+
+### OpenClaw (recommended)
+
+`agenr init` auto-detects OpenClaw, installs the native plugin, and restarts the gateway. The plugin handles everything automatically: session-start context injection (recent turns, core recall, browse recall, and a memory index), mid-session signals when important entries arrive, cross-session handoff summaries, and native `agenr_recall`, `agenr_store`, `agenr_extract`, `agenr_retire`, `agenr_update`, and session-project tools.
+
+No AGENTS.md edits needed. No MCP config needed. The bundled SKILL.md loads automatically and instructs the agent when to call `agenr_store` proactively.
+
+**Manual alternative:**
+
+```bash
+openclaw plugins install agenr
+```
+
+> **Security notice:** The OpenClaw plugin runs recall, store, extract, retire, update, and trace flows through shared in-process agenr services. It does not shell out to the agenr CLI, read your OpenClaw credentials, or send data anywhere except your configured model and embedding providers. The plugin source is open and auditable.
+
+Optional config in `openclaw.json`:
+
+```json
+{
+  "plugins": {
+    "entries": {
+      "agenr": {
+        "config": {
+          "budget": 2000,
+          "signalMinImportance": 8,
+          "signalCooldownMs": 30000,
+          "signalMaxPerSession": 10
+        }
+      }
+    }
+  }
+}
+```
+
+Signal config controls how often mid-session notifications fire. See [docs/OPENCLAW.md](./docs/OPENCLAW.md) for all available options.
+
+### Claude Code
+
+```bash
+agenr init --platform claude-code
+```
+
+Adds the `agenr_recall` instruction block to `~/.claude/CLAUDE.md` and wires `.mcp.json`.
+
+### Codex
+
+```bash
+agenr init --platform codex
+```
+
+Adds the `agenr_recall` instruction block to `~/.codex/AGENTS.md` and wires `~/.codex/config.toml`.
+
+### Cursor
+
+```bash
+agenr init --platform cursor
+```
+
+Adds instructions to `.cursor/rules/agenr.mdc` and wires `.cursor/mcp.json`.
+
+### Windsurf
+
+```bash
+agenr init --platform windsurf
+```
+
+Adds instructions to `~/.codeium/windsurf/memories/global_rules.md` and wires `.mcp.json`.
+
+### Generic / Any MCP Tool
+
+```bash
+agenr init   # auto-detects platform, falls back to generic AGENTS.md
+```
+
+Or start `agenr mcp` as a stdio MCP server and configure it in your tool's MCP settings manually. Your agent gets `agenr_recall`, `agenr_extract`, `agenr_retire`, and `agenr_update` as tools.
+
+## How Memory Works
+
+### Extraction & Storage
+
+AGENR reads your session transcripts, filters out noise, and extracts structured knowledge entries. Each entry has a type, subject, content, importance, and expiry. Near-duplicates are caught automatically - if you discussed the same decision in three sessions, you get one entry with higher confirmations, not three copies.
+
+```bash
+agenr ingest ~/.openclaw/agents/main/sessions/ --glob '**/*.jsonl'
+
+[1/108] session-abc123.jsonl (1.2MB) - 12 extracted, 10 stored, 1 skipped (duplicate), 1 reinforced
+[2/108] session-def456.jsonl (800KB) - 8 extracted, 7 stored, 0 skipped, 1 reinforced
+...
+```
+
+### Recall (semantic + memory-aware)
+
+```bash
+agenr recall "package manager"
+```
+
+```text
+1 results (46ms)
+1. [decision] project tooling: We switched this project to pnpm.
+   importance=7 | today | recalled 3 times
+   tags: tooling, package-manager
+```
+
+Recall supports date range queries (`--since 14d --until 7d`), temporal browse mode (`--browse --since 1d`), and around-date targeting (`--around 2026-02-15 --around-radius 14`) to rank entries by distance from a specific date.
+
+### Cross-session Handoff
+
+When you start a new OpenClaw session, agenr injects a startup context assembled from four pieces:
+
+1. **Recent turns** - the last few user/assistant turns from the previous session file for immediate continuity
+2. **Core recall** - universal core memory plus project-tagged core memory for configured `coreProjects`
+3. **Browse recall** - recent high-value memory, scoped by explicit session project when one exists, otherwise limited to universal / NULL-project entries
+4. **Memory index** - a compact breadcrumb list of available projects and memory buckets
+
+The plugin formats those pieces into startup markdown, applies selector and budget limits, and records only the entries that were actually rendered so startup and mid-session recall can dedupe cleanly.
+
+When a session ends, the plugin writes a handoff using a fallback-first strategy: it stores a lightweight fallback entry immediately, then attempts an LLM-upgraded handoff summary. If the LLM upgrade succeeds, the fallback is retired. On the next session start, surfaced handoff entries are consumed and retired after use.
+
+See [docs/OPENCLAW.md](./docs/OPENCLAW.md) for the current startup flow and [docs/OPENCLAW_HANDOFFS.md](./docs/OPENCLAW_HANDOFFS.md) for the detailed handoff lifecycle.
+
+### Consolidation
+
+Periodic cleanup merges near-duplicates and expires stale entries. Run manually or let the init wizard prompt you after a bulk ingest:
+
+```bash
+agenr consolidate
+```
+
+## Advanced
+
+### Multi-instance & DB Isolation
+
+When running multiple OpenClaw instances (or mixing OpenClaw and Codex), each instance gets registered in a global projects map at `~/.agenr/config.json`. By default, all instances share `~/.agenr/knowledge.db` with data separated by project tags.
+
+For non-default OpenClaw paths, the init wizard offers isolated databases:
+
+```text
+~/.agenr/knowledge.db          # shared (default)
+~/my-openclaw/agenr-data/knowledge.db  # isolated
+```
+
+The wizard writes the isolated DB path directly to the OpenClaw plugin config so no manual editing is needed.
+
+### Manual Ingest
+
+```bash
+agenr ingest <paths...> --bulk --workers 10 --whole-file
+```
+
+The init wizard offers cost estimation before ingestion using model pricing, showing estimated token counts and costs for recent (last 7 days) vs full history ingestion.
+
+### Live Watching & Watcher
+
+The watcher tails your session files, extracts new knowledge every few minutes, and stores it. If you ingested history first, watch resumes right where ingest left off.
+
+```bash
+# Watch your sessions directory
+agenr watch --platform openclaw
+
+# Install as a background daemon (macOS launchd, 120s interval)
+agenr watcher install
+agenr watcher status
+agenr watcher logs
+```
+
+### Benchmarking
+
+Evaluate extraction quality against scored rubrics:
+
+```bash
+agenr benchmark
+```
+
+Runs extraction against benchmark session fixtures, scores results against rubric JSON, and reports per-session plus overall metrics (recall, partial recall, precision proxy, composite score, pass rate). Supports multi-run aggregation with mean/min/stdev reporting.
+
+### MCP Integration (manual)
+
+If you prefer manual MCP setup over `agenr init`, start the stdio server:
+
+```bash
+agenr mcp
+```
+
+This exposes four MCP tools: `agenr_recall`, `agenr_extract`, `agenr_retire`, and `agenr_update`. Persistent session capture comes from watcher ingestion and platform integrations rather than an MCP `agenr_store` tool.
+
+## Commands
+
+| Command | What it does |
+| --- | --- |
+| `agenr init` | Interactive setup wizard: auth, platform detection, plugin install, ingestion, watcher. Replaces the old `setup` flow. Use `--platform` to skip auto-detection. |
+| `agenr setup` | Configure LLM provider, auth, and model defaults (also available inside `init`) |
+| `agenr config` | Show and update agenr configuration |
+| `agenr auth` | Authentication status and diagnostics |
+| `agenr ingest <paths...>` | Bulk-ingest files and directories |
+| `agenr synthetic` | Generate synthetic recall signals from existing DB entries (no re-ingest required) |
+| `agenr extract <files...>` | Extract knowledge entries from text files |
+| `agenr store [files...]` | Store entries with semantic dedup |
+| `agenr recall [query]` | Semantic + memory-aware recall. Use `--since`/`--until` for date ranges, `--around` for target-date ranking, `--browse` for temporal mode. |
+| `agenr retire [subject]` | Retire a stale entry (hidden, not deleted). Match by subject or `--id`. |
+| `agenr update --id <id> --importance <n>` | Update an entry in place. Currently supports importance only. |
+| `agenr watch [file]` | Live-watch files/directories, auto-extract knowledge |
+| `agenr watcher install` | Install background watch daemon (macOS launchd) |
+| `agenr watcher status` | Show daemon status (running/stopped, pid, watched file, recent logs) |
+| `agenr watcher logs` | Stream or show recent daemon logs |
+| `agenr consolidate` | Clean up and merge near-duplicates |
+| `agenr benchmark` | Run extraction against benchmark fixtures and score results |
+| `agenr context` | Generate context file for AI tool integration |
+| `agenr health` | Show database health and forgetting candidates |
+| `agenr mcp` | Start MCP server (stdio) |
+| `agenr todo <subcommand>` | Manage todos in the knowledge base |
+| `agenr db <cmd>` | Database management (stats, version, export, reset, path, check, rebuild-index) |
+
+Full reference: [docs/CLI.md](./docs/CLI.md) | [docs/CONFIGURATION.md](./docs/CONFIGURATION.md)
+
+## Architecture
+
+- **Runtime:** Node.js 20+, TypeScript, ESM
+- **Storage:** libsql/SQLite - default at `~/.agenr/knowledge.db`, optionally isolated per instance
+- **Embeddings:** OpenAI `text-embedding-3-small`, 1024 dimensions
+- **Recall scoring:** Vector similarity x recency x memory strength (max(importance, recall strength)), with contradiction penalties
+- **Global config:** `~/.agenr/config.json` - stores auth, model, and a projects map keyed by directory path with platform, project slug, and optional isolated DB path per instance
+
+Deep dive: [docs/ARCHITECTURE.md](./docs/ARCHITECTURE.md)
+
+## Status
+
+The core pipeline is stable and tested. We use it daily managing thousands of knowledge entries across OpenClaw sessions.
+
+**Shipped:** extraction, storage, recall (semantic + browse), MCP integration, online dedup, consolidation, smart filtering, live watching, daemon mode, cross-session handoff (LLM-summarized), three-phase context injection, interactive init wizard, cost estimation, DB isolation, benchmarking.
+
+**Next:** GUI Management Console (browse, search, and curate your knowledge database visually), Cursor live signals, Claude Code UserPromptSubmit adapter, transitive project dependencies.
+
+## Philosophy
+
+The big labs are building bigger brains. agenr is building better continuity.
+
+The product bet is that memory should be local, structured, universal, and living: local because it is yours, structured because "what did we decide?" needs a real answer, universal because it should work across surfaces, and living because stale or contradicted memory must be maintained rather than merely accumulated.
+
+For the product thesis, see [docs/vision.md](./docs/vision.md).
+
+## Troubleshooting
+
+| Problem | Fix |
+|---|---|
+| `agenr init` wizard fails to detect platform | Pass `--platform openclaw` (or `codex`, `claude-code`, etc.) explicitly |
+| Plugin install fails during wizard | Run `openclaw plugins install agenr` manually, then `openclaw gateway restart` |
+| Embeddings fail | Set `OPENAI_API_KEY` env var or `agenr config set-key openai <key>` |
+| Database locked | Wait for consolidation to finish, or check `~/.agenr/consolidation.lock` |
+| Recall returns nothing after force-kill | `agenr db rebuild-index` (vector index corruption) |
+| Extraction fails mid-file | Retry - dedup skips already-stored entries |
+| Stale handoff entries persist | Run `agenr recall --browse --since 1d` to check, then `agenr retire --id <id>` |
+| Gateway doesn't pick up plugin | Run `openclaw gateway restart` after plugin install |
+
+## License
+
+AGPL-3.0 - [LICENSE](./LICENSE)
+
+## Contributing
+
+See [CONTRIBUTING.md](./CONTRIBUTING.md)

package/dist/index.d.ts

@@ -0,0 +1,338 @@
+import { Model, Api, Context, SimpleStreamOptions, AssistantMessageEvent, AssistantMessage } from '@mariozechner/pi-ai';
+import * as _sinclair_typebox from '@sinclair/typebox';
+
+/**
+ * Handoff transcript helpers - reading, parsing, building, and formatting
+ * transcript content for session handoff summaries.
+ */
+type HandoffMessage = {
+    role: "user" | "assistant";
+    content: string;
+    timestamp: string;
+};
+declare function getBaseSessionPath(filePath: string): string;
+declare function readSessionsJson(sessionsDir: string): Promise<Record<string, unknown>>;
+declare function readAndParseSessionJsonl(sessionFile: string): Promise<unknown[]>;
+declare function getSurfaceForSessionFile(sessionFilePath: string, sessionsJson: Record<string, unknown>, sessionsDir?: string): string;
+declare function readMessagesFromJsonl(filePath: string): Promise<HandoffMessage[]>;
+declare function findPriorResetFile(sessionsDir: string, currentSessionFile: string): Promise<string | null>;
+declare function buildTranscript(messages: HandoffMessage[], surface: string): string;
+declare function buildMergedTranscript(priorMessages: HandoffMessage[], priorSurface: string, currentMessages: HandoffMessage[], currentSurface: string): string;
+declare function capTranscriptLength(params: {
+    priorMessages: HandoffMessage[];
+    priorSurface: string;
+    currentMessages: HandoffMessage[];
+    currentSurface: string;
+    maxChars: number;
+}): string;
+
+type RecallIntentFamily = "generic" | "invariant_lookup" | "prerequisite_step" | "policy_bundle_lookup";
+/**
+ * Stable, product-level semantics for the bounded recall decision layer.
+ * Keep lexical hits, thresholds, and other heuristic internals in trace data.
+ */
+type RecallReasonCode = "sufficient_direct_support" | "sufficient_composite_support" | "subject_mismatch" | "no_answer_bearing_support" | "ambiguous_competing_support" | "support_set_too_diffuse" | "support_below_confidence_floor";
+type RecallSupportMode = "single" | "pair" | "continuity_bundle";
+/**
+ * Additive recall payload emitted only when the bounded MVP layer is allowed to
+ * intervene. Absence means generic retrieval fallback, not an implicit abstain.
+ *
+ * In this MVP, `abstain` means the supported-intent post-retrieval pass found
+ * no single-support winner above its confidence and ambiguity guardrails.
+ */
+interface RecallDecision {
+    decision: "answer" | "abstain";
+    intent: RecallIntentFamily;
+    reasonCodes: RecallReasonCode[];
+    supportMode?: RecallSupportMode;
+    supportIds: string[];
+    surfacedIds: string[];
+    competingIds: string[];
+}
+interface RecallCategoryRollupFacetSummary {
+    facet: string;
+    label: string;
+    summary: string;
+    evidence_ids: string[];
+    evidence_subjects: string[];
+}
+interface RecallCategoryRollupSummary {
+    mode: "category_rollup";
+    path: "category_rollup_synthesis_v1";
+    style: "broad_synthesis" | "project_story";
+    kind: "family" | "personal_life" | "work" | "project";
+    target: string;
+    subject?: string;
+    narrative: string;
+    coverage: "broad" | "partial" | "sparse";
+    evidence_ids: string[];
+    evidence_subjects: string[];
+    evidence_count: number;
+    covered_facets: string[];
+    facet_summaries: RecallCategoryRollupFacetSummary[];
+    low_coverage_note?: string;
+    project_rollup?: {
+        kind: "project_history_v1";
+        project_subject: string;
+        prioritized_facets: Array<"project_scope" | "architecture" | "implementation" | "validation" | "follow_up">;
+        section_order: string[];
+    };
+}
+
+type SimpleAssistantStream = AsyncIterable<AssistantMessageEvent> & {
+    result: () => Promise<AssistantMessage>;
+};
+type StreamSimpleFn = (model: Model<Api>, context: Context, options?: SimpleStreamOptions) => SimpleAssistantStream;
+
+declare const OPENCLAW_MEMORY_RELIABILITY_DIAGNOSTIC_SCHEMA_VERSION: "openclaw-memory-reliability-diagnostic-v1";
+type DiagnosticSessionProjectState = "set" | "cleared" | "unset" | "not-applicable";
+type DiagnosticWriteAttributionSurface = "native-store" | "watcher" | "handoff" | "openclaw-bridge-store";
+type DiagnosticWriteAttributionSource = "tool-project" | "session-project" | "plugin-default" | "watcher-fallback" | "entry-project" | "shared-attribution" | "bridge-fallback" | "none";
+type DiagnosticWriteAttributionReason = "explicit-tool-project" | "explicit-session-project" | "explicit-session-cleared" | "session-project-not-worthy" | "plugin-default-project" | "watcher-inferred-project" | "existing-entry-project" | "shared-project-attribution" | "bridge-fallback-project" | "no-project-candidate";
+type DiagnosticWriteAttributionKind = "explicit" | "inferred" | "default" | "shared" | "fallback" | "global";
+interface WriteAttributionResolutionDiagnostic {
+    kind: "openclaw-memory-reliability-diagnostic";
+    schemaVersion: typeof OPENCLAW_MEMORY_RELIABILITY_DIAGNOSTIC_SCHEMA_VERSION;
+    decisionClass: "write-attribution-resolution";
+    ownerSubsystem: "write-attribution";
+    laneHint: "cross-surface-scope-attribution";
+    surface: DiagnosticWriteAttributionSurface;
+    inputs: {
+        explicitProjectProvided: boolean;
+        sessionProjectState: DiagnosticSessionProjectState;
+        defaultProjectPresent: boolean;
+        fallbackProjectPresent: boolean;
+        entryProjectPresent: boolean;
+        upstreamAttributionPresent: boolean;
+    };
+    outcome: {
+        project: string | null;
+        source: DiagnosticWriteAttributionSource;
+        reason: DiagnosticWriteAttributionReason;
+        attributionKind: DiagnosticWriteAttributionKind;
+        sessionProjectGate: "batch" | "entry" | "not-applicable";
+    };
+}
+type DiagnosticSurfacedMemorySurface = "session-start" | "mid-session-recall" | "agent-tool-recall";
+type DiagnosticSurfacedMemoryStage = "browse-admitted" | "selector-shaped" | "render-input" | "retrieved" | "prompt-visible" | "nudge-candidates";
+type DiagnosticSurfacedMemorySource = "plugin-injection" | "agent-tool-output";
+type DiagnosticSurfacedMemoryOwnershipClass = "startup-pre-prompt-candidate" | "startup-render-input-candidate" | "startup-prompt-visible-before-reset-owned" | "mid-session-retrieved-candidate" | "mid-session-prompt-visible-dedupe-only" | "mid-session-nudge-candidate" | "agent-tool-prompt-visible-dedupe-only";
+type DiagnosticSurfacedMemoryReason = "startup-pre-prompt-stage" | "startup-render-input-stage" | "startup-prompt-visible-stage" | "mid-session-retrieved-stage" | "mid-session-prompt-visible-stage" | "mid-session-nudge-stage" | "agent-tool-prompt-visible-stage";
+interface SurfacedMemoryOwnershipDiagnostic {
+    kind: "openclaw-memory-reliability-diagnostic";
+    schemaVersion: typeof OPENCLAW_MEMORY_RELIABILITY_DIAGNOSTIC_SCHEMA_VERSION;
+    decisionClass: "surfaced-memory-ownership-classification";
+    ownerSubsystem: "surfaced-memory-contract";
+    laneHint: "user-facing-surfacing";
+    surface: DiagnosticSurfacedMemorySurface;
+    stage: DiagnosticSurfacedMemoryStage;
+    source?: DiagnosticSurfacedMemorySource;
+    ownershipClass: DiagnosticSurfacedMemoryOwnershipClass;
+    reason: DiagnosticSurfacedMemoryReason;
+    outcome: {
+        promptVisible: boolean;
+        dedupeEligible: boolean;
+        beforeResetOwned: boolean;
+        handoffConsumptionEligible: boolean;
+    };
+}
+
+interface RecallSurfaceSelection {
+    authoritative: boolean;
+    abstained: boolean;
+    surfacedIds: string[];
+}
+
+type RecallEntry = {
+    type: string;
+    subject: string;
+    content: string;
+    importance?: number;
+};
+type RecallResult = {
+    query: string;
+    decision?: RecallDecision;
+    rollupSummary?: RecallCategoryRollupSummary;
+    surfaceSelection?: RecallSurfaceSelection;
+    results: Array<{
+        entry: RecallEntry & Record<string, unknown>;
+        score: number;
+        category?: string;
+    }>;
+};
+type RecallResultItems = RecallResult["results"];
+
+type MidSessionMemoryItems = RecallResultItems;
+interface PromptVisibleAgentToolRecallMemory {
+    surface: "agent-tool-recall";
+    stage: "prompt-visible";
+    visibility: "prompt-visible";
+    source: "agent-tool-output";
+    query: string;
+    items: MidSessionMemoryItems;
+    memoryReliabilityDiagnostic?: SurfacedMemoryOwnershipDiagnostic;
+}
+interface PromptVisibleAgentToolRecallMemoryBookkeeping {
+    surface: "agent-tool-recall";
+    stage: "prompt-visible";
+    visibility: "prompt-visible";
+    source: PromptVisibleAgentToolRecallMemory["source"];
+    surfacedEntryIds: string[];
+    beforeResetOwnedEntryIds: string[];
+    memoryReliabilityDiagnostic?: SurfacedMemoryOwnershipDiagnostic;
+}
+
+type BeforeAgentStartEvent = {
+    prompt?: string;
+    messages?: unknown[];
+    [key: string]: unknown;
+};
+type PluginHookAgentContext = {
+    sessionKey?: string;
+    sessionId?: string;
+    agentId?: string;
+    workspaceDir?: string;
+    [key: string]: unknown;
+};
+type BeforeAgentStartResult = {
+    prependContext?: string;
+};
+type BeforePromptBuildEvent = {
+    prompt?: string;
+    messages?: unknown[];
+    [key: string]: unknown;
+};
+type BeforePromptBuildResult = {
+    systemPrompt?: string;
+    prependContext?: string;
+    prependSystemContext?: string;
+};
+type BeforeResetEvent = {
+    sessionFile?: string;
+    messages?: unknown[];
+    reason?: string;
+    [key: string]: unknown;
+};
+type PluginLogger = {
+    debug?: (message: string) => void;
+    info?: (message: string) => void;
+    warn: (message: string) => void;
+    error: (message: string) => void;
+};
+type PluginToolResult = {
+    content: Array<{
+        type: "text";
+        text: string;
+    }>;
+    details?: Record<string, unknown>;
+    agentToolRecallSurface?: PromptVisibleAgentToolRecallMemoryBookkeeping;
+};
+type PluginTool = {
+    name: string;
+    label?: string;
+    description: string;
+    parameters: _sinclair_typebox.TObject;
+    execute: (toolCallId: string, params: Record<string, unknown>) => Promise<PluginToolResult>;
+};
+type PluginToolOptions = {
+    name?: string;
+    names?: string[];
+    optional?: boolean;
+};
+type InternalHookEvent = {
+    type: "command" | "session" | "agent" | "gateway" | "message";
+    action: string;
+    sessionKey: string;
+    context: Record<string, unknown>;
+    timestamp: Date;
+    messages: string[];
+};
+type InternalHookHandler = (event: InternalHookEvent) => Promise<void> | void;
+type PluginHookOptions = {
+    priority?: number;
+    entry?: unknown;
+    name?: string;
+    description?: string;
+    register?: boolean;
+};
+type PluginApi = {
+    id: string;
+    name: string;
+    version?: string;
+    pluginConfig?: Record<string, unknown>;
+    logger: PluginLogger;
+    registerTool?: (tool: PluginTool, opts?: PluginToolOptions) => void;
+    registerHook?: (events: string | string[], handler: InternalHookHandler, opts?: PluginHookOptions) => void;
+    on: {
+        (hook: "before_agent_start", handler: (event: BeforeAgentStartEvent, ctx: PluginHookAgentContext) => Promise<BeforeAgentStartResult | undefined> | BeforeAgentStartResult | undefined): void;
+        (hook: "before_prompt_build", handler: (event: BeforePromptBuildEvent, ctx: PluginHookAgentContext) => Promise<BeforePromptBuildResult | undefined> | BeforePromptBuildResult | undefined): void;
+        (hook: "before_reset", handler: (event: BeforeResetEvent, ctx: PluginHookAgentContext) => Promise<void> | void): void;
+    };
+};
+
+type OpenClawWriteAttributionSurface = "native-store" | "watcher" | "handoff";
+type OpenClawWriteAttributionSource = "tool-project" | "session-project" | "plugin-default" | "watcher-fallback" | "entry-project" | "none";
+type OpenClawWriteAttributionReason = "explicit-tool-project" | "explicit-session-project" | "explicit-session-cleared" | "session-project-not-worthy" | "plugin-default-project" | "watcher-inferred-project" | "existing-entry-project" | "no-project-candidate";
+type OpenClawWriteAttributionKind = "explicit" | "inferred" | "default" | "global";
+type OpenClawWriteAttributionResolution = {
+    surface: OpenClawWriteAttributionSurface;
+    project: string | null;
+    source: OpenClawWriteAttributionSource;
+    reason: OpenClawWriteAttributionReason;
+    attributionKind: OpenClawWriteAttributionKind;
+    sessionProjectGate: "batch" | "entry" | "not-applicable";
+    strictnessRelevant: false;
+    dependencyExpansionRelevant: false;
+    memoryReliabilityDiagnostic?: WriteAttributionResolutionDiagnostic;
+};
+
+declare function summarizeSessionForHandoff(currentRawMessages: BeforeResetEvent["messages"], sessionsDir: string, currentSessionFile: string, logger: PluginApi["logger"], includeBackground: boolean, streamSimpleImpl?: StreamSimpleFn, logEnabled?: boolean, logDir?: string, debugEnabled?: boolean): Promise<string | null>;
+interface RunHandoffForSessionOptions {
+    messages: unknown[];
+    sessionFile: string | null;
+    sessionId: string;
+    sessionKey: string;
+    agentId: string;
+    budget: number;
+    defaultProject: string | undefined;
+    projectAttribution?: OpenClawWriteAttributionResolution;
+    storeConfig: Record<string, unknown>;
+    sessionsDir: string;
+    includeBackground?: boolean;
+    logEnabled?: boolean;
+    logDir?: string;
+    debugEnabled?: boolean;
+    logger: PluginLogger | undefined;
+    source: "before_reset" | "command" | "session_start";
+    dbPath?: string;
+    summarizeSessionForHandoffImpl?: typeof summarizeSessionForHandoff;
+}
+
+declare function stripInjectedContext(text: string): string;
+
+type RunHandoffForSessionArgs = Omit<RunHandoffForSessionOptions, "summarizeSessionForHandoffImpl">;
+declare const plugin: {
+    id: string;
+    name: string;
+    description: string;
+    register(api: PluginApi): void;
+};
+declare const __testing: {
+    clearState(): void;
+    readSessionsJson: typeof readSessionsJson;
+    readAndParseSessionJsonl: typeof readAndParseSessionJsonl;
+    getBaseSessionPath: typeof getBaseSessionPath;
+    getSurfaceForSessionFile: typeof getSurfaceForSessionFile;
+    readMessagesFromJsonl: typeof readMessagesFromJsonl;
+    stripInjectedContext: typeof stripInjectedContext;
+    findPriorResetFile: typeof findPriorResetFile;
+    buildTranscript: typeof buildTranscript;
+    buildMergedTranscript: typeof buildMergedTranscript;
+    capTranscriptLength: typeof capTranscriptLength;
+    HANDOFF_SUMMARY_SYSTEM_PROMPT: string;
+    HANDOFF_SUMMARY_SYSTEM_PROMPT_WITH_BACKGROUND: string;
+    summarizeSessionForHandoff: typeof summarizeSessionForHandoff;
+    runHandoffForSession(opts: RunHandoffForSessionArgs): Promise<void>;
+};
+
+export { __testing, plugin as default };