melchizedek-agents 1.0.3 → 1.2.0

package/dist/lib/models/reasoning.d.ts

@@ -12,15 +12,43 @@ import type { ReasoningLevel, ReasoningSetting } from './contract.ts';
 /**
  * Thinking tokens per level, for the providers that take a budget (Claude,
  * Gemini 2.x). The same table rounds a `budget_tokens` value up to a level
- * for the providers that take only a level or an effort word.
+ * for the providers that take only a level or an effort word. `xhigh` and
+ * `max` take `high`'s budget (ADR 0117): above it a non-streaming Claude
+ * request passes the Anthropic SDK's ceiling (ADR 0047), so a budget path
+ * sends them as `high`, and a budget never rounds up to either.
  */
 export declare const REASONING_BUDGETS: Readonly<Record<ReasoningLevel, number>>;
+/** The levels in order of how hard they ask the model to think. */
+export declare const REASONING_ORDER: readonly ReasoningLevel[];
+/** The levels above `high`, which only some models take (ADR 0117). */
+export declare const isAboveHigh: (setting: ReasoningSetting | undefined) => setting is 'xhigh' | 'max';
+/**
+ * The highest level the direct adapter for `model` sends as asked (ADR
+ * 0117); a level above it goes as this one. `max` where every level
+ * passes: Claude's adaptive generations (the Claude adapter sends its budget
+ * generations `high`'s budget) and Kimi K3. OpenAI's GPT-5.2 and later and
+ * grok-4.7 stop at `xhigh`; other OpenAI and Grok ids, Gemini and Ollama at
+ * `high`. A gateway stops at `high` whatever the id (gatewayAdapter.ts).
+ */
+export declare function effortCeiling(model: string): ReasoningLevel;
+/**
+ * The effort word an adapter sends for one setting: ADR 0047's word for the
+ * model, held at `ceiling` (default effortCeiling(model)). `weakened` is the
+ * level asked for when the word sent is below it; the adapter marks the span
+ * `llm.reasoning.weakened` with it.
+ */
+export declare function effortWord(model: string, setting: ReasoningSetting, ceiling?: ReasoningLevel): {
+    word: string;
+    weakened?: ReasoningLevel;
+};
 /**
  * The generateContentConfig fields a `reasoning:` setting becomes for one
  * model (ADR 0047). `reasoningEffort` is always set, so the gateway (which
  * may serve any id) carries the level too; the Claude adapter reads it first
  * on the adaptive generations (ADR 0049), and the genai SDK drops it from a
  * Gemini request. Claude and Gemini also get the `thinkingConfig` their
- * adapters read.
+ * adapters read. `xhigh` and `max` are written as asked (Kimi's `xhigh` as
+ * `max`), beside `high`'s thinkingConfig: the adapter holds the word at its
+ * model's ceiling (effortWord), so the setting reaches it intact (ADR 0117).
  */
 export declare function reasoningConfig(model: string, setting: ReasoningSetting): Record<string, unknown>;

package/dist/lib/models/reasoning.js

@@ -2,10 +2,25 @@ import { providerForModel } from './providerMap.js';
 /**
  * Thinking tokens per level, for the providers that take a budget (Claude,
  * Gemini 2.x). The same table rounds a `budget_tokens` value up to a level
- * for the providers that take only a level or an effort word.
+ * for the providers that take only a level or an effort word. `xhigh` and
+ * `max` take `high`'s budget (ADR 0117): above it a non-streaming Claude
+ * request passes the Anthropic SDK's ceiling (ADR 0047), so a budget path
+ * sends them as `high`, and a budget never rounds up to either.
  */
