@caplets/core 0.18.9 → 0.20.0

package/dist/project-binding/session.d.ts

@@ -0,0 +1,82 @@
+import type { ResolvedCapletsRemote } from "../remote/options";
+import type { BindingTerminalReason, ProjectBindingState, ProjectBindingSyncState } from "./types";
+import { type ProjectBindingWebSocketFactory } from "./transport";
+export type ProjectBindingSessionEvent = {
+    type: "state";
+    state: ProjectBindingState;
+    message?: string | undefined;
+    requestId?: string;
+} | {
+    type: "ready";
+    bindingId: string;
+    sessionId: string;
+    projectRoot: string;
+    projectFingerprint: string;
+    webSocketUrl: string;
+    requestId?: string | undefined;
+} | {
+    type: "reconnecting";
+    bindingId: string;
+    sessionId: string;
+    attempt: number;
+    reason: string;
+    requestId?: string | undefined;
+} | {
+    type: "heartbeat";
+    bindingId: string;
+    sessionId: string;
+    state: ProjectBindingState;
+} | {
+    type: "ended";
+    bindingId?: string;
+    sessionId?: string;
+    reason: BindingTerminalReason;
+};
+export type ProjectBindingSocketServerMessage = {
+    type: "state";
+    state: ProjectBindingState;
+    syncState: ProjectBindingSyncState;
+    requestId?: string | undefined;
+} | {
+    type: "ready";
+    bindingId: string;
+    sessionId: string;
+    syncState: ProjectBindingSyncState;
+    requestId?: string | undefined;
+} | {
+    type: "blocked";
+    reason: BindingTerminalReason;
+} | {
+    type: "ended";
+    reason: BindingTerminalReason;
+};
+export type ProjectBindingSocketClientMessage = {
+    type: "heartbeat";
+    bindingId: string;
+    sessionId: string;
+    state: ProjectBindingState;
+    syncState: ProjectBindingSyncState;
+} | {
+    type: "end";
+    bindingId: string;
+    sessionId: string;
+    reason: BindingTerminalReason;
+};
+export type RunProjectBindingSessionInput = {
+    projectRoot: string;
+    remote: ResolvedCapletsRemote;
+    fetch?: typeof fetch | undefined;
+    webSocketFactory?: ProjectBindingWebSocketFactory | undefined;
+    signal?: AbortSignal | undefined;
+    heartbeatIntervalMs?: number | undefined;
+    onEvent?: ((event: ProjectBindingSessionEvent) => void) | undefined;
+};
+export declare function runProjectBindingSession(input: RunProjectBindingSessionInput): Promise<{
+    ok: true;
+    bindingId: string;
+    sessionId: string;
+    projectRoot: string;
+    projectFingerprint: string;
+    webSocketUrl: string;
+    ended: true;
+}>;

package/dist/project-binding/sync-filter.d.ts

@@ -0,0 +1,19 @@
+export type ProjectSyncExclusionSource = "hard_denylist" | "gitignore" | "capletsignore";
+export type ProjectSyncExclusionSummary = {
+    source: ProjectSyncExclusionSource;
+    pattern: string;
+    count: number;
+};
+export type ProjectSyncManifestFile = {
+    relativePath: string;
+    sizeBytes: number;
+};
+export type ProjectSyncManifest = {
+    projectRoot: string;
+    files: ProjectSyncManifestFile[];
+    totalBytes: number;
+    exclusionSummary: ProjectSyncExclusionSummary[];
+};
+export declare function buildProjectSyncManifest(input: {
+    projectRoot: string;
+}): ProjectSyncManifest;

package/dist/project-binding/sync-size.d.ts

@@ -0,0 +1,27 @@
+import type { ProjectBindingErrorCode } from "./errors";
+import type { ProjectSyncManifestFile } from "./sync-filter";
+export type ProjectSyncTier = "free" | "plus" | "pro" | "enterprise" | "self_hosted";
+export type ProjectSyncLimits = {
+    maxSingleFileBytes: number;
+    maxProjectBytes: number;
+};
+export declare const DEFAULT_SYNC_LIMITS: Record<ProjectSyncTier, ProjectSyncLimits>;
+export type ProjectSyncSizeResult = {
+    ok: true;
+    totalBytes: number;
+    maxSingleFileBytes: number;
+    maxProjectBytes: number;
+} | {
+    ok: false;
+    code: ProjectBindingErrorCode;
+    totalBytes: number;
+    maxSingleFileBytes: number;
+    maxProjectBytes: number;
+    largestFileBytes?: number | undefined;
+    recoveryCommand: string;
+};
+export declare function enforceProjectSyncSizeLimits(input: {
+    tier: ProjectSyncTier;
+    files: ProjectSyncManifestFile[];
+    limits?: Partial<ProjectSyncLimits> | undefined;
+}): ProjectSyncSizeResult;

