@z3rno/sdk 0.4.0 → 0.5.0

package/dist/index.d.cts

@@ -989,6 +989,120 @@ declare const RefineJobStatusResponse: z.ZodObject<{
     job_metadata?: Record<string, unknown> | undefined;
 }>;
 type RefineJobStatusResponse = z.infer<typeof RefineJobStatusResponse>;
+/** Conversation metadata. */
+declare const ConversationResponse: z.ZodObject<{
+    id: z.ZodString;
+    agent_id: z.ZodString;
+    user_id: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    title: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    summary_cadence: z.ZodNumber;
+    turn_count: z.ZodNumber;
+    last_summary_turn: z.ZodNumber;
+    metadata: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+    created_at: z.ZodString;
+    updated_at: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    metadata: Record<string, unknown>;
+    id: string;
+    agent_id: string;
+    created_at: string;
+    updated_at: string;
+    summary_cadence: number;
+    turn_count: number;
+    last_summary_turn: number;
+    user_id?: string | null | undefined;
+    title?: string | null | undefined;
+}, {
+    id: string;
+    agent_id: string;
+    created_at: string;
+    updated_at: string;
+    summary_cadence: number;
+    turn_count: number;
+    last_summary_turn: number;
+    metadata?: Record<string, unknown> | undefined;
+    user_id?: string | null | undefined;
+    title?: string | null | undefined;
+}>;
+type ConversationResponse = z.infer<typeof ConversationResponse>;
+/** Result of POST /v1/conversations/{id}/turns. */
+declare const TurnAddResponse: z.ZodObject<{
+    turn_index: z.ZodNumber;
+    needs_summary: z.ZodBoolean;
+}, "strip", z.ZodTypeAny, {
+    turn_index: number;
+    needs_summary: boolean;
+}, {
+    turn_index: number;
+    needs_summary: boolean;
+}>;
+type TurnAddResponse = z.infer<typeof TurnAddResponse>;
+/** One turn within a conversation. */
+declare const TurnResponse: z.ZodObject<{
+    memory_id: z.ZodString;
+    turn_index: z.ZodNumber;
+    turn_role: z.ZodString;
+    content: z.ZodString;
+    created_at: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    content: string;
+    created_at: string;
+    memory_id: string;
+    turn_index: number;
+    turn_role: string;
+}, {
+    content: string;
+    created_at: string;
+    memory_id: string;
+    turn_index: number;
+    turn_role: string;
+}>;
+type TurnResponse = z.infer<typeof TurnResponse>;
+/** Paginated turn list. */
+declare const TurnListResponse: z.ZodObject<{
+    turns: z.ZodArray<z.ZodObject<{
+        memory_id: z.ZodString;
+        turn_index: z.ZodNumber;
+        turn_role: z.ZodString;
+        content: z.ZodString;
+        created_at: z.ZodString;
+    }, "strip", z.ZodTypeAny, {
+        content: string;
+        created_at: string;
+        memory_id: string;
+        turn_index: number;
+        turn_role: string;
+    }, {
+        content: string;
+        created_at: string;
+        memory_id: string;
+        turn_index: number;
+        turn_role: string;
+    }>, "many">;
+    total: z.ZodNumber;
+    conversation_id: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    total: number;
+    turns: {
+        content: string;
+        created_at: string;
+        memory_id: string;
+        turn_index: number;
+        turn_role: string;
+    }[];
+    conversation_id: string;
+}, {
+    total: number;
+    turns: {
+        content: string;
+        created_at: string;
+        memory_id: string;
+        turn_index: number;
+        turn_role: string;
+    }[];
+    conversation_id: string;
+}>;
+type TurnListResponse = z.infer<typeof TurnListResponse>;
 
 /**
  * Z3rno TypeScript SDK client.
@@ -1197,6 +1311,11 @@ declare class Z3rnoClient {
          * `sentence-transformers` on the server side.
          */
         rerank?: boolean;