-export const REASONING_BUDGETS = { none: 0, low: 2048, medium: 8192, high: 16384 };
-const GEMINI_THINKING_LEVEL = { none: 'MINIMAL', low: 'LOW', medium: 'MEDIUM', high: 'HIGH' };
+export const REASONING_BUDGETS = { none: 0, low: 2048, medium: 8192, high: 16384, xhigh: 16384, max: 16384 };
+const GEMINI_THINKING_LEVEL = { none: 'MINIMAL', low: 'LOW', medium: 'MEDIUM', high: 'HIGH', xhigh: 'HIGH', max: 'HIGH' };
+/** The levels in order of how hard they ask the model to think. */
+export const REASONING_ORDER = ['none', 'low', 'medium', 'high', 'xhigh', 'max'];
+/** The levels above `high`, which only some models take (ADR 0117). */
+export const isAboveHigh = (setting) => setting === 'xhigh' || setting === 'max';
+/** An OpenAI id that takes `xhigh`: GPT-5.2 and later (the o-series and GPT-5 and 5.1 stop at `high`). */
+function openAiTakesXhigh(model) {
+    const m = /^gpt-(\d{1,3})(?:\.(\d{1,3}))?/.exec(model);
+    if (!m)
+        return false;
+    const major = Number(m[1]);
+    return major > 5 || (major === 5 && Number(m[2] ?? 0) >= 2);
+}
 /** The smallest level whose budget covers the setting: never less thought than asked. */
 function reasoningLevel(setting) {
     if (typeof setting === 'string')
@@ -29,18 +44,54 @@ function reasoningEffort(model, level) {
         case 'xai':
             return level === 'none' ? 'low' : level; // Grok 4.5/4.7 cannot stop reasoning
         case 'moonshot':
-            return level === 'medium' ? 'high' : level; // K3 has low | high | max
+            // K3 has low | high | max: a missing word rounds up.
+            return level === 'medium' ? 'high' : level === 'xhigh' ? 'max' : level;
         default:
             return level;
     }
 }
