@agentfold/shared 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 AgentFold contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/dist/index.d.ts

@@ -0,0 +1,157 @@
+/**
+ * AgentFold shared types — protocol-neutral, dependency-free.
+ *
+ * RAW HISTORY IS SOURCE OF TRUTH.
+ * Every folded piece of context must be recoverable from the immutable ledger.
+ */
+export type EventKind = "system" | "developer" | "user" | "assistant" | "tool_call" | "tool_result";
+/**
+ * A single protocol-neutral event extracted from an agent conversation.
+ * Events are immutable once written. Updates to memory/task state never
+ * rewrite events.
+ */
+export interface AgentEvent {
+    id: string;
+    sessionId: string;
+    /** Position within the session conversation. Stable across requests. */
+    sequence: number;
+    /** ISO-8601 timestamp of first observation. */
+    timestamp: string;
+    kind: EventKind;
+    /** Tool name for tool_call / tool_result events. */
+    toolName?: string;
+    /** Protocol-level pairing id (OpenAI tool_call_id / Responses call_id). */
+    toolCallId?: string;
+    /** Normalized text content (redacted if redaction is enabled). */
+    content: string;
+    /** sha256 hex of `content` (post-redaction). */
+    contentSha256: string;
+    metadataJson: string;
+    tokenEstimate: number;
+    /** True if content contained secrets that were redacted or private tags. */
+    sensitive: boolean;
+    /** Whether the fold engine may ever fold this event's content. */
+    foldable: boolean;
+    source: string;
+}
+/**
+ * Deterministic record replacing a folded block in the outgoing context.
+ * Format is specified in docs/FOLD_FORMAT.md and must stay byte-stable
+ * for identical inputs.
+ */
+export interface FoldRecord {
+    /** 8-hex public id, printed in the digest as [AFOLD:<id>]. */
+    foldId: string;
+    sessionId: string;
+    /** Ledger event holding the original raw content. */
+    originalEventId: string;
+    /** sha256 hex of the raw (redacted) content — verified on recall. */
+    sha256: string;
+    toolName?: string;
+    resultKind?: "ok" | "failed" | "unknown";
+    originalTokens: number;
+    digestTokens: number;
+    lineCount: number;
+    errorCount: number;
+    /** Deterministically extracted identifiers, paths, numbers, errors... */
+    anchors: string[];
+    digest: string;
+    createdAt: string;
+}
+export interface AgentFoldConfig {
+    /** Fold when estimated live tokens exceed contextWindow * foldAt. */
+    foldAt: number;
+    /** Minimum relative savings (fraction of contextWindow) to trigger a fold pass. */
+    foldStep: number;
+    /** Post-fold live budget as fraction of usable window. */
+    targetLiveBudgetFraction: number;
+    /** Hard cap on live tokens regardless of window size. */
+    absoluteLiveCap: number;
+    /** Fraction of the window reserved for the model's output. */
+    outputReserve: number;
+    /** Fraction reserved for protocol overhead / safety margin. */
+    protocolReserve: number;
+    /** Protected tail tokens override (null = dynamic). */
+    protectedTailTokens: number | null;
+    /** Retrieval: max memory cards injected per request. */
+    retrievalTopK: number;
+    /** Max tokens of retrieved memory injected per request. */
+    retrievalBudgetTokens: number;
+    storage: {
+        /** Path to the SQLite database file. */
+        dbPath: string;
+        redactSecrets: boolean;
+    };
+    /** When true, internal errors fail the request instead of failing open. */
+    strictMode: boolean;
+    /** Default context window (tokens) for unknown models. */
+    defaultContextWindow: number;
+    /** Upstream base URL for proxy mode. */
+    upstreamBaseUrl: string;
+    /** Proxy listen port. */
+    port: number;
+    /** MCP recall result token cap. */
+    recallTokenCap: number;
+}
+export declare const DEFAULT_CONFIG: AgentFoldConfig;
+/** Known model context windows (tokens). Extend as needed. */
+export declare const CONTEXT_WINDOWS: Record<string, number>;
+export declare function contextWindowFor(model: string, config: AgentFoldConfig): number;
+export interface TokenCount {
+    tokens: number;
+    /** true when produced by the heuristic counter, not a model tokenizer. */
+    estimated: boolean;
+}
+export interface TokenCounter {
+    count(text: string): TokenCount;
+}
+export interface RequestMetrics {
+    sessionId: string;
+    model: string;
+    originalTokens: number;
+    compiledTokens: number;
+    savedTokens: number;
+    savingRatio: number;
+    foldedBlocks: number;
+    retrievedMemoryTokens: number;
+    protectedTailTokens: number;
+    pinnedTokens: number;
+    estimatedContextUsage: number;
+    compileLatencyMs: number;
+    proxyOverheadMs: number;
+    /** gross estimated savings before cache-refill penalty. */
+    grossTokensSaved: number;
+    /** estimated tokens to re-refill provider prefix cache after folding. */
+    estimatedReprefillCost: number;
+    netEstimatedSaving: number;
+    cacheMetricsAvailable: boolean;
+    warnings: string[];
+    diagnostics: string[];
+}
+export type MemoryStatus = "active" | "superseded" | "expired" | "invalid";
+export interface MemoryCard {
+    id: string;
+    sessionId: string;
+    kind: string;
+    title: string;
+    timestamp: string;
+    evidence: string;
+    tokenCost: number;
+    confidence: number;
+    status: MemoryStatus;
+    supersededBy: string | null;
+    sourceEventId: string | null;
+    score: number;
+    scoreReasons: string[];
+}
+export interface Pin {
+    id: string;
+    sessionId: string | null;
+    text: string;
+    createdAt: string;
+    source: "user" | "agent" | "system";
+}
+export declare class AgentFoldError extends Error {
+    readonly code: "integrity_error" | "not_found" | "budget_exceeded" | "store_unavailable" | "invalid_input";
+    constructor(message: string, code: "integrity_error" | "not_found" | "budget_exceeded" | "store_unavailable" | "invalid_input");
+}