package/dist/project-binding/transport.d.ts

@@ -0,0 +1,21 @@
+export type ProjectBindingSocketEvent = {
+    data?: unknown;
+    code?: number | undefined;
+    reason?: string | undefined;
+};
+export type ProjectBindingWebSocket = {
+    readonly readyState?: number;
+    send(data: string): void;
+    close(code?: number, reason?: string): void;
+    addEventListener?: (type: "open" | "message" | "close" | "error", listener: (event: ProjectBindingSocketEvent) => void, options?: {
+        once?: boolean;
+    }) => void;
+    removeEventListener?: (type: "open" | "message" | "close" | "error", listener: (event: ProjectBindingSocketEvent) => void) => void;
+    onopen?: ((event: ProjectBindingSocketEvent) => void) | null;
+    onmessage?: ((event: ProjectBindingSocketEvent) => void) | null;
+    onclose?: ((event: ProjectBindingSocketEvent) => void) | null;
+    onerror?: ((event: ProjectBindingSocketEvent) => void) | null;
+};
+export type ProjectBindingWebSocketFactory = (url: string, protocols?: string | string[] | undefined) => ProjectBindingWebSocket;
+export declare const PROJECT_BINDING_SOCKET_OPEN = 1;
+export declare function defaultProjectBindingWebSocketFactory(url: string, protocols?: string | string[] | undefined): ProjectBindingWebSocket;

package/dist/project-binding/types.d.ts

@@ -0,0 +1,31 @@
+export type ProjectBindingState = "not_attached" | "attaching" | "syncing" | "ready" | "degraded" | "blocked" | "offline" | "cleaning_up" | "ended" | "expired";
+export declare const PROJECT_BINDING_STATES: readonly ProjectBindingState[];
+export declare const PROJECT_BINDING_SYNC_STATES: readonly ["not_started", "pending", "syncing", "idle", "failed"];
+export type ProjectBindingSyncState = (typeof PROJECT_BINDING_SYNC_STATES)[number];
+export type BindingTerminalReason = {
+    code: import("./errors").ProjectBindingErrorCode | "interrupted" | "completed";
+    message: string;
+    recoveryCommand?: string | undefined;
+    requestId?: string | undefined;
+};
+export type ProjectBindingLease = {
+    bindingId: string;
+    projectFingerprint: string;
+    state: ProjectBindingState;
+    active: boolean;
+    updatedAt: string;
+    expiresAt?: string;
+    diagnosticCode?: string;
+};
+export type ProjectBindingWorkspaceMetadata = {
+    projectFingerprint: string;
+    projectRoot: string;
+    createdAt: string;
+    lastActiveAt: string;
+};
+export type ProjectBindingSetupReceipt = {
+    capletId: string;
+    status: "succeeded" | "failed" | "skipped";
+    recordedAt?: string;
+    contentHash?: string;
+};

package/dist/project-binding/workspaces.d.ts