+/**
+ * The highest level the direct adapter for `model` sends as asked (ADR
+ * 0117); a level above it goes as this one. `max` where every level
+ * passes: Claude's adaptive generations (the Claude adapter sends its budget
+ * generations `high`'s budget) and Kimi K3. OpenAI's GPT-5.2 and later and
+ * grok-4.7 stop at `xhigh`; other OpenAI and Grok ids, Gemini and Ollama at
+ * `high`. A gateway stops at `high` whatever the id (gatewayAdapter.ts).
+ */
+export function effortCeiling(model) {
+    switch (providerForModel(model)) {
+        case 'anthropic':
+        case 'moonshot':
+            return 'max';
+        case 'openai':
+            return openAiTakesXhigh(model) ? 'xhigh' : 'high';
+        case 'xai':
+            return /^grok-4\.7(?!\d)/.test(model) ? 'xhigh' : 'high';
+        default:
+            return 'high';
+    }
+}
+/**
+ * The effort word an adapter sends for one setting: ADR 0047's word for the
+ * model, held at `ceiling` (default effortCeiling(model)). `weakened` is the
+ * level asked for when the word sent is below it; the adapter marks the span
+ * `llm.reasoning.weakened` with it.
+ */
+export function effortWord(model, setting, ceiling = effortCeiling(model)) {
+    const word = reasoningConfig(model, setting).reasoningEffort;
+    if (!isAboveHigh(setting) || REASONING_ORDER.indexOf(word) <= REASONING_ORDER.indexOf(ceiling))
+        return { word };
+    return { word: ceiling, weakened: setting };
+}
 /**
  * The generateContentConfig fields a `reasoning:` setting becomes for one
  * model (ADR 0047). `reasoningEffort` is always set, so the gateway (which
  * may serve any id) carries the level too; the Claude adapter reads it first
  * on the adaptive generations (ADR 0049), and the genai SDK drops it from a
  * Gemini request. Claude and Gemini also get the `thinkingConfig` their
- * adapters read.
+ * adapters read. `xhigh` and `max` are written as asked (Kimi's `xhigh` as
+ * `max`), beside `high`'s thinkingConfig: the adapter holds the word at its
+ * model's ceiling (effortWord), so the setting reaches it intact (ADR 0117).
  */
 export function reasoningConfig(model, setting) {
     const level = reasoningLevel(setting);

package/dist/lib/observability/tracer.d.ts

@@ -1,4 +1,4 @@
-import type { SpanContext } from '@opentelemetry/api';
+import type { Span, SpanContext, SpanOptions } from '@opentelemetry/api';
 import type { ReadableSpan } from '@opentelemetry/sdk-trace-base';
 import type { LlmResponse } from '../models/genaiMapping.ts';
 import type { TurnEvent as Event } from '../runtime/events.ts';
@@ -43,6 +43,13 @@ export declare function takeTraceStats(traceId: string): TraceStats | undefined;
 /** Name of the agent of the nearest enclosing agent span (ADK's `invoke_agent`, the loop's `agent.invoke`), or null. */
 export declare function agentForSpan(spanId: string | undefined): string | null;
 export declare function initializeTracing(): void;
+/**
+ * Starts a span on the named tracer, starting the tracer first; in a turn
+ * that opted out of tracing, a non-recording span and no tracer. Every span
+ * the engine opens inside a turn goes through here or checks turnUntraced
+ * itself.
+ */
+export declare function startEngineSpan(tracerName: string, name: string, options?: SpanOptions): Span;
 export interface TraceMetadata {
     syndicateName: string;
     bindings?: Record<string, any>;

package/dist/lib/observability/tracer.js

@@ -1,9 +1,9 @@
-import { trace, context, defaultTextMapGetter, ROOT_CONTEXT } from '@opentelemetry/api';
+import { trace, context, defaultTextMapGetter, ROOT_CONTEXT, INVALID_SPAN_CONTEXT } from '@opentelemetry/api';
 import { createRequire } from 'node:module';
 import { ADK_SPAN_SCOPE, RUNTIME_SPAN_SCOPE, TELEMETRY_SCHEMA_VERSION, agentOfSpanName, engineVersion, isModelCallSpan, isToolSpanName } from './lineage.js';
 import { FilteringSpanExporter, otlpContentMode } from './otlpFilter.js';
 import { telemetryRedactor } from './redact.js';
-import { chargeLlmCall, chargeTokens } from '../runtime/turnControl.js';
+import { chargeLlmCall, chargeTokens, turnUntraced } from '../runtime/turnControl.js';
 import sdkNode from '@opentelemetry/sdk-trace-node';
 const { NodeTracerProvider } = sdkNode;
 import sdkBase from '@opentelemetry/sdk-trace-base';
@@ -275,6 +275,26 @@ export function initializeTracing() {
     }
 }
 const tracer = trace.getTracer('melchizedek-tracer');
+/**
+ * A span that records nothing, for code running in a turn that opted out of
+ * tracing (`runSyndicateTurn({ trace: false })`, turnUntraced): its
+ * attributes, events and end go nowhere, and no tracer is started for it.
+ */
+function nonRecordingSpan() {
+    return trace.wrapSpanContext(INVALID_SPAN_CONTEXT);
+}
+/**
+ * Starts a span on the named tracer, starting the tracer first; in a turn
+ * that opted out of tracing, a non-recording span and no tracer. Every span
+ * the engine opens inside a turn goes through here or checks turnUntraced
+ * itself.
+ */
+export function startEngineSpan(tracerName, name, options) {
+    if (turnUntraced())
+        return nonRecordingSpan();
+    initializeTracing();
+    return trace.getTracer(tracerName).startSpan(name, options);
+}
 /** Turn identity by trace id, so llm.request children can carry it too. */
 const turnContexts = new Map();
 /**
@@ -328,6 +348,11 @@ export function callerSpanContext(traceparent) {
     return trace.getSpanContext(ctx);
 }
 export async function* traceAgentRun(stream, metadata) {
+    // A turn that opted out of tracing gets its events untouched and no span.
+    if (turnUntraced()) {
+        yield* stream;
+        return;
+    }
     initializeTracing();
     const caller = callerSpanContext(metadata.traceparent);
     const span = tracer.startSpan(`Syndicate Execution: ${metadata.syndicateName}`, caller ? { links: [{ context: caller }], attributes: { 'caller.trace_id': caller.traceId } } : undefined);
@@ -551,7 +576,10 @@ function refineErrorCode(code, message) {
  * (e.g. llm.web_search.native) via setLlmSpanAttribute below.
  */
 export async function* traceLlmGeneration(meta, inner) {
-    initializeTracing();
+    // An untraced turn still charges the call and its tokens; it opens no span.
+    const untraced = turnUntraced();
+    if (!untraced)
+        initializeTracing();
     // Every model call on every provider passes here, so this is where the
     // turn's step budget and cancellation are enforced (lib/runtime/
     // turnControl.ts). A refused call never reaches the provider.
@@ -561,7 +589,7 @@ export async function* traceLlmGeneration(meta, inner) {
         yield { errorCode: charge.code, errorMessage: charge.message };
         return;
     }
-    const span = tracer.startSpan('llm.request');
+    const span = untraced ? nonRecordingSpan() : tracer.startSpan('llm.request');
     span.setAttribute('llm.provider', meta.provider);
     span.setAttribute('llm.model', meta.model);
     // OpenTelemetry GenAI semantic conventions alongside the llm.* names, so
@@ -633,7 +661,7 @@ export async function* traceLlmGeneration(meta, inner) {
         if (thinkingPreview) {
             span.addEvent('llm.thinking', { 'thinking.preview': thinkingPreview });
         }
-        if (errorCode) {
+        if (errorCode && span.isRecording()) {
             span.setAttribute('llm.error_code', errorCode);
             span.setAttribute('llm.error_message', errorMessage.slice(0, ERROR_MESSAGE_MAX_CHARS));
             // Make this span a payload candidate (see supabaseSpanExporter's

package/dist/lib/onboarding.d.ts

@@ -0,0 +1,134 @@
+/**
+ * lib/onboarding.ts — the authentication levels and their startup guides.
+ *
+ * WHY this file exists:
+ *   A newcomer arrives with something: no key, one provider's key, several, a
+ *   gateway key, a cloud account, a server to put in front of other people,
+ *   or a ChatGPT / Claude.ai / Gemini CLI sign-in. Each of those is a
+ *   different first ten minutes. This module names those levels once, from
+ *   what the engine actually supports (lib/models/providerMap.ts,
+ *   endpoints.ts, gateway.ts, the A2A server's identity modes and the OAuth
+ *   grant setup), and renders one startup guide per level. The
+ *   `melchizedek-setup` menu prints these guides and ONBOARDING.md is
+ *   generated from the same function, so the two cannot drift
+ *   (tests/onboarding.test.ts holds them equal).
+ *
+ * DETECTION IS THE DOCTOR'S:
+ *   `detectLevels` reads a DoctorResult (lib/doctor.ts: the providers line,
+ *   the gateway, the cloud endpoints, the serving and OAuth lines). It never
+ *   reads a key itself, so `--auto` cannot disagree with the doctor.
+ *
+ * WHAT IT NEVER DOES:
+ *   print a value. Guides carry variable NAMES and SHAPES; detection carries
+ *   names and set/unset. Writing `.env` (writeEnvForLevel) copies
+ *   `.env.example`, leaves every chosen name blank, refuses to overwrite an
+ *   existing file, and refuses unless `git check-ignore` says `.env` is
+ *   ignored (secrets-hygiene).
+ */
+import type { DoctorResult, Tier } from './doctor.ts';
+export type LevelId = 'local' | 'one-provider' | 'several-providers' | 'gateway' | 'cloud-platform' | 'byok' | 'caller-tokens' | 'oauth-grants' | 'subscription-signin';
+/** How a command is spelled: in a project that installed the package, or in a clone of the repository. */
+export type CommandForm = 'package' | 'clone';
+export interface EnvLine {
+    name: string;
+    /** The shape of the value, never a value. */
+    shape: string;
+    /** What setting it does. */
+    purpose: string;
+}
+export interface Level {
+    id: LevelId;
+    /** The menu line: what the user has. */
+    menu: string;
+    title: string;
+    summary: string;
+    env: EnvLine[];
+    /** What the doctor shows when this level is set up. */
+    confirm: string;
+    /** Shipped syndicates that run at this level, rendered by `shippedFor`. */
+    runs: (shipped: ShippedIndex) => string[];
+    first: Record<CommandForm, string[]>;
+    notes: string[];
+    /** The onboarding skill a coding agent follows for this level. */
+    skill: string;
+    /** False for an entry that is not a way to run the engine (subscription sign-ins). */
+    detectable: boolean;
+}
+/** Shipped templates and examples by the tier their models imply, and which declare an OAuth grant. */
+export interface ShippedIndex {
+    byTier: Partial<Record<Tier, string[]>>;
+    withGrants: string[];
+    /** Files that carry a commented-out `oauth2:` grant to start from. */
+    grantExamples: string[];
+    templates: string[];
+}
+/** The package (or clone) root: the directory holding config/agents/syndicate.schema.json. */
+export declare function packageRoot(from?: string): string;
+/**
+ * Index the shipped templates and examples by tier, using the doctor's own
+ * diagnosis (lib/doctor.ts `diagnoseSyndicate`: the tier the models imply,
+ * and the OAuth grants the tools declare). The tier does not depend on the
+ * environment, so the index is the same wherever it is computed.
+ */
+export declare function shippedIndex(root?: string): ShippedIndex;
+export declare const LEVELS: readonly Level[];
+export declare function levelById(id: string): Level | undefined;
+/** Every variable name the guides mention. */
+export declare function guideEnvNames(): string[];
+/** One level's startup guide, as Markdown (the terminal prints the same text). */
+export declare function renderGuide(level: Level, form: CommandForm, shipped?: ShippedIndex): string;
+/** The menu: one numbered line per level. */
+export declare function renderMenu(): string;
+/** ONBOARDING.md, generated in full from the levels (package spelling). */
+export declare function renderOnboardingDoc(shipped?: ShippedIndex): string;
+export interface LevelDetection {
+    id: LevelId;
+    detected: boolean;
+    /** Names and set/unset only. */
+    evidence: string;
+    /** The doctor's problems for this level, by variable name. */
+    problems: string[];
+}
+/**
+ * Which levels the environment is set up for, read from the doctor's result.
+ * Local is always available (whether Ollama is running is not checked).
+ */
+export declare function detectLevels(result: DoctorResult): LevelDetection[];
+/** The highest detected level (the last in menu order). */
+export declare function highestLevel(detections: LevelDetection[]): Level;
+/** `--auto`: what the environment has (names only), then the guide for the highest level. */
+export declare function renderAuto(result: DoctorResult, form: CommandForm, shipped?: ShippedIndex): string;
+export type EnvWriteResult = {
+    status: 'written';
+    path: string;
+    added: string[];
+} | {
+    status: 'exists';
+    path: string;
+} | {
+    status: 'not-ignored';
+    path: string;
+    reason: string;
+} | {
+    status: 'no-template';
+    path: string;
+};
+/** True when git confirms `.env` in `cwd` is ignored (exit 0 from `git check-ignore`). */
+export declare function gitIgnoresEnv(cwd: string): {
+    ignored: boolean;
+    reason: string;
+};
+/**
+ * Create `.env` from `.env.example` for a level: the template verbatim, then
+ * every name the level lists that the template does not already assign, left
+ * blank. Never overwrites, never writes a value, and refuses unless git
+ * confirms `.env` is ignored. The file is created mode 600.
+ */
+export declare function writeEnvForLevel(level: Level, opts?: {
+    cwd?: string;
+    root?: string;
+    checkIgnored?: (cwd: string) => {
+        ignored: boolean;
+        reason: string;
+    };
+}): EnvWriteResult;