@agenr/openclaw-plugin 0.14.1 → 1.2.0

package/dist/index.d.ts

@@ -1,338 +0,0 @@
-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 };

package/skills/SKILL.md

@@ -1,77 +0,0 @@
----
-name: agenr
-description: Use when storing new knowledge (decisions, preferences, lessons, todos) or recalling context mid-session. The agenr plugin auto-injects memory at session start - this skill covers proactive store and on-demand recall.
----
-
-## agenr_store
-
-Use proactively for durable knowledge - decisions, preferences, lessons, and facts that future sessions need to make better decisions.
-
-**The future-session test:** Before storing, ask: "If I woke up in a fresh session and recalled this, would it change how I act?" If the answer is just "it tells me something that already happened and is done" - do not store it.
-
-**Store:**
-- Architecture decisions and design rationale
-- Workflow constraints and operational rules
-- Lessons learned from problems (recurring bugs, what worked, what did not)
-- User preferences and working-style observations
-- Durable facts about systems, environments, people, projects
-- Important open risks or unresolved hazards
-
-**Do not store:**
-- Version or release shipping events ("v1.2.3 shipped") - changelogs are the system of record
-- Issue or PR filing records ("filed #123, #124") - the issue tracker is the system of record
-- Phase plans or release packaging decisions - transient coordination artifacts, stale within a session
-- Progress snapshots ("3 of 5 tasks done") - stale within minutes
-- Prompt file paths or internal build logistics - look-up-able, not memory-worthy
-- Anything whose only value is duplicating files, the issue tracker, or git history
-
-Do not ask before storing - but do ask whether future-you needs it.
-
-Required: `type`, `content`, `importance`.
-Optional: `subject` (short label), `tags` (array), `scope` (`private`|`personal`|`public`), `project`, `platform`, `source`.
-
-Types: `fact | decision | preference | todo | lesson | event | relationship`
-Do not store secrets/credentials, temporary state, or verbatim conversation.
-
-### Importance calibration
-
-- **10**: Once-per-project permanent constraints. At most 1-2 per project lifetime.
-- **9**: Critical breaking changes or immediate cross-session decisions. At most 1 per significant session, often 0.
-- **8**: Things an active parallel session would act on right now. Fires a cross-session signal. Use conservatively.
-- **7**: Default. Project facts, decisions, preferences, milestones. No signal fired.
-- **6**: Routine dev observations (verified X, tests passing). Cap here unless the result is surprising.
-- **5**: Borderline. Only store if clearly durable beyond today.
-- **Importance is not recency.** Something that just happened is not automatically important. A shipping event is importance 5-6 at best unless it teaches a lesson. A recurring operational hazard is importance 7-8 because it affects future decisions.
-
-Entries at 7 are saved silently. Use 8+ only if other active sessions need to know NOW.
-
-### Confidence-aware extraction (OpenClaw transcripts)
-
-OpenClaw transcripts include `[user]` / `[assistant]` role labels. The extractor uses this signal:
-- Hedged or unverified assistant factual claims are tagged `unverified` and hard-capped at importance 5.
-- Tool-verified assistant claims follow normal importance rules.
-- User messages are never capped.
-
-This means: if you say something unverified, it will be stored at max importance 5. To store a fact at higher importance, verify it with a tool call first.
-
-## agenr_recall
-
-Use mid-session when you need context you don't already have. Session-start recall is handled automatically - do not call at turn 1 unless you need extra context beyond the injected summary.
-
-Parameters:
-- `query` (required): semantic search string
-- `limit`: max results (default 10)
-- `context`: `"default"` (semantic+vector) or `"session-start"` (fast bootstrap)
-- `since`: lower date bound - only entries newer than this (ISO or relative, e.g. `"7d"`, `"2026-01-01"`)
-- `until`: upper date bound - only entries older than this ceiling (e.g. `"7d"` = entries created before 7 days ago). Use with `since` for a date window.
-- `types`: comma-separated entry types (`fact,decision,preference,todo,lesson,event`)
-- `platform`: filter by platform (`openclaw`, `claude-code`, `codex`)
-- `project`: filter by project scope (pass `*` for all projects)
-
-## agenr_retire
-
-Soft-deletes an entry. Use when something is outdated, wrong, or superseded. Pass `entry_id` (from recall results) and optionally `reason` and `persist: true` to write to the retirements ledger.
-
-## agenr_extract
-
-Extracts structured knowledge entries from raw text without storing them. Useful for previewing what would be stored from a block of text before committing.