@cadreen/sdk 0.1.0

package/dist/resources/failures.d.ts

@@ -0,0 +1,33 @@
+import type { IntelligenceTraceEntry, ListIntelligenceResponse, TraceExplain } from "../types";
+import { TracesResource } from "./traces";
+/**
+ * FailuresResource — Builder-shaped naming facade for understanding errors.
+ *
+ * When something goes wrong, developers ask `cadreen.failures.explain(id)`
+ * or `cadreen.failures.recent()` instead of navigating the trace API directly.
+ *
+ * This is a thin wrapper; no new backend routes are introduced.
+ */
+export declare class FailuresResource {
+    private traces;
+    constructor(traces: TracesResource);
+    /** Fetch a trace and return it with an `.explain()` helper. */
+    explain(id: string): Promise<IntelligenceTraceEntry & {
+        explain: () => TraceExplain;
+    }>;
+    /** List recent traces with optional filtering. */
+    recent(options?: {
+        domain?: string;
+        decision?: string;
+        from?: string;
+        to?: string;
+        limit?: number;
+        offset?: number;
+    }): Promise<ListIntelligenceResponse>;
+    /** Summarize why an error occurred, using intelligence data when available. */
+    why(error: unknown): {
+        summary: string;
+        traceId?: string;
+        recommendation?: string;
+    };
+}

package/dist/resources/failures.js

@@ -0,0 +1,51 @@
+/**
+ * FailuresResource — Builder-shaped naming facade for understanding errors.
+ *
+ * When something goes wrong, developers ask `cadreen.failures.explain(id)`
+ * or `cadreen.failures.recent()` instead of navigating the trace API directly.
+ *
+ * This is a thin wrapper; no new backend routes are introduced.
+ */
+export class FailuresResource {
+    constructor(traces) {
+        this.traces = traces;
+    }
+    /** Fetch a trace and return it with an `.explain()` helper. */
+    async explain(id) {
+        return this.traces.get(id);
+    }
+    /** List recent traces with optional filtering. */
+    async recent(options) {
+        return this.traces.list(options);
+    }
+    /** Summarize why an error occurred, using intelligence data when available. */
+    why(error) {
+        if (error && typeof error === "object") {
+            const e = error;
+            const traceId = typeof e.traceId === "string"
+                ? e.traceId
+                : typeof e.trace_id === "string"
+                    ? e.trace_id
+                    : undefined;
+            const code = typeof e.code === "string" ? e.code : "unknown";
+            const message = typeof e.message === "string" ? e.message : String(error);
+            return {
+                summary: `${code}: ${message}`,
+                traceId,
+                recommendation: code === "timeout"
+                    ? "Retry with a longer timeout or check network connectivity."
+                    : code === "rate_limited"
+                        ? "Back off and retry with exponential delay."
+                        : code === "policy_blocked"
+                            ? "Review the policy that blocked this request or request an override."
+                            : traceId
+                                ? `Look up trace ${traceId} for full provenance.`
+                                : "Check recent traces for context.",
+            };
+        }
+        return {
+            summary: String(error),
+            recommendation: "Check recent traces for context.",
+        };
+    }
+}

package/dist/resources/guardrails.d.ts

@@ -0,0 +1,12 @@
+import type { CreatePolicyRequest, CreatePolicyResponse, ConfirmPolicyResponse, EvaluatePolicyRequest, EvaluatePolicyResponse, ListPoliciesResponse, PolicyBundle } from "../types";
+import { PoliciesResource } from "./policies";
+export declare class GuardrailsResource {
+    private policies;
+    constructor(policies: PoliciesResource);
+    check(request: EvaluatePolicyRequest): Promise<EvaluatePolicyResponse>;
+    add(request: CreatePolicyRequest): Promise<CreatePolicyResponse>;
+    requireApproval(description: string): Promise<CreatePolicyResponse>;
+    approve(id: string): Promise<ConfirmPolicyResponse>;
+    list(): Promise<ListPoliciesResponse>;
+    get(id: string): Promise<PolicyBundle>;
+}

