@firststep-studio/sdk 0.10.0 → 0.11.0

package/dist/index.d.mts

@@ -1,5 +1,5 @@
-import { C as ChatMessage, S as SchemaDeclarationPayload, P as ProtocolStreamChunk, A as AgentTransitionPayload, R as RoutingClassificationPayload, H as HandoffRequestPayload, a as HandoffReturnPayload, b as HandoffOfferPayload } from './types-GoTI_c14.mjs';
-export { O as AnalyticsContext, E as ChatbotInfo, F as ClassifierConfig, D as DeploymentInfo, G as FormData, V as FormFieldDefinition, W as FormFieldType, J as FormFieldValue, U as FormSchema, n as HandlerInfo, _ as HandoffContext, f as HandoffInboundContext, $ as HandoffOptions, x as Helpline, w as HelplineResult, v as HelplineSearchOptions, I as IntegrationContext, u as IntegrationResult, Q as InteractionEvent, T as InteractionEventType, t as KnowledgeColumnMetadata, K as KnowledgeContext, s as KnowledgeMetadata, r as KnowledgeResult, L as LoggerContext, m as ProtocolCapabilities, o as ProtocolContext, k as ProtocolError, j as ProtocolFieldValidation, g as ProtocolForm, h as ProtocolFormField, i as ProtocolFormOption, l as ProtocolHandler, X as ProtocolRegistration, c as ProtocolRequest, d as ProtocolResponse, B as RoutingDecision, M as RoutingLog, Y as SchemaAgent, Z as SchemaQuestion, p as SessionContext, N as SessionMetadata, q as SessionState, e as SessionStatus, y as StorageContext, z as StorageSetOptions } from './types-GoTI_c14.mjs';
+import { C as ChatMessage, S as SchemaDeclarationPayload, P as ProtocolStreamChunk, A as AgentTransitionPayload, R as RoutingClassificationPayload, H as HandoffRequestPayload, a as HandoffReturnPayload, b as HandoffOfferPayload } from './types-DYJ44S2E.mjs';
+export { O as AnalyticsContext, E as ChatbotInfo, F as ClassifierConfig, D as DeploymentInfo, G as FormData, V as FormFieldDefinition, W as FormFieldType, J as FormFieldValue, U as FormSchema, n as HandlerInfo, _ as HandoffContext, f as HandoffInboundContext, $ as HandoffOptions, x as Helpline, w as HelplineResult, v as HelplineSearchOptions, I as IntegrationContext, u as IntegrationResult, Q as InteractionEvent, T as InteractionEventType, t as KnowledgeColumnMetadata, K as KnowledgeContext, s as KnowledgeMetadata, r as KnowledgeResult, L as LoggerContext, m as ProtocolCapabilities, o as ProtocolContext, k as ProtocolError, j as ProtocolFieldValidation, g as ProtocolForm, h as ProtocolFormField, i as ProtocolFormOption, l as ProtocolHandler, X as ProtocolRegistration, c as ProtocolRequest, d as ProtocolResponse, B as RoutingDecision, M as RoutingLog, Y as SchemaAgent, Z as SchemaQuestion, p as SessionContext, N as SessionMetadata, q as SessionState, e as SessionStatus, y as StorageContext, z as StorageSetOptions } from './types-DYJ44S2E.mjs';
 
 /**
  * UCP (Universal Classification Protocol) Types
@@ -680,6 +680,14 @@ interface PlatformKnowledgeSummary {
     type?: string;
     /** Owning organization ID */
     organizationId: string;
+    /**
+     * True for handler-managed documents created through the protocol
+     * write API. System-owned knowledge is hidden from every Studio UI
+     * surface and only appears in `list` when `includeSystemOwned` is set.
+     */
+    isSystemOwned?: boolean;
+    /** Whether semantic search (record embedding) is enabled. */
+    ragEnabled?: boolean;
     /** Timestamps */
     createdAt?: number | string;
     updatedAt?: number | string;
