@ay-2814/era-sdk 0.1.0

package/README.md

@@ -0,0 +1,53 @@
+# @season/era-sdk
+
+Drop-in cognitive context for any conversational AI agent. Zero runtime
+dependencies (uses global `fetch`).
+
+```bash
+npm install @season/era-sdk
+```
+
+## Quick start
+
+```ts
+import { Era } from "@season/era-sdk";
+
+const era = new Era({
+  apiKey: process.env.ERA_API_KEY!,
+  baseUrl: process.env.ERA_URL!,
+  partnerId: "your_partner_id",
+});
+
+const block = await era.turnContext(messages, { userId, sessionId });
+systemPrompt += "\n\n" + block;
+```
+
+For Vercel AI SDK auto-injection middleware, import `@season/era-sdk/ai-sdk`.
+
+## Modes & production behavior
+
+- `mode: "async"` (default) — stale-while-revalidate; instant response with the
+  previous turn's block. `mode: "sync"` waits for the current turn.
+- **Fail-open**: any error returns `""` — your agent never breaks.
+- **Bounded retries** on transient failures (timeout/network/5xx); `4xx` is
+  terminal. Configure with `maxRetries` (default 1).
+- **Timeouts**: 2s async / 30s sync, override with `timeoutMs`.
+- **Logging**: pass a `logger` (`{ warn, info }`) to integrate with pino/winston,
+  or `debug: true` for verbose per-turn console output. Warnings only by default.
+
+## Options
+
+| Option | Default | Notes |
+|--------|---------|-------|
+| `mode` | `"async"` | `"async"` \| `"sync"` |
+| `brandVoice` | — | words the `[REC]` action |
+| `timeoutMs` | 2000 / 30000 | per request |
+| `maxRetries` | 1 | transient-only |
+| `logger` / `debug` | console / false | observability |
+
+## Develop
+
+```bash
+npm run build   # tsc -> dist/
+npm test        # node --test
+```

package/dist/ai-sdk.d.ts

@@ -0,0 +1,4 @@
+import type { LanguageModel, LanguageModelMiddleware } from "ai";
+import type { Era, TurnContextOptions } from "./index.js";
+export declare function eraMiddleware(era: Era, options?: TurnContextOptions): LanguageModelMiddleware;
+export declare function withEra(model: LanguageModel, era: Era, options?: TurnContextOptions): LanguageModel;

package/dist/ai-sdk.js

@@ -0,0 +1,55 @@
+// @season/era-sdk/ai-sdk — Vercel AI SDK middleware. Auto-injects Era's
+// cognitive block into the system prompt on every model call.
+//
+// The whole integration:
+//
+//   import { Era } from "@season/era-sdk";
+//   import { withEra } from "@season/era-sdk/ai-sdk";
+//
+//   const era = new Era({ apiKey, baseUrl, partnerId });
+//   const model = withEra(anthropic("claude-sonnet-4-5"), era, { userId, sessionId });
+//
+//   // streamText/generateText through `model` now carry Era context automatically.
+import { wrapLanguageModel } from "ai";
+export function eraMiddleware(era, options = {}) {
+    // The middleware runs once per model invocation (steps, retries); log the
+    // final prompt only on the first injection so a single request prints once.
+    let loggedPrompt = false;
+    return {
+        specificationVersion: "v3",
+        transformParams: async ({ params }) => {
+            const prompt = params.prompt;
+            if (!Array.isArray(prompt))
+                return params;
+            const conversation = prompt.filter((m) => m.role === "user" || m.role === "assistant");
+            const block = await era.turnContext(conversation, options);
+            if (!block)
+                return params;
+            const newPrompt = [...prompt];
+            const sysIdx = newPrompt.findIndex((m) => m.role === "system");
+            if (sysIdx >= 0 && typeof newPrompt[sysIdx].content === "string") {
+                newPrompt[sysIdx] = {
+                    ...newPrompt[sysIdx],
+                    content: `${newPrompt[sysIdx].content}\n\n${block}`,
+                };
+            }
+            else {
+                newPrompt.unshift({ role: "system", content: block });
+            }
+            if (!loggedPrompt) {
+                loggedPrompt = true;
+                const sys = newPrompt.find((m) => m.role === "system");
+                const sysContent = typeof sys?.content === "string" ? sys.content : "";
+                console.log(`[era-sdk] system prompt sent to model (${sysContent.length} chars):\n--- BEGIN SYSTEM PROMPT ---\n${sysContent}\n--- END SYSTEM PROMPT ---`);
+            }
+            return { ...params, prompt: newPrompt };
+        },
+    };
+}
+export function withEra(model, era, options = {}) {
+    return wrapLanguageModel({
+        // biome-ignore lint/suspicious/noExplicitAny: wrapLanguageModel accepts provider model objects
+        model: model,
+        middleware: eraMiddleware(era, options),
+    });
+}

