@caplets/core 0.19.0 → 0.20.1

package/dist/native/service.d.ts

@@ -1,6 +1,7 @@
 import type { NativeCapletsServiceResolutionInput } from "./options";
 import { resolveNativeCapletsServiceOptions } from "./options";
 import { type RemoteCapletsClient } from "./remote";
+import type { CodeModeCallableCaplet } from "../code-mode/types";
 import { type CapletsConfig } from "../config";
 import { generatedToolInputJsonSchemaForCaplet } from "../generated-tool-input-schema";
 export type NativeCapletsServiceOptions = NativeCapletsServiceResolutionInput & {
@@ -18,9 +19,14 @@ export type NativeCapletTool = {
     toolName: string;
     title: string;
     description: string;
+    codeModeRun?: boolean;
+    useWhen?: string;
+    avoidWhen?: string;
     promptGuidance: string[];
     inputSchema?: ReturnType<typeof generatedToolInputJsonSchemaForCaplet> | Record<string, unknown>;
+    outputSchema?: Record<string, unknown>;
     operationNames?: string[];
+    codeModeCaplets?: CodeModeCallableCaplet[];
 };
 export type NativeCapletsToolsChangedListener = (tools: NativeCapletTool[]) => void;
 export type NativeCapletsService = {

package/dist/native/tools.d.ts

@@ -1,4 +1,6 @@
 import type { CapletConfig } from "../config";
+export declare const nativeCodeModeToolId = "code_mode";
+export declare const nativeCodeModeToolName = "caplets__code_mode";
 export declare function nativeCapletToolName(capletId: string): string;
 export declare function nativeCapletsSystemGuidance(toolNames: string[]): string;
 export declare function nativeCapletPromptGuidance(toolName: string, caplet: CapletConfig): string[];

package/dist/native.d.ts

@@ -1,6 +1,6 @@
 export { createNativeCapletsService, type NativeCapletTool, type NativeCapletsService, type NativeCapletsServiceOptions, type NativeCapletsToolsChangedListener, } from "./native/service";
 export { registerNativeCapletsProcessCleanup, type NativeCapletsProcessCleanupOptions, } from "./native/process-cleanup";
-export { nativeCapletPromptGuidance, nativeCapletToolDescription, nativeCapletToolName, nativeCapletsSystemGuidance, } from "./native/tools";
+export { nativeCapletPromptGuidance, nativeCapletToolDescription, nativeCapletToolName, nativeCapletsSystemGuidance, nativeCodeModeToolId, nativeCodeModeToolName, } from "./native/tools";
 export { generatedToolInputSchema } from "./tools";
 export { generatedToolInputJsonSchema } from "./generated-tool-input-schema";
 export { resolveNativeCapletsServiceOptions, type NativeCapletsEnv, type NativeCapletsMode, type NativeCapletsServiceResolutionInput, type NativeRemoteAuthOptions, type NativeRemoteCapletsOptions, type ResolvedNativeCapletsServiceOptions, } from "./native/options";

package/dist/native.js

@@ -1,4 +1,4 @@
-import { a as createSdkRemoteCapletsClient, c as nativeCapletToolName, i as RemoteNativeCapletsService, l as nativeCapletsSystemGuidance, o as nativeCapletPromptGuidance, r as resolveNativeCapletsServiceOptions, s as nativeCapletToolDescription, t as createNativeCapletsService } from "./service-BXcE4Rv8.js";
+import { C as nativeCapletToolName, E as nativeCodeModeToolName, S as nativeCapletToolDescription, T as nativeCodeModeToolId, f as RemoteNativeCapletsService, h as resolveNativeCapletsServiceOptions, p as createSdkRemoteCapletsClient, t as createNativeCapletsService, w as nativeCapletsSystemGuidance, x as nativeCapletPromptGuidance } from "./service-Bsq7R0mt.js";
 import { generatedToolInputJsonSchema, generatedToolInputSchema } from "./generated-tool-input-schema.js";
 //#region src/native/process-cleanup.ts
 function registerNativeCapletsProcessCleanup(service, options = {}) {
@@ -29,4 +29,4 @@ function errorMessage(error) {
 	return error instanceof Error ? error.message : String(error);
 }
 //#endregion
-export { RemoteNativeCapletsService, createNativeCapletsService, createSdkRemoteCapletsClient, generatedToolInputJsonSchema, generatedToolInputSchema, nativeCapletPromptGuidance, nativeCapletToolDescription, nativeCapletToolName, nativeCapletsSystemGuidance, registerNativeCapletsProcessCleanup, resolveNativeCapletsServiceOptions };
+export { RemoteNativeCapletsService, createNativeCapletsService, createSdkRemoteCapletsClient, generatedToolInputJsonSchema, generatedToolInputSchema, nativeCapletPromptGuidance, nativeCapletToolDescription, nativeCapletToolName, nativeCapletsSystemGuidance, nativeCodeModeToolId, nativeCodeModeToolName, registerNativeCapletsProcessCleanup, resolveNativeCapletsServiceOptions };

package/dist/observed-output-shapes/extract.d.ts

@@ -0,0 +1,5 @@
+import { type ExtractObservedOutputShapeInput, type JsonShape, type ObservedOutputShape } from "./types";
+export declare function observeOutputShape(input: ExtractObservedOutputShapeInput): ObservedOutputShape | undefined;
+export declare function extractJsonShape(value: unknown): JsonShape | undefined;
+export declare function parseShapeableJsonText(value: unknown): unknown | undefined;
+export declare function normalizedObservableValue(result: unknown): unknown | undefined;

package/dist/observed-output-shapes/file-store.d.ts

@@ -0,0 +1,17 @@
+import { type ObservedOutputShape, type ObservedOutputShapeKey, type ObservedOutputShapePruneResult, type ObservedOutputShapeStore, type ObservedOutputShapeStoreHealth } from "./types";
+export declare class FileObservedOutputShapeStore implements ObservedOutputShapeStore {
+    private readonly cacheDir;
+    private readonly options;
+    constructor(cacheDir: string, options?: {
+        ttlMs?: number | undefined;
+        maxEntries?: number | undefined;
+    });
+    read(key: ObservedOutputShapeKey): Promise<ObservedOutputShape | undefined>;
+    write(key: ObservedOutputShapeKey, shape: ObservedOutputShape): Promise<void>;
+    prune(now?: Date): Promise<ObservedOutputShapePruneResult>;
+    health(): Promise<ObservedOutputShapeStoreHealth>;
+    private pathFor;
+    private entries;
+    private ttlMs;
+    private maxEntries;
+}

package/dist/observed-output-shapes/index.d.ts

@@ -0,0 +1,7 @@
+export { FileObservedOutputShapeStore } from "./file-store";
+export { extractJsonShape, normalizedObservableValue, observeOutputShape, parseShapeableJsonText, } from "./extract";
+export { backendFingerprint, observedOutputShapeKey, observedOutputShapeStorageKey, stableHash, } from "./key";
+export { mergeJsonShapes } from "./merge";
+export { usefulOutputSchema } from "./schema";
+export { hasTruncatedShape, shapeToTypeScript, shapeType } from "./typescript";
+export { OBSERVED_OUTPUT_SHAPE_LIMITS, OBSERVED_OUTPUT_SHAPE_VERSION, type JsonShape, type ObservedOutputShape, type ObservedOutputShapeKey, type ObservedOutputShapePruneResult, type ObservedOutputShapeStore, type ObservedOutputShapeStoreHealth, } from "./types";

package/dist/observed-output-shapes/key.d.ts

@@ -0,0 +1,14 @@
+import type { CapletConfig } from "../config";
+import { type ObservedOutputShapeKey } from "./types";
+export declare function observedOutputShapeStorageKey(key: ObservedOutputShapeKey): string;
+export declare function observedOutputShapeKey(input: {
+    scope: ObservedOutputShapeKey["scope"];
+    workspaceId?: string | undefined;
+    projectFingerprint?: string | undefined;
+    caplet: CapletConfig;
+    toolName: string;
+    toolDescriptor?: unknown;
+    outputSchema?: unknown;
+}): ObservedOutputShapeKey;
+export declare function backendFingerprint(caplet: CapletConfig): string;
+export declare function stableHash(value: unknown): string;

package/dist/observed-output-shapes/merge.d.ts

@@ -0,0 +1,2 @@
+import { type JsonShape } from "./types";
+export declare function mergeJsonShapes(left: JsonShape, right: JsonShape): JsonShape;

package/dist/observed-output-shapes/pure.d.ts

@@ -0,0 +1,5 @@
+export { extractJsonShape, normalizedObservableValue, observeOutputShape, parseShapeableJsonText, } from "./extract";
+export { mergeJsonShapes } from "./merge";
+export { usefulOutputSchema } from "./schema";
+export { hasTruncatedShape, shapeToTypeScript, shapeType } from "./typescript";
+export { OBSERVED_OUTPUT_SHAPE_LIMITS, OBSERVED_OUTPUT_SHAPE_VERSION, type JsonShape, type ObservedOutputShape, type ExtractObservedOutputShapeInput, } from "./types";

package/dist/observed-output-shapes/pure.js

@@ -0,0 +1,241 @@
+//#region src/observed-output-shapes/types.ts
+const OBSERVED_OUTPUT_SHAPE_VERSION = 1;
+const OBSERVED_OUTPUT_SHAPE_LIMITS = {
+	maxDepth: 6,
+	maxObjectFields: 40,
+	maxArrayElements: 20,
+	maxUnionVariants: 4,
+	maxTypeScriptChars: 4e3,
+	maxStoredJsonBytes: 16e3,
+	ttlMs: 720 * 60 * 60 * 1e3,
+	maxLocalEntries: 2e3
+};
+//#endregion
+//#region src/observed-output-shapes/merge.ts
+function mergeJsonShapes(left, right) {
+	if (left.kind === "unknown" || right.kind === "unknown") return { kind: "unknown" };
+	if (left.kind === right.kind) {
+		if (left.kind === "object" && right.kind === "object") return mergeObjects(left, right);
+		if (left.kind === "array" && right.kind === "array") return mergeArrays(left, right);
+		if (left.kind === "union" && right.kind === "union") return boundedUnion([...left.variants, ...right.variants]);
+		return left;
+	}
+	return boundedUnion([...left.kind === "union" ? left.variants : [left], ...right.kind === "union" ? right.variants : [right]]);
+}
+function mergeObjects(left, right) {
+	const fields = {};
+	const keys = [...new Set([...Object.keys(left.fields), ...Object.keys(right.fields)])].sort();
+	let truncated = left.truncated === true || right.truncated === true;
+	const selected = keys.slice(0, OBSERVED_OUTPUT_SHAPE_LIMITS.maxObjectFields);
+	truncated = truncated || keys.length > selected.length;
+	for (const key of selected) {
+		const leftField = left.fields[key];
+		const rightField = right.fields[key];
+		if (leftField && rightField) fields[key] = {
+			optional: true,
+			shape: mergeJsonShapes(leftField.shape, rightField.shape)
+		};
+		else fields[key] = {
+			optional: true,
+			shape: (leftField ?? rightField).shape
+		};
+	}
+	return {
+		kind: "object",
+		fields,
+		...truncated ? { truncated: true } : {}
+	};
+}
+function mergeArrays(left, right) {
+	const element = left.element && right.element ? mergeJsonShapes(left.element, right.element) : left.element ?? right.element;
+	return {
+		kind: "array",
+		...element ? { element } : {},
+		...left.truncated === true || right.truncated === true ? { truncated: true } : {}
+	};
+}
+function boundedUnion(variants) {
+	const flattened = variants.flatMap((variant) => variant.kind === "union" ? variant.variants : [variant]);
+	const unique = [];
+	for (const variant of flattened) {
+		if (variant.kind === "unknown") return { kind: "unknown" };
+		const key = JSON.stringify(variant);
+		if (!unique.some((existing) => JSON.stringify(existing) === key)) unique.push(variant);
+	}
+	if (unique.length === 1) return unique[0];
+	if (unique.length > OBSERVED_OUTPUT_SHAPE_LIMITS.maxUnionVariants) return { kind: "unknown" };
+	return {
+		kind: "union",
+		variants: unique.sort((a, b) => a.kind.localeCompare(b.kind))
+	};
+}
+//#endregion
+//#region src/observed-output-shapes/typescript.ts
+function shapeToTypeScript(shape, typeName = "ObservedOutput", maxChars = OBSERVED_OUTPUT_SHAPE_LIMITS.maxTypeScriptChars) {
+	const typeScript = `type ${typeName} = ${shapeType(shape)};`;
+	if (typeScript.length <= maxChars) return {
+		typeScript,
+		truncated: hasTruncatedShape(shape)
+	};
+	return {
+		typeScript: `type ${typeName} = unknown;`,
+		truncated: true
+	};
+}
+function shapeType(shape) {
+	switch (shape.kind) {
+		case "null": return "null";
+		case "boolean": return "boolean";
+		case "number": return "number";
+		case "string": return "string";
+		case "unknown": return "unknown";
+		case "array": return `${shape.element ? wrapArrayElement(shapeType(shape.element)) : "unknown"}[]`;
+		case "object": return objectType(shape);
+		case "union": return unionType(shape.variants);
+	}
+}
+function hasTruncatedShape(shape) {
+	if ("truncated" in shape && shape.truncated === true) return true;
+	if (shape.kind === "array") return shape.element ? hasTruncatedShape(shape.element) : false;
+	if (shape.kind === "object") return Object.values(shape.fields).some((field) => hasTruncatedShape(field.shape));
+	if (shape.kind === "union") return shape.variants.some((variant) => hasTruncatedShape(variant));
+	return false;
+}
+function objectType(shape) {
+	const entries = Object.entries(shape.fields);
+	if (entries.length === 0) return "Record<string, unknown>";
+	return `{ ${entries.map(([key, field]) => `${propertyName(key)}?: ${shapeType(field.shape)};`).join(" ")} }`;
+}
+function unionType(variants) {
+	const rendered = [...new Set(variants.map((variant) => shapeType(variant)))];
+	return rendered.length === 0 ? "unknown" : rendered.join(" | ");
+}
+function wrapArrayElement(value) {
+	return value.includes(" | ") ? `(${value})` : value;
+}
+function propertyName(key) {
+	return /^[A-Za-z_$][\w$]*$/u.test(key) ? key : JSON.stringify(key);
+}
+//#endregion
+//#region src/observed-output-shapes/extract.ts
+function observeOutputShape(input) {
+	const shape = extractJsonShape(input.value);
+	if (!shape) return void 0;
+	const merged = input.existing ? mergeJsonShapes(input.existing.jsonShape, shape) : shape;
+	const emitted = shapeToTypeScript(merged);
+	const observed = {
+		version: 1,
+		source: "observed",
+		observedAt: (input.now ?? /* @__PURE__ */ new Date()).toISOString(),
+		sampleCount: (input.existing?.sampleCount ?? 0) + 1,
+		typeScript: emitted.typeScript,
+		jsonShape: merged,
+		truncated: emitted.truncated || hasTruncatedShape(merged)
+	};
+	return storedBytes(observed) > OBSERVED_OUTPUT_SHAPE_LIMITS.maxStoredJsonBytes ? {
+		...observed,
+		typeScript: "type ObservedOutput = unknown;",
+		jsonShape: { kind: "unknown" },
+		truncated: true
+	} : observed;
+}
+function extractJsonShape(value) {
+	if (!isShapeableJsonRoot(value)) return void 0;
+	return shapeFor(value, 0);
+}
+function parseShapeableJsonText(value) {
+	if (!isPlainObject$1(value) || !Array.isArray(value.content) || value.content.length !== 1) return;
+	const [item] = value.content;
+	if (!isPlainObject$1(item) || item.type !== "text" || typeof item.text !== "string") return;
+	const text = item.text.trim();
+	if (!text || !text.startsWith("{") && !text.startsWith("[")) return void 0;
+	try {
+		const parsed = JSON.parse(text);
+		return isShapeableJsonRoot(parsed) ? parsed : void 0;
+	} catch {
+		return;
+	}
+}
+function normalizedObservableValue(result) {
+	if (isPlainObject$1(result)) {
+		const structured = result.structuredContent;
+		if (structured !== void 0) {
+			if (isPlainObject$1(structured) && "caplets" in structured && "result" in structured) return isShapeableJsonRoot(structured.result) ? structured.result : void 0;
+			return isShapeableJsonRoot(structured) ? structured : void 0;
+		}
+	}
+	return parseShapeableJsonText(result);
+}
+function shapeFor(value, depth) {
+	if (depth >= OBSERVED_OUTPUT_SHAPE_LIMITS.maxDepth) return { kind: "unknown" };
+	if (value === null) return { kind: "null" };
+	if (typeof value === "boolean") return { kind: "boolean" };
+	if (typeof value === "number") return { kind: "number" };
+	if (typeof value === "string") return { kind: "string" };
+	if (Array.isArray(value)) return arrayShape(value, depth);
+	if (isPlainObject$1(value)) return objectShape(value, depth);
+	return { kind: "unknown" };
+}
+function arrayShape(value, depth) {
+	const sampled = value.slice(0, OBSERVED_OUTPUT_SHAPE_LIMITS.maxArrayElements);
+	let element;
+	for (const item of sampled) {
+		const itemShape = shapeFor(item, depth + 1);
+		element = element ? mergeJsonShapes(element, itemShape) : itemShape;
+	}
+	return {
+		kind: "array",
+		...element ? { element } : {},
+		...value.length > sampled.length ? { truncated: true } : {}
+	};
+}
+function objectShape(value, depth) {
+	const keys = Object.keys(value).sort();
+	const selected = keys.slice(0, OBSERVED_OUTPUT_SHAPE_LIMITS.maxObjectFields);
+	const fields = {};
+	for (const key of selected) fields[key] = {
+		optional: true,
+		shape: shapeFor(value[key], depth + 1)
+	};
+	return {
+		kind: "object",
+		fields,
+		...keys.length > selected.length ? { truncated: true } : {}
+	};
+}
+function isShapeableJsonRoot(value) {
+	return Array.isArray(value) || isPlainObject$1(value);
+}
+function isPlainObject$1(value) {
+	return Boolean(value) && typeof value === "object" && !Array.isArray(value);
+}
+function storedBytes(value) {
+	return new TextEncoder().encode(JSON.stringify(value)).byteLength;
+}
+//#endregion
+//#region src/observed-output-shapes/schema.ts
+function usefulOutputSchema(schema) {
+	if (!isPlainObject(schema)) return false;
+	if (Object.keys(schema).length === 0) return false;
+	if ("const" in schema || Array.isArray(schema.enum)) return true;
+	const type = schema.type;
+	if (Array.isArray(type)) return type.some((item) => usefulOutputSchema({
+		...schema,
+		type: item
+	}));
+	if (type === "object" || isPlainObject(schema.properties)) {
+		if (isPlainObject(schema.properties) && Object.keys(schema.properties).length > 0) return true;
+		if (schema.additionalProperties === false) return true;
+		if (isPlainObject(schema.additionalProperties)) return true;
+		return false;
+	}
+	if (type === "array") return usefulOutputSchema(schema.items);
+	if (typeof type === "string") return true;
+	if (Array.isArray(schema.oneOf) || Array.isArray(schema.anyOf) || Array.isArray(schema.allOf)) return true;
+	return false;
+}
+function isPlainObject(value) {
+	return Boolean(value) && typeof value === "object" && !Array.isArray(value);
+}
+//#endregion
+export { OBSERVED_OUTPUT_SHAPE_LIMITS, OBSERVED_OUTPUT_SHAPE_VERSION, extractJsonShape, hasTruncatedShape, mergeJsonShapes, normalizedObservableValue, observeOutputShape, parseShapeableJsonText, shapeToTypeScript, shapeType, usefulOutputSchema };

package/dist/observed-output-shapes/schema.d.ts

@@ -0,0 +1 @@
+export declare function usefulOutputSchema(schema: unknown): boolean;

package/dist/observed-output-shapes/types.d.ts

@@ -0,0 +1,84 @@
+import type { JsonValue } from "../code-mode/types";
+export declare const OBSERVED_OUTPUT_SHAPE_VERSION = 1;
+export declare const OBSERVED_OUTPUT_SHAPE_LIMITS: {
+    readonly maxDepth: 6;
+    readonly maxObjectFields: 40;
+    readonly maxArrayElements: 20;
+    readonly maxUnionVariants: 4;
+    readonly maxTypeScriptChars: 4000;
+    readonly maxStoredJsonBytes: 16000;
+    readonly ttlMs: number;
+    readonly maxLocalEntries: 2000;
+};
+export type JsonShape = {
+    kind: "null";
+} | {
+    kind: "boolean";
+} | {
+    kind: "number";
+} | {
+    kind: "string";
+} | {
+    kind: "unknown";
+} | {
+    kind: "array";
+    element?: JsonShape;
+    truncated?: boolean;
+} | {
+    kind: "object";
+    fields: Record<string, {
+        optional: boolean;
+        shape: JsonShape;
+    }>;
+    truncated?: boolean;
+} | {
+    kind: "union";
+    variants: JsonShape[];
+};
+export type ObservedOutputShape = {
+    version: 1;
+    source: "observed";
+    observedAt: string;
+    sampleCount: number;
+    typeScript: string;
+    jsonShape: JsonShape;
+    truncated: boolean;
+};
+export type ObservedOutputShapeKey = {
+    scope: "local" | "self_hosted" | "cloud";
+    workspaceId?: string | undefined;
+    projectFingerprint?: string | undefined;
+    capletId: string;
+    backendKind: string;
+    backendFingerprint: string;
+    toolName: string;
+    toolDescriptorHash?: string | undefined;
+    outputSchemaHash?: string | undefined;
+    resultVersion: 1;
+};
+export type ObservedOutputShapePruneResult = {
+    removed: number;
+    remaining: number;
+};
+export type ObservedOutputShapeStoreHealth = {
+    path?: string | undefined;
+    readable: boolean;
+    writable: boolean;
+    entryCount?: number | undefined;
+    prune?: ObservedOutputShapePruneResult | undefined;
+    error?: string | undefined;
+};
+export interface ObservedOutputShapeStore {
+    read(key: ObservedOutputShapeKey): Promise<ObservedOutputShape | undefined>;
+    write(key: ObservedOutputShapeKey, shape: ObservedOutputShape): Promise<void>;
+    prune?(now?: Date): Promise<ObservedOutputShapePruneResult>;
+    health?(): Promise<ObservedOutputShapeStoreHealth>;
+}
+export type ExtractObservedOutputShapeInput = {
+    value: unknown;
+    now?: Date | undefined;
+    existing?: ObservedOutputShape | undefined;
+};
+export type ExtractedJsonValue = Extract<JsonValue, unknown[] | {
+    [key: string]: JsonValue;
+}>;

package/dist/observed-output-shapes/typescript.d.ts

@@ -0,0 +1,7 @@
+import { type JsonShape } from "./types";
+export declare function shapeToTypeScript(shape: JsonShape, typeName?: string, maxChars?: number): {
+    typeScript: string;
+    truncated: boolean;
+};
+export declare function shapeType(shape: JsonShape): string;
+export declare function hasTruncatedShape(shape: JsonShape): boolean;