@relayflows/sdk 2.0.58 → 2.0.60

package/src/classify-contract.ts

@@ -0,0 +1,63 @@
+import type { ClassifyOptions, ClassifyResult } from '@relayflows/surface';
+import { snapshotJsonValue } from './json-value.js';
+
+export const JEV_MODEL = 'jev-latest';
+export const CLASSIFY_KIND = 'typesafe.classify';
+export const CLASSIFY_BUDGET_WARNING = 'Jev classification reports no token or dollar usage. Token and dollar ceilings cannot bound its spend; timeoutMs bounds its HTTP duration.';
+
+/** Copy in fixed field order: journal reads sort keys, admission binds bytes. */
+export function classifyOptions(raw: unknown): Required<Omit<ClassifyOptions, 'fallback'>> & { fallback?: string } {
+  // At most 39 nodes at depth 2; 560 KB covers even six-byte JSON escaping
+  // of every character in the largest valid question, state and 32 criteria.
+  const value = snapshotJsonValue(raw, 'f.classify options', {
+    maxDepth: 2, maxNodes: 40, maxBytes: 560_000,
+  }) as unknown as ClassifyOptions;
+  const invalid = (detail: string): never => { throw new TypeError(`f.classify ${detail}`); };
+  if (!value || typeof value !== 'object' || Array.isArray(value)
+    || Object.keys(value).some(k => !['question', 'state', 'options', 'minConfidence', 'fallback', 'timeoutMs'].includes(k))) {
+    invalid('accepts question, state, options, minConfidence, fallback, and timeoutMs.');
+  }
+  if (typeof value.question !== 'string' || !value.question.trim() || value.question.length > 4000) invalid('question must contain 1–4000 characters.');
+  if (typeof value.state !== 'string' || value.state.length > 20_000) invalid('state must be a string of at most 20,000 characters.');
+  if (!value.options || typeof value.options !== 'object' || Array.isArray(value.options)) invalid('options must map choices to criteria.');
+  const entries = Object.entries(value.options).sort(([a], [b]) => a < b ? -1 : a > b ? 1 : 0);
+  if (entries.length < 2 || entries.length > 32 || entries.some(([key, criteria]) =>
+    !key.trim() || key.length > 100 || typeof criteria !== 'string' || !criteria.trim() || criteria.length > 2000)) {
+    invalid('requires 2–32 named choices (1–100 characters) with criteria (1–2000 characters).');
+  }
+  const minConfidence = value.minConfidence === undefined ? 0.6 : value.minConfidence;
+  if (!Number.isFinite(minConfidence) || minConfidence < 0 || minConfidence > 1) invalid('minConfidence must be between 0 and 1.');
+  const timeoutMs = value.timeoutMs === undefined ? 8000 : value.timeoutMs;
+  if (!Number.isSafeInteger(timeoutMs) || timeoutMs < 1 || timeoutMs > 30_000) invalid('timeoutMs must be an integer from 1 to 30000.');
+  if (value.fallback !== undefined && (typeof value.fallback !== 'string' || !Object.hasOwn(value.options, value.fallback))) invalid('fallback must name a declared choice.');
+  return {
+    question: value.question, state: value.state, options: Object.fromEntries(entries), minConfidence,
+    timeoutMs, ...(value.fallback === undefined ? {} : { fallback: value.fallback }),
+  };
+}
+
+export function classifyPrompt(options: unknown): string {
+  return JSON.stringify({ type: CLASSIFY_KIND, ...classifyOptions(options) });
+}
+
+/** Recognize the SDK's direct Jev protocol without selecting a project CLI. */
+export function isClassifyStep(step: { type: string; model?: string; cli?: string; prompt?: string }, flowCli?: string): boolean {
+  if (step.type !== 'llm' || step.model !== JEV_MODEL || step.cli !== undefined || flowCli !== undefined || typeof step.prompt !== 'string') return false;
+  try { return JSON.parse(step.prompt)?.type === CLASSIFY_KIND; }
+  catch { return false; }
+}
+
+/** Refuse a malformed or foreign successful journal value before typed branching. */
+export function readClassifyResult(value: unknown, rawOptions: unknown): ClassifyResult | undefined {
+  const options = classifyOptions(rawOptions);
+  if (typeof value !== 'object' || value === null || Array.isArray(value)) return undefined;
+  const result = value as Record<string, unknown>;
+  const { choice, confidence, completionReason, fallbackReason } = result;
+  if (completionReason !== 'success' || typeof choice !== 'string' || !Object.hasOwn(options.options, choice)
+    || typeof confidence !== 'number' || !Number.isFinite(confidence) || confidence < 0 || confidence > 1) return undefined;
+  if (fallbackReason !== undefined) {
+    if (typeof fallbackReason !== 'string' || !/^[a-z0-9_]{1,64}$/.test(fallbackReason)
+      || options.fallback !== choice || confidence !== 0) return undefined;
+  } else if (confidence < options.minConfidence) return undefined;
+  return { choice, confidence, completionReason: 'success', ...(fallbackReason === undefined ? {} : { fallbackReason }) };
+}

package/src/hosted-extension-sandbox.ts

@@ -125,7 +125,7 @@ const ADDRESS_SPACE_BYTES = 16 * 1024 * 1024 * 1024;
 const DATA_BYTES = 3 * 1024 * 1024 * 1024;
 const SURFACE_RUNTIME_SHA256 = OBJECT_FREEZE({
   'flow.js': '2ba972849bf435bba36b918c348efeab71ec34d180cec7a722e535f482687a6a',
-  'helpers/providers.js': '4eb06d0d85ca0a3434bb2dbba7407e3d95eef2dfbedaeb0e2de0c0c0ea812457',
+  'helpers/providers.js': 'cba2c6767673b47047c6cb9549c63e797b5a9b1af53e293c50ea028f64d21025',
   'provider-trigger.js': 'e2664c65397f93fb486eb6f1e756c7cec3f88b3851d79c23567cad986f80f1ff',
   'schedule.js': '8fe72f176a75ec0b5f26e12db7a597575c259a2e2cbb59690f9dc20a5e63940b',
   'triggers.js': '421609a6ea6d2ea77051dd4826a32e773b7db81dedd1dde91f4187b382cd46e3',

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 {