package/dist/index.d.ts

@@ -0,0 +1,55 @@
+export declare const VERSION = "0.1.0";
+export type EraMode = "sync" | "async";
+/** Minimal logger surface. Defaults to console; pass your own to integrate
+ *  with pino/winston, or `{ warn: () => {}, info: () => {} }` to silence. */
+export interface EraLogger {
+    warn: (msg: string) => void;
+    info: (msg: string) => void;
+}
+export interface EraOptions {
+    apiKey: string;
+    baseUrl: string;
+    partnerId: string;
+    userId?: string;
+    sessionId?: string;
+    /** "async" (default): instant response with the previous turn's block.
+     *  "sync": wait for the current turn's block — adds pipeline latency to every call. */
+    mode?: EraMode;
+    /** Partner brand voice — the phrasing layer words the [REC] action with it. */
+    brandVoice?: string;
+    /** Override the request timeout (ms). Defaults: 2000 async, 30000 sync. */
+    timeoutMs?: number;
+    /** Retries on transient failures (timeout/network/5xx). 4xx never retries. Default 1. */
+    maxRetries?: number;
+    /** Custom logger. Defaults to console.warn for warnings; info is silent unless `debug`. */
+    logger?: EraLogger;
+    /** When true (and no custom logger), per-turn info is logged to console. Default false. */
+    debug?: boolean;
+}
+export interface EraMessage {
+    role: string;
+    content: unknown;
+}
+export interface EraTurn {
+    role: "user" | "assistant";
+    turn_index: number;
+    text: string;
+}
+export interface TurnContextOptions {
+    userId?: string;
+    sessionId?: string;
+}
+export declare function messagesToTurns(messages: EraMessage[]): EraTurn[];
+export declare class Era {
+    private readonly opts;
+    private readonly log;
+    private lastTurn;
+    constructor(opts: EraOptions);
+    /**
+     * Get the cognitive block for the current turn. Returns "" on any failure
+     * (fail-open: your agent must never break because Era is unreachable).
+     * The last message must be from the user.
+     */
+    turnContext(messages: EraMessage[], options?: TurnContextOptions): Promise<string>;
+    private fetchTurn;
+}

package/dist/index.js