+        /**
+         * Phase G slice 2: scope recall to a single conversation. Older
+         * servers ignore the field.
+         */
+        conversationId?: string;
     }): Promise<RecallResponse>;
     /**
      * Forgets (deletes) one or more memories.
@@ -1418,6 +1537,33 @@ declare class Z3rnoClient {
         datasetId?: string;
     }): Promise<RefineJobResponse>;
     getRefineStatus(jobId: string): Promise<RefineJobStatusResponse>;
+    /**
+     * Open a new conversation. Returns the conversation row including
+     * the assigned `id`, which subsequent `recall`s and `addTurn`s
+     * reference. The `summaryCadence` controls how often the server
+     * flags the conversation for summarization.
+     */
+    createConversation(params: {
+        agentId: string;
+        userId?: string;
+        title?: string;
+        summaryCadence?: number;
+        metadata?: Record<string, unknown>;
+    }): Promise<ConversationResponse>;
+    getConversation(conversationId: string): Promise<ConversationResponse>;
+    /**
+     * Stamp an existing Memo as the next turn of the conversation.
+     * Returns the assigned `turn_index` plus `needs_summary` — when
+     * `true`, the conversation has crossed its cadence threshold.
+     */
+    addTurn(conversationId: string, params: {
+        memoryId: string;
+        turnRole: string;
+    }): Promise<TurnAddResponse>;
+    listTurns(conversationId: string, params?: {
+        afterTurn?: number;
+        limit?: number;
+    }): Promise<TurnListResponse>;
     private request;
     private sleep;
     private handleResponse;
@@ -1622,4 +1768,107 @@ declare class Z3rnoConnectionError extends Z3rnoError {
     constructor(message: string);
 }
 
-export { AuditEntry, AuditPageResponse, AuthenticationError, BatchStoreResponse, DistillJobResponse, DistillJobStatusResponse, EndSessionResponse, ForgetResponse, IngestJobResponse, IngestJobStatusResponse, MemoryHistoryResponse, MemoryResponse, MemoryType, MemoryVersion, NotFoundError, RateLimitError, RecallResponse, RecallResultItem, RefineJobResponse, RefineJobStatusResponse, RelationshipType, RetrievalStrategy, ServerError, SessionResponse, StoreMemoryRequest, ValidationError, Z3rnoClient, type Z3rnoClientConfig, Z3rnoConnectionError, Z3rnoError, Z3rnoTimeoutError };
+/**
+ * Vercel AI SDK adapter for Z3rno (Phase G slice 3).
+ *
+ * Vercel AI SDK accepts a plain `CoreMessage[]` history; this adapter
+ * loads + persists that history through Z3rno conversations. Drop the
+ * `messages` accessor straight into `streamText` / `generateText`,
+ * call `appendUserMessage` / `appendAssistantMessage` after each turn,
+ * and Z3rno handles ordering + recall.
+ *
+ * Zero hard dependency on the `ai` package — we duck-type on the
+ * minimal `CoreMessage` shape (`{ role, content }`).
+ */
+
+type Z3rnoMessageRole = "user" | "assistant" | "system" | "tool";
+/** Subset of Vercel `ai` `CoreMessage` the adapter needs. */
+interface CoreMessage {
+    role: Z3rnoMessageRole;
+    content: string;
+}
+interface Z3rnoVercelMemoryOptions {
+    client: Z3rnoClient;
+    agentId: string;
+    /** When set, recall + persisted turns are scoped to this Z3rno conversation. */
+    conversationId?: string;
+    /** Max history slice to load. Default 50. */
+    topK?: number;
+}
+/**
+ * Lightweight history adapter you can hand straight to Vercel AI SDK
+ * helpers. `await mem.messages()` returns a CoreMessage[] ready to
+ * pass to `streamText({ messages: ... })`. After each turn, call
+ * `appendUserMessage` / `appendAssistantMessage` so future recalls
+ * see the latest state.
+ */
+declare class Z3rnoVercelMemory {
+    private readonly client;
+    private readonly agentId;
+    private readonly conversationId;
+    private readonly topK;
+    constructor(options: Z3rnoVercelMemoryOptions);
+    messages(): Promise<CoreMessage[]>;
+    appendUserMessage(content: string): Promise<void>;
+    appendAssistantMessage(content: string): Promise<void>;
+    appendToolMessage(content: string): Promise<void>;
+    private append;
+    private normaliseRole;
+}
+
+/**
+ * Mastra adapter for Z3rno (Phase G slice 3).
+ *
+ * Mastra exposes a `MastraMemory`-shaped interface — see
+ * https://mastra.ai/docs/agents/memory. This adapter implements
+ * the same surface (`getMessages` / `addMessage` / `clear`) using
+ * Z3rno conversations as the backing store.
+ *
+ * Zero hard dependency on the `@mastra/core` package — we provide
+ * the typed surface and Mastra's runtime accepts any conforming
+ * object.
+ */
+
+type MastraRole = "user" | "assistant" | "system" | "tool";
+interface MastraMessage {
+    role: MastraRole;
+    content: string;
+    threadId?: string;
+    resourceId?: string;
+}
+interface Z3rnoMastraMemoryOptions {
+    client: Z3rnoClient;
+    agentId: string;
+    /** Mastra's thread is Z3rno's conversation; supply or look up by threadId. */
+    conversationId?: string;
+    topK?: number;
+}
+/**
+ * Mastra-compatible memory backed by Z3rno conversations. Plug into
+ * a Mastra `Agent`:
+ *
+ *   const memory = new Z3rnoMastraMemory({ client, agentId, conversationId });
+ *   const agent = new Agent({ name: "support", memory });
+ */
+declare class Z3rnoMastraMemory {
+    private readonly client;
+    private readonly agentId;
+    private readonly conversationId;
+    private readonly topK;
+    constructor(options: Z3rnoMastraMemoryOptions);
+    /** Mastra contract: return ordered prior messages for the thread. */
+    getMessages(_args?: {
+        limit?: number;
+    }): Promise<MastraMessage[]>;
+    /** Mastra contract: persist one message. */
+    addMessage(message: MastraMessage): Promise<void>;
+    /**
+     * Mastra `clear()` — deliberate no-op. Z3rno keeps the source of
+     * truth and recall is already scoped per conversation; flushing
+     * the thread would risk losing audit-relevant history.
+     */
+    clear(): Promise<void>;
+    private normaliseRole;
+}
+
+export { AuditEntry, AuditPageResponse, AuthenticationError, BatchStoreResponse, ConversationResponse, type CoreMessage, DistillJobResponse, DistillJobStatusResponse, EndSessionResponse, ForgetResponse, IngestJobResponse, IngestJobStatusResponse, type MastraMessage, type MastraRole, MemoryHistoryResponse, MemoryResponse, MemoryType, MemoryVersion, NotFoundError, RateLimitError, RecallResponse, RecallResultItem, RefineJobResponse, RefineJobStatusResponse, RelationshipType, RetrievalStrategy, ServerError, SessionResponse, StoreMemoryRequest, TurnAddResponse, TurnListResponse, TurnResponse, ValidationError, Z3rnoClient, type Z3rnoClientConfig, Z3rnoConnectionError, Z3rnoError, Z3rnoMastraMemory, type Z3rnoMastraMemoryOptions, type Z3rnoMessageRole, Z3rnoTimeoutError, Z3rnoVercelMemory, type Z3rnoVercelMemoryOptions };

