@keemakr/agent-sdk 0.15.0 → 0.16.0-dev-20260924112033

package/dist/canvases.d.ts

@@ -0,0 +1,49 @@
+/** Any card. Open by construction: a client may render a `type` this SDK predates. */
+export type Canvas = {
+    type: string;
+} & Record<string, unknown>;
+/** A titled markdown document — a run summary, a written answer, a table of results. */
+export interface ReportCanvas {
+    type: 'report';
+    markdown: string;
+    title?: string;
+}
+/**
+ * A picture, shown inline in the chat.
+ *
+ * Prefer this over putting the URL in `reply`. Clients do preview a URL a reply merely names, but
+ * the card is the better copy on both sides of the wire: core validates the URL at ingestion, the
+ * card carries its own alt text and dimensions, and a client that shows the card suppresses the
+ * duplicate preview of the same URL in your prose.
+ */
+export interface ImageCanvas {
+    type: 'image';
+    url: string;
+    /** What the picture shows. This is the fallback text, so write it for someone who cannot see it. */
+    alt?: string;
+    /** The prompt that produced it, when it was generated. Shown as a caption. */
+    prompt?: string;
+    width?: number;
+    height?: number;
+}
+/**
+ * Build an image card, refusing a URL that would not reach a reader.
+ *
+ * Two different things drop a URL on the way, and both are silent from here — the delegation
+ * succeeds, the card never appears, and nothing in your logs says why:
+ *
+ *  - Core's ingestion default-denies anything that is not http(s). A `data:`, `file:` or
+ *    `javascript:` URL is never persisted.
+ *  - The dashboards are served over https, so an `http:` image is mixed content the browser
+ *    refuses after upgrading the request. Core stores it happily; nobody ever sees it.
+ *
+ * So this is stricter than ingestion on purpose: https only. Throwing at construction turns a
+ * picture that quietly never arrives into an error where the mistake was made.
+ */
+export declare function imageCanvas(input: {
+    url: string;
+    alt?: string;
+    prompt?: string;
+    width?: number;
+    height?: number;
+}): ImageCanvas;

package/dist/canvases.js

@@ -0,0 +1,47 @@
+// Canvases — the inline cards an agent's reply can carry back to the Operator.
+//
+// A department returns `canvases` on its DelegationResult and core persists each one as a content
+// block the clients render. The wire is deliberately permissive (core validates a canvas is
+// `{ type, … }` and nothing more, so a client that knows a card can render it even if core has
+// never heard of it), which is right for the pipe and unhelpful when you are writing the agent:
+// nothing tells you a card exists, what it is called, or which fields it needs.
+//
+// So this is a floor, not a schema. The types name the cards clients render today, and the helper
+// refuses the one mistake that is silent end to end — a URL core will drop at ingestion, leaving
+// an agent that believes it delivered a picture and a user who sees nothing.
+/**
+ * Build an image card, refusing a URL that would not reach a reader.
+ *
+ * Two different things drop a URL on the way, and both are silent from here — the delegation
+ * succeeds, the card never appears, and nothing in your logs says why:
+ *
+ *  - Core's ingestion default-denies anything that is not http(s). A `data:`, `file:` or
+ *    `javascript:` URL is never persisted.
+ *  - The dashboards are served over https, so an `http:` image is mixed content the browser
+ *    refuses after upgrading the request. Core stores it happily; nobody ever sees it.
+ *
+ * So this is stricter than ingestion on purpose: https only. Throwing at construction turns a
+ * picture that quietly never arrives into an error where the mistake was made.
+ */
+export function imageCanvas(input) {
+    let parsed;
+    try {
+        parsed = new URL(input.url);
+    }
+    catch {
+        throw new TypeError(`imageCanvas: not a URL: ${input.url}`);
+    }
+    if (parsed.protocol !== 'https:') {
+        throw new TypeError(`imageCanvas: images must be https; "${parsed.protocol}" either never reaches the ` +
+            'transcript (core drops non-http(s) at ingestion) or is blocked as mixed content by the ' +
+            'browser that would show it');
+    }
+    return {
+        type: 'image',
+        url: input.url,
+        ...(input.alt === undefined ? {} : { alt: input.alt }),
+        ...(input.prompt === undefined ? {} : { prompt: input.prompt }),
+        ...(input.width === undefined ? {} : { width: input.width }),
+        ...(input.height === undefined ? {} : { height: input.height }),
+    };
+}

package/dist/index.d.ts

@@ -3,3 +3,4 @@ export { verifyGrant, type VerifiedGrant } from './verify-grant.js';
 export { useKee, MemoryConflictError, RecordConflictError, RecordValidationError, type Kee, type KeeConnection, type KeeContext, type KeeError, type KeeMemory, type KeeRecords, type KeeKb, type KBHit, type KeeTools, type KeeConfig, type MemoryEntry, type MemorySearchHit, type RecordEntry, } from './client.js';
 export { keemakrToolDirectory } from './tool-directory.js';
 export { refreshGrant, REFRESH_THRESHOLD_SECONDS } from './refresh.js';
+export { imageCanvas, type Canvas, type ImageCanvas, type ReportCanvas } from './canvases.js';

package/dist/index.js

@@ -13,3 +13,4 @@ export { verifyGrant } from './verify-grant.js';
 export { useKee, MemoryConflictError, RecordConflictError, RecordValidationError, } from './client.js';
 export { keemakrToolDirectory } from './tool-directory.js';
 export { refreshGrant, REFRESH_THRESHOLD_SECONDS } from './refresh.js';
+export { imageCanvas } from './canvases.js';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@keemakr/agent-sdk",
-  "version": "0.15.0",
+  "version": "0.16.0-dev-20260924112033",
   "description": "The floor for keemakr marketplace agents: verify the capability grant and reach tenant connections, memory, and shared platform tools through keemakr-core — without holding raw secrets or resolving the tenant yourself.",
   "license": "MIT",
   "type": "module",