package/dist/resources/guardrails.js

@@ -0,0 +1,23 @@
+export class GuardrailsResource {
+    constructor(policies) {
+        this.policies = policies;
+    }
+    async check(request) {
+        return this.policies.evaluate(request);
+    }
+    async add(request) {
+        return this.policies.create(request);
+    }
+    async requireApproval(description) {
+        return this.policies.requireApproval(description);
+    }
+    async approve(id) {
+        return this.policies.confirm(id);
+    }
+    async list() {
+        return this.policies.list();
+    }
+    async get(id) {
+        return this.policies.get(id);
+    }
+}

package/dist/resources/intent.d.ts

@@ -0,0 +1,7 @@
+import type { IntentRequest, IntentResult } from "../types";
+import { HttpClient } from "../client";
+export declare class IntentResource {
+    private client;
+    constructor(client: HttpClient);
+    invoke(request: IntentRequest): Promise<IntentResult>;
+}

package/dist/resources/intent.js

@@ -0,0 +1,77 @@
+function mapIntentResponse(raw) {
+    const intelligence = raw.intelligence || {
+        capability: { total_available: 0, healthy_count: 0 },
+        reasoning: {},
+        memory: { healthy: true },
+        governance: { active: false },
+        humility: {},
+        process: { started_at: "", steps_taken: 0, duration_ms: 0 },
+        field_stability: { stable: [], evolving: [], internal: [] },
+    };
+    const traceId = raw.trace_id || raw.id;
+    switch (raw.type) {
+        case "direct":
+            return {
+                type: "direct",
+                message: raw.message || { role: "assistant", content: "" },
+                intelligence,
+                traceId,
+            };
+        case "clarify":
+            return {
+                type: "clarify",
+                questions: (raw.clarification?.questions || []).map((q) => typeof q === "string" ? { id: "", question: q, type: "open", required: false } : q),
+                conversationId: raw.clarification?.conversation_id || "",
+                intelligence,
+                traceId,
+            };
+        case "mission":
+            return {
+                type: "execution",
+                execution: {
+                    id: raw.mission?.id || "",
+                    status: raw.mission?.status || "",
+                    stream_url: raw.mission?.stream_url,
+                    poll_url: raw.mission?.poll_url,
+                },
+                intelligence,
+                traceId,
+            };
+        case "blocked":
+            return {
+                type: "blocked",
+                policy: {
+                    name: raw.meta?.governance?.decision || "policy",
+                    reason: raw.meta?.governance?.reason || "blocked by policy",
+                },
+                intelligence,
+                traceId,
+            };
+        case "connect_required":
+            return {
+                type: "connect_required",
+                connection: {
+                    endpoint: raw.mission?.stream_url || "",
+                    reason: raw.meta?.governance?.reason || "connection required",
+                },
+                intelligence,
+                traceId,
+            };
+        default:
+            return {
+                type: "direct",
+                message: raw.message || { role: "assistant", content: "" },
+                intelligence,
+                traceId,
+            };
+    }
+}
+export class IntentResource {
+    constructor(client) {
+        this.client = client;
+    }
+    async invoke(request) {
+        const raw = await this.client.post("/api/v1/cadreen/intent", request);
+        return mapIntentResponse(raw);
+    }
+}

package/dist/resources/memory.d.ts

@@ -0,0 +1,9 @@
+import type { RememberRequest, CreateMemoryResponse, SearchMemoryRequest, SearchMemoryResponse, Atom } from "../types";
+import { HttpClient } from "../client";
+export declare class MemoryResource {
+    private client;
+    constructor(client: HttpClient);
+    remember(request: RememberRequest): Promise<CreateMemoryResponse>;
+    search(request: SearchMemoryRequest): Promise<SearchMemoryResponse>;
+    get(id: string): Promise<Atom>;
+}

package/dist/resources/memory.js