@@ -0,0 +1,60 @@
+import type { ProjectBindingLease, ProjectBindingSetupReceipt } from "./types";
+type PathEnv = Partial<Record<"XDG_STATE_HOME" | "LOCALAPPDATA", string>>;
+export type ProjectBindingWorkspaceRootOptions = {
+    env?: PathEnv;
+    platform?: NodeJS.Platform;
+    homedir?: string;
+    root?: string;
+};
+export type ProjectBindingWorkspacePaths = {
+    projectFingerprint: string;
+    root: string;
+    project: string;
+    metadata: string;
+    leases: string;
+    setup: string;
+    setupReceipts: string;
+    lease(bindingId: string): string;
+};
+export type ProjectBindingWorkspaceStoreOptions = ProjectBindingWorkspaceRootOptions & {
+    now?: () => Date;
+    staleLeaseTtlMs?: number;
+    inactiveWorkspaceTtlMs?: number;
+    softDiskCapBytes?: number;
+    workspaceSizeBytes?: (paths: ProjectBindingWorkspacePaths) => number;
+};
+export type EnsureProjectBindingWorkspaceInput = {
+    projectFingerprint: string;
+    projectRoot: string;
+    lastActiveAt?: string;
+    createdAt?: string;
+};
+export type ProjectBindingCleanupResult = {
+    expiredLeases: string[];
+    deletedWorkspaces: string[];
+    retainedWorkspaces: string[];
+};
+export declare function projectBindingWorkspaceRoot(options?: ProjectBindingWorkspaceRootOptions): string;
+export declare function projectBindingWorkspacePaths(projectFingerprint: string, options?: ProjectBindingWorkspaceRootOptions): ProjectBindingWorkspacePaths;
+export declare class ProjectBindingWorkspaceStore {
+    private readonly options;
+    private readonly root;
+    private readonly now;
+    private readonly staleLeaseTtlMs;
+    private readonly inactiveWorkspaceTtlMs;
+    private readonly softDiskCapBytes;
+    private readonly workspaceSizeBytes;
+    constructor(options?: ProjectBindingWorkspaceStoreOptions);
+    paths(projectFingerprint: string): ProjectBindingWorkspacePaths;
+    ensureWorkspace(input: EnsureProjectBindingWorkspaceInput): Promise<ProjectBindingWorkspacePaths>;
+    writeLease(lease: ProjectBindingLease): Promise<void>;
+    listLeases(projectFingerprint: string): Promise<ProjectBindingLease[]>;
+    writeSetupReceipts(projectFingerprint: string, receipts: ProjectBindingSetupReceipt[]): Promise<void>;
+    cleanup(): Promise<ProjectBindingCleanupResult>;
+    private readMetadata;
+    private workspacePaths;
+    private leasesFor;
+    private isStaleLease;
+    private isInactiveWorkspace;
+}
+export {};

package/dist/project-binding.js

@@ -0,0 +1,22 @@
+//#region src/project-binding/types.ts
+const PROJECT_BINDING_STATES = [
+	"not_attached",
+	"attaching",
+	"syncing",
+	"ready",
+	"degraded",
+	"blocked",
+	"offline",
+	"cleaning_up",
+	"ended",
+	"expired"
+];
+const PROJECT_BINDING_SYNC_STATES = [
+	"not_started",
+	"pending",
+	"syncing",
+	"idle",
+	"failed"
+];
+//#endregion
+export { PROJECT_BINDING_STATES, PROJECT_BINDING_SYNC_STATES };

package/dist/redaction.d.ts

@@ -0,0 +1,14 @@
+export declare const SECRET_KEY_PATTERN: RegExp;
+export declare const SECRET_TEXT_PATTERNS: readonly [RegExp, RegExp, RegExp];
+export type RedactionResult = {
+    text: string;
+    redacted: boolean;
+};
+export type RedactionOptions = {
+    patterns?: readonly RegExp[] | undefined;
+    additionalSecrets?: readonly string[] | undefined;
+    replacement?: string | undefined;
+};
+export declare function isSecretKey(key: string): boolean;
+export declare function redactSecretText(value: string, options?: RedactionOptions): RedactionResult;
+export declare function redactUnknownSecrets<T>(value: T, options?: RedactionOptions): T;

package/dist/redaction.js

