@rkat/sdk 0.3.4 → 0.4.1

package/dist/streaming.js

@@ -1,78 +1,183 @@
 /**
- * Async event stream over JSON-RPC notifications from rkat-rpc.
- */
-/**
- * Async iterator that yields WireEvent objects from JSON-RPC notifications.
+ * Streaming API for the Meerkat TypeScript SDK.
  *
- * Skips response messages (which have an `id` field) and only yields
- * notification payloads parsed as WireEvent.
+ * {@link EventStream} is an `AsyncIterable<StreamEvent>` that yields typed
+ * events from a running turn, with access to the final {@link RunResult}
+ * after iteration.
  *
  * @example
  * ```ts
- * for await (const event of new EventStream(readline)) {
- *   console.log(event.session_id, event.event);
+ * for await (const event of session.stream("prompt")) {
+ *   if (event.type === "text_delta") {
+ *     process.stdout.write(event.delta);
+ *   }
  * }
+ * console.log(stream.result.usage.inputTokens);
  * ```
  */
-export class EventStream {
+import { isTextDelta, parseEvent } from "./events.js";
+import { MeerkatError } from "./generated/errors.js";
+/** @internal Queue with promise-based get(). */
+class AsyncQueue {
     buffer = [];
     waiters = [];
-    closed = false;
-    constructor(rl) {
-        rl.on("line", (line) => {
-            try {
-                const data = JSON.parse(line);
-                // Skip responses (they have an "id" field)
-                if ("id" in data)
-                    return;
-                const params = (data.params ?? {});
-                const event = {
-                    session_id: String(params.session_id ?? ""),
-                    sequence: Number(params.sequence ?? 0),
-                    event: (params.event ?? {}),
-                    contract_version: String(params.contract_version ?? ""),
-                };
-                if (this.waiters.length > 0) {
-                    const waiter = this.waiters.shift();
-                    waiter({ value: event, done: false });
-                }
-                else {
-                    this.buffer.push(event);
+    put(item) {
+        if (this.waiters.length > 0) {
+            this.waiters.shift()(item);
+        }
+        else {
+            this.buffer.push(item);
+        }
+    }
+    get() {
+        if (this.buffer.length > 0) {
+            return Promise.resolve(this.buffer.shift());
+        }
+        return new Promise((resolve) => {
+            this.waiters.push(resolve);
+        });
+    }
+    tryGet() {
+        return this.buffer.shift();
+    }
+    get isEmpty() {
+        return this.buffer.length === 0;
+    }
+    failAll(error) {
+        // Waiters receive a rejected promise; we wrap by rejecting in the next tick
+        for (const waiter of this.waiters) {
+            // Use a sentinel; callers handle it
+            waiter(undefined);
+        }
+        this.waiters = [];
+    }
+}
+/** Sentinel for end-of-stream. */
+const SENTINEL = Symbol("eos");
+/**
+ * Typed async iterable of {@link StreamEvent} objects from a running turn.
+ *
+ * After iteration completes, the {@link result} getter returns the final
+ * {@link RunResult}.
+ */
+export class EventStream {
+    /** @internal */ _sessionId;
+    _eventQueue;
+    _responsePromise;
+    _parseResult;
+    _result = null;
+    _session;
+    /** @internal — constructed by MeerkatClient, not directly. */
+    constructor(opts) {
+        this._sessionId = opts.sessionId;
+        this._eventQueue = opts.eventQueue;
+        this._responsePromise = opts.responsePromise;
+        this._parseResult = opts.parseResult;
+        this._session = opts.session ?? null;
+    }
+    /** The session ID for this turn. */
+    get sessionId() {
+        return this._sessionId;
+    }
+    /** The final {@link RunResult}. Available after iteration completes. */
+    get result() {
+        if (this._result === null) {
+            throw new MeerkatError("STREAM_NOT_CONSUMED", "Iterate the stream before accessing result");
+        }
+        return this._result;
+    }
+    async *[Symbol.asyncIterator]() {
+        // Race event queue items against the response promise
+        let responseDone = false;
+        let responseResult = null;
+        const responseHandler = this._responsePromise.then((result) => {
+            responseDone = true;
+            responseResult = result;
+        });
+        while (true) {
+            if (responseDone) {
+                // Drain remaining queued events
+                while (!this._eventQueue.isEmpty) {
+                    const raw = this._eventQueue.tryGet();
+                    if (raw == null)
+                        break;
+                    yield parseEvent(raw);
                 }
+                this._finalise(responseResult);
+                return;
             }
-            catch {
-                // Ignore non-JSON lines
+            // Race: next event vs response
+            const eventPromise = this._eventQueue.get();
+            const result = await Promise.race([
+                eventPromise.then((raw) => ({ kind: "event", raw })),
+                responseHandler.then(() => ({ kind: "response", raw: null })),
+            ]);
+            if (result.kind === "event") {
+                if (result.raw == null) {
+                    // Sentinel — stream ended
+                    await responseHandler;
+                    this._finalise(responseResult);
+                    return;
+                }
+                yield parseEvent(result.raw);
             }
-        });
-        rl.on("close", () => {
-            this.closed = true;
-            // Resolve any pending waiters with done
-            for (const waiter of this.waiters) {
-                waiter({ value: undefined, done: true });
+            // If response, loop back to the top which handles drain
+        }
+    }
+    /** Consume all events silently and return the final result. */
+    async collect() {
+        for await (const _ of this) {
+            // discard
+        }
+        return this.result;
+    }
+    /** Consume events, accumulate text deltas, return `[fullText, result]`. */
+    async collectText() {
+        const parts = [];
+        for await (const event of this) {
+            if (isTextDelta(event)) {
+                parts.push(event.delta);
             }
-            this.waiters = [];
-        });
+        }
+        return [parts.join(""), this.result];
     }
-    [Symbol.asyncIterator]() {
-        return {
-            next: () => {
-                if (this.buffer.length > 0) {
-                    return Promise.resolve({
-                        value: this.buffer.shift(),
-                        done: false,
-                    });
-                }
-                if (this.closed) {
-                    return Promise.resolve({
-                        value: undefined,
-                        done: true,
-                    });
-                }
-                return new Promise((resolve) => {
-                    this.waiters.push(resolve);
-                });
-            },
-        };
+    _finalise(rawResult) {
+        this._result = this._parseResult(rawResult);
+        if (!this._sessionId) {
+            this._sessionId = this._result.sessionId;
+        }
+        if (this._session) {
+            this._session._lastResult = this._result;
+        }
+    }
+}
+/**
+ * Async iterable of raw comms stream notifications emitted via `comms/stream_event`.
+ */
+export class CommsEventStream {
+    _streamId;
+    _eventQueue;
+    _onClose;
+    constructor(opts) {
+        this._streamId = opts.streamId;
+        this._eventQueue = opts.eventQueue;
+        this._onClose = opts.onClose;
+    }
+    get streamId() {
+        return this._streamId;
+    }
+    async *[Symbol.asyncIterator]() {
+        while (true) {
+            const raw = await this._eventQueue.get();
+            if (raw == null)
+                return;
+            yield raw;
+        }
+    }
+    async close() {
+        await this._onClose(this._streamId);
     }
 }
+// Re-export AsyncQueue for internal use by client
+export { AsyncQueue };
 //# sourceMappingURL=streaming.js.map

package/dist/streaming.js.map

@@ -1 +1 @@
-{"version":3,"file":"streaming.js","sourceRoot":"","sources":["../src/streaming.ts"],"names":[],"mappings":"AAAA;;GAEG;AAKH;;;;;;;;;;;;GAYG;AACH,MAAM,OAAO,WAAW;IACd,MAAM,GAAgB,EAAE,CAAC;IACzB,OAAO,GAAsD,EAAE,CAAC;IAChE,MAAM,GAAG,KAAK,CAAC;IAEvB,YAAY,EAAqB;QAC/B,EAAE,CAAC,EAAE,CAAC,MAAM,EAAE,CAAC,IAAY,EAAE,EAAE;YAC7B,IAAI,CAAC;gBACH,MAAM,IAAI,GAAG,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;gBAC9B,2CAA2C;gBAC3C,IAAI,IAAI,IAAI,IAAI;oBAAE,OAAO;gBAEzB,MAAM,MAAM,GAAG,CAAC,IAAI,CAAC,MAAM,IAAI,EAAE,CAA4B,CAAC;gBAC9D,MAAM,KAAK,GAAc;oBACvB,UAAU,EAAE,MAAM,CAAC,MAAM,CAAC,UAAU,IAAI,EAAE,CAAC;oBAC3C,QAAQ,EAAE,MAAM,CAAC,MAAM,CAAC,QAAQ,IAAI,CAAC,CAAC;oBACtC,KAAK,EAAE,CAAC,MAAM,CAAC,KAAK,IAAI,EAAE,CAA4B;oBACtD,gBAAgB,EAAE,MAAM,CAAC,MAAM,CAAC,gBAAgB,IAAI,EAAE,CAAC;iBACxD,CAAC;gBAEF,IAAI,IAAI,CAAC,OAAO,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;oBAC5B,MAAM,MAAM,GAAG,IAAI,CAAC,OAAO,CAAC,KAAK,EAAG,CAAC;oBACrC,MAAM,CAAC,EAAE,KAAK,EAAE,KAAK,EAAE,IAAI,EAAE,KAAK,EAAE,CAAC,CAAC;gBACxC,CAAC;qBAAM,CAAC;oBACN,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;gBAC1B,CAAC;YACH,CAAC;YAAC,MAAM,CAAC;gBACP,wBAAwB;YAC1B,CAAC;QACH,CAAC,CAAC,CAAC;QAEH,EAAE,CAAC,EAAE,CAAC,OAAO,EAAE,GAAG,EAAE;YAClB,IAAI,CAAC,MAAM,GAAG,IAAI,CAAC;YACnB,wCAAwC;YACxC,KAAK,MAAM,MAAM,IAAI,IAAI,CAAC,OAAO,EAAE,CAAC;gBAClC,MAAM,CAAC,EAAE,KAAK,EAAE,SAAiC,EAAE,IAAI,EAAE,IAAI,EAAE,CAAC,CAAC;YACnE,CAAC;YACD,IAAI,CAAC,OAAO,GAAG,EAAE,CAAC;QACpB,CAAC,CAAC,CAAC;IACL,CAAC;IAED,CAAC,MAAM,CAAC,aAAa,CAAC;QACpB,OAAO;YACL,IAAI,EAAE,GAAuC,EAAE;gBAC7C,IAAI,IAAI,CAAC,MAAM,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;oBAC3B,OAAO,OAAO,CAAC,OAAO,CAAC;wBACrB,KAAK,EAAE,IAAI,CAAC,MAAM,CAAC,KAAK,EAAG;wBAC3B,IAAI,EAAE,KAAK;qBACZ,CAAC,CAAC;gBACL,CAAC;gBACD,IAAI,IAAI,CAAC,MAAM,EAAE,CAAC;oBAChB,OAAO,OAAO,CAAC,OAAO,CAAC;wBACrB,KAAK,EAAE,SAAiC;wBACxC,IAAI,EAAE,IAAI;qBACX,CAAC,CAAC;gBACL,CAAC;gBACD,OAAO,IAAI,OAAO,CAAC,CAAC,OAAO,EAAE,EAAE;oBAC7B,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;gBAC7B,CAAC,CAAC,CAAC;YACL,CAAC;SACF,CAAC;IACJ,CAAC;CACF"}
+{"version":3,"file":"streaming.js","sourceRoot":"","sources":["../src/streaming.ts"],"names":[],"mappings":"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"}

package/dist/types.d.ts

@@ -0,0 +1,103 @@
+/**
+ * Public domain types for the Meerkat TypeScript SDK.
+ *
+ * These replace the `Wire*` prefixed generated types.  All fields use
+ * idiomatic camelCase.
+ */
+import type { Usage } from "./events.js";
+export type { Usage } from "./events.js";
+/** Warning emitted when structured output doesn't match a provider's schema. */
+export interface SchemaWarning {
+    readonly provider: string;
+    readonly path: string;
+    readonly message: string;
+}
+/** Runtime health snapshot for skill source resolution. */
+export interface SourceHealthSnapshot {
+    readonly state: string;
+    readonly invalidRatio: number;
+    readonly invalidCount: number;
+    readonly totalCount: number;
+    readonly failureStreak: number;
+    readonly handshakeFailed: boolean;
+}
+/** Diagnostic details for a single quarantined skill entry. */
+export interface SkillQuarantineDiagnostic {
+    readonly sourceUuid: string;
+    readonly skillId: string;
+    readonly location: string;
+    readonly errorCode: string;
+    readonly errorClass: string;
+    readonly message: string;
+    readonly firstSeenUnixSecs: number;
+    readonly lastSeenUnixSecs: number;
+}
+/** Runtime diagnostics emitted by the Rust skill subsystem. */
+export interface SkillRuntimeDiagnostics {
+    readonly sourceHealth: SourceHealthSnapshot;
+    readonly quarantined: readonly SkillQuarantineDiagnostic[];
+}
+/** Structured skill identifier (source UUID + skill name). */
+export interface SkillKey {
+    readonly sourceUuid: string;
+    readonly skillName: string;
+}
+/** A skill reference — either a {@link SkillKey} or a legacy string. */
+export type SkillRef = SkillKey | string;
+/** Ephemeral per-turn tool visibility overlay. */
+export interface TurnToolOverlay {
+    readonly allowedTools?: readonly string[];
+    readonly blockedTools?: readonly string[];
+}
+/** Result of an agent session creation or turn. */
+export interface RunResult {
+    readonly sessionId: string;
+    readonly sessionRef?: string;
+    readonly text: string;
+    readonly turns: number;
+    readonly toolCalls: number;
+    readonly usage: Usage;
+    readonly structuredOutput?: unknown;
+    readonly schemaWarnings?: readonly SchemaWarning[];
+    readonly skillDiagnostics?: SkillRuntimeDiagnostics;
+}
+/** Summary of an active session. */
+export interface SessionInfo {
+    readonly sessionId: string;
+    readonly sessionRef?: string;
+    readonly createdAt: string;
+    readonly updatedAt: string;
+    readonly messageCount: number;
+    readonly totalTokens: number;
+    readonly isActive: boolean;
+}
+/** A runtime capability and its availability status. */
+export interface Capability {
+    readonly id: string;
+    readonly description: string;
+    readonly status: string;
+}
+/** Options for creating a new session. */
+export interface SessionOptions {
+    model?: string;
+    provider?: string;
+    systemPrompt?: string;
+    maxTokens?: number;
+    outputSchema?: Record<string, unknown>;
+    structuredOutputRetries?: number;
+    hooksOverride?: Record<string, unknown>;
+    enableBuiltins?: boolean;
+    enableShell?: boolean;
+    enableSubagents?: boolean;
+    enableMemory?: boolean;
+    enableMob?: boolean;
+    hostMode?: boolean;
+    commsName?: string;
+    peerMeta?: Record<string, unknown>;
+    budgetLimits?: Record<string, unknown>;
+    providerParams?: Record<string, unknown>;
+    preloadSkills?: string[];
+    skillRefs?: SkillRef[];
+    skillReferences?: string[];
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"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"}

package/dist/types.js

@@ -0,0 +1,8 @@
+/**
+ * Public domain types for the Meerkat TypeScript SDK.
+ *
+ * These replace the `Wire*` prefixed generated types.  All fields use
+ * idiomatic camelCase.
+ */
+export {};
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;;;;GAKG"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rkat/sdk",
-  "version": "0.3.4",
+  "version": "0.4.1",
   "description": "TypeScript SDK for Meerkat agent runtime",
   "type": "module",
   "main": "./dist/index.js",

package/dist/capabilities.d.ts

@@ -1,24 +0,0 @@
-/**
- * Capability checking and method gating for the Meerkat SDK.
- */
-import type { CapabilitiesResponse } from "./generated/types.js";
-/**
- * Gates method calls by checking runtime capabilities.
- *
- * @example
- * ```ts
- * const checker = new CapabilityChecker(capabilitiesResponse);
- * checker.require("comms"); // throws if comms not available
- * ```
- */
-export declare class CapabilityChecker {
-    private capabilities;
-    constructor(response: CapabilitiesResponse);
-    /** Check if a capability is available. */
-    has(capabilityId: string): boolean;
-    /** Throw CapabilityUnavailableError if capability is not available. */
-    require(capabilityId: string): void;
-    /** List all available capability IDs. */
-    get available(): string[];
-}
-//# sourceMappingURL=capabilities.d.ts.map

package/dist/capabilities.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"capabilities.d.ts","sourceRoot":"","sources":["../src/capabilities.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,sBAAsB,CAAC;AAGjE;;;;;;;;GAQG;AACH,qBAAa,iBAAiB;IAC5B,OAAO,CAAC,YAAY,CAAsB;gBAE9B,QAAQ,EAAE,oBAAoB;IAM1C,0CAA0C;IAC1C,GAAG,CAAC,YAAY,EAAE,MAAM,GAAG,OAAO;IAIlC,uEAAuE;IACvE,OAAO,CAAC,YAAY,EAAE,MAAM,GAAG,IAAI;IASnC,yCAAyC;IACzC,IAAI,SAAS,IAAI,MAAM,EAAE,CAIxB;CACF"}

package/dist/capabilities.js

@@ -1,36 +0,0 @@
-/**
- * Capability checking and method gating for the Meerkat SDK.
- */
-import { CapabilityUnavailableError } from "./generated/errors.js";
-/**
- * Gates method calls by checking runtime capabilities.
- *
- * @example
- * ```ts
- * const checker = new CapabilityChecker(capabilitiesResponse);
- * checker.require("comms"); // throws if comms not available
- * ```
- */
-export class CapabilityChecker {
-    capabilities;
-    constructor(response) {
-        this.capabilities = new Map(response.capabilities.map((c) => [c.id, c.status]));
-    }
-    /** Check if a capability is available. */
-    has(capabilityId) {
-        return this.capabilities.get(capabilityId) === "Available";
-    }
-    /** Throw CapabilityUnavailableError if capability is not available. */
-    require(capabilityId) {
-        if (!this.has(capabilityId)) {
-            throw new CapabilityUnavailableError("CAPABILITY_UNAVAILABLE", `Capability '${capabilityId}' is not available in this runtime`);
-        }
-    }
-    /** List all available capability IDs. */
-    get available() {
-        return [...this.capabilities.entries()]
-            .filter(([, status]) => status === "Available")
-            .map(([id]) => id);
-    }
-}
-//# sourceMappingURL=capabilities.js.map

package/dist/capabilities.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"capabilities.js","sourceRoot":"","sources":["../src/capabilities.ts"],"names":[],"mappings":"AAAA;;GAEG;AAGH,OAAO,EAAE,0BAA0B,EAAE,MAAM,uBAAuB,CAAC;AAEnE;;;;;;;;GAQG;AACH,MAAM,OAAO,iBAAiB;IACpB,YAAY,CAAsB;IAE1C,YAAY,QAA8B;QACxC,IAAI,CAAC,YAAY,GAAG,IAAI,GAAG,CACzB,QAAQ,CAAC,YAAY,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,MAAM,CAAC,CAAC,CACnD,CAAC;IACJ,CAAC;IAED,0CAA0C;IAC1C,GAAG,CAAC,YAAoB;QACtB,OAAO,IAAI,CAAC,YAAY,CAAC,GAAG,CAAC,YAAY,CAAC,KAAK,WAAW,CAAC;IAC7D,CAAC;IAED,uEAAuE;IACvE,OAAO,CAAC,YAAoB;QAC1B,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,YAAY,CAAC,EAAE,CAAC;YAC5B,MAAM,IAAI,0BAA0B,CAClC,wBAAwB,EACxB,eAAe,YAAY,oCAAoC,CAChE,CAAC;QACJ,CAAC;IACH,CAAC;IAED,yCAAyC;IACzC,IAAI,SAAS;QACX,OAAO,CAAC,GAAG,IAAI,CAAC,YAAY,CAAC,OAAO,EAAE,CAAC;aACpC,MAAM,CAAC,CAAC,CAAC,EAAE,MAAM,CAAC,EAAE,EAAE,CAAC,MAAM,KAAK,WAAW,CAAC;aAC9C,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,EAAE,CAAC,CAAC;IACvB,CAAC;CACF"}

package/dist/skills.d.ts

@@ -1,41 +0,0 @@
-/**
- * Skill invocation helpers for the Meerkat SDK.
- */
-import type { MeerkatClient } from "./client.js";
-import type { WireRunResult } from "./generated/types.js";
-/**
- * Helpers for working with Meerkat skills.
- *
- * Skills are loaded by the agent from filesystem and embedded sources.
- * The agent's system prompt contains an inventory of available skills.
- * To invoke a skill, include its reference (e.g. `/shell-patterns`)
- * in the user prompt.
- *
- * @example
- * ```ts
- * const helper = new SkillHelper(client);
- * helper.requireSkills();
- * const result = await helper.invoke(sessionId, "/shell-patterns", "How do I run a background job?");
- * ```
- */
-export declare class SkillHelper {
-    private client;
-    constructor(client: MeerkatClient);
-    /** Check if the skills capability is available in this runtime. */
-    isAvailable(): boolean;
-    /** Throw if skills capability is not available. */
-    requireSkills(): void;
-    /**
-     * Invoke a skill within an existing session.
-     *
-     * The skill reference (e.g. `/shell-patterns`) is prepended to the prompt.
-     * The agent's system prompt already contains the skill inventory, so it
-     * knows how to resolve the reference.
-     */
-    invoke(sessionId: string, skillReference: string, prompt: string): Promise<WireRunResult>;
-    /**
-     * Create a new session and invoke a skill in the first turn.
-     */
-    invokeNewSession(skillReference: string, prompt: string, model?: string): Promise<WireRunResult>;
-}
-//# sourceMappingURL=skills.d.ts.map

package/dist/skills.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"skills.d.ts","sourceRoot":"","sources":["../src/skills.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AACjD,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,sBAAsB,CAAC;AAG1D;;;;;;;;;;;;;;GAcG;AACH,qBAAa,WAAW;IACtB,OAAO,CAAC,MAAM,CAAgB;gBAElB,MAAM,EAAE,aAAa;IAIjC,mEAAmE;IACnE,WAAW,IAAI,OAAO;IAItB,mDAAmD;IACnD,aAAa,IAAI,IAAI;IAUrB;;;;;;OAMG;IACG,MAAM,CACV,SAAS,EAAE,MAAM,EACjB,cAAc,EAAE,MAAM,EACtB,MAAM,EAAE,MAAM,GACb,OAAO,CAAC,aAAa,CAAC;IAMzB;;OAEG;IACG,gBAAgB,CACpB,cAAc,EAAE,MAAM,EACtB,MAAM,EAAE,MAAM,EACd,KAAK,CAAC,EAAE,MAAM,GACb,OAAO,CAAC,aAAa,CAAC;CAK1B"}

package/dist/skills.js

@@ -1,57 +0,0 @@
-/**
- * Skill invocation helpers for the Meerkat SDK.
- */
-import { CapabilityUnavailableError } from "./generated/errors.js";
-/**
- * Helpers for working with Meerkat skills.
- *
- * Skills are loaded by the agent from filesystem and embedded sources.
- * The agent's system prompt contains an inventory of available skills.
- * To invoke a skill, include its reference (e.g. `/shell-patterns`)
- * in the user prompt.
- *
- * @example
- * ```ts
- * const helper = new SkillHelper(client);
- * helper.requireSkills();
- * const result = await helper.invoke(sessionId, "/shell-patterns", "How do I run a background job?");
- * ```
- */
-export class SkillHelper {
-    client;
-    constructor(client) {
-        this.client = client;
-    }
-    /** Check if the skills capability is available in this runtime. */
-    isAvailable() {
-        return this.client.hasCapability("skills");
-    }
-    /** Throw if skills capability is not available. */
-    requireSkills() {
-        if (!this.isAvailable()) {
-            throw new CapabilityUnavailableError("CAPABILITY_UNAVAILABLE", "Skills capability is not available in this runtime. " +
-                "Build with --features skills to enable.");
-        }
-    }
-    /**
-     * Invoke a skill within an existing session.
-     *
-     * The skill reference (e.g. `/shell-patterns`) is prepended to the prompt.
-     * The agent's system prompt already contains the skill inventory, so it
-     * knows how to resolve the reference.
-     */
-    async invoke(sessionId, skillReference, prompt) {
-        this.requireSkills();
-        const fullPrompt = `${skillReference} ${prompt}`;
-        return this.client.startTurn(sessionId, fullPrompt);
-    }
-    /**
-     * Create a new session and invoke a skill in the first turn.
-     */
-    async invokeNewSession(skillReference, prompt, model) {
-        this.requireSkills();
-        const fullPrompt = `${skillReference} ${prompt}`;
-        return this.client.createSession({ prompt: fullPrompt, model });
-    }
-}
-//# sourceMappingURL=skills.js.map

package/dist/skills.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"skills.js","sourceRoot":"","sources":["../src/skills.ts"],"names":[],"mappings":"AAAA;;GAEG;AAIH,OAAO,EAAE,0BAA0B,EAAE,MAAM,uBAAuB,CAAC;AAEnE;;;;;;;;;;;;;;GAcG;AACH,MAAM,OAAO,WAAW;IACd,MAAM,CAAgB;IAE9B,YAAY,MAAqB;QAC/B,IAAI,CAAC,MAAM,GAAG,MAAM,CAAC;IACvB,CAAC;IAED,mEAAmE;IACnE,WAAW;QACT,OAAO,IAAI,CAAC,MAAM,CAAC,aAAa,CAAC,QAAQ,CAAC,CAAC;IAC7C,CAAC;IAED,mDAAmD;IACnD,aAAa;QACX,IAAI,CAAC,IAAI,CAAC,WAAW,EAAE,EAAE,CAAC;YACxB,MAAM,IAAI,0BAA0B,CAClC,wBAAwB,EACxB,sDAAsD;gBACpD,yCAAyC,CAC5C,CAAC;QACJ,CAAC;IACH,CAAC;IAED;;;;;;OAMG;IACH,KAAK,CAAC,MAAM,CACV,SAAiB,EACjB,cAAsB,EACtB,MAAc;QAEd,IAAI,CAAC,aAAa,EAAE,CAAC;QACrB,MAAM,UAAU,GAAG,GAAG,cAAc,IAAI,MAAM,EAAE,CAAC;QACjD,OAAO,IAAI,CAAC,MAAM,CAAC,SAAS,CAAC,SAAS,EAAE,UAAU,CAAC,CAAC;IACtD,CAAC;IAED;;OAEG;IACH,KAAK,CAAC,gBAAgB,CACpB,cAAsB,EACtB,MAAc,EACd,KAAc;QAEd,IAAI,CAAC,aAAa,EAAE,CAAC;QACrB,MAAM,UAAU,GAAG,GAAG,cAAc,IAAI,MAAM,EAAE,CAAC;QACjD,OAAO,IAAI,CAAC,MAAM,CAAC,aAAa,CAAC,EAAE,MAAM,EAAE,UAAU,EAAE,KAAK,EAAE,CAAC,CAAC;IAClE,CAAC;CACF"}