cognia-sdk 0.2.0 → 0.2.2

package/README.md

@@ -91,6 +91,10 @@ A verified success needs a signal (a test, a check, a metric) or a human. Inject
 counts as success. Your Cognia Cloud Overview shows the loop per week: turns with context → cited → used → verified, with
 unverified reports listed apart.
 
+**Router decision values** (`x-cognia-decision`): `INJECT`, `ABSTAIN`, `unavailable:timeout` (the context budget passed),
+`unavailable:<status>` (Cognia answered an error), `unavailable:error`, `no_user_message`. Every `unavailable` means the
+call was forwarded untouched.
+
 **Credits.** Reporting on other owners' knowledge earns Cloud credits (verified outcomes most, used receipts a little,
 context calls that injected a little), and your own memories earn when an independent agent's verified success lands on
 them. Credits pay for Workbench messages beyond your plan. They are not money. `GET /v1/cloud/me/credits` lists them.
@@ -107,3 +111,17 @@ Every context call then carries that namespace. A private memory saved under it
 namespace: the `mine` scope never crosses from one of your users to another, and the `organization` and `network`
 scopes add only what is shared with your organizations or public. Omit the namespace for a single-agent integration.
 Your own Cognia Cloud still shows everything the key owns: you are the data controller for your users' memories.
+
+## Memory lifecycle: supersede, contradict, expire (API, 2026-10-08)
+
+A long-running agent accumulates private memories that go stale. Three private-only fields on `POST /v1/memories/author`
+keep retrieval honest without deleting anything:
+
+- `supersedes: "<memoryId>"` — this memory replaces one of yours (same namespace). The old one stays readable by id, says
+  what replaced it, and never comes back in context or search.
+- `contradicts: "<memoryId>"` — same mechanics, recorded as a contradiction.
+- `validUntil: "<ISO date-time>"` — retrieved only until then.
+
+`PATCH /v1/memories/:id/lifecycle` sets or clears `validUntil` and `supersededBy` later. Session learning
+(`session.end()`) marks a proposal with `supersedes` when its title matches one of your live private memories, so your
+accept step can pass it through and update instead of duplicating.