@@ -0,0 +1,30 @@
+export class MemoryResource {
+    constructor(client) {
+        this.client = client;
+    }
+    async remember(request) {
+        return this.client.post("/api/v1/cadreen/memory", {
+            type: request.type,
+            content: request.content,
+            domain: request.domain,
+            scope: request.scope,
+            authority: request.authority,
+            tags: request.tags,
+        });
+    }
+    async search(request) {
+        const params = {
+            query: request.query,
+        };
+        if (request.domain)
+            params.domain = request.domain;
+        if (request.tag)
+            params.tag = request.tag;
+        if (request.limit)
+            params.limit = request.limit;
+        return this.client.get("/api/v1/cadreen/memory/search", params);
+    }
+    async get(id) {
+        return this.client.get(`/api/v1/cadreen/memory/${encodeURIComponent(id)}`);
+    }
+}

package/dist/resources/policies.d.ts

@@ -0,0 +1,12 @@
+import type { CreatePolicyRequest, CreatePolicyResponse, ConfirmPolicyResponse, EvaluatePolicyRequest, EvaluatePolicyResponse, ListPoliciesResponse, PolicyBundle } from "../types";
+import { HttpClient } from "../client";
+export declare class PoliciesResource {
+    private client;
+    constructor(client: HttpClient);
+    create(request: CreatePolicyRequest): Promise<CreatePolicyResponse>;
+    evaluate(request: EvaluatePolicyRequest): Promise<EvaluatePolicyResponse>;
+    confirm(id: string): Promise<ConfirmPolicyResponse>;
+    list(): Promise<ListPoliciesResponse>;
+    get(id: string): Promise<PolicyBundle>;
+    requireApproval(description: string): Promise<CreatePolicyResponse>;
+}

package/dist/resources/policies.js

@@ -0,0 +1,26 @@
+export class PoliciesResource {
+    constructor(client) {
+        this.client = client;
+    }
+    async create(request) {
+        return this.client.post("/api/v1/cadreen/policies", request);
+    }
+    async evaluate(request) {
+        return this.client.post("/api/v1/cadreen/policies/evaluate", request);
+    }
+    async confirm(id) {
+        return this.client.post(`/api/v1/cadreen/policies/${encodeURIComponent(id)}/confirm`);
+    }
+    async list() {
+        return this.client.get("/api/v1/cadreen/policies");
+    }
+    async get(id) {
+        return this.client.get(`/api/v1/cadreen/policies/${encodeURIComponent(id)}`);
+    }
+    async requireApproval(description) {
+        return this.create({
+            name: description,
+            auto_draft: true,
+        });
+    }
+}

package/dist/resources/skills.d.ts

@@ -0,0 +1,41 @@
+import type { IntentResult, IntentContext, RememberRequest, CreateMemoryResponse, SearchMemoryRequest, SearchMemoryResponse, RegisterOpenAPIRequest, RegisterOpenAPIResponse, RegisterMCPRequest, RegisterMCPResponse, InstallComposioRequest } from "../types";
+import { IntentResource } from "./intent";
+import { MemoryResource } from "./memory";
+import { ConnectionsResource } from "./connections";
+/**
+ * SkillsResource — Builder-shaped naming facade for the system's capabilities.
+ *
+ * Instead of remembering that `intent` is the chat endpoint and `memory`
+ * is the knowledge store, developers work with `cadreen.skills.ask()`,
+ * `cadreen.skills.remember()`, and `cadreen.skills.connect()`.
+ *
+ * This is a thin wrapper; no new backend routes are introduced.
+ */
+export declare class SkillsResource {
+    private intent;
+    private memory;
+    private connections;
+    constructor(intent: IntentResource, memory: MemoryResource, connections: ConnectionsResource);
+    /** Ask a question and get a direct answer or clarifying questions. */
+    ask(prompt: string, options?: {
+        conversation_id?: string;
+        context?: IntentContext;
+        stream?: boolean;
+    }): Promise<IntentResult>;
+    /** Execute an action (mission-bound intent). */
+    act(prompt: string, options?: {
+        conversation_id?: string;
+        context?: IntentContext;
+        stream?: boolean;
+    }): Promise<IntentResult>;
+    /** Store a memory atom. */
+    remember(request: RememberRequest): Promise<CreateMemoryResponse>;
+    /** Search stored memories. */
+    recall(request: SearchMemoryRequest): Promise<SearchMemoryResponse>;
+    /** Register an OpenAPI connector. */
+    connectOpenAPI(request: RegisterOpenAPIRequest): Promise<RegisterOpenAPIResponse>;
+    /** Register an MCP connector. */
+    connectMCP(request: RegisterMCPRequest): Promise<RegisterMCPResponse>;
+    /** Install a Composio integration. */
+    connectComposio(request: InstallComposioRequest): Promise<Record<string, unknown>>;
+}