package/dist/index.js

@@ -0,0 +1,71 @@
+/**
+ * AgentFold shared types — protocol-neutral, dependency-free.
+ *
+ * RAW HISTORY IS SOURCE OF TRUTH.
+ * Every folded piece of context must be recoverable from the immutable ledger.
+ */
+export const DEFAULT_CONFIG = {
+    foldAt: 0.45,
+    foldStep: 0.12,
+    targetLiveBudgetFraction: 0.7,
+    absoluteLiveCap: 200_000,
+    outputReserve: 0.2,
+    protocolReserve: 0.05,
+    protectedTailTokens: null,
+    retrievalTopK: 3,
+    retrievalBudgetTokens: 800,
+    storage: {
+        dbPath: ".agentfold/agentfold.db",
+        redactSecrets: true
+    },
+    strictMode: false,
+    defaultContextWindow: 128_000,
+    upstreamBaseUrl: "https://api.openai.com",
+    port: 3897,
+    recallTokenCap: 8_000
+};
+/** Known model context windows (tokens). Extend as needed. */
+export const CONTEXT_WINDOWS = {
+    "gpt-4o": 128_000,
+    "gpt-4o-mini": 128_000,
+    "gpt-4.1": 1_000_000,
+    "gpt-4.1-mini": 1_000_000,
+    "gpt-4.1-nano": 1_000_000,
+    "gpt-5": 400_000,
+    "gpt-5-mini": 400_000,
+    o1: 200_000,
+    o3: 200_000,
+    "o4-mini": 200_000,
+    "claude-opus-4": 200_000,
+    "claude-sonnet-4": 200_000,
+    "claude-3-7-sonnet": 200_000,
+    "gemini-2.5-pro": 1_000_000,
+    "gemini-2.5-flash": 1_000_000,
+    "deepseek-chat": 128_000,
+    "deepseek-reasoner": 128_000,
+    "qwen-max": 128_000,
+    "glm-4.5": 128_000,
+    "kimi-k2": 256_000
+};
+export function contextWindowFor(model, config) {
+    if (CONTEXT_WINDOWS[model] != null)
+        return CONTEXT_WINDOWS[model];
+    // family prefix match, e.g. "gpt-4o-2024-08-13"
+    for (const [key, value] of Object.entries(CONTEXT_WINDOWS)) {
+        if (model.startsWith(key))
+            return value;
+    }
+    return config.defaultContextWindow;
+}
+// ---------------------------------------------------------------------------
+// Errors
+// ---------------------------------------------------------------------------
+export class AgentFoldError extends Error {
+    code;
+    constructor(message, code) {
+        super(message);
+        this.code = code;
+        this.name = "AgentFoldError";
+    }
+}
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAiHH,MAAM,CAAC,MAAM,cAAc,GAAoB;IAC7C,MAAM,EAAE,IAAI;IACZ,QAAQ,EAAE,IAAI;IACd,wBAAwB,EAAE,GAAG;IAC7B,eAAe,EAAE,OAAO;IACxB,aAAa,EAAE,GAAG;IAClB,eAAe,EAAE,IAAI;IACrB,mBAAmB,EAAE,IAAI;IACzB,aAAa,EAAE,CAAC;IAChB,qBAAqB,EAAE,GAAG;IAC1B,OAAO,EAAE;QACP,MAAM,EAAE,yBAAyB;QACjC,aAAa,EAAE,IAAI;KACpB;IACD,UAAU,EAAE,KAAK;IACjB,oBAAoB,EAAE,OAAO;IAC7B,eAAe,EAAE,wBAAwB;IACzC,IAAI,EAAE,IAAI;IACV,cAAc,EAAE,KAAK;CACtB,CAAC;AAEF,8DAA8D;AAC9D,MAAM,CAAC,MAAM,eAAe,GAA2B;IACrD,QAAQ,EAAE,OAAO;IACjB,aAAa,EAAE,OAAO;IACtB,SAAS,EAAE,SAAS;IACpB,cAAc,EAAE,SAAS;IACzB,cAAc,EAAE,SAAS;IACzB,OAAO,EAAE,OAAO;IAChB,YAAY,EAAE,OAAO;IACrB,EAAE,EAAE,OAAO;IACX,EAAE,EAAE,OAAO;IACX,SAAS,EAAE,OAAO;IAClB,eAAe,EAAE,OAAO;IACxB,iBAAiB,EAAE,OAAO;IAC1B,mBAAmB,EAAE,OAAO;IAC5B,gBAAgB,EAAE,SAAS;IAC3B,kBAAkB,EAAE,SAAS;IAC7B,eAAe,EAAE,OAAO;IACxB,mBAAmB,EAAE,OAAO;IAC5B,UAAU,EAAE,OAAO;IACnB,SAAS,EAAE,OAAO;IAClB,SAAS,EAAE,OAAO;CACnB,CAAC;AAEF,MAAM,UAAU,gBAAgB,CAAC,KAAa,EAAE,MAAuB;IACrE,IAAI,eAAe,CAAC,KAAK,CAAC,IAAI,IAAI;QAAE,OAAO,eAAe,CAAC,KAAK,CAAE,CAAC;IACnE,gDAAgD;IAChD,KAAK,MAAM,CAAC,GAAG,EAAE,KAAK,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,eAAe,CAAC,EAAE,CAAC;QAC3D,IAAI,KAAK,CAAC,UAAU,CAAC,GAAG,CAAC;YAAE,OAAO,KAAK,CAAC;IAC1C,CAAC;IACD,OAAO,MAAM,CAAC,oBAAoB,CAAC;AACrC,CAAC;AA8ED,8EAA8E;AAC9E,SAAS;AACT,8EAA8E;AAE9E,MAAM,OAAO,cAAe,SAAQ,KAAK;IAGrB;IAFlB,YACE,OAAe,EACC,IAKG;QAEnB,KAAK,CAAC,OAAO,CAAC,CAAC;QAPC,SAAI,GAAJ,IAAI,CAKD;QAGnB,IAAI,CAAC,IAAI,GAAG,gBAAgB,CAAC;IAC/B,CAAC;CACF"}

package/package.json

@@ -0,0 +1,43 @@
+{
+  "name": "@agentfold/shared",
+  "version": "0.1.0",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "devDependencies": {
+    "typescript": "^5.7.0"
+  },
+  "files": [
+    "dist"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/279458179/agentfold.git"
+  },
+  "keywords": [
+    "ai",
+    "agents",
+    "context",
+    "llm",
+    "memory",
+    "tokens",
+    "context-window",
+    "openai",
+    "mcp"
+  ],
+  "license": "MIT",
+  "description": "AgentFold — virtual memory for AI agents: fold cold context, recall anything.",
+  "scripts": {
+    "build": "tsc -b",
+    "test": "vitest run"
+  }
+}