package/dist/cjs/client.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.Cognia = exports.CogniaError = void 0;
+exports.Cognia = exports.CogniaError = exports.SDK_VERSION = void 0;
 exports.shapeContext = shapeContext;
 /** Accept only what the contract promises; anything else is treated as unavailable so the model call proceeds (fail-open). */
 function shapeContext(r) {
@@ -42,6 +42,8 @@ function shapeContext(r) {
     const abstain = decision === "ABSTAIN" ? { reason: (o.abstain && typeof o.abstain.reason === "string" ? o.abstain.reason : o.decision === "INJECT" ? "malformed_items" : "abstain") } : undefined;
     return { contextId: o.contextId, decision, ...(abstain ? { abstain } : {}), scope, items: items, receipts, metrics };
 }
+/** kept in step with package.json by the version test */
+exports.SDK_VERSION = "0.2.2";
 class CogniaError extends Error {
     status;
     body;
@@ -63,8 +65,10 @@ class Cognia {
     f;
     onError;
     namespace;
+    receiptTimeoutMs;
     constructor(o) {
         this.namespace = o.namespace;
+        this.receiptTimeoutMs = o.receiptTimeoutMs ?? 10_000;
         if (!o.apiKey && !o.tokenProvider)
             throw new Error("Cognia: apiKey or tokenProvider is required");
         this.key = o.apiKey ?? null;
@@ -136,7 +140,7 @@ class Cognia {
                 token = this.key;
             if (!token)
                 throw new CogniaError(`Cognia ${method} ${path} → no credential`, 0, null);
-            const r = await this.f(this.baseUrl + path, { method, headers: { authorization: `Bearer ${token}`, "content-type": "application/json", "user-agent": "cognia-sdk/0.1.6" }, body: body === undefined ? undefined : JSON.stringify(body), signal: ac.signal });
+            const r = await this.f(this.baseUrl + path, { method, headers: { authorization: `Bearer ${token}`, "content-type": "application/json", "user-agent": "cognia-sdk/" + exports.SDK_VERSION }, body: body === undefined ? undefined : JSON.stringify(body), signal: ac.signal });
             let j = null;
             try {
                 j = await r.json();
@@ -186,41 +190,45 @@ class Cognia {
             return { contextId: null, decision: "UNAVAILABLE", items: [], reason: err.name === "AbortError" ? "timeout" : err.message };
         }
     }
+    /** A usage receipt (injected / cited / used): never on the model call's critical path, so it gets a generous budget
+     *  (RECEIPT_TIMEOUT_MS, default 10 s) and one retry; a failure is reported to onError and never thrown (NEW-RECEIPT). */
+    async receipt(kind, contextId, body) {
+        const url = `/v1/context/${encodeURIComponent(contextId)}/${kind}`;
+        let last = null;
+        for (let attempt = 0; attempt < 2; attempt++) {
+            try {
+                return await this.call(url.startsWith("/") ? "POST" : "POST", url, body, this.receiptTimeoutMs);
+            }
+            catch (e) {
+                last = e instanceof Error ? e : new Error(String(e));
+                if (!/timed out|AbortError|fetch failed|ECONN|5\d\d/.test(last.message + last.name))
+                    break;
+            }
+        }
+        if (last)
+            this.onError?.(last);
+        return null;
+    }
     /** Tell Cognia which returned items were actually placed in front of the model. A usage receipt, never evidence. */
     async injected(contextId, itemIds) {
         if (!contextId || !itemIds.length)
             return;
-        try {
-            await this.call("POST", `/v1/context/${encodeURIComponent(contextId)}/injected`, { itemIds }, 2000);
-        }
-        catch (e) {
-            this.onError?.(e instanceof Error ? e : new Error(String(e)));
-        }
+        await this.receipt("injected", contextId, { itemIds });
     }
     /** CITED: the model's reply referenced these items (the middleware detects this by itself). A usage receipt, never evidence. */
     async cited(contextId, itemIds) {
         if (!contextId || !itemIds.length)
             return;
-        try {
-            await this.call("POST", `/v1/context/${encodeURIComponent(contextId)}/cited`, { itemIds }, 2000);
-        }
-        catch (e) {
-            this.onError?.(e instanceof Error ? e : new Error(String(e)));
-        }
+        await this.receipt("cited", contextId, { itemIds });
     }
     /** USED: your agent actually used these items, whether or not you know yet how it turned out. The cheapest honest signal. */
     async used(contextId, itemIds) {
         if (!contextId || !itemIds.length)
             return null;
-        try {
-            return await this.call("POST", `/v1/context/${encodeURIComponent(contextId)}/used`, { itemIds }, 3000);
-        }
-        catch (e) {
-            this.onError?.(e instanceof Error ? e : new Error(String(e)));
-            return null;
-        }
+        return (await this.receipt("used", contextId, { itemIds }));
     }
-    /** Report what happened with one item: used or not, success / failure (/ neutral for a Skill). This is the only path to success. */
+    /** Report what happened with one item: used or not, success / failure (/ neutral for a Skill). USED comes from this or from
+     *  `used()`; success and failure come only from here. */
     outcome(contextId, input) {
         return this.call("POST", `/v1/context/${encodeURIComponent(contextId)}/outcome`, input);
     }

package/dist/cjs/index.js

@@ -1,9 +1,10 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.provenanceLine = exports.renderContextBlock = exports.textOf = exports.prependSystem = exports.contextFor = exports.afterReply = exports.citedItems = exports.withCognia = exports.CogniaSession = exports.shapeContext = exports.CogniaError = exports.Cognia = void 0;
+exports.provenanceLine = exports.renderContextBlock = exports.textOf = exports.prependSystem = exports.contextFor = exports.afterReply = exports.citedItems = exports.withCognia = exports.CogniaSession = exports.shapeContext = exports.SDK_VERSION = exports.CogniaError = exports.Cognia = void 0;
 var client_js_1 = require("./client.js");
 Object.defineProperty(exports, "Cognia", { enumerable: true, get: function () { return client_js_1.Cognia; } });
 Object.defineProperty(exports, "CogniaError", { enumerable: true, get: function () { return client_js_1.CogniaError; } });
+Object.defineProperty(exports, "SDK_VERSION", { enumerable: true, get: function () { return client_js_1.SDK_VERSION; } });
 Object.defineProperty(exports, "shapeContext", { enumerable: true, get: function () { return client_js_1.shapeContext; } });
 var session_js_1 = require("./session.js");
 Object.defineProperty(exports, "CogniaSession", { enumerable: true, get: function () { return session_js_1.CogniaSession; } });

package/dist/esm/client.d.ts

@@ -1,5 +1,7 @@
 import type { ReceiptResponse, ContextRequest, ContextResponse, ContextResult, OutcomeInput, OutcomeResponse, ExtractResponse, Scope } from "./types.js";
 export interface CogniaOptions {
+    /** budget for usage receipts (injected / cited / used), which never block the model call; default 10 000 ms, one retry */
+    receiptTimeoutMs?: number;
     /** end-user namespace sent on every context call (0.2.0). Use one per end user of YOUR app: their private memories
      *  are then invisible to every other namespace under the same key. Omit for a single-agent integration. */
     namespace?: string;
@@ -25,6 +27,8 @@ export interface CogniaOptions {
 }
 /** Accept only what the contract promises; anything else is treated as unavailable so the model call proceeds (fail-open). */
 export declare function shapeContext(r: unknown): ContextResponse | null;
+/** kept in step with package.json by the version test */
+export declare const SDK_VERSION = "0.2.2";
 export declare class CogniaError extends Error {
     readonly status: number;
     readonly body: unknown;
@@ -43,6 +47,7 @@ export declare class Cognia {
     private readonly f;
     private readonly onError;
     readonly namespace: string | undefined;
+    readonly receiptTimeoutMs: number;
     constructor(o: CogniaOptions);
     /** Every string that reaches the host through an error or a reason has the bearer removed first (independent E2E F28). */
     private scrub;
@@ -53,13 +58,17 @@ export declare class Cognia {
      * A bad credential is also reported this way, with the reason, so a misconfigured app degrades instead of breaking.
      */
     context(req: ContextRequest | string): Promise<ContextResult>;
+    /** A usage receipt (injected / cited / used): never on the model call's critical path, so it gets a generous budget
+     *  (RECEIPT_TIMEOUT_MS, default 10 s) and one retry; a failure is reported to onError and never thrown (NEW-RECEIPT). */
+    private receipt;
     /** Tell Cognia which returned items were actually placed in front of the model. A usage receipt, never evidence. */
     injected(contextId: string, itemIds: string[]): Promise<void>;
     /** CITED: the model's reply referenced these items (the middleware detects this by itself). A usage receipt, never evidence. */
     cited(contextId: string, itemIds: string[]): Promise<void>;
     /** USED: your agent actually used these items, whether or not you know yet how it turned out. The cheapest honest signal. */
     used(contextId: string, itemIds: string[]): Promise<ReceiptResponse | null>;
-    /** Report what happened with one item: used or not, success / failure (/ neutral for a Skill). This is the only path to success. */
+    /** Report what happened with one item: used or not, success / failure (/ neutral for a Skill). USED comes from this or from
+     *  `used()`; success and failure come only from here. */
     outcome(contextId: string, input: OutcomeInput): Promise<OutcomeResponse>;
     /** One-liners for the two outcomes. Pass `verification` when a signal (a test, a check, a metric) or a human confirmed it;
      *  without it the report is recorded as agent-reported, which counts as used but never as verified success. */

package/dist/esm/client.js

@@ -38,6 +38,8 @@ export function shapeContext(r) {
     const abstain = decision === "ABSTAIN" ? { reason: (o.abstain && typeof o.abstain.reason === "string" ? o.abstain.reason : o.decision === "INJECT" ? "malformed_items" : "abstain") } : undefined;
     return { contextId: o.contextId, decision, ...(abstain ? { abstain } : {}), scope, items: items, receipts, metrics };
 }
+/** kept in step with package.json by the version test */
+export const SDK_VERSION = "0.2.2";
 export class CogniaError extends Error {
     status;
     body;
@@ -58,8 +60,10 @@ export class Cognia {
     f;
     onError;
     namespace;
+    receiptTimeoutMs;
     constructor(o) {
         this.namespace = o.namespace;
+        this.receiptTimeoutMs = o.receiptTimeoutMs ?? 10_000;
         if (!o.apiKey && !o.tokenProvider)
             throw new Error("Cognia: apiKey or tokenProvider is required");
         this.key = o.apiKey ?? null;
@@ -131,7 +135,7 @@ export class Cognia {
                 token = this.key;
             if (!token)
                 throw new CogniaError(`Cognia ${method} ${path} → no credential`, 0, null);
-            const r = await this.f(this.baseUrl + path, { method, headers: { authorization: `Bearer ${token}`, "content-type": "application/json", "user-agent": "cognia-sdk/0.1.6" }, body: body === undefined ? undefined : JSON.stringify(body), signal: ac.signal });
+            const r = await this.f(this.baseUrl + path, { method, headers: { authorization: `Bearer ${token}`, "content-type": "application/json", "user-agent": "cognia-sdk/" + SDK_VERSION }, body: body === undefined ? undefined : JSON.stringify(body), signal: ac.signal });
             let j = null;
             try {
                 j = await r.json();
@@ -181,41 +185,45 @@ export class Cognia {
             return { contextId: null, decision: "UNAVAILABLE", items: [], reason: err.name === "AbortError" ? "timeout" : err.message };
         }
     }
+    /** A usage receipt (injected / cited / used): never on the model call's critical path, so it gets a generous budget
+     *  (RECEIPT_TIMEOUT_MS, default 10 s) and one retry; a failure is reported to onError and never thrown (NEW-RECEIPT). */
+    async receipt(kind, contextId, body) {
+        const url = `/v1/context/${encodeURIComponent(contextId)}/${kind}`;
+        let last = null;
+        for (let attempt = 0; attempt < 2; attempt++) {
+            try {
+                return await this.call(url.startsWith("/") ? "POST" : "POST", url, body, this.receiptTimeoutMs);
+            }
+            catch (e) {
+                last = e instanceof Error ? e : new Error(String(e));
+                if (!/timed out|AbortError|fetch failed|ECONN|5\d\d/.test(last.message + last.name))
+                    break;
+            }
+        }
+        if (last)
+            this.onError?.(last);
+        return null;
+    }
     /** Tell Cognia which returned items were actually placed in front of the model. A usage receipt, never evidence. */
     async injected(contextId, itemIds) {
         if (!contextId || !itemIds.length)
             return;
-        try {
-            await this.call("POST", `/v1/context/${encodeURIComponent(contextId)}/injected`, { itemIds }, 2000);
-        }
-        catch (e) {
-            this.onError?.(e instanceof Error ? e : new Error(String(e)));
-        }
+        await this.receipt("injected", contextId, { itemIds });
     }
     /** CITED: the model's reply referenced these items (the middleware detects this by itself). A usage receipt, never evidence. */
     async cited(contextId, itemIds) {
         if (!contextId || !itemIds.length)
             return;
-        try {
-            await this.call("POST", `/v1/context/${encodeURIComponent(contextId)}/cited`, { itemIds }, 2000);
-        }
-        catch (e) {
-            this.onError?.(e instanceof Error ? e : new Error(String(e)));
-        }
+        await this.receipt("cited", contextId, { itemIds });
     }
     /** USED: your agent actually used these items, whether or not you know yet how it turned out. The cheapest honest signal. */
     async used(contextId, itemIds) {
         if (!contextId || !itemIds.length)
             return null;
-        try {
-            return await this.call("POST", `/v1/context/${encodeURIComponent(contextId)}/used`, { itemIds }, 3000);
-        }
-        catch (e) {
-            this.onError?.(e instanceof Error ? e : new Error(String(e)));
-            return null;
-        }
+        return (await this.receipt("used", contextId, { itemIds }));
     }
-    /** Report what happened with one item: used or not, success / failure (/ neutral for a Skill). This is the only path to success. */
+    /** Report what happened with one item: used or not, success / failure (/ neutral for a Skill). USED comes from this or from
+     *  `used()`; success and failure come only from here. */
     outcome(contextId, input) {
         return this.call("POST", `/v1/context/${encodeURIComponent(contextId)}/outcome`, input);
     }

package/dist/esm/index.d.ts

@@ -1,4 +1,4 @@
-export { Cognia, CogniaError, shapeContext, type CogniaOptions } from "./client.js";
+export { Cognia, CogniaError, SDK_VERSION, shapeContext, type CogniaOptions } from "./client.js";
 export { CogniaSession, type SessionTurn } from "./session.js";
 export { withCognia, citedItems, afterReply, contextFor, prependSystem, textOf, type WithCogniaOptions } from "./middleware.js";
 export { renderContextBlock, provenanceLine } from "./render.js";

package/dist/esm/index.js

@@ -1,4 +1,4 @@
-export { Cognia, CogniaError, shapeContext } from "./client.js";
+export { Cognia, CogniaError, SDK_VERSION, shapeContext } from "./client.js";
 export { CogniaSession } from "./session.js";
 export { withCognia, citedItems, afterReply, contextFor, prependSystem, textOf } from "./middleware.js";
 export { renderContextBlock, provenanceLine } from "./render.js";

package/dist/esm/types.d.ts

@@ -121,6 +121,13 @@ export interface OutcomeResponse {
 export interface ExtractProposal {
     title?: string;
     summary?: string;
+    /** lifecycle V1: this proposal matches one of your live private memories by title; accept it WITH `supersedes` to replace instead of adding a copy */
+    supersedes?: {
+        memoryId: string;
+        displayId: string | null;
+        title: string;
+        why: string;
+    };
     [k: string]: unknown;
 }
 export interface ExtractResponse {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cognia-sdk",
-  "version": "0.2.0",
+  "version": "0.2.2",
   "description": "Cognia for your model calls: one line gives any agent the Memories and Skills it may use, with provenance and honest receipts. Fails open.",
   "license": "MIT",
   "author": "Cognia",