package/dist/resources/skills.js

@@ -0,0 +1,56 @@
+/**
+ * SkillsResource — Builder-shaped naming facade for the system's capabilities.
+ *
+ * Instead of remembering that `intent` is the chat endpoint and `memory`
+ * is the knowledge store, developers work with `cadreen.skills.ask()`,
+ * `cadreen.skills.remember()`, and `cadreen.skills.connect()`.
+ *
+ * This is a thin wrapper; no new backend routes are introduced.
+ */
+export class SkillsResource {
+    constructor(intent, memory, connections) {
+        this.intent = intent;
+        this.memory = memory;
+        this.connections = connections;
+    }
+    /** Ask a question and get a direct answer or clarifying questions. */
+    async ask(prompt, options) {
+        return this.intent.invoke({
+            messages: [{ role: "user", content: prompt }],
+            mode: "chat",
+            conversation_id: options?.conversation_id,
+            context: options?.context,
+            stream: options?.stream,
+        });
+    }
+    /** Execute an action (mission-bound intent). */
+    async act(prompt, options) {
+        return this.intent.invoke({
+            messages: [{ role: "user", content: prompt }],
+            mode: "execution",
+            conversation_id: options?.conversation_id,
+            context: options?.context,
+            stream: options?.stream,
+        });
+    }
+    /** Store a memory atom. */
+    async remember(request) {
+        return this.memory.remember(request);
+    }
+    /** Search stored memories. */
+    async recall(request) {
+        return this.memory.search(request);
+    }
+    /** Register an OpenAPI connector. */
+    async connectOpenAPI(request) {
+        return this.connections.registerOpenAPI(request);
+    }
+    /** Register an MCP connector. */
+    async connectMCP(request) {
+        return this.connections.registerMCP(request);
+    }
+    /** Install a Composio integration. */
+    async connectComposio(request) {
+        return this.connections.installComposio(request);
+    }
+}

package/dist/resources/traces.d.ts

@@ -0,0 +1,18 @@
+import type { IntelligenceTraceEntry, ListIntelligenceResponse, IntelligenceStats, TraceExplain } from "../types";
+import { HttpClient } from "../client";
+export declare class TracesResource {
+    private client;
+    constructor(client: HttpClient);
+    get(id: string): Promise<IntelligenceTraceEntry & {
+        explain: () => TraceExplain;
+    }>;
+    list(options?: {
+        domain?: string;
+        decision?: string;
+        from?: string;
+        to?: string;
+        limit?: number;
+        offset?: number;
+    }): Promise<ListIntelligenceResponse>;
+    stats(): Promise<IntelligenceStats>;
+}

package/dist/resources/traces.js