@@ -0,0 +1,30 @@
+//#region src/redaction.ts
+const SECRET_KEY_PATTERN = /(token|secret|authorization|auth|api[-_]?key|password|credential|clientsecret|client_secret|code|refresh)/iu;
+const SECRET_TEXT_PATTERNS = [
+	/(Authorization:\s*Bearer\s+)[0-9A-Za-z._~+/=-]+/giu,
+	/(bearer\s+)[a-z0-9._~+/=-]+/giu,
+	/([?&](?:access_token|refresh_token|token|code)=)[^&\s]+/giu
+];
+function isSecretKey(key) {
+	return SECRET_KEY_PATTERN.test(key);
+}
+function redactSecretText(value, options = {}) {
+	const replacement = options.replacement ?? "[REDACTED]";
+	let text = value;
+	for (const pattern of [...options.patterns ?? [], ...SECRET_TEXT_PATTERNS]) text = text.replace(pattern, (...args) => {
+		return `${typeof args[1] === "string" ? args[1] : ""}${replacement}`;
+	});
+	for (const secret of options.additionalSecrets?.filter(Boolean) ?? []) text = text.split(secret).join(replacement);
+	return {
+		text,
+		redacted: text !== value
+	};
+}
+function redactUnknownSecrets(value, options = {}) {
+	if (typeof value === "string") return redactSecretText(value, options).text;
+	if (Array.isArray(value)) return value.map((item) => redactUnknownSecrets(item, options));
+	if (!value || typeof value !== "object") return value;
+	return Object.fromEntries(Object.entries(value).map(([key, entry]) => [key, isSecretKey(key) ? "[REDACTED]" : redactUnknownSecrets(entry, options)]));
+}
+//#endregion
+export { SECRET_KEY_PATTERN, SECRET_TEXT_PATTERNS, isSecretKey, redactSecretText, redactUnknownSecrets };

package/dist/registry.d.ts

