@sonzai-labs/openclaw-context 1.0.0

package/dist/index.d.ts

@@ -0,0 +1,282 @@
+import { Sonzai, PersonalityResponse, MoodResponse, RelationshipResponse, MemorySearchResponse, GoalsResponse, InterestsResponse, HabitsResponse } from '@sonzai-labs/agents';
+
+/**
+ * OpenClaw ContextEngine plugin interfaces.
+ *
+ * Defined locally via structural typing — no OpenClaw import required.
+ * OpenClaw uses duck-typing for plugin registration.
+ */
+interface ContextEngineInfo {
+    id: string;
+    name: string;
+    ownsCompaction: boolean;
+}
+interface MessageItem {
+    role: string;
+    content: string;
+}
+interface MessageOrigin {
+    label?: string;
+    provider?: string;
+    from?: string;
+    to?: string;
+    accountId?: string;
+    threadId?: string;
+    senderName?: string;
+}
+interface BootstrapArgs {
+    sessionId: string;
+}
+interface IngestArgs {
+    sessionId: string;
+    message: MessageItem;
+    isHeartbeat: boolean;
+    origin?: MessageOrigin;
+}
+interface AssembleArgs {
+    sessionId: string;
+    messages: MessageItem[];
+    tokenBudget: number;
+    origin?: MessageOrigin;
+}
+interface AssembleResult {
+    messages: MessageItem[];
+    estimatedTokens: number;
+    systemPromptAddition?: string;
+}
+interface CompactArgs {
+    sessionId: string;
+    force: boolean;
+}
+interface CompactResult {
+    ok: boolean;
+    compacted: boolean;
+}
+interface AfterTurnArgs {
+    sessionId: string;
+    origin?: MessageOrigin;
+}
+interface ContextEngine {
+    info: ContextEngineInfo;
+    bootstrap(args: BootstrapArgs): Promise<void>;
+    ingest(args: IngestArgs): Promise<{
+        ingested: boolean;
+    }>;
+    assemble(args: AssembleArgs): Promise<AssembleResult>;
+    compact(args: CompactArgs): Promise<CompactResult>;
+    afterTurn(args: AfterTurnArgs): Promise<void>;
+    dispose(): Promise<void>;
+}
+interface PluginAPI {
+    registerContextEngine(id: string, factory: () => ContextEngine): void;
+}
+interface SessionState {
+    agentId: string;
+    userId: string;
+    sonzaiSessionId: string;
+    startedAt: number;
+    turnCount: number;
+    lastProcessedIndex: number;
+    lastMessages: MessageItem[];
+}
+
+/**
+ * OpenClaw plugin entry point.
+ *
+ * Registers the "sonzai" ContextEngine with OpenClaw's plugin system.
+ */
+
+declare function register(api: PluginAPI): void;
+
+/**
+ * Plugin configuration — maps to `plugins.entries.sonzai` in openclaw.json
+ * or environment variables.
+ */
+interface DisableMap {
+    mood?: boolean;
+    personality?: boolean;
+    relationships?: boolean;
+    memory?: boolean;
+    goals?: boolean;
+    interests?: boolean;
+    habits?: boolean;
+}
+interface SonzaiPluginConfig {
+    /** Sonzai API key (sk-...). Required. */
+    apiKey: string;
+    /** Pre-provisioned agent UUID. If omitted, auto-provisions from agentName. */
+    agentId?: string;
+    /** Base URL override (e.g. for staging). Defaults to https://api.sonz.ai */
+    baseUrl?: string;
+    /**
+     * Agent name for auto-provisioning. The backend derives a deterministic
+     * UUID from (tenantID + lowercase(name)), so the same API key + same name
+     * always maps to the same agent — no duplicates across restarts.
+     *
+     * IMPORTANT for B2B: if multiple OpenClaw instances share one API key,
+     * each needs a unique agentName to get its own Sonzai agent.
+     * Defaults to "openclaw-agent".
+     */
+    agentName?: string;
+    /** Default userId when session key has no peer identity (CLI 1:1). Defaults to "owner". */
+    defaultUserId?: string;
+    /** Max tokens for Sonzai context injection. Defaults to 2000. */
+    contextTokenBudget?: number;
+    /** Selectively disable context sources. */
+    disable?: DisableMap;
+    /** LLM provider for side-effect extraction (e.g. "gemini", "openai"). Uses platform default if omitted. */
+    extractionProvider?: string;
+    /** LLM model for side-effect extraction (e.g. "gemini-2.5-flash"). Uses platform default if omitted. */
+    extractionModel?: string;
+}
+interface ResolvedConfig {
+    apiKey: string;
+    agentId: string | undefined;
+    baseUrl: string;
+    agentName: string;
+    defaultUserId: string;
+    contextTokenBudget: number;
+    disable: DisableMap;
+    extractionProvider: string | undefined;
+    extractionModel: string | undefined;
+}
+/**
+ * Resolve configuration from explicit config, then fall back to env vars.
+ */
+declare function resolveConfig(raw?: Partial<SonzaiPluginConfig>): ResolvedConfig;
+
+/**
+ * SonzaiContextEngine — bridges OpenClaw lifecycle hooks to the
+ * Sonzai Mind Layer API via @sonzai-labs/agents.
+ */
+
+declare class SonzaiContextEngine implements ContextEngine {
+    private readonly client;
+    private readonly config;
+    readonly info: ContextEngineInfo;
+    private readonly sessions;
+    private readonly agentCache;
+    constructor(client: Sonzai, config: ResolvedConfig);
+    bootstrap({ sessionId }: BootstrapArgs): Promise<void>;
+    ingest(_args: IngestArgs): Promise<{
+        ingested: boolean;
+    }>;
+    assemble({ sessionId, messages, tokenBudget, origin, }: AssembleArgs): Promise<AssembleResult>;
+    compact({ sessionId }: CompactArgs): Promise<CompactResult>;
+    afterTurn({ sessionId }: AfterTurnArgs): Promise<void>;
+    dispose(): Promise<void>;
+    /**
+     * Resolve the Sonzai agent ID: use config if provided, otherwise
+     * auto-provision via the idempotent create endpoint.
+     *
+     * Idempotency guarantee: the backend derives a deterministic UUID v5 from
+     * `SHA1(namespace, tenantID + "/" + lowercase(name))`. Same API key (tenant)
+     * + same name → same UUID on every call, even across restarts or pod
+     * replacements.
+     *
+     * The name used is always `config.agentName` (default: "openclaw-agent").
+     * This is stable because it comes from the plugin config / env var, not
+     * from any runtime state like pod IDs or session UUIDs.
+     *
+     * If a B2B client needs multiple distinct agents under one API key, they
+     * set a unique `agentName` per OpenClaw instance in their config.
+     */
+    private resolveAgentId;
+}
+
+/**
+ * Extracts user identity from OpenClaw session keys.
+ *
+ * Session key formats:
+ *   CLI 1:1     — agent:<agentId>:<mainKey>
+ *   DM          — agent:<agentId>:<channel>:direct:<peerId>
+ *   Group       — agent:<agentId>:<channel>:group:<groupId>
+ *   Cron        — cron:<jobId>
+ *   Webhook     — hook:<uuid>
+ */
+interface ParsedSessionKey {
+    /** The agentId segment from the session key (may differ from configured agentId). */
+    agentId: string | null;
+    /** Resolved userId for Sonzai SDK calls. */
+    userId: string;
+    /** Channel identifier (e.g. "telegram", "discord"), if present. */
+    channel: string | null;
+    /** How this session was identified. */
+    sessionType: "cli" | "dm" | "group" | "cron" | "webhook" | "unknown";
+}
+declare function parseSessionKey(sessionId: string, defaultUserId: string): ParsedSessionKey;
+
+/**
+ * Transforms Sonzai API responses into a formatted systemPromptAddition
+ * string for OpenClaw context injection.
+ */
+
+interface ContextSources {
+    personality?: PersonalityResponse;
+    mood?: MoodResponse;
+    relationships?: RelationshipResponse;
+    memories?: MemorySearchResponse;
+    goals?: GoalsResponse;
+    interests?: InterestsResponse;
+    habits?: HabitsResponse;
+}
+/**
+ * Build the systemPromptAddition from all available context sources.
+ * Returns an empty string if no data is available.
+ */
+declare function buildSystemPromptAddition(sources: ContextSources, tokenBudget: number): string;
+/**
+ * Rough token estimate: ~4 chars per token, erring on overestimation.
+ */
+declare function estimateTokens(text: string): number;
+
+/**
+ * Lightweight in-memory TTL cache.
+ *
+ * Used to avoid re-fetching slow-changing data (personality, agent profile)
+ * on every assemble() call.
+ */
+declare class SessionCache<T> {
+    private readonly ttlMs;
+    private readonly store;
+    constructor(ttlMs: number);
+    get(key: string): T | undefined;
+    set(key: string, value: T): void;
+    delete(key: string): void;
+    clear(): void;
+}
+
+/**
+ * Interactive and programmatic setup for the Sonzai OpenClaw plugin.
+ *
+ * Interactive:  `npx @sonzai-labs/openclaw-context setup`
+ * Programmatic: `import { setup } from "@sonzai-labs/openclaw-context"`
+ */
+interface SetupOptions {
+    /** Sonzai API key. */
+    apiKey: string;
+    /** Agent name (deterministic ID derived from tenant + name). */
+    agentName?: string;
+    /** Pre-existing agent ID (skips agent provisioning). */
+    agentId?: string;
+    /** Base URL override. */
+    baseUrl?: string;
+    /** Path to openclaw.json. Defaults to ./openclaw.json */
+    configPath?: string;
+    /** If true, writes to openclaw.json. If false, returns config object only. */
+    writeConfig?: boolean;
+}
+interface SetupResult {
+    agentId: string;
+    agentName: string;
+    config: Record<string, unknown>;
+    configPath?: string;
+    written: boolean;
+}
+/**
+ * Programmatic setup — validates API key, provisions agent, optionally
+ * writes openclaw.json. Designed for B2B automation scripts.
+ */
+declare function setup(options: SetupOptions): Promise<SetupResult>;
+
+export { type AfterTurnArgs, type AssembleArgs, type AssembleResult, type BootstrapArgs, type CompactArgs, type CompactResult, type ContextEngine, type ContextEngineInfo, type ContextSources, type DisableMap, type IngestArgs, type MessageItem, type MessageOrigin, type ParsedSessionKey, type PluginAPI, type ResolvedConfig, SessionCache, type SessionState, type SetupOptions, type SetupResult, SonzaiContextEngine, type SonzaiPluginConfig, buildSystemPromptAddition, register as default, estimateTokens, parseSessionKey, resolveConfig, setup };