@relayflows/sdk 2.0.58 → 2.0.59

package/src/jev-client.ts

@@ -0,0 +1,78 @@
+import type { ClassifyOptions, ClassifyResult } from '@relayflows/surface';
+import { classifyOptions, JEV_MODEL } from './classify-contract.js';
+import type { CompletionReason } from './protocol.js';
+
+export class JevError extends Error {
+  constructor(readonly diagnostic: string, readonly completionReason: CompletionReason = 'worker_error') {
+    super(`f.classify: ${diagnostic}`);
+  }
+}
+
+/** Errors deliberately contain no provider body, request text, or credential. */
+export async function askJev(
+  raw: ClassifyOptions, environment: NodeJS.ProcessEnv = process.env, signal?: AbortSignal,
+): Promise<ClassifyResult> {
+  const options = classifyOptions(raw);
+  signal?.throwIfAborted();
+  try {
+    const key = environment['TYPESAFE_API_KEY'];
+    if (!key?.trim()) throw new JevError('typesafe_api_key_missing');
+    const deadline = AbortSignal.timeout(options.timeoutMs);
+    const combined = signal === undefined ? deadline : AbortSignal.any([deadline, signal]);
+    try {
+      const response = await globalThis.fetch('https://api.typesafe.ai/v1/systemone', {
+        method: 'POST', redirect: 'manual', signal: combined,
+        headers: { Authorization: `Bearer ${key}`, 'Content-Type': 'application/json' },
+        body: JSON.stringify({ model: JEV_MODEL, state: options.state, questions: {
+          classification: { type: 'choice', instructions: options.question, criteria: options.options },
+        } }),
+      });
+      if (!response.ok) {
+        void response.body?.cancel().catch(() => undefined);
+        throw new JevError(`jev_http_${response.status}`);
+      }
+      const body = await boundedBody(response);
+      const answer = body?.answers?.classification;
+      if (answer?.type !== 'choice' || typeof answer.choice !== 'string'
+        || !Object.hasOwn(options.options, answer.choice) || typeof answer.confidence !== 'number'
+        || !Number.isFinite(answer.confidence) || answer.confidence < 0 || answer.confidence > 1) {
+        throw new JevError('jev_invalid_answer', 'verification_failed');
+      }
+      if (answer.confidence < options.minConfidence) throw new JevError('jev_low_confidence', 'verification_failed');
+      return { choice: answer.choice, confidence: answer.confidence, completionReason: 'success' };
+    } catch (error) {
+      // Losing the worker lease is never permission to complete with fallback.
+      signal?.throwIfAborted();
+      if (deadline.aborted) throw new JevError('jev_timeout', 'timeout');
+      if (error instanceof JevError) throw error;
+      throw new JevError('jev_network_error');
+    }
+  } catch (error) {
+    if (!(error instanceof JevError) || options.fallback === undefined) throw error;
+    return { choice: options.fallback, confidence: 0, completionReason: 'success', fallbackReason: error.diagnostic };
+  }
+}
+
+async function boundedBody(response: Response): Promise<{ answers?: { classification?: { type?: unknown; choice?: unknown; confidence?: unknown } } }> {
+  const reader = response.body?.getReader();
+  if (!reader) throw new JevError('jev_invalid_answer', 'verification_failed');
+  const chunks: Uint8Array[] = [];
+  let size = 0;
+  try {
+    for (;;) {
+      const { done, value } = await reader.read();
+      if (done) break;
+      size += value.byteLength;
+      if (size > 16_384) {
+        void reader.cancel().catch(() => undefined);
+        throw new JevError('jev_response_too_large', 'verification_failed');
+      }
+      chunks.push(value);
+    }
+  } finally { reader.releaseLock(); }
+  const bytes = new Uint8Array(size);
+  let offset = 0;
+  for (const chunk of chunks) { bytes.set(chunk, offset); offset += chunk.byteLength; }
+  try { return JSON.parse(new TextDecoder().decode(bytes)); }
+  catch { throw new JevError('jev_invalid_json', 'verification_failed'); }
+}

package/src/llm-worker.ts

@@ -1,3 +1,5 @@
+import { askJev, JevError } from './jev-client.js';
+import { CLASSIFY_KIND, isClassifyStep } from './classify-contract.js';
 import { workerSpend } from './worker-spend.js';
 import { reportedCost } from './reported-cost.js';
 import { DEFAULT_LOCAL_AGENT_CAPACITY } from './worker-slots.js';
@@ -53,8 +55,36 @@ export class LlmWorker extends EventEmitter {
     void running.finally(() => { this.inFlight.delete(running); });
   };
 