@@ -698,6 +706,42 @@ interface ListKnowledgeOptions {
      * `publicReadable` in Studio).
      */
     orgId?: string;
+    /**
+     * Include system-owned (handler-managed) knowledge in the listing.
+     * Only honored when listing the token's own org; other orgs never
+     * expose their system-owned documents.
+     */
+    includeSystemOwned?: boolean;
+}
+/** Sheet definition for `knowledge.create`. */
+interface CreateKnowledgeSheet {
+    /** Stable sheet id, referenced later by record writes and search. */
+    id: string;
+    name: string;
+    description?: string;
+    /**
+     * Column definitions ({ id, name, type, ... }). Loose-typed; the
+     * Studio schema validates `type` against its column-type enum.
+     */
+    columns?: Array<Record<string, unknown>>;
+}
+interface CreateKnowledgeOptions {
+    description?: string;
+    /**
+     * Enable semantic search at creation time. Defaults to false; can be
+     * flipped later with `setRagEnabled` (which also backfills embeddings
+     * for records inserted while the flag was off).
+     */
+    ragEnabled?: boolean;
+}
+/** A raw record as returned by the protocol record-write endpoints. */
+interface PlatformKnowledgeRecord {
+    id: string;
+    knowledgeId: string;
+    sheetId: string;
+    data: Record<string, unknown>;
+    createdAt?: number | string;
+    updatedAt?: number | string;
 }
 interface KnowledgeSearchOptions {
     /** Max records to return (server-side clamped to 1..50, default 10). */
@@ -769,8 +813,12 @@ declare class PlatformClient {
      *
      * Reads are allowed when the SDK token's org matches the target org,
      * OR when the target org has `publicReadable: true` on the Studio side.
-     * Writes are not yet exposed here — those still go through the user-
-     * authenticated /api/knowledge routes from the Studio UI.
+     *
+     * Writes target system-owned (handler-managed) knowledge only: the
+     * protocol API stamps everything created here `isSystemOwned: true`,
+     * which keeps it out of every Studio UI surface — Studio acts as a
+     * plain storage + RAG layer for it. UI-managed knowledge cannot be
+     * modified through this surface.
      */
     knowledge: {
         /**
@@ -813,6 +861,43 @@ declare class PlatformClient {
             ragEnabled: boolean;
             backfillTriggered: boolean;
         }>;
+        /**
+         * Create a system-owned database knowledge under the token's org.
+         *
+         * 409 (surfaced as an error) means a knowledge of the same name
+         * already exists in the org. Idempotent callers should recover by
+         * listing with `includeSystemOwned: true` and matching on name.
+         */
+        create: (name: string, sheets: CreateKnowledgeSheet[], options?: CreateKnowledgeOptions) => Promise<PlatformKnowledge>;
+        /**
+         * Delete a system-owned knowledge and all of its records.
+         * Refused (403) for UI-managed knowledge.
+         */
+        delete: (id: string) => Promise<{
+            deletedRecords: number;
+        }>;
+        /**
+         * Append one record to a sheet. Embeds async when ragEnabled.
+         */
+        addRecord: (id: string, sheetId: string, data: Record<string, unknown>) => Promise<PlatformKnowledgeRecord>;
+        /**
+         * Replace a record's data payload. Re-embeds async when ragEnabled.
+         */
+        updateRecord: (id: string, recordId: string, data: Record<string, unknown>) => Promise<PlatformKnowledgeRecord>;
+        /** Delete one record. */
+        deleteRecord: (id: string, recordId: string) => Promise<void>;
+        /**
+         * Bulk-insert records into one sheet (each array entry becomes one
+         * record's `data`). With `replace: true` the sheet's existing
+         * records are deleted first — the full-resync primitive backfills
+         * use. Server caps a single call at 5000 records.
+         */
+        bulkRecords: (id: string, sheetId: string, records: Array<Record<string, unknown>>, options?: {
+            replace?: boolean;
+        }) => Promise<{
+            insertedCount: number;
+            deletedCount: number;
+        }>;
     };
     /**
      * Throughline (find-a-helpline) surface.
@@ -1123,4 +1208,4 @@ declare class LLMClient {
  */
 declare function createLLMClient(config: LLMClientConfig): LLMClient;
 
-export { AgentTransitionPayload, ChatMessage, type ClassificationResult, type EmergencyPayload, HandoffOfferPayload, HandoffRequestPayload, HandoffReturnPayload, type HelplineCardItem, type HelplineCardPayload, type KnowledgeSearchOptions, type LLMCacheCreateRequest, type LLMCachedContent, type LLMCandidate, LLMClient, type LLMClientConfig, type LLMContent, LLMError, type LLMGenerateRequest, type LLMGenerateResponse, type LLMGenerationConfig, type LLMPart, type LLMSafetySetting, type LLMUsageMetadata, type ListKnowledgeOptions, MARKER_TYPES, type MarkerType, type PlatformChatbot, PlatformClient, type PlatformClientConfig, PlatformError, type PlatformKnowledge, type PlatformKnowledgeSearchHit, type PlatformKnowledgeSummary, ProtocolStreamChunk, type ProviderCardItem, type ProviderCardPayload, type ReportCardPayload, type ResourceCardItem, type ResourceCardPayload, RoutingClassificationPayload, type SafetyPlanPayload, type SafetyPlanSection, SchemaDeclarationPayload, type ThroughlineHelplinesQuery, type UCPClassifyRequest, type UCPClassifyResponse, UCPClient, type UCPClientConfig, type UCPEndpointConfig, UCPError, type UCPErrorResponse, type UCPInfoResponse, type UCPMessage, classifyWithUCP, createAuthHeader, createLLMClient, createPlatformClient, createRequestSignature, createUCPClient, isValidToken, renderMarkers, streamMetadata, verifyRequestSignature };
+export { AgentTransitionPayload, ChatMessage, type ClassificationResult, type CreateKnowledgeOptions, type CreateKnowledgeSheet, type EmergencyPayload, HandoffOfferPayload, HandoffRequestPayload, HandoffReturnPayload, type HelplineCardItem, type HelplineCardPayload, type KnowledgeSearchOptions, type LLMCacheCreateRequest, type LLMCachedContent, type LLMCandidate, LLMClient, type LLMClientConfig, type LLMContent, LLMError, type LLMGenerateRequest, type LLMGenerateResponse, type LLMGenerationConfig, type LLMPart, type LLMSafetySetting, type LLMUsageMetadata, type ListKnowledgeOptions, MARKER_TYPES, type MarkerType, type PlatformChatbot, PlatformClient, type PlatformClientConfig, PlatformError, type PlatformKnowledge, type PlatformKnowledgeRecord, type PlatformKnowledgeSearchHit, type PlatformKnowledgeSummary, ProtocolStreamChunk, type ProviderCardItem, type ProviderCardPayload, type ReportCardPayload, type ResourceCardItem, type ResourceCardPayload, RoutingClassificationPayload, type SafetyPlanPayload, type SafetyPlanSection, SchemaDeclarationPayload, type ThroughlineHelplinesQuery, type UCPClassifyRequest, type UCPClassifyResponse, UCPClient, type UCPClientConfig, type UCPEndpointConfig, UCPError, type UCPErrorResponse, type UCPInfoResponse, type UCPMessage, classifyWithUCP, createAuthHeader, createLLMClient, createPlatformClient, createRequestSignature, createUCPClient, isValidToken, renderMarkers, streamMetadata, verifyRequestSignature };

package/dist/index.d.ts

@@ -1,5 +1,5 @@
-import { C as ChatMessage, S as SchemaDeclarationPayload, P as ProtocolStreamChunk, A as AgentTransitionPayload, R as RoutingClassificationPayload, H as HandoffRequestPayload, a as HandoffReturnPayload, b as HandoffOfferPayload } from './types-GoTI_c14.js';
-export { O as AnalyticsContext, E as ChatbotInfo, F as ClassifierConfig, D as DeploymentInfo, G as FormData, V as FormFieldDefinition, W as FormFieldType, J as FormFieldValue, U as FormSchema, n as HandlerInfo, _ as HandoffContext, f as HandoffInboundContext, $ as HandoffOptions, x as Helpline, w as HelplineResult, v as HelplineSearchOptions, I as IntegrationContext, u as IntegrationResult, Q as InteractionEvent, T as InteractionEventType, t as KnowledgeColumnMetadata, K as KnowledgeContext, s as KnowledgeMetadata, r as KnowledgeResult, L as LoggerContext, m as ProtocolCapabilities, o as ProtocolContext, k as ProtocolError, j as ProtocolFieldValidation, g as ProtocolForm, h as ProtocolFormField, i as ProtocolFormOption, l as ProtocolHandler, X as ProtocolRegistration, c as ProtocolRequest, d as ProtocolResponse, B as RoutingDecision, M as RoutingLog, Y as SchemaAgent, Z as SchemaQuestion, p as SessionContext, N as SessionMetadata, q as SessionState, e as SessionStatus, y as StorageContext, z as StorageSetOptions } from './types-GoTI_c14.js';
+import { C as ChatMessage, S as SchemaDeclarationPayload, P as ProtocolStreamChunk, A as AgentTransitionPayload, R as RoutingClassificationPayload, H as HandoffRequestPayload, a as HandoffReturnPayload, b as HandoffOfferPayload } from './types-DYJ44S2E.js';
+export { O as AnalyticsContext, E as ChatbotInfo, F as ClassifierConfig, D as DeploymentInfo, G as FormData, V as FormFieldDefinition, W as FormFieldType, J as FormFieldValue, U as FormSchema, n as HandlerInfo, _ as HandoffContext, f as HandoffInboundContext, $ as HandoffOptions, x as Helpline, w as HelplineResult, v as HelplineSearchOptions, I as IntegrationContext, u as IntegrationResult, Q as InteractionEvent, T as InteractionEventType, t as KnowledgeColumnMetadata, K as KnowledgeContext, s as KnowledgeMetadata, r as KnowledgeResult, L as LoggerContext, m as ProtocolCapabilities, o as ProtocolContext, k as ProtocolError, j as ProtocolFieldValidation, g as ProtocolForm, h as ProtocolFormField, i as ProtocolFormOption, l as ProtocolHandler, X as ProtocolRegistration, c as ProtocolRequest, d as ProtocolResponse, B as RoutingDecision, M as RoutingLog, Y as SchemaAgent, Z as SchemaQuestion, p as SessionContext, N as SessionMetadata, q as SessionState, e as SessionStatus, y as StorageContext, z as StorageSetOptions } from './types-DYJ44S2E.js';
 
 /**
  * UCP (Universal Classification Protocol) Types
@@ -680,6 +680,14 @@ interface PlatformKnowledgeSummary {
     type?: string;
     /** Owning organization ID */
     organizationId: string;
+    /**
+     * True for handler-managed documents created through the protocol
+     * write API. System-owned knowledge is hidden from every Studio UI
+     * surface and only appears in `list` when `includeSystemOwned` is set.
+     */
+    isSystemOwned?: boolean;
+    /** Whether semantic search (record embedding) is enabled. */
+    ragEnabled?: boolean;
     /** Timestamps */
     createdAt?: number | string;
     updatedAt?: number | string;
@@ -698,6 +706,42 @@ interface ListKnowledgeOptions {
      * `publicReadable` in Studio).
      */
     orgId?: string;
+    /**
+     * Include system-owned (handler-managed) knowledge in the listing.
+     * Only honored when listing the token's own org; other orgs never
+     * expose their system-owned documents.
+     */
+    includeSystemOwned?: boolean;
+}
+/** Sheet definition for `knowledge.create`. */
+interface CreateKnowledgeSheet {
+    /** Stable sheet id, referenced later by record writes and search. */
+    id: string;
+    name: string;
+    description?: string;
+    /**
+     * Column definitions ({ id, name, type, ... }). Loose-typed; the
+     * Studio schema validates `type` against its column-type enum.
+     */
+    columns?: Array<Record<string, unknown>>;
+}
+interface CreateKnowledgeOptions {
+    description?: string;
+    /**
+     * Enable semantic search at creation time. Defaults to false; can be
+     * flipped later with `setRagEnabled` (which also backfills embeddings
+     * for records inserted while the flag was off).
+     */
+    ragEnabled?: boolean;
+}
+/** A raw record as returned by the protocol record-write endpoints. */
+interface PlatformKnowledgeRecord {
+    id: string;
+    knowledgeId: string;
+    sheetId: string;
+    data: Record<string, unknown>;
+    createdAt?: number | string;
+    updatedAt?: number | string;
 }
 interface KnowledgeSearchOptions {
     /** Max records to return (server-side clamped to 1..50, default 10). */
@@ -769,8 +813,12 @@ declare class PlatformClient {
      *
      * Reads are allowed when the SDK token's org matches the target org,
      * OR when the target org has `publicReadable: true` on the Studio side.
-     * Writes are not yet exposed here — those still go through the user-
-     * authenticated /api/knowledge routes from the Studio UI.
+     *
+     * Writes target system-owned (handler-managed) knowledge only: the
+     * protocol API stamps everything created here `isSystemOwned: true`,
+     * which keeps it out of every Studio UI surface — Studio acts as a
+     * plain storage + RAG layer for it. UI-managed knowledge cannot be
+     * modified through this surface.
      */
     knowledge: {
         /**
@@ -813,6 +861,43 @@ declare class PlatformClient {
             ragEnabled: boolean;
             backfillTriggered: boolean;
         }>;
+        /**
+         * Create a system-owned database knowledge under the token's org.
+         *
+         * 409 (surfaced as an error) means a knowledge of the same name
+         * already exists in the org. Idempotent callers should recover by
+         * listing with `includeSystemOwned: true` and matching on name.
+         */
+        create: (name: string, sheets: CreateKnowledgeSheet[], options?: CreateKnowledgeOptions) => Promise<PlatformKnowledge>;
+        /**
+         * Delete a system-owned knowledge and all of its records.
+         * Refused (403) for UI-managed knowledge.
+         */
+        delete: (id: string) => Promise<{
+            deletedRecords: number;
+        }>;
+        /**
+         * Append one record to a sheet. Embeds async when ragEnabled.
+         */
+        addRecord: (id: string, sheetId: string, data: Record<string, unknown>) => Promise<PlatformKnowledgeRecord>;
+        /**
+         * Replace a record's data payload. Re-embeds async when ragEnabled.
+         */
+        updateRecord: (id: string, recordId: string, data: Record<string, unknown>) => Promise<PlatformKnowledgeRecord>;
+        /** Delete one record. */
+        deleteRecord: (id: string, recordId: string) => Promise<void>;
+        /**
+         * Bulk-insert records into one sheet (each array entry becomes one
+         * record's `data`). With `replace: true` the sheet's existing
+         * records are deleted first — the full-resync primitive backfills
+         * use. Server caps a single call at 5000 records.
+         */
+        bulkRecords: (id: string, sheetId: string, records: Array<Record<string, unknown>>, options?: {
+            replace?: boolean;
+        }) => Promise<{
+            insertedCount: number;
+            deletedCount: number;
+        }>;
     };
     /**
      * Throughline (find-a-helpline) surface.
@@ -1123,4 +1208,4 @@ declare class LLMClient {
  */
 declare function createLLMClient(config: LLMClientConfig): LLMClient;
 
-export { AgentTransitionPayload, ChatMessage, type ClassificationResult, type EmergencyPayload, HandoffOfferPayload, HandoffRequestPayload, HandoffReturnPayload, type HelplineCardItem, type HelplineCardPayload, type KnowledgeSearchOptions, type LLMCacheCreateRequest, type LLMCachedContent, type LLMCandidate, LLMClient, type LLMClientConfig, type LLMContent, LLMError, type LLMGenerateRequest, type LLMGenerateResponse, type LLMGenerationConfig, type LLMPart, type LLMSafetySetting, type LLMUsageMetadata, type ListKnowledgeOptions, MARKER_TYPES, type MarkerType, type PlatformChatbot, PlatformClient, type PlatformClientConfig, PlatformError, type PlatformKnowledge, type PlatformKnowledgeSearchHit, type PlatformKnowledgeSummary, ProtocolStreamChunk, type ProviderCardItem, type ProviderCardPayload, type ReportCardPayload, type ResourceCardItem, type ResourceCardPayload, RoutingClassificationPayload, type SafetyPlanPayload, type SafetyPlanSection, SchemaDeclarationPayload, type ThroughlineHelplinesQuery, type UCPClassifyRequest, type UCPClassifyResponse, UCPClient, type UCPClientConfig, type UCPEndpointConfig, UCPError, type UCPErrorResponse, type UCPInfoResponse, type UCPMessage, classifyWithUCP, createAuthHeader, createLLMClient, createPlatformClient, createRequestSignature, createUCPClient, isValidToken, renderMarkers, streamMetadata, verifyRequestSignature };
+export { AgentTransitionPayload, ChatMessage, type ClassificationResult, type CreateKnowledgeOptions, type CreateKnowledgeSheet, type EmergencyPayload, HandoffOfferPayload, HandoffRequestPayload, HandoffReturnPayload, type HelplineCardItem, type HelplineCardPayload, type KnowledgeSearchOptions, type LLMCacheCreateRequest, type LLMCachedContent, type LLMCandidate, LLMClient, type LLMClientConfig, type LLMContent, LLMError, type LLMGenerateRequest, type LLMGenerateResponse, type LLMGenerationConfig, type LLMPart, type LLMSafetySetting, type LLMUsageMetadata, type ListKnowledgeOptions, MARKER_TYPES, type MarkerType, type PlatformChatbot, PlatformClient, type PlatformClientConfig, PlatformError, type PlatformKnowledge, type PlatformKnowledgeRecord, type PlatformKnowledgeSearchHit, type PlatformKnowledgeSummary, ProtocolStreamChunk, type ProviderCardItem, type ProviderCardPayload, type ReportCardPayload, type ResourceCardItem, type ResourceCardPayload, RoutingClassificationPayload, type SafetyPlanPayload, type SafetyPlanSection, SchemaDeclarationPayload, type ThroughlineHelplinesQuery, type UCPClassifyRequest, type UCPClassifyResponse, UCPClient, type UCPClientConfig, type UCPEndpointConfig, UCPError, type UCPErrorResponse, type UCPInfoResponse, type UCPMessage, classifyWithUCP, createAuthHeader, createLLMClient, createPlatformClient, createRequestSignature, createUCPClient, isValidToken, renderMarkers, streamMetadata, verifyRequestSignature };

package/dist/index.js

@@ -343,8 +343,12 @@ var PlatformClient = class {
      *
      * Reads are allowed when the SDK token's org matches the target org,
      * OR when the target org has `publicReadable: true` on the Studio side.
-     * Writes are not yet exposed here — those still go through the user-
-     * authenticated /api/knowledge routes from the Studio UI.
+     *
+     * Writes target system-owned (handler-managed) knowledge only: the
+     * protocol API stamps everything created here `isSystemOwned: true`,
+     * which keeps it out of every Studio UI surface — Studio acts as a
+     * plain storage + RAG layer for it. UI-managed knowledge cannot be
+     * modified through this surface.
      */
     this.knowledge = {
       /**
@@ -352,9 +356,12 @@ var PlatformClient = class {
        * Defaults to the SDK token's own org if `orgId` is omitted.
        */
       list: async (options = {}) => {
-        const qs = options.orgId ? `?organizationId=${encodeURIComponent(options.orgId)}` : "";
+        const params = new URLSearchParams();
+        if (options.orgId) params.set("organizationId", options.orgId);
+        if (options.includeSystemOwned) params.set("includeSystemOwned", "1");
+        const qsStr = params.toString();
         const data = await this.request(
-          `/api/protocol/knowledge${qs}`,
+          `/api/protocol/knowledge${qsStr ? `?${qsStr}` : ""}`,
           "Failed to list knowledge"
         );
         return data.knowledge;
@@ -416,6 +423,92 @@ var PlatformClient = class {
           { method: "POST", body: { enabled } }
         );
         return data.knowledge;
+      },
+      /**
+       * Create a system-owned database knowledge under the token's org.
+       *
+       * 409 (surfaced as an error) means a knowledge of the same name
+       * already exists in the org. Idempotent callers should recover by
+       * listing with `includeSystemOwned: true` and matching on name.
+       */
+      create: async (name, sheets, options = {}) => {
+        const data = await this.request(
+          "/api/protocol/knowledge",
+          "Failed to create knowledge",
+          {
+            method: "POST",
+            body: {
+              name,
+              sheets,
+              ...options.description !== void 0 ? { description: options.description } : {},
+              ...options.ragEnabled !== void 0 ? { ragEnabled: options.ragEnabled } : {}
+            }
+          }
+        );
+        return data.knowledge;
+      },
+      /**
+       * Delete a system-owned knowledge and all of its records.
+       * Refused (403) for UI-managed knowledge.
+       */
+      delete: async (id) => {
+        const data = await this.request(
+          `/api/protocol/knowledge/${encodeURIComponent(id)}`,
+          "Failed to delete knowledge",
+          { method: "DELETE" }
+        );
+        return { deletedRecords: data.deletedRecords };
+      },
+      /**
+       * Append one record to a sheet. Embeds async when ragEnabled.
+       */
+      addRecord: async (id, sheetId, data) => {
+        const res = await this.request(
+          `/api/protocol/knowledge/${encodeURIComponent(id)}/records`,
+          "Failed to create record",
+          { method: "POST", body: { sheetId, data } }
+        );
+        return res.record;
+      },
+      /**
+       * Replace a record's data payload. Re-embeds async when ragEnabled.
+       */
+      updateRecord: async (id, recordId, data) => {
+        const res = await this.request(
+          `/api/protocol/knowledge/${encodeURIComponent(id)}/records/${encodeURIComponent(recordId)}`,
+          "Failed to update record",
+          { method: "PUT", body: { data } }
+        );
+        return res.record;
+      },
+      /** Delete one record. */
+      deleteRecord: async (id, recordId) => {
+        await this.request(
+          `/api/protocol/knowledge/${encodeURIComponent(id)}/records/${encodeURIComponent(recordId)}`,
+          "Failed to delete record",
+          { method: "DELETE" }
+        );
+      },
+      /**
+       * Bulk-insert records into one sheet (each array entry becomes one
+       * record's `data`). With `replace: true` the sheet's existing
+       * records are deleted first — the full-resync primitive backfills
+       * use. Server caps a single call at 5000 records.
+       */
+      bulkRecords: async (id, sheetId, records, options = {}) => {
+        const data = await this.request(
+          `/api/protocol/knowledge/${encodeURIComponent(id)}/records/bulk`,
+          "Failed to bulk-write records",
+          {
+            method: "POST",
+            body: {
+              sheetId,
+              records,
+              ...options.replace !== void 0 ? { replace: options.replace } : {}
+            }
+          }
+        );
+        return { insertedCount: data.insertedCount, deletedCount: data.deletedCount };
       }
     };
     /**