@@ -0,0 +1,58 @@
+export class TracesResource {
+    constructor(client) {
+        this.client = client;
+    }
+    async get(id) {
+        const trace = await this.client.get(`/api/v1/cadreen/intelligence/${encodeURIComponent(id)}`);
+        return {
+            ...trace,
+            explain: () => {
+                const meta = trace.meta;
+                const steps = [];
+                if (meta.capability.total_available > 0) {
+                    steps.push(`${meta.capability.healthy_count}/${meta.capability.total_available} capabilities healthy`);
+                }
+                if (meta.governance.active) {
+                    steps.push(`Governance: ${meta.governance.decision || "active"} (confidence: ${meta.governance.confidence || 0})`);
+                }
+                if (meta.humility.gaps_detected && meta.humility.gaps_detected > 0) {
+                    steps.push(`${meta.humility.gaps_detected} gaps detected (${meta.humility.blocking || 0} blocking)`);
+                }
+                if (meta.memory.knowledge_queried) {
+                    steps.push(`${meta.memory.knowledge_queried} knowledge items queried`);
+                }
+                const recommendations = [];
+                if (meta.humility.blocking && meta.humility.blocking > 0) {
+                    recommendations.push("Resolve blocking capability gaps before proceeding");
+                }
+                if (!meta.memory.healthy) {
+                    recommendations.push("Knowledge store is degraded — expect reduced context quality");
+                }
+                return {
+                    summary: meta.summary || `Trace ${trace.id}: ${steps.join("; ")}`,
+                    steps,
+                    recommendations: recommendations.length > 0 ? recommendations : undefined,
+                };
+            },
+        };
+    }
+    async list(options) {
+        const params = {};
+        if (options?.domain)
+            params.domain = options.domain;
+        if (options?.decision)
+            params.decision = options.decision;
+        if (options?.from)
+            params.from = options.from;
+        if (options?.to)
+            params.to = options.to;
+        if (options?.limit)
+            params.limit = options.limit;
+        if (options?.offset)
+            params.offset = options.offset;
+        return this.client.get("/api/v1/cadreen/intelligence", params);
+    }
+    async stats() {
+        return this.client.get("/api/v1/cadreen/intelligence/stats");
+    }
+}

package/dist/telemetry.d.ts

@@ -0,0 +1,56 @@
+import type { CadreenError } from "./client";
+export interface SpanContext {
+    traceId: string;
+    spanId: string;
+}
+export interface TelemetrySpan {
+    setName(name: string): void;
+    setAttribute(key: string, value: string | number | boolean): void;
+    setStatus(status: "ok" | "error"): void;
+    end(): void;
+}
+export interface TelemetryMeter {
+    recordRequest(method: string, path: string, status: number, durationMs: number): void;
+    recordRetry(method: string, path: string, attempt: number): void;
+    recordStreamEvent(eventType: string): void;
+}
+export interface TelemetryProvider {
+    startSpan(name: string, options?: SpanOptions): TelemetrySpan;
+    getMeter(): TelemetryMeter;
+}
+export interface SpanOptions {
+    parent?: SpanContext;
+    attributes?: Record<string, string | number | boolean>;
+}
+export declare class NoOpSpan implements TelemetrySpan {
+    setName(): void;
+    setAttribute(): void;
+    setStatus(): void;
+    end(): void;
+}
+export declare class NoOpMeter implements TelemetryMeter {
+    recordRequest(): void;
+    recordRetry(): void;
+    recordStreamEvent(): void;
+}
+export declare class NoOpProvider implements TelemetryProvider {
+    startSpan(_name: string, _options?: SpanOptions): TelemetrySpan;
+    getMeter(): TelemetryMeter;
+}
+export declare class OpenTelemetryAdapter implements TelemetryProvider {
+    private tracer;
+    private requestCounter;
+    private retryCounter;
+    private streamCounter;
+    private durationHistogram;
+    constructor(tracer: any, meter: any);
+    startSpan(name: string, options?: SpanOptions): TelemetrySpan;
+    getMeter(): TelemetryMeter;
+}
+export declare function wrapWithTelemetry(provider: TelemetryProvider): {
+    onRequestStart(method: string, path: string): TelemetrySpan;
+    onRequestEnd(span: TelemetrySpan, method: string, path: string, status: number, durationMs: number): void;
+    onRetry(method: string, path: string, attempt: number): void;
+    onStreamEvent(eventType: string): void;
+    onError(span: TelemetrySpan, error: CadreenError): void;
+};

package/dist/telemetry.js