@@ -0,0 +1,150 @@
+// @season/era-sdk — provider-agnostic core. Zero runtime dependencies (global fetch).
+//
+// Usage with ANY framework:
+//
+//   import { Era } from "@season/era-sdk";
+//
+//   const era = new Era({
+//     apiKey: process.env.ERA_API_KEY!,
+//     baseUrl: process.env.ERA_URL!,
+//     partnerId: "your_partner_id",
+//   });
+//
+//   const block = await era.turnContext(messages, { userId, sessionId });
+//   systemPrompt += "\n\n" + block;   // inject wherever your stack puts system context
+//
+// For Vercel AI SDK auto-injection, see "@season/era-sdk/ai-sdk".
+export const VERSION = "0.1.0";
+const ERA_ASYNC_TIMEOUT_MS = 2000;
+// Sync mode waits for the full extraction pipeline (two LLM calls) before
+// responding, so it needs far more headroom than the async fast path.
+const ERA_SYNC_TIMEOUT_MS = 30000;
+const DEFAULT_MAX_RETRIES = 1;
+const RETRY_BACKOFF_BASE_MS = 100;
+function extractText(content) {
+    if (typeof content === "string")
+        return content;
+    if (Array.isArray(content)) {
+        return content
+            .filter((p) => typeof p === "object" && p !== null && p.type === "text")
+            .map((p) => p.text)
+            .join(" ");
+    }
+    return "";
+}
+export function messagesToTurns(messages) {
+    const turns = [];
+    let idx = 0;
+    for (const m of messages) {
+        if (m.role !== "user" && m.role !== "assistant")
+            continue;
+        const text = extractText(m.content);
+        if (!text.trim())
+            continue;
+        idx += 1;
+        turns.push({ role: m.role, turn_index: idx, text });
+    }
+    return turns;
+}
+async function defaultSessionId(turns) {
+    const firstUser = turns.find((t) => t.role === "user")?.text ?? "";
+    const digest = await crypto.subtle.digest("SHA-256", new TextEncoder().encode(firstUser));
+    const hex = Array.from(new Uint8Array(digest))
+        .map((b) => b.toString(16).padStart(2, "0"))
+        .join("");
+    return `sdk_${hex.slice(0, 16)}`;
+}
+const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+export class Era {
+    opts;
+    log;
+    // Memoizes the latest turn lookup. streamText invokes the middleware once
+    // per model call (steps, retries), so without this a single chat request
+    // pays one Era round-trip per invocation. Keyed by user/session/turn so a
+    // shared instance never serves another conversation's block.
+    lastTurn = null;
+    constructor(opts) {
+        const mode = opts.mode ?? "async";
+        if (mode !== "sync" && mode !== "async") {
+            throw new Error(`era-sdk: mode must be "sync" or "async", got "${mode}"`);
+        }
+        this.opts = { ...opts, baseUrl: opts.baseUrl.replace(/\/+$/, "") };
+        this.log =
+            opts.logger ?? {
+                warn: (m) => console.warn(`[era-sdk] ${m}`),
+                info: (m) => {
+                    if (opts.debug)
+                        console.log(`[era-sdk] ${m}`);
+                },
+            };
+    }
+    /**
+     * Get the cognitive block for the current turn. Returns "" on any failure
+     * (fail-open: your agent must never break because Era is unreachable).
+     * The last message must be from the user.
+     */
+    async turnContext(messages, options = {}) {
+        const turns = messagesToTurns(messages);
+        if (turns.length === 0 || turns[turns.length - 1].role !== "user")
+            return "";
+        const userId = options.userId ?? this.opts.userId ?? "anonymous";
+        const sessionId = options.sessionId ?? this.opts.sessionId ?? (await defaultSessionId(turns));
+        const key = `${userId}|${sessionId}|${turns[turns.length - 1].turn_index}`;
+        if (this.lastTurn?.key === key)
+            return this.lastTurn.block;
+        const block = this.fetchTurn(turns, userId, sessionId);
+        this.lastTurn = { key, block };
+        return block;
+    }
+    async fetchTurn(turns, userId, sessionId) {
+        const mode = this.opts.mode ?? "async";
+        const timeoutMs = this.opts.timeoutMs ?? (mode === "sync" ? ERA_SYNC_TIMEOUT_MS : ERA_ASYNC_TIMEOUT_MS);
+        const maxRetries = Math.max(0, this.opts.maxRetries ?? DEFAULT_MAX_RETRIES);
+        const body = JSON.stringify({
+            partner_id: this.opts.partnerId,
+            user_id: userId,
+            session_id: sessionId,
+            mode,
+            brand_voice: this.opts.brandVoice,
+            turns,
+        });
+        for (let attempt = 0; attempt <= maxRetries; attempt++) {
+            try {
+                const resp = await fetch(`${this.opts.baseUrl}/v1/era/turn`, {
+                    method: "POST",
+                    headers: { "Content-Type": "application/json", "X-API-Key": this.opts.apiKey },
+                    body,
+                    signal: AbortSignal.timeout(timeoutMs),
+                });
+                if (resp.ok) {
+                    const data = (await resp.json());
+                    const block = data.block ?? "";
+                    this.log.info(`block ${block ? "received" : "empty"} | mode=${mode} freshness=${data.freshness} chars=${block.length}`);
+                    return block;
+                }
+                if (resp.status >= 400 && resp.status < 500) {
+                    // Config/usage error — retrying won't help; fail open loudly.
+                    this.log.warn(`request rejected (${resp.status}), failing open`);
+                    return "";
+                }
+                // 5xx — transient; retry if budget remains.
+                if (attempt < maxRetries) {
+                    await sleep(RETRY_BACKOFF_BASE_MS * 2 ** attempt);
+                    continue;
+                }
+                this.log.warn(`server error ${resp.status}, failing open`);
+                return "";
+            }
+            catch (err) {
+                // Timeout / network error — transient; retry if budget remains.
+                if (attempt < maxRetries) {
+                    await sleep(RETRY_BACKOFF_BASE_MS * 2 ** attempt);
+                    continue;
+                }
+                this.log.warn(`unavailable, failing open: ${err instanceof Error ? err.message : err}`);
+                return "";
+            }
+        }
+        return "";
+    }
+}

package/package.json

@@ -0,0 +1,44 @@
+{
+	"name": "@ay-2814/era-sdk",
+	"version": "0.1.0",
+	"description": "Era cognitive context for any conversational AI agent",
+	"type": "module",
+	"exports": {
+		".": {
+			"types": "./dist/index.d.ts",
+			"default": "./dist/index.js"
+		},
+		"./ai-sdk": {
+			"types": "./dist/ai-sdk.d.ts",
+			"default": "./dist/ai-sdk.js"
+		}
+	},
+	"license": "UNLICENSED",
+	"files": [
+		"dist"
+	],
+	"engines": {
+		"node": ">=18"
+	},
+	"sideEffects": false,
+	"publishConfig": {
+		"access": "public"
+	},
+	"scripts": {
+		"build": "tsc -p tsconfig.build.json",
+		"test": "node --test \"test/*.test.mjs\"",
+		"prepublishOnly": "npm run build && npm test"
+	},
+	"peerDependencies": {
+		"ai": ">=5"
+	},
+	"peerDependenciesMeta": {
+		"ai": {
+			"optional": true
+		}
+	},
+	"devDependencies": {
+		"ai": "^6.0.116",
+		"typescript": "^5.9.0"
+	}
+}