risicare 0.1.3 → 0.1.5

package/dist/index.d.cts

@@ -5,15 +5,19 @@
  *   RISICARE_API_KEY, RISICARE_ENDPOINT, RISICARE_PROJECT_ID, etc.
  */
 interface RisicareConfig {
-    /** API key for authentication (format: "rsk-{random}") */
+    /** API key for authentication (format: "rsk-{random}"). Each key is scoped to one project. */
     apiKey?: string;
     /** Gateway endpoint URL */
     endpoint?: string;
-    /** Project ID */
+    /**
+     * @deprecated Project is determined by your API key. This field is ignored
+     * by the gateway and will be removed in v1.0. Use `serviceName` and
+     * `environment` for within-project organization.
+     */
     projectId?: string;
-    /** Environment name (production, staging, development) */
+    /** Environment name (production, staging, development). Used for within-project organization. */
     environment?: string;
-    /** Service name for identification */
+    /** Service name for within-project organization. */
     serviceName?: string;
     /** Service version */
     serviceVersion?: string;
@@ -288,7 +292,7 @@ declare class Tracer {
  *
  * Usage:
  *   import { init, shutdown } from 'risicare';
- *   init({ apiKey: 'rsk-...', projectId: 'my-project' });
+ *   init({ apiKey: 'rsk-...' }); // API key determines project
  *   // ... instrument code ...
  *   await shutdown(); // flush remaining spans
  */
@@ -298,7 +302,7 @@ declare class Tracer {
  *
  * @example
  * import { init } from 'risicare';
- * init({ apiKey: 'rsk-...', projectId: 'my-project' });
+ * init({ apiKey: 'rsk-...', serviceName: 'my-agent', environment: 'production' });
  */
 declare function init(config?: Partial<RisicareConfig>): void;
 /**
@@ -341,6 +345,34 @@ declare function getMetrics(): {
     queueCapacity: number;
     queueUtilization: number;
 };
+/**
+ * Report a caught exception to the self-healing pipeline.
+ *
+ * Creates an error span that triggers diagnosis and fix generation.
+ * This function never throws and is non-blocking.
+ *
+ * @param error - The caught exception (Error object or string)
+ * @param options - Optional attributes and context overrides
+ */
+declare function reportError(error: unknown, options?: {
+    name?: string;
+    attributes?: Record<string, unknown>;
+}): void;
+/**
+ * Record a custom evaluation score on a trace.
+ *
+ * Sends the score to the server in a fire-and-forget fashion.
+ * This function never throws and is non-blocking.
+ *
+ * @param traceId - The trace to score
+ * @param name - Score name (e.g., "accuracy", "user_satisfaction")
+ * @param value - Score value between 0.0 and 1.0 inclusive
+ * @param options - Optional span_id and comment
+ */
+declare function score(traceId: string, name: string, value: number, options?: {
+    spanId?: string;
+    comment?: string;
+}): void;
 
 /**
  * Agent context — identifies which agent is executing.
@@ -586,4 +618,4 @@ declare function registerSpan(span: Span, ttlMs?: number): void;
 declare function getSpanById(spanId: string): Span | undefined;
 declare function unregisterSpan(spanId: string): void;
 
-export { type AgentContext, type AgentOptions, AgentRole, MessageType, type RisicareConfig, SemanticPhase, type SessionContext, type SessionOptions, Span, SpanKind, type SpanOptions, SpanStatus, type StartSpanOptions, type TraceContext, Tracer, agent, disable, enable, extractTraceContext, flush, getCurrentAgent, getCurrentAgentId, getCurrentContext, getCurrentPhase, getCurrentSession, getCurrentSessionId, getCurrentSpan, getCurrentSpanId, getCurrentTraceId, getMetrics, getSpanById, getTraceContent, getTraceContext, getTracer, init, injectTraceContext, isEnabled, registerSpan, session, shutdown, traceAct, traceCoordinate, traceDecide, traceDelegate, traceMessage, traceObserve, traceThink, unregisterSpan, withAgent, withPhase, withSession };
+export { type AgentContext, type AgentOptions, AgentRole, MessageType, type RisicareConfig, SemanticPhase, type SessionContext, type SessionOptions, Span, SpanKind, type SpanOptions, SpanStatus, type StartSpanOptions, type TraceContext, Tracer, agent, disable, enable, extractTraceContext, flush, getCurrentAgent, getCurrentAgentId, getCurrentContext, getCurrentPhase, getCurrentSession, getCurrentSessionId, getCurrentSpan, getCurrentSpanId, getCurrentTraceId, getMetrics, getSpanById, getTraceContent, getTraceContext, getTracer, init, injectTraceContext, isEnabled, registerSpan, reportError, score, session, shutdown, traceAct, traceCoordinate, traceDecide, traceDelegate, traceMessage, traceObserve, traceThink, unregisterSpan, withAgent, withPhase, withSession };

package/dist/index.d.ts

@@ -5,15 +5,19 @@
  *   RISICARE_API_KEY, RISICARE_ENDPOINT, RISICARE_PROJECT_ID, etc.
  */
 interface RisicareConfig {
-    /** API key for authentication (format: "rsk-{random}") */
+    /** API key for authentication (format: "rsk-{random}"). Each key is scoped to one project. */
     apiKey?: string;
     /** Gateway endpoint URL */
     endpoint?: string;
-    /** Project ID */
+    /**
+     * @deprecated Project is determined by your API key. This field is ignored
+     * by the gateway and will be removed in v1.0. Use `serviceName` and
+     * `environment` for within-project organization.
+     */
     projectId?: string;
-    /** Environment name (production, staging, development) */
+    /** Environment name (production, staging, development). Used for within-project organization. */
     environment?: string;
-    /** Service name for identification */
+    /** Service name for within-project organization. */
     serviceName?: string;
     /** Service version */
     serviceVersion?: string;
@@ -288,7 +292,7 @@ declare class Tracer {
  *
  * Usage:
  *   import { init, shutdown } from 'risicare';
- *   init({ apiKey: 'rsk-...', projectId: 'my-project' });
+ *   init({ apiKey: 'rsk-...' }); // API key determines project
  *   // ... instrument code ...
  *   await shutdown(); // flush remaining spans
  */
@@ -298,7 +302,7 @@ declare class Tracer {
  *
  * @example
  * import { init } from 'risicare';
- * init({ apiKey: 'rsk-...', projectId: 'my-project' });
+ * init({ apiKey: 'rsk-...', serviceName: 'my-agent', environment: 'production' });
  */
 declare function init(config?: Partial<RisicareConfig>): void;
 /**
@@ -341,6 +345,34 @@ declare function getMetrics(): {
     queueCapacity: number;
     queueUtilization: number;
 };
+/**
+ * Report a caught exception to the self-healing pipeline.
+ *
+ * Creates an error span that triggers diagnosis and fix generation.
+ * This function never throws and is non-blocking.
+ *
+ * @param error - The caught exception (Error object or string)
+ * @param options - Optional attributes and context overrides
+ */
+declare function reportError(error: unknown, options?: {
+    name?: string;
+    attributes?: Record<string, unknown>;
+}): void;
+/**
+ * Record a custom evaluation score on a trace.
+ *
+ * Sends the score to the server in a fire-and-forget fashion.
+ * This function never throws and is non-blocking.
+ *
+ * @param traceId - The trace to score
+ * @param name - Score name (e.g., "accuracy", "user_satisfaction")
+ * @param value - Score value between 0.0 and 1.0 inclusive
+ * @param options - Optional span_id and comment
+ */
+declare function score(traceId: string, name: string, value: number, options?: {
+    spanId?: string;
+    comment?: string;
+}): void;
 
 /**
  * Agent context — identifies which agent is executing.
@@ -586,4 +618,4 @@ declare function registerSpan(span: Span, ttlMs?: number): void;
 declare function getSpanById(spanId: string): Span | undefined;
 declare function unregisterSpan(spanId: string): void;
 
-export { type AgentContext, type AgentOptions, AgentRole, MessageType, type RisicareConfig, SemanticPhase, type SessionContext, type SessionOptions, Span, SpanKind, type SpanOptions, SpanStatus, type StartSpanOptions, type TraceContext, Tracer, agent, disable, enable, extractTraceContext, flush, getCurrentAgent, getCurrentAgentId, getCurrentContext, getCurrentPhase, getCurrentSession, getCurrentSessionId, getCurrentSpan, getCurrentSpanId, getCurrentTraceId, getMetrics, getSpanById, getTraceContent, getTraceContext, getTracer, init, injectTraceContext, isEnabled, registerSpan, session, shutdown, traceAct, traceCoordinate, traceDecide, traceDelegate, traceMessage, traceObserve, traceThink, unregisterSpan, withAgent, withPhase, withSession };
+export { type AgentContext, type AgentOptions, AgentRole, MessageType, type RisicareConfig, SemanticPhase, type SessionContext, type SessionOptions, Span, SpanKind, type SpanOptions, SpanStatus, type StartSpanOptions, type TraceContext, Tracer, agent, disable, enable, extractTraceContext, flush, getCurrentAgent, getCurrentAgentId, getCurrentContext, getCurrentPhase, getCurrentSession, getCurrentSessionId, getCurrentSpan, getCurrentSpanId, getCurrentTraceId, getMetrics, getSpanById, getTraceContent, getTraceContext, getTracer, init, injectTraceContext, isEnabled, registerSpan, reportError, score, session, shutdown, traceAct, traceCoordinate, traceDecide, traceDelegate, traceMessage, traceObserve, traceThink, unregisterSpan, withAgent, withPhase, withSession };

package/dist/index.js

@@ -5,6 +5,11 @@ function resolveConfig(config) {
   const apiKey = config?.apiKey ?? env.RISICARE_API_KEY;
   const endpoint = config?.endpoint ?? env.RISICARE_ENDPOINT ?? DEFAULT_ENDPOINT;
   const projectId = config?.projectId ?? env.RISICARE_PROJECT_ID;
+  if (config?.projectId || env.RISICARE_PROJECT_ID) {
+    console.warn(
+      "[risicare] projectId is deprecated and ignored by the gateway. Your API key determines the project. Use serviceName and environment for within-project organization. projectId will be removed in v1.0."
+    );
+  }
   const environment = config?.environment ?? env.RISICARE_ENVIRONMENT ?? "development";
   const serviceName = config?.serviceName ?? env.RISICARE_SERVICE_NAME;
   const serviceVersion = config?.serviceVersion ?? env.RISICARE_SERVICE_VERSION;
@@ -1038,10 +1043,66 @@ function getMetrics() {
     queueUtilization: 0
   };
 }
+function reportError(error, options) {
+  try {
+    const tracer = getTracer2();
+    if (!tracer) return;
+    const err = error instanceof Error ? error : new Error(String(error));
+    const spanName = options?.name ?? `error:${err.constructor.name}`;
+    tracer.startSpan({ name: spanName, kind: "internal" /* INTERNAL */ }, (span) => {
+      span.setStatus("error" /* ERROR */, err.message);
+      span.setAttribute("error", true);
+      span.setAttribute("error.type", err.constructor.name);
+      span.setAttribute("error.message", err.message.slice(0, 2e3));
+      if (err.stack) span.setAttribute("error.stack", err.stack.slice(0, 4e3));
+      span.setAttribute("risicare.reported_error", true);
+      if (options?.attributes) {
+        for (const [k, v] of Object.entries(options.attributes)) {
+          span.setAttribute(k, v);
+        }
+      }
+    });
+  } catch {
+    debug("reportError failed");
+  }
+}
+function score(traceId, name, value, options) {
+  try {
+    if (typeof value !== "number" || value < 0 || value > 1) {
+      debug(`score: value must be in [0.0, 1.0], got ${value}. Score not sent.`);
+      return;
+    }
+    if (!traceId || !name) {
+      debug("score: traceId and name are required");
+      return;
+    }
+    const client = getClient();
+    if (!client?.enabled || !client.config.apiKey) return;
+    const endpoint = client.config.endpoint.replace(/\/$/, "");
+    const url = `${endpoint}/api/v1/scores`;
+    const body = JSON.stringify({
+      trace_id: traceId,
+      name,
+      score: value,
+      source: "sdk",
+      ...options?.spanId && { span_id: options.spanId },
+      ...options?.comment && { comment: options.comment }
+    });
+    fetch(url, {
+      method: "POST",
+      headers: {
+        "Content-Type": "application/json",
+        "Authorization": `Bearer ${client.config.apiKey}`
+      },
+      body
+    }).catch((err) => debug(`score: send failed: ${err}`));
+  } catch {
+    debug("score failed");
+  }
+}
 
 // src/context/agent.ts
 function withAgent(options, fn) {
-  if (!isEnabled()) return fn();
   const parent = getCurrentAgent();
   const agentName = options.name ?? "agent";
   const agent2 = {
@@ -1074,7 +1135,6 @@ function agent(options, fn) {
 
 // src/context/session.ts
 function withSession(options, fn) {
-  if (!isEnabled()) return fn();
   const session2 = {
     sessionId: options.sessionId,
     userId: options.userId,
@@ -1095,7 +1155,6 @@ function session(optionsOrResolver, fn) {
 
 // src/context/phase.ts
 function withPhase(phase, fn) {
-  if (!isEnabled()) return fn();
   return runWithContext({ phase }, fn);
 }
 
@@ -1331,6 +1390,8 @@ export {
   injectTraceContext,
   isEnabled,
   registerSpan,
+  reportError,
+  score,
   session,
   shutdown,
   traceAct,