@rkat/sdk 0.3.4 → 0.4.0

package/dist/client.d.ts

@@ -1,103 +1,120 @@
 /**
- * Meerkat client — spawns rkat-rpc subprocess and communicates via JSON-RPC.
+ * Meerkat client — spawns rkat-rpc and communicates via JSON-RPC.
+ *
+ * @example
+ * ```ts
+ * import { MeerkatClient } from "@rkat/sdk";
+ *
+ * const client = new MeerkatClient();
+ * await client.connect();
+ *
+ * const session = await client.createSession("Hello!");
+ * console.log(session.text);
+ *
+ * const result = await session.turn("Tell me more");
+ * console.log(result.text);
+ *
+ * for await (const event of session.stream("Explain in detail")) {
+ *   if (event.type === "text_delta") {
+ *     process.stdout.write(event.delta);
+ *   }
+ * }
+ *
+ * await session.archive();
+ * await client.close();
+ * ```
  */
-import type { WireRunResult, CapabilitiesResponse } from "./generated/types.js";
-/** Supplementary discovery metadata for a comms peer. */
-export interface PeerMeta {
-    description?: string;
-    labels?: Record<string, string>;
+import { Session } from "./session.js";
+import { EventStream } from "./streaming.js";
+import type { Capability, RunResult, SessionInfo, SessionOptions, SkillRef } from "./types.js";
+/** Options for connecting to the rkat-rpc runtime. */
+export interface ConnectOptions {
+    realmId?: string;
+    instanceId?: string;
+    realmBackend?: "jsonl" | "redb";
+    isolated?: boolean;
+    stateRoot?: string;
+    contextRoot?: string;
+    userConfigRoot?: string;
 }
 export declare class MeerkatClient {
     private process;
     private requestId;
-    private capabilities;
+    private _capabilities;
     private rkatPath;
     private pendingRequests;
+    private eventQueues;
+    private rl;
     constructor(rkatPath?: string);
-    private static commandPath;
-    private static resolveCandidatePath;
-    private static platformTarget;
-    private static runCommand;
-    private static extractZip;
-    private static ensureDownloadedBinary;
-    private static resolveBinaryPath;
-    connect(options?: {
-        realmId?: string;
-        instanceId?: string;
-        realmBackend?: "jsonl" | "redb";
-        isolated?: boolean;
-        stateRoot?: string;
-        contextRoot?: string;
-        userConfigRoot?: string;
-    }): Promise<this>;
+    connect(options?: ConnectOptions): Promise<this>;
     close(): Promise<void>;
-    createSession(params: {
-        prompt: string;
-        model?: string;
-        provider?: string;
-        system_prompt?: string;
-        max_tokens?: number;
-        output_schema?: Record<string, unknown>;
-        structured_output_retries?: number;
-        hooks_override?: Record<string, unknown>;
-        enable_builtins?: boolean;
-        enable_shell?: boolean;
-        enable_subagents?: boolean;
-        enable_memory?: boolean;
-        host_mode?: boolean;
-        comms_name?: string;
-        peer_meta?: PeerMeta;
-        provider_params?: Record<string, unknown>;
-        preload_skills?: string[];
-        skill_references?: string[];
-    }): Promise<WireRunResult>;
-    startTurn(sessionId: string, prompt: string, options?: {
-        skill_references?: string[];
-    }): Promise<WireRunResult>;
-    interrupt(sessionId: string): Promise<void>;
-    listSessions(): Promise<unknown[]>;
-    readSession(sessionId: string): Promise<Record<string, unknown>>;
-    archiveSession(sessionId: string): Promise<void>;
-    getCapabilities(): Promise<CapabilitiesResponse>;
-    hasCapability(capabilityId: string): boolean;
-    requireCapability(capabilityId: string): void;
-    getConfig(): Promise<Record<string, unknown>>;
-    setConfig(config: Record<string, unknown>): Promise<void>;
-    patchConfig(patch: Record<string, unknown>): Promise<Record<string, unknown>>;
     /**
-     * Send a canonical comms command to a session.
+     * Create a new session, run the first turn, and return a {@link Session}.
      *
-     * @param sessionId - Target session ID
-     * @param command - Command fields (kind, to, body, intent, params, etc.)
-     * @returns Receipt info on success
+     * @example
+     * ```ts
+     * const session = await client.createSession("Summarise this project", {
+     *   model: "claude-sonnet-4-5",
+     * });
+     * console.log(session.text);
+     * ```
      */
-    send(sessionId: string, command: Record<string, unknown>): Promise<Record<string, unknown>>;
+    createSession(prompt: string, options?: SessionOptions): Promise<Session>;
     /**
-     * Send a command and open a stream in one call.
+     * Create a new session and stream typed events from the first turn.
      *
-     * @param sessionId - Target session ID
-     * @param command - Command fields (kind, to, body, etc.)
-     * @returns Receipt and stream info
+     * Returns an {@link EventStream} `AsyncIterable<AgentEvent>`.
      */
-    sendAndStream(sessionId: string, command: Record<string, unknown>): Promise<Record<string, unknown>>;
-    /**
-     * List peers visible to a session's comms runtime.
-     *
-     * @param sessionId - Target session ID
-     * @returns Object with `{ peers: [...] }`
-     */
-    peers(sessionId: string): Promise<{
-        peers: Array<Record<string, unknown>>;
-    }>;
-    /**
-     * Normalize a CapabilityStatus from the wire.
-     * Available is the string "Available", but other variants are
-     * externally-tagged objects like {"DisabledByPolicy": {"description": "..."}}.
-     * We normalize to the variant name string.
-     */
-    private static normalizeStatus;
+    createSessionStreaming(prompt: string, options?: SessionOptions): EventStream;
+    listSessions(): Promise<SessionInfo[]>;
+    readSession(sessionId: string): Promise<Record<string, unknown>>;
+    get capabilities(): readonly Capability[];
+    hasCapability(capabilityId: string): boolean;
+    requireCapability(capabilityId: string): void;
+    getConfig(): Promise<Record<string, unknown>>;
+    setConfig(config: Record<string, unknown>, options?: {
+        expectedGeneration?: number;
+    }): Promise<void>;
+    patchConfig(patch: Record<string, unknown>, options?: {
+        expectedGeneration?: number;
+    }): Promise<Record<string, unknown>>;
+    listSkills(): Promise<Array<Record<string, unknown>>>;
+    inspectSkill(id: string, options?: {
+        source?: string;
+    }): Promise<Record<string, unknown>>;
+    /** @internal */
+    _startTurn(sessionId: string, prompt: string, options?: {
+        skillRefs?: SkillRef[];
+        skillReferences?: string[];
+    }): Promise<RunResult>;
+    /** @internal */
+    _startTurnStreaming(sessionId: string, prompt: string, options?: {
+        skillRefs?: SkillRef[];
+        skillReferences?: string[];
+    }, session?: Session): EventStream;
+    /** @internal */
+    _interrupt(sessionId: string): Promise<void>;
+    /** @internal */
+    _archive(sessionId: string): Promise<void>;
+    /** @internal */
+    _send(sessionId: string, command: Record<string, unknown>): Promise<Record<string, unknown>>;
+    /** @internal */
+    _peers(sessionId: string): Promise<Record<string, unknown>>;
+    private handleLine;
     private request;
-    private checkVersionCompatible;
-    private parseRunResult;
+    private registerRequest;
+    private static normalizeStatus;
+    private static parseSkillDiagnostics;
+    private static checkVersionCompatible;
+    static parseRunResult(data: Record<string, unknown>): RunResult;
+    private static buildCreateParams;
+    private static commandPath;
+    private static resolveCandidatePath;
+    private static platformTarget;
+    private static runCommand;
+    private static extractZip;
+    private static ensureDownloadedBinary;
+    private static resolveBinaryPath;
+    private static buildArgs;
 }
 //# sourceMappingURL=client.d.ts.map

package/dist/client.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AAeH,OAAO,EAAE,OAAO,EAAE,MAAM,cAAc,CAAC;AACvC,OAAO,EAAE,WAAW,EAAc,MAAM,gBAAgB,CAAC;AACzD,OAAO,KAAK,EACV,UAAU,EACV,SAAS,EAET,WAAW,EACX,cAAc,EAEd,QAAQ,EAGT,MAAM,YAAY,CAAC;AAuBpB,sDAAsD;AACtD,MAAM,WAAW,cAAc;IAC7B,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,YAAY,CAAC,EAAE,OAAO,GAAG,MAAM,CAAC;IAChC,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,cAAc,CAAC,EAAE,MAAM,CAAC;CACzB;AA8BD,qBAAa,aAAa;IACxB,OAAO,CAAC,OAAO,CAA6B;IAC5C,OAAO,CAAC,SAAS,CAAK;IACtB,OAAO,CAAC,aAAa,CAAoB;IACzC,OAAO,CAAC,QAAQ,CAAS;IACzB,OAAO,CAAC,eAAe,CAGnB;IACJ,OAAO,CAAC,WAAW,CAAiE;IACpF,OAAO,CAAC,EAAE,CAAkC;gBAEhC,QAAQ,SAAa;IAM3B,OAAO,CAAC,OAAO,CAAC,EAAE,cAAc,GAAG,OAAO,CAAC,IAAI,CAAC;IA+ChD,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAqB5B;;;;;;;;;;OAUG;IACG,aAAa,CACjB,MAAM,EAAE,MAAM,EACd,OAAO,CAAC,EAAE,cAAc,GACvB,OAAO,CAAC,OAAO,CAAC;IAOnB;;;;OAIG;IACH,sBAAsB,CACpB,MAAM,EAAE,MAAM,EACd,OAAO,CAAC,EAAE,cAAc,GACvB,WAAW;IAkCR,YAAY,IAAI,OAAO,CAAC,WAAW,EAAE,CAAC;IAgBtC,WAAW,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAMtE,IAAI,YAAY,IAAI,SAAS,UAAU,EAAE,CAExC;IAED,aAAa,CAAC,YAAY,EAAE,MAAM,GAAG,OAAO;IAM5C,iBAAiB,CAAC,YAAY,EAAE,MAAM,GAAG,IAAI;IAWvC,SAAS,IAAI,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAI7C,SAAS,CACb,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC/B,OAAO,CAAC,EAAE;QAAE,kBAAkB,CAAC,EAAE,MAAM,CAAA;KAAE,GACxC,OAAO,CAAC,IAAI,CAAC;IAQV,WAAW,CACf,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC9B,OAAO,CAAC,EAAE;QAAE,kBAAkB,CAAC,EAAE,MAAM,CAAA;KAAE,GACxC,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAU7B,UAAU,IAAI,OAAO,CAAC,KAAK,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC;IAKrD,YAAY,CAChB,EAAE,EAAE,MAAM,EACV,OAAO,CAAC,EAAE;QAAE,MAAM,CAAC,EAAE,MAAM,CAAA;KAAE,GAC5B,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAUnC,gBAAgB;IACV,UAAU,CACd,SAAS,EAAE,MAAM,EACjB,MAAM,EAAE,MAAM,EACd,OAAO,CAAC,EAAE;QAAE,SAAS,CAAC,EAAE,QAAQ,EAAE,CAAC;QAAC,eAAe,CAAC,EAAE,MAAM,EAAE,CAAA;KAAE,GAC/D,OAAO,CAAC,SAAS,CAAC;IAarB,gBAAgB;IAChB,mBAAmB,CACjB,SAAS,EAAE,MAAM,EACjB,MAAM,EAAE,MAAM,EACd,OAAO,CAAC,EAAE;QAAE,SAAS,CAAC,EAAE,QAAQ,EAAE,CAAC;QAAC,eAAe,CAAC,EAAE,MAAM,EAAE,CAAA;KAAE,EAChE,OAAO,CAAC,EAAE,OAAO,GAChB,WAAW;IAiCd,gBAAgB;IACV,UAAU,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAIlD,gBAAgB;IACV,QAAQ,CAAC,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAIhD,gBAAgB;IACV,KAAK,CACT,SAAS,EAAE,MAAM,EACjB,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAC/B,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAInC,gBAAgB;IACV,MAAM,CACV,SAAS,EAAE,MAAM,GAChB,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAMnC,OAAO,CAAC,UAAU;IAqClB,OAAO,CAAC,OAAO;IAaf,OAAO,CAAC,eAAe;IAQvB,OAAO,CAAC,MAAM,CAAC,eAAe;IAU9B,OAAO,CAAC,MAAM,CAAC,qBAAqB;IAkCpC,OAAO,CAAC,MAAM,CAAC,sBAAsB;IAWrC,MAAM,CAAC,cAAc,CAAC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,SAAS;IAmC/D,OAAO,CAAC,MAAM,CAAC,iBAAiB;IAiChC,OAAO,CAAC,MAAM,CAAC,WAAW;IA4B1B,OAAO,CAAC,MAAM,CAAC,oBAAoB;IAQnC,OAAO,CAAC,MAAM,CAAC,cAAc;mBAoBR,UAAU;mBAaV,UAAU;mBAWV,sBAAsB;mBAkCtB,iBAAiB;IAgCtC,OAAO,CAAC,MAAM,CAAC,SAAS;CAazB"}