cognia-sdk 0.1.1 → 0.1.3

package/README.md

@@ -33,6 +33,22 @@ const proposals = await session.end();
 Injecting something never counts as using it. Only `outcome()` creates evidence, and only for items this context
 returned. Dogfood, canary and operator traffic is classified server-side and never counts.
 
+
+## Auth: key or delegated token
+
+```ts
+// a developer credential or an SDK credential (cognia_sk_…)
+new Cognia({ apiKey: process.env.COGNIA_API_KEY })
+
+// delegated auth: the host already holds a Cognia bearer (e.g. the MCP OAuth access token)
+new Cognia({ tokenProvider: async () => await getCogniaToken() })   // called on every request, never cached, never in errors
+```
+
+If your identity lives in a connected client (Claude, ChatGPT, OpenClaw…) and the host hides its token, ask the connected
+Cognia to run `sdk_link_start`: it shows a one-time code and a Cloud link; you approve on the website and receive an
+**SDK credential** — a separate, narrow credential that can read context and report outcomes only. Details:
+`docs/SDK_CREDENTIALS.md` in the Cognia repository.
+
 ## Scope
 
 `mine` = the identity's own memories and Skills. `organization` (default) = plus everything its organizations share

package/dist/cjs/client.js

@@ -9,7 +9,32 @@ function shapeContext(r) {
     const o = r;
     if (typeof o.contextId !== "string" || (o.decision !== "INJECT" && o.decision !== "ABSTAIN"))
         return null;
-    const items = Array.isArray(o.items) ? o.items.filter((it) => it && typeof it === "object" && typeof it.id === "string" && (it.kind === "memory" || it.kind === "skill") && typeof it.title === "string" && !!it.body) : [];
+    // every item is NORMALISED, not merely filtered (independent E2E F01 retest, 2026-10-07): a missing or null
+    // provenance, a Skill body whose arrays arrive as strings, a non-string title — none of these may reach the
+    // renderer and throw, because a throw here means the host model is never called (the fail-open contract)
+    const arr = (v) => Array.isArray(v) ? v.filter((x) => typeof x === "string") : typeof v === "string" && v ? [v] : [];
+    const str = (v, d = "") => (typeof v === "string" ? v : d);
+    const num = (v) => (typeof v === "number" && Number.isFinite(v) ? v : 0);
+    const q = (p) => (p && typeof p === "object" ? p : {});
+    const sOrNull = (v) => (typeof v === "string" ? v : null);
+    const items = (Array.isArray(o.items) ? o.items : []).flatMap((raw) => {
+        if (!raw || typeof raw !== "object")
+            return [];
+        const it = raw;
+        if (typeof it.id !== "string" || (it.kind !== "memory" && it.kind !== "skill"))
+            return [];
+        const owner = it.owner === "mine" ? "mine" : it.owner === "organization" ? "organization" : "network";
+        const body = q(it.body), p = q(it.provenance);
+        const base = { id: it.id, displayId: str(it.displayId, it.id), title: str(it.title, "(untitled)"), owner, score: typeof it.score === "number" && Number.isFinite(it.score) ? it.score : null };
+        if (it.kind === "memory") {
+            const m = { ...base, kind: "memory", body: { text: str(body.text), kind: sOrNull(body.kind) },
+                provenance: { ownerName: sOrNull(p.ownerName), organizationName: sOrNull(p.organizationName), maturity: sOrNull(p.maturity), verifiedUses: num(p.verifiedUses), created: sOrNull(p.created) } };
+            return [m];
+        }
+        const k = { ...base, kind: "skill", body: { summary: str(body.summary), trigger: arr(body.trigger), procedure: arr(body.procedure), verification: arr(body.verification), doNotApplyWhen: arr(body.doNotApplyWhen) },
+            provenance: { ownerName: sOrNull(p.ownerName), maturity: str(p.maturity, "unknown"), verifiedUses: num(p.verifiedUses), routeId: sOrNull(p.routeId) } };
+        return [k];
+    });
     const decision = o.decision === "INJECT" && items.length ? "INJECT" : "ABSTAIN";
     const scope = o.scope === "mine" || o.scope === "organization" || o.scope === "network" ? o.scope : "organization";
     const metrics = (o.metrics && typeof o.metrics === "object" ? o.metrics : { ms: { search: 0, total: 0 }, considered: 0, returned: items.length });
@@ -34,12 +59,14 @@ class Cognia {
     budget;
     timeoutMs;
     key;
+    tokenProvider;
     f;
     onError;
     constructor(o) {
-        if (!o.apiKey)
-            throw new Error("Cognia: apiKey is required");
-        this.key = o.apiKey;
+        if (!o.apiKey && !o.tokenProvider)
+            throw new Error("Cognia: apiKey or tokenProvider is required");
+        this.key = o.apiKey ?? null;
+        this.tokenProvider = o.tokenProvider ?? null;
         this.baseUrl = (o.baseUrl ?? "https://api.cognia.fun").replace(/\/$/, "");
         this.scope = o.scope ?? "organization";
         this.budget = o.budget;
@@ -51,7 +78,11 @@ class Cognia {
         const ac = new AbortController();
         const t = timeoutMs ? setTimeout(() => ac.abort(), timeoutMs) : null;
         try {
-            const r = await this.f(this.baseUrl + path, { method, headers: { authorization: `Bearer ${this.key}`, "content-type": "application/json", "user-agent": "cognia-sdk/0.1.1" }, body: body === undefined ? undefined : JSON.stringify(body), signal: ac.signal });
+            // delegated auth: the provider is asked on EVERY request; its answer is used once and never stored on the client
+            const token = this.tokenProvider ? await this.tokenProvider() : 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.3" }, body: body === undefined ? undefined : JSON.stringify(body), signal: ac.signal });
             let j = null;
             try {
                 j = await r.json();

package/dist/cjs/render.js

@@ -4,9 +4,10 @@ exports.provenanceLine = provenanceLine;
 exports.renderContextBlock = renderContextBlock;
 /** One provenance line the model can cite and a reader can look up: reference · owner · organization · evidence. */
 function provenanceLine(it) {
-    const who = it.owner === "mine" ? "yours" : it.owner === "organization" ? `shared by ${neutral(it.provenance.ownerName ?? "a colleague")}` : `public, by ${neutral(it.provenance.ownerName ?? "another owner")}`;
-    const ev = it.provenance.verifiedUses > 0 ? `${it.provenance.verifiedUses} verified ${it.provenance.verifiedUses === 1 ? "use" : "uses"}` : "no verified use yet";
-    const mat = it.provenance.maturity ? ` · ${String(it.provenance.maturity).toLowerCase()}` : "";
+    const who = it.owner === "mine" ? "yours" : it.owner === "organization" ? `shared by ${neutral(it.provenance?.ownerName ?? "a colleague")}` : `public, by ${neutral(it.provenance.ownerName ?? "another owner")}`;
+    const uses = Number(it.provenance?.verifiedUses ?? 0) || 0;
+    const ev = uses > 0 ? `${uses} verified ${uses === 1 ? "use" : "uses"}` : "no verified use yet";
+    const mat = it.provenance?.maturity ? ` · ${String(it.provenance.maturity).toLowerCase()}` : "";
     return `[${it.displayId} · ${who}${mat} · ${ev}]`;
 }
 /** The context block placed before the model's instructions. Plain text, deterministic, nothing invented. */
@@ -25,10 +26,11 @@ function renderContextBlock(ctx) {
             parts.push(`\n[${n}] MEMORY ${provenanceLine(it)}\nTitle: ${neutral(it.title)}\n${neutral(it.body.text)}`);
         }
         else {
-            const steps = (it.body.procedure ?? []).map((s, j) => `  ${j + 1}. ${neutral(s)}`).join("\n");
-            const when = it.body.trigger?.length ? `When: ${neutral(it.body.trigger.join("; "))}\n` : "";
-            const not = it.body.doNotApplyWhen?.length ? `Do not apply when: ${neutral(it.body.doNotApplyWhen.join("; "))}\n` : "";
-            const verify = it.body.verification?.length ? `Verify: ${neutral(it.body.verification.join("; "))}\n` : "";
+            const list = (v) => Array.isArray(v) ? v.map(String) : typeof v === "string" && v ? [v] : [];
+            const steps = list(it.body?.procedure).map((s, j) => `  ${j + 1}. ${neutral(s)}`).join("\n");
+            const when = list(it.body?.trigger).length ? `When: ${neutral(list(it.body?.trigger).join("; "))}\n` : "";
+            const not = list(it.body?.doNotApplyWhen).length ? `Do not apply when: ${neutral(list(it.body?.doNotApplyWhen).join("; "))}\n` : "";
+            const verify = list(it.body?.verification).length ? `Verify: ${neutral(list(it.body?.verification).join("; "))}\n` : "";
             parts.push(`\n[${n}] SKILL ${provenanceLine(it)}\nTitle: ${neutral(it.title)}\n${neutral(it.body.summary)}\n${when}${not}Procedure:\n${steps}\n${verify}`.trimEnd());
         }
     });

package/dist/esm/client.d.ts

@@ -1,7 +1,10 @@
 import type { ContextRequest, ContextResponse, ContextResult, OutcomeInput, OutcomeResponse, ExtractResponse, Scope } from "./types.js";
 export interface CogniaOptions {
-    /** the agent's credential (cognia_sk_…); never logged, never put in a URL */
-    apiKey: string;
+    /** the agent's credential (cognia_sk_…, a developer or SDK credential); never logged, never put in a URL */
+    apiKey?: string;
+    /** Delegated auth: called at REQUEST time to obtain the bearer (e.g. an MCP OAuth access token the host already
+     *  holds); async so the host can refresh. The SDK never caches the token and never puts it in errors or onError. */
+    tokenProvider?: () => Promise<string> | string;
     baseUrl?: string;
     /** default scope for context(); the identity's grants decide what that means */
     scope?: Scope;
@@ -33,6 +36,7 @@ export declare class Cognia {
     } | undefined;
     readonly timeoutMs: number;
     private readonly key;
+    private readonly tokenProvider;
     private readonly f;
     private readonly onError;
     constructor(o: CogniaOptions);

package/dist/esm/client.js

@@ -5,7 +5,32 @@ export function shapeContext(r) {
     const o = r;
     if (typeof o.contextId !== "string" || (o.decision !== "INJECT" && o.decision !== "ABSTAIN"))
         return null;
-    const items = Array.isArray(o.items) ? o.items.filter((it) => it && typeof it === "object" && typeof it.id === "string" && (it.kind === "memory" || it.kind === "skill") && typeof it.title === "string" && !!it.body) : [];
+    // every item is NORMALISED, not merely filtered (independent E2E F01 retest, 2026-10-07): a missing or null
+    // provenance, a Skill body whose arrays arrive as strings, a non-string title — none of these may reach the
+    // renderer and throw, because a throw here means the host model is never called (the fail-open contract)
+    const arr = (v) => Array.isArray(v) ? v.filter((x) => typeof x === "string") : typeof v === "string" && v ? [v] : [];
+    const str = (v, d = "") => (typeof v === "string" ? v : d);
+    const num = (v) => (typeof v === "number" && Number.isFinite(v) ? v : 0);
+    const q = (p) => (p && typeof p === "object" ? p : {});
+    const sOrNull = (v) => (typeof v === "string" ? v : null);
+    const items = (Array.isArray(o.items) ? o.items : []).flatMap((raw) => {
+        if (!raw || typeof raw !== "object")
+            return [];
+        const it = raw;
+        if (typeof it.id !== "string" || (it.kind !== "memory" && it.kind !== "skill"))
+            return [];
+        const owner = it.owner === "mine" ? "mine" : it.owner === "organization" ? "organization" : "network";
+        const body = q(it.body), p = q(it.provenance);
+        const base = { id: it.id, displayId: str(it.displayId, it.id), title: str(it.title, "(untitled)"), owner, score: typeof it.score === "number" && Number.isFinite(it.score) ? it.score : null };
+        if (it.kind === "memory") {
+            const m = { ...base, kind: "memory", body: { text: str(body.text), kind: sOrNull(body.kind) },
+                provenance: { ownerName: sOrNull(p.ownerName), organizationName: sOrNull(p.organizationName), maturity: sOrNull(p.maturity), verifiedUses: num(p.verifiedUses), created: sOrNull(p.created) } };
+            return [m];
+        }
+        const k = { ...base, kind: "skill", body: { summary: str(body.summary), trigger: arr(body.trigger), procedure: arr(body.procedure), verification: arr(body.verification), doNotApplyWhen: arr(body.doNotApplyWhen) },
+            provenance: { ownerName: sOrNull(p.ownerName), maturity: str(p.maturity, "unknown"), verifiedUses: num(p.verifiedUses), routeId: sOrNull(p.routeId) } };
+        return [k];
+    });
     const decision = o.decision === "INJECT" && items.length ? "INJECT" : "ABSTAIN";
     const scope = o.scope === "mine" || o.scope === "organization" || o.scope === "network" ? o.scope : "organization";
     const metrics = (o.metrics && typeof o.metrics === "object" ? o.metrics : { ms: { search: 0, total: 0 }, considered: 0, returned: items.length });
@@ -29,12 +54,14 @@ export class Cognia {
     budget;
     timeoutMs;
     key;
+    tokenProvider;
     f;
     onError;
     constructor(o) {
-        if (!o.apiKey)
-            throw new Error("Cognia: apiKey is required");
-        this.key = o.apiKey;
+        if (!o.apiKey && !o.tokenProvider)
+            throw new Error("Cognia: apiKey or tokenProvider is required");
+        this.key = o.apiKey ?? null;
+        this.tokenProvider = o.tokenProvider ?? null;
         this.baseUrl = (o.baseUrl ?? "https://api.cognia.fun").replace(/\/$/, "");
         this.scope = o.scope ?? "organization";
         this.budget = o.budget;
@@ -46,7 +73,11 @@ export class Cognia {
         const ac = new AbortController();
         const t = timeoutMs ? setTimeout(() => ac.abort(), timeoutMs) : null;
         try {
-            const r = await this.f(this.baseUrl + path, { method, headers: { authorization: `Bearer ${this.key}`, "content-type": "application/json", "user-agent": "cognia-sdk/0.1.1" }, body: body === undefined ? undefined : JSON.stringify(body), signal: ac.signal });
+            // delegated auth: the provider is asked on EVERY request; its answer is used once and never stored on the client
+            const token = this.tokenProvider ? await this.tokenProvider() : 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.3" }, body: body === undefined ? undefined : JSON.stringify(body), signal: ac.signal });
             let j = null;
             try {
                 j = await r.json();

package/dist/esm/render.js

@@ -1,8 +1,9 @@
 /** One provenance line the model can cite and a reader can look up: reference · owner · organization · evidence. */
 export function provenanceLine(it) {
-    const who = it.owner === "mine" ? "yours" : it.owner === "organization" ? `shared by ${neutral(it.provenance.ownerName ?? "a colleague")}` : `public, by ${neutral(it.provenance.ownerName ?? "another owner")}`;
-    const ev = it.provenance.verifiedUses > 0 ? `${it.provenance.verifiedUses} verified ${it.provenance.verifiedUses === 1 ? "use" : "uses"}` : "no verified use yet";
-    const mat = it.provenance.maturity ? ` · ${String(it.provenance.maturity).toLowerCase()}` : "";
+    const who = it.owner === "mine" ? "yours" : it.owner === "organization" ? `shared by ${neutral(it.provenance?.ownerName ?? "a colleague")}` : `public, by ${neutral(it.provenance.ownerName ?? "another owner")}`;
+    const uses = Number(it.provenance?.verifiedUses ?? 0) || 0;
+    const ev = uses > 0 ? `${uses} verified ${uses === 1 ? "use" : "uses"}` : "no verified use yet";
+    const mat = it.provenance?.maturity ? ` · ${String(it.provenance.maturity).toLowerCase()}` : "";
     return `[${it.displayId} · ${who}${mat} · ${ev}]`;
 }
 /** The context block placed before the model's instructions. Plain text, deterministic, nothing invented. */
@@ -21,10 +22,11 @@ export function renderContextBlock(ctx) {
             parts.push(`\n[${n}] MEMORY ${provenanceLine(it)}\nTitle: ${neutral(it.title)}\n${neutral(it.body.text)}`);
         }
         else {
-            const steps = (it.body.procedure ?? []).map((s, j) => `  ${j + 1}. ${neutral(s)}`).join("\n");
-            const when = it.body.trigger?.length ? `When: ${neutral(it.body.trigger.join("; "))}\n` : "";
-            const not = it.body.doNotApplyWhen?.length ? `Do not apply when: ${neutral(it.body.doNotApplyWhen.join("; "))}\n` : "";
-            const verify = it.body.verification?.length ? `Verify: ${neutral(it.body.verification.join("; "))}\n` : "";
+            const list = (v) => Array.isArray(v) ? v.map(String) : typeof v === "string" && v ? [v] : [];
+            const steps = list(it.body?.procedure).map((s, j) => `  ${j + 1}. ${neutral(s)}`).join("\n");
+            const when = list(it.body?.trigger).length ? `When: ${neutral(list(it.body?.trigger).join("; "))}\n` : "";
+            const not = list(it.body?.doNotApplyWhen).length ? `Do not apply when: ${neutral(list(it.body?.doNotApplyWhen).join("; "))}\n` : "";
+            const verify = list(it.body?.verification).length ? `Verify: ${neutral(list(it.body?.verification).join("; "))}\n` : "";
             parts.push(`\n[${n}] SKILL ${provenanceLine(it)}\nTitle: ${neutral(it.title)}\n${neutral(it.body.summary)}\n${when}${not}Procedure:\n${steps}\n${verify}`.trimEnd());
         }
     });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cognia-sdk",
-  "version": "0.1.1",
+  "version": "0.1.3",
   "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",