@@ -6,6 +6,8 @@ export type CapletServerSummary = {
     id: string;
     name: string;
     description: string;
+    useWhen?: string;
+    avoidWhen?: string;
     disabled?: boolean;
     status: ServerStatus;
     lastError?: SafeErrorSummary;
@@ -14,6 +16,8 @@ export type CapletServerDetail = {
     id: string;
     name: string;
     description: string;
+    useWhen?: string;
+    avoidWhen?: string;
     tags?: string[];
     backend: {
         type: "mcp";

package/dist/remote/options.d.ts

@@ -0,0 +1,44 @@
+export type CapletsRemoteEnv = Partial<Record<"CAPLETS_MODE" | "CAPLETS_REMOTE_URL" | "CAPLETS_REMOTE_USER" | "CAPLETS_REMOTE_PASSWORD" | "CAPLETS_REMOTE_TOKEN" | "CAPLETS_REMOTE_WORKSPACE" | "CAPLETS_SERVER_URL", string>>;
+export type CapletsRemoteModeInput = {
+    mode?: string;
+    remoteUrl?: string;
+};
+export type CapletsRemoteMode = "local" | "remote" | "cloud";
+export type CapletsRemoteInput = {
+    url?: string;
+    user?: string;
+    password?: string;
+    token?: string;
+    workspace?: string;
+    fetch?: typeof fetch;
+};
+export type CapletsRemoteAuth = {
+    type: "none";
+    user: string;
+} | {
+    type: "basic";
+    user: string;
+    password: string;
+} | {
+    type: "bearer";
+    token: string;
+};
+export type ResolvedCapletsRemote = {
+    baseUrl: URL;
+    mcpUrl: URL;
+    controlUrl: URL;
+    healthUrl: URL;
+    projectBindingWebSocketUrl: URL;
+    auth: CapletsRemoteAuth;
+    requestInit: RequestInit;
+    workspace?: string | undefined;
+    fetch?: typeof fetch;
+};
+export declare function resolveRemoteMode(input?: CapletsRemoteModeInput, env?: CapletsRemoteEnv): {
+    mode: CapletsRemoteMode;
+};
+export declare function resolveCapletsRemote(input?: CapletsRemoteInput, env?: CapletsRemoteEnv): ResolvedCapletsRemote;
+export declare function resolveHostedCloudRemote(input?: CapletsRemoteInput, env?: CapletsRemoteEnv): ResolvedCapletsRemote;
+export declare function hostedCloudWorkspaceFromRemoteUrl(value: string): string | undefined;
+export declare function projectBindingWebSocketUrlForBase(baseUrl: URL): URL;
+export declare function isCapletsCloudUrl(value: string): boolean;

package/dist/remote/selection.d.ts

@@ -0,0 +1,26 @@
+import { type CloudAuthCredentials } from "../cloud-auth/store";
+import { type ResolvedCapletsRemote } from "./options";
+export type RemoteSelectionInput = {
+    mode?: string;
+    remoteUrl?: string;
+    user?: string;
+    password?: string;
+    token?: string;
+    workspace?: string;
+    fetch?: typeof fetch;
+};
+export type ResolvedRemoteSelection = {
+    kind: "self_hosted_remote";
+    remote: ResolvedCapletsRemote;
+} | {
+    kind: "hosted_cloud";
+    remote: ResolvedCapletsRemote;
+    selectedWorkspace: string;
+    credentials: CloudAuthCredentials;
+    cloudPresence: {
+        url: URL;
+        accessToken: string;
+        workspaceId: string;
+    };
+};
+export declare function resolveRemoteSelection(input?: RemoteSelectionInput, env?: Record<string, string | undefined>): Promise<ResolvedRemoteSelection>;

package/dist/remote-control/types.d.ts

@@ -1,5 +1,5 @@
 import type { CapletsErrorCode } from "../errors";
-export type RemoteCliCommand = "list" | "inspect" | "check_backend" | "list_tools" | "search_tools" | "get_tool" | "call_tool" | "list_resources" | "search_resources" | "list_resource_templates" | "read_resource" | "list_prompts" | "search_prompts" | "get_prompt" | "complete" | "init" | "add" | "install" | "complete_cli" | "auth_login_start" | "auth_login_complete" | "auth_logout" | "auth_list";
+export type RemoteCliCommand = "list" | "inspect" | "check" | "tools" | "search_tools" | "describe_tool" | "call_tool" | "resources" | "search_resources" | "resource_templates" | "read_resource" | "prompts" | "search_prompts" | "get_prompt" | "complete" | "init" | "add" | "install" | "complete_cli" | "auth_login_start" | "auth_login_complete" | "auth_logout" | "auth_list";
 export type RemoteCliRequest = {
     command: RemoteCliCommand;
     arguments: Record<string, unknown>;

package/dist/runtime-plan/features.d.ts

@@ -0,0 +1,7 @@
+import type { CapletConfig, RuntimeFeature } from "../config-runtime";
+import type { RuntimeFeatureProvenance } from "./types";
+export type RuntimeFeatureInference = {
+    features: RuntimeFeature[];
+    provenance: RuntimeFeatureProvenance[];
+};
+export declare function inferRuntimeFeatures(caplet: CapletConfig | Record<string, unknown>): RuntimeFeatureInference;

package/dist/runtime-plan/index.d.ts

@@ -0,0 +1,4 @@
+export * from "./types";
+export * from "./features";
+export * from "./resources";
+export * from "./planner";

package/dist/runtime-plan/planner.d.ts

@@ -0,0 +1,5 @@
+import type { CapletConfig } from "../config-runtime";
+import type { CapletRuntimePlan, RuntimePlanOptions, RuntimeRouteKind } from "./types";
+export declare function planCapletRuntimeRoutes(caplets: Array<CapletConfig | Record<string, unknown>>, options?: RuntimePlanOptions): CapletRuntimePlan[];
+export declare function planCapletRuntimeRoute(caplet: CapletConfig | Record<string, unknown>, options?: RuntimePlanOptions): CapletRuntimePlan;
+export declare function classifyCapletRuntimeRoute(caplet: Record<string, unknown>): RuntimeRouteKind;

package/dist/runtime-plan/resources.d.ts

@@ -0,0 +1,13 @@
+import type { HostedRuntimeResourceClass, RuntimeResourcePolicy, RuntimeResourceResolution } from "./types";
+export declare function resourceClassRank(value: string): number;
+export declare function isRuntimeResourceClassAllowed(requested: string, maximum: string): boolean;
+type ResourceInput = {
+    backend?: string | undefined;
+    features: string[];
+    explicitClass?: HostedRuntimeResourceClass | undefined;
+    setupRequired?: boolean | undefined;
+    policy?: RuntimeResourcePolicy | undefined;
+};
+export declare function resolveRuntimeResources(input: ResourceInput): RuntimeResourceResolution;
+export declare function resolveRuntimeResources(caplet: Record<string, unknown>, features: string[], policy?: RuntimeResourcePolicy | undefined): RuntimeResourceResolution;
+export {};

package/dist/runtime-plan/types.d.ts

@@ -0,0 +1,82 @@
+import type { CapletConfig, RuntimeFeature, RuntimeResourceClass } from "../config-runtime";
+export type HostedRuntimeResourceClass = RuntimeResourceClass | "small" | "medium";
+export type { RuntimeFeature, RuntimeResourceClass };
+export type RuntimeRouteKind = "worker_safe" | "process" | "project_bound_process" | "local_only";
+export type SetupTargetKind = "local_host" | "remote_host" | "hosted_sandbox";
+export type HostedSetupState = "not_required" | "approval_required" | "approved" | "queued" | "running" | "verifying" | "ready" | "failed" | "expired";
+export type HostedBackendCheckState = "not_run" | "queued" | "running" | "passed" | "failed" | "stale";
+export type HostedSandboxState = "not_started" | "preparing" | "uploading_bundle" | "running_setup" | "starting_adapter" | "ready" | "busy" | "degraded" | "stopping" | "stopped" | "failed";
+export declare const HIDDEN_REASON_CODES: readonly ["setup_required", "setup_running", "setup_failed", "verify_failed", "backend_auth_required", "backend_check_failed", "project_binding_required", "project_binding_syncing", "project_binding_blocked", "project_binding_stale", "provider_unavailable", "provider_capacity_exhausted", "provider_queue_timeout", "policy_denied", "billing_required", "subscription_past_due", "usage_limit_reached", "email_verification_required", "docker_required", "docker_denied", "browser_required", "browser_denied", "resource_class_denied", "local_only", "invalid_bundle", "unsupported_backend"];
+export type HiddenReasonCode = (typeof HIDDEN_REASON_CODES)[number];
+export type RuntimePlanDeployment = "hosted" | "self_hosted" | "local";
+export type RuntimePlanOptions = {
+    deployment?: RuntimePlanDeployment | undefined;
+    resourcePolicy?: RuntimeResourcePolicy | undefined;
+};
+export type RuntimeFeatureProvenanceSource = "explicit" | "setup.commands" | "setup.verify" | "mcp.command" | "cli.command" | "cli.action";
+export type RuntimeFeatureProvenance = {
+    feature: RuntimeFeature;
+    source: RuntimeFeatureProvenanceSource;
+    matched: string;
+    command?: string | undefined;
+};
+export type RuntimeResourcePolicy = {
+    maxClass?: HostedRuntimeResourceClass | undefined;
+};
+export type RuntimeResourceResolution = {
+    class: HostedRuntimeResourceClass;
+    cpu: number;
+    memoryMb: number;
+    diskMb: number;
+    cappedByPolicy?: HostedRuntimeResourceClass | undefined;
+};
+export type RuntimeRequirementsResolution = {
+    features: RuntimeFeature[];
+    featureProvenance: RuntimeFeatureProvenance[];
+    resources: RuntimeResourceResolution;
+};
+export type CapletRuntimePlan = {
+    id: string;
+    backend: CapletConfig["backend"] | string;
+    route: RuntimeRouteKind;
+    setupTarget?: SetupTargetKind | undefined;
+    setupRequired: boolean;
+    authRequired: boolean;
+    projectBindingRequired: boolean;
+    runtime: RuntimeRequirementsResolution;
+    caplet: CapletConfig | Record<string, unknown>;
+};
+export type HostedRoutePlan = {
+    workspaceId: string;
+    capletId: string;
+    contentHash: string;
+    bundleRevision: string;
+    route: RuntimeRouteKind;
+    backend: string;
+    runtimeFeatures: string[];
+    resourceClass: HostedRuntimeResourceClass;
+    setupState: HostedSetupState;
+    checkState: HostedBackendCheckState;
+    projectBindingRequired: boolean;
+    projectFingerprint?: string | undefined;
+    hiddenReasons: HiddenReasonCode[];
+    primaryHiddenReason?: HiddenReasonCode | undefined;
+    policyDecision: "allowed" | "denied" | "not_evaluated";
+    provenanceSource: "bundle_validation" | "install" | "runtime_refresh" | "call";
+    updatedAt: string;
+};
+export type HostedCallProvenance = {
+    requestId: string;
+    workspaceId: string;
+    capletId: string;
+    contentHash: string;
+    route: RuntimeRouteKind;
+    backend: string;
+    provider?: "daytona" | undefined;
+    sandboxId?: string | undefined;
+    snapshotId?: string | undefined;
+    runtimeFeatures: string[];
+    projectFingerprint?: string | undefined;
+    usageEventIds: string[];
+    auditEventId?: string | undefined;
+};