package/dist/index.d.ts

@@ -989,6 +989,120 @@ declare const RefineJobStatusResponse: z.ZodObject<{
     job_metadata?: Record<string, unknown> | undefined;
 }>;
 type RefineJobStatusResponse = z.infer<typeof RefineJobStatusResponse>;
+/** Conversation metadata. */
+declare const ConversationResponse: z.ZodObject<{
+    id: z.ZodString;
+    agent_id: z.ZodString;
+    user_id: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    title: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    summary_cadence: z.ZodNumber;
+    turn_count: z.ZodNumber;
+    last_summary_turn: z.ZodNumber;
+    metadata: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+    created_at: z.ZodString;
+    updated_at: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    metadata: Record<string, unknown>;
+    id: string;
+    agent_id: string;
+    created_at: string;
+    updated_at: string;
+    summary_cadence: number;
+    turn_count: number;
+    last_summary_turn: number;
+    user_id?: string | null | undefined;
+    title?: string | null | undefined;
+}, {
+    id: string;
+    agent_id: string;
+    created_at: string;
+    updated_at: string;
+    summary_cadence: number;
+    turn_count: number;
+    last_summary_turn: number;
+    metadata?: Record<string, unknown> | undefined;
+    user_id?: string | null | undefined;
+    title?: string | null | undefined;
+}>;
+type ConversationResponse = z.infer<typeof ConversationResponse>;
+/** Result of POST /v1/conversations/{id}/turns. */
+declare const TurnAddResponse: z.ZodObject<{
+    turn_index: z.ZodNumber;
+    needs_summary: z.ZodBoolean;
+}, "strip", z.ZodTypeAny, {
+    turn_index: number;
+    needs_summary: boolean;
+}, {
+    turn_index: number;
+    needs_summary: boolean;
+}>;
+type TurnAddResponse = z.infer<typeof TurnAddResponse>;
+/** One turn within a conversation. */
+declare const TurnResponse: z.ZodObject<{
+    memory_id: z.ZodString;
+    turn_index: z.ZodNumber;
+    turn_role: z.ZodString;
+    content: z.ZodString;
+    created_at: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    content: string;
+    created_at: string;
+    memory_id: string;
+    turn_index: number;
+    turn_role: string;
+}, {
+    content: string;
+    created_at: string;
+    memory_id: string;
+    turn_index: number;
+    turn_role: string;
+}>;
+type TurnResponse = z.infer<typeof TurnResponse>;
+/** Paginated turn list. */
+declare const TurnListResponse: z.ZodObject<{
+    turns: z.ZodArray<z.ZodObject<{
+        memory_id: z.ZodString;
+        turn_index: z.ZodNumber;
+        turn_role: z.ZodString;
+        content: z.ZodString;
+        created_at: z.ZodString;
+    }, "strip", z.ZodTypeAny, {
+        content: string;
+        created_at: string;
+        memory_id: string;
+        turn_index: number;
+        turn_role: string;
+    }, {
+        content: string;
+        created_at: string;
+        memory_id: string;
+        turn_index: number;
+        turn_role: string;
+    }>, "many">;
+    total: z.ZodNumber;
+    conversation_id: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    total: number;
+    turns: {
+        content: string;
+        created_at: string;
+        memory_id: string;
+        turn_index: number;
+        turn_role: string;
+    }[];
+    conversation_id: string;
+}, {
+    total: number;
+    turns: {
+        content: string;
+        created_at: string;
+        memory_id: string;
+        turn_index: number;
+        turn_role: string;
+    }[];
+    conversation_id: string;
+}>;
+type TurnListResponse = z.infer<typeof TurnListResponse>;
 
 /**
  * Z3rno TypeScript SDK client.
@@ -1197,6 +1311,11 @@ declare class Z3rnoClient {
          * `sentence-transformers` on the server side.
          */
         rerank?: boolean;