@@ -0,0 +1,125 @@
+export class NoOpSpan {
+    setName() { }
+    setAttribute() { }
+    setStatus() { }
+    end() { }
+}
+export class NoOpMeter {
+    recordRequest() { }
+    recordRetry() { }
+    recordStreamEvent() { }
+}
+export class NoOpProvider {
+    startSpan(_name, _options) {
+        return new NoOpSpan();
+    }
+    getMeter() {
+        return new NoOpMeter();
+    }
+}
+export class OpenTelemetryAdapter {
+    constructor(tracer, meter) {
+        this.tracer = tracer;
+        this.requestCounter = meter.createCounter("cadreen.client.requests", {
+            description: "Number of API requests made",
+            unit: "1",
+        });
+        this.retryCounter = meter.createCounter("cadreen.client.retries", {
+            description: "Number of request retries",
+            unit: "1",
+        });
+        this.streamCounter = meter.createCounter("cadreen.client.stream_events", {
+            description: "Number of SSE events received",
+            unit: "1",
+        });
+        this.durationHistogram = meter.createHistogram("cadreen.client.request_duration", {
+            description: "Request duration in milliseconds",
+            unit: "ms",
+        });
+    }
+    startSpan(name, options) {
+        const span = this.tracer.startSpan(name, {
+            attributes: options?.attributes,
+        });
+        if (options?.parent) {
+            span.setAttribute("parent.trace_id", options.parent.traceId);
+            span.setAttribute("parent.span_id", options.parent.spanId);
+        }
+        return new OtelSpanAdapter(span);
+    }
+    getMeter() {
+        return new OtelMeterAdapter(this.requestCounter, this.retryCounter, this.streamCounter, this.durationHistogram);
+    }
+}
+class OtelSpanAdapter {
+    constructor(span) {
+        this.span = span;
+    }
+    setName(name) {
+        this.span.updateName(name);
+    }
+    setAttribute(key, value) {
+        this.span.setAttribute(key, value);
+    }
+    setStatus(status) {
+        if (status === "error") {
+            this.span.setStatus({ code: 2 });
+        }
+        else {
+            this.span.setStatus({ code: 1 });
+        }
+    }
+    end() {
+        this.span.end();
+    }
+}
+class OtelMeterAdapter {
+    constructor(requestCounter, retryCounter, streamCounter, durationHistogram) {
+        this.requestCounter = requestCounter;
+        this.retryCounter = retryCounter;
+        this.streamCounter = streamCounter;
+        this.durationHistogram = durationHistogram;
+    }
+    recordRequest(method, path, status, durationMs) {
+        this.requestCounter.add(1, { "http.method": method, "http.url": path, "http.status_code": status });
+        this.durationHistogram.record(durationMs, { "http.method": method, "http.url": path, "http.status_code": status });
+    }
+    recordRetry(method, path, attempt) {
+        this.retryCounter.add(1, { "http.method": method, "http.url": path, attempt });
+    }
+    recordStreamEvent(eventType) {
+        this.streamCounter.add(1, { "event.type": eventType });
+    }
+}
+export function wrapWithTelemetry(provider) {
+    return {
+        onRequestStart(method, path) {
+            const span = provider.startSpan(`cadreen.${method.toLowerCase()}`, {
+                attributes: {
+                    "http.method": method,
+                    "http.url": path,
+                    "cadreen.version": "2026-06-03",
+                },
+            });
+            return span;
+        },
+        onRequestEnd(span, method, path, status, durationMs) {
+            span.setAttribute("http.status_code", status);
+            span.setStatus(status < 400 ? "ok" : "error");
+            span.end();
+            provider.getMeter().recordRequest(method, path, status, durationMs);
+        },
+        onRetry(method, path, attempt) {
+            provider.getMeter().recordRetry(method, path, attempt);
+        },
+        onStreamEvent(eventType) {
+            provider.getMeter().recordStreamEvent(eventType);
+        },
+        onError(span, error) {
+            span.setAttribute("cadreen.error.code", error.code);
+            span.setAttribute("cadreen.error.type", error.errorType);
+            span.setStatus("error");
+            span.end();
+        },
+    };
+}