+  private async classify(dispatch: StepDispatchEvent, prompt: string): Promise<void> {
+    let output: unknown;
+    let diagnostic: string | undefined;
+    let reason: CompletionReason = 'success';
+    await withWorkerLease(this.client, dispatch, async signal => {
+      try {
+        const { type, ...options } = JSON.parse(prompt);
+        if (type !== CLASSIFY_KIND) throw new TypeError('invalid classification');
+        output = await askJev(options, this.environment ?? process.env, signal);
+      } catch (error) {
+        signal.throwIfAborted();
+        diagnostic = error instanceof JevError ? error.diagnostic : 'jev_invalid_options';
+        reason = error instanceof JevError ? error.completionReason : 'verification_failed';
+      }
+    });
+    // The provider does not return usage or price; leave cost unknown.
+    await this.client.stepComplete(dispatch.run_id, dispatch.step_id, dispatch.attempt,
+      dispatch.idempotency_key, reason, {
+        output: output ?? { diagnostic },
+        usage: { tokens_in: 0, tokens_out: 0, dollars_unmetered: true },
+        ...(diagnostic === undefined ? {} : { trajectory_tail: { error: `f.classify: ${diagnostic}` } }),
+      });
+  }
+
   private async execute(dispatch: StepDispatchEvent): Promise<void> {
     const spec = dispatch.spec as ResolvedKernelLlmStep;
+    if (isClassifyStep(spec)) {
+      await this.classify(dispatch, spec.prompt);
+      return;
+    }
     const schema = spec.verification?.json_schema;
     const prompt = schema === undefined ? spec.prompt
       : `${spec.prompt}\n\nReturn only a JSON value matching this JSON Schema (no Markdown fences):\n${JSON.stringify(schema)}`;

package/src/local-agent-environment.ts

@@ -13,6 +13,7 @@ const AGENT_CREDENTIAL_NAMES = new Set([
   'ANTHROPIC_BASE_URL',
   'OPENAI_API_KEY',
   'OPENAI_BASE_URL',
+  'TYPESAFE_API_KEY',
 ]);
 
 export function localAgentEnvironment(base: NodeJS.ProcessEnv = process.env): NodeJS.ProcessEnv | undefined {

package/src/plugin-manifest.ts

@@ -39,7 +39,7 @@ export interface PluginManifest {
   preflight: { credentials: readonly string[]; servers: readonly string[] };
 }
 const identifier = /^[A-Za-z_$][A-Za-z0-9_$]*$/;
-const reserved = new Set(['run', 'llm', 'agent', 'message', 'release', 'human', 'dispatch', 'done', 'cloud', 'memory', 'mcp', 'slack', '__proto__', 'constructor', 'prototype', 'then']);
+const reserved = new Set(['run', 'llm', 'classify', 'agent', 'message', 'release', 'human', 'dispatch', 'done', 'cloud', 'memory', 'mcp', 'slack', '__proto__', 'constructor', 'prototype', 'then']);
 const object = (v: unknown): v is Record<string, unknown> => typeof v === 'object' && v !== null && !Array.isArray(v);
 const strings = (v: unknown): v is string[] => Array.isArray(v) && v.every(s => typeof s === 'string' && s.trim().length > 0);
 export function pluginPackageName(name: string): string {

package/src/preflight.ts

@@ -1,3 +1,4 @@
+import { isClassifyStep } from './classify-contract.js';
 import { brokerInstruction } from './communication/broker-spec.js';
 import { communicationInstruction } from './communication/spec.js';
 import { loadPlugins, type LoadedPlugin } from './plugin-loader.js';
@@ -278,6 +279,7 @@ export function resolvePreflight(flow: unknown, options: ResolutionOptions): Pre
   for (const step of compiled.steps) {
     if (step.type === 'deterministic') continue;
     if (step.type === 'agent' && helperCall(step) !== undefined) continue;
+    if (isClassifyStep(step, compiled.cli)) continue;
     const resolution = resolveCli(step, compiled, options.projectCli);
     if (resolution === undefined) {
       cliResolutionDiagnostics.push({
@@ -327,7 +329,7 @@ function preflightSync(flow: unknown, options: PreflightOptions): PreflightResul
     probeNamedGate(step, options.probes, diagnostics);
     warnOnVacuousGate(step, diagnostics);
     warnOnUnprovableEffects(step, options.probes, diagnostics);
-    if (step.type === 'deterministic') continue;
+    if (step.type === 'deterministic' || isClassifyStep(step, compiled.cli)) continue;
     const helper = step.type === 'agent' ? helperCall(step) : undefined;
     if (helper !== undefined) {
       try {