+        /**
+         * Phase G slice 2: scope recall to a single conversation. Older
+         * servers ignore the field.
+         */
+        conversationId?: string;
     }): Promise<RecallResponse>;
     /**
      * Forgets (deletes) one or more memories.
@@ -1418,6 +1537,33 @@ declare class Z3rnoClient {
         datasetId?: string;
     }): Promise<RefineJobResponse>;
     getRefineStatus(jobId: string): Promise<RefineJobStatusResponse>;
+    /**
+     * Open a new conversation. Returns the conversation row including
+     * the assigned `id`, which subsequent `recall`s and `addTurn`s
+     * reference. The `summaryCadence` controls how often the server
+     * flags the conversation for summarization.
+     */
+    createConversation(params: {
+        agentId: string;
+        userId?: string;
+        title?: string;
+        summaryCadence?: number;
+        metadata?: Record<string, unknown>;
+    }): Promise<ConversationResponse>;
+    getConversation(conversationId: string): Promise<ConversationResponse>;
+    /**
+     * Stamp an existing Memo as the next turn of the conversation.
+     * Returns the assigned `turn_index` plus `needs_summary` — when
+     * `true`, the conversation has crossed its cadence threshold.
+     */
+    addTurn(conversationId: string, params: {
+        memoryId: string;
+        turnRole: string;
+    }): Promise<TurnAddResponse>;
+    listTurns(conversationId: string, params?: {
+        afterTurn?: number;
+        limit?: number;
+    }): Promise<TurnListResponse>;
     private request;
     private sleep;
     private handleResponse;
@@ -1622,4 +1768,107 @@ declare class Z3rnoConnectionError extends Z3rnoError {
     constructor(message: string);
 }
 
-export { AuditEntry, AuditPageResponse, AuthenticationError, BatchStoreResponse, DistillJobResponse, DistillJobStatusResponse, EndSessionResponse, ForgetResponse, IngestJobResponse, IngestJobStatusResponse, MemoryHistoryResponse, MemoryResponse, MemoryType, MemoryVersion, NotFoundError, RateLimitError, RecallResponse, RecallResultItem, RefineJobResponse, RefineJobStatusResponse, RelationshipType, RetrievalStrategy, ServerError, SessionResponse, StoreMemoryRequest, ValidationError, Z3rnoClient, type Z3rnoClientConfig, Z3rnoConnectionError, Z3rnoError, Z3rnoTimeoutError };
+/**
+ * Vercel AI SDK adapter for Z3rno (Phase G slice 3).
+ *
+ * Vercel AI SDK accepts a plain `CoreMessage[]` history; this adapter
+ * loads + persists that history through Z3rno conversations. Drop the
+ * `messages` accessor straight into `streamText` / `generateText`,
+ * call `appendUserMessage` / `appendAssistantMessage` after each turn,
+ * and Z3rno handles ordering + recall.
+ *
+ * Zero hard dependency on the `ai` package — we duck-type on the
+ * minimal `CoreMessage` shape (`{ role, content }`).
+ */
+
+type Z3rnoMessageRole = "user" | "assistant" | "system" | "tool";
+/** Subset of Vercel `ai` `CoreMessage` the adapter needs. */
+interface CoreMessage {
+    role: Z3rnoMessageRole;
+    content: string;
+}
+interface Z3rnoVercelMemoryOptions {
+    client: Z3rnoClient;
+    agentId: string;
+    /** When set, recall + persisted turns are scoped to this Z3rno conversation. */
+    conversationId?: string;
+    /** Max history slice to load. Default 50. */
+    topK?: number;
+}
+/**
+ * Lightweight history adapter you can hand straight to Vercel AI SDK
+ * helpers. `await mem.messages()` returns a CoreMessage[] ready to
+ * pass to `streamText({ messages: ... })`. After each turn, call
+ * `appendUserMessage` / `appendAssistantMessage` so future recalls
+ * see the latest state.
+ */
+declare class Z3rnoVercelMemory {
+    private readonly client;
+    private readonly agentId;
+    private readonly conversationId;
+    private readonly topK;
+    constructor(options: Z3rnoVercelMemoryOptions);
+    messages(): Promise<CoreMessage[]>;
+    appendUserMessage(content: string): Promise<void>;
+    appendAssistantMessage(content: string): Promise<void>;
+    appendToolMessage(content: string): Promise<void>;
+    private append;
+    private normaliseRole;
+}
+
+/**
+ * Mastra adapter for Z3rno (Phase G slice 3).
+ *
+ * Mastra exposes a `MastraMemory`-shaped interface — see
+ * https://mastra.ai/docs/agents/memory. This adapter implements
+ * the same surface (`getMessages` / `addMessage` / `clear`) using
+ * Z3rno conversations as the backing store.
+ *
+ * Zero hard dependency on the `@mastra/core` package — we provide
+ * the typed surface and Mastra's runtime accepts any conforming
+ * object.
+ */
+
+type MastraRole = "user" | "assistant" | "system" | "tool";
+interface MastraMessage {
+    role: MastraRole;
+    content: string;
+    threadId?: string;
+    resourceId?: string;
+}
+interface Z3rnoMastraMemoryOptions {
+    client: Z3rnoClient;
+    agentId: string;
+    /** Mastra's thread is Z3rno's conversation; supply or look up by threadId. */
+    conversationId?: string;
+    topK?: number;
+}
+/**
+ * Mastra-compatible memory backed by Z3rno conversations. Plug into
+ * a Mastra `Agent`:
+ *
+ *   const memory = new Z3rnoMastraMemory({ client, agentId, conversationId });
+ *   const agent = new Agent({ name: "support", memory });
+ */
+declare class Z3rnoMastraMemory {
+    private readonly client;
+    private readonly agentId;
+    private readonly conversationId;
+    private readonly topK;
+    constructor(options: Z3rnoMastraMemoryOptions);
+    /** Mastra contract: return ordered prior messages for the thread. */
+    getMessages(_args?: {
+        limit?: number;
+    }): Promise<MastraMessage[]>;
+    /** Mastra contract: persist one message. */
+    addMessage(message: MastraMessage): Promise<void>;
+    /**
+     * Mastra `clear()` — deliberate no-op. Z3rno keeps the source of
+     * truth and recall is already scoped per conversation; flushing
+     * the thread would risk losing audit-relevant history.
+     */
+    clear(): Promise<void>;
+    private normaliseRole;
+}
+
+export { AuditEntry, AuditPageResponse, AuthenticationError, BatchStoreResponse, ConversationResponse, type CoreMessage, DistillJobResponse, DistillJobStatusResponse, EndSessionResponse, ForgetResponse, IngestJobResponse, IngestJobStatusResponse, type MastraMessage, type MastraRole, MemoryHistoryResponse, MemoryResponse, MemoryType, MemoryVersion, NotFoundError, RateLimitError, RecallResponse, RecallResultItem, RefineJobResponse, RefineJobStatusResponse, RelationshipType, RetrievalStrategy, ServerError, SessionResponse, StoreMemoryRequest, TurnAddResponse, TurnListResponse, TurnResponse, ValidationError, Z3rnoClient, type Z3rnoClientConfig, Z3rnoConnectionError, Z3rnoError, Z3rnoMastraMemory, type Z3rnoMastraMemoryOptions, type Z3rnoMessageRole, Z3rnoTimeoutError, Z3rnoVercelMemory, type Z3rnoVercelMemoryOptions };