@bubblebrain-ai/bubble 0.0.63 → 0.0.65

package/dist/agent/structured-output.js

@@ -0,0 +1,193 @@
+/**
+ * Structured output for subagents (design v2 §1.2).
+ *
+ * When a spawn/batch member carries an `output_schema`, its task is augmented
+ * with an instruction to return ONLY JSON matching the schema; after it
+ * finishes, its summary is validated against the schema, with one corrective
+ * retry. The parent then gets a typed object it can branch on, rather than
+ * prose to re-parse.
+ *
+ * The validator is a deliberately small, dependency-free subset of JSON Schema
+ * — enough for LLM structured output (object/array/string/number/integer/
+ * boolean/null, properties, required, items, enum, nullable). It is not a full
+ * JSON Schema implementation; unknown keywords are ignored (permissive).
+ */
+/** Extracts a JSON value from a child summary that may be fenced or prose-wrapped. */
+export function extractJson(summary) {
+    const text = (summary ?? "").trim();
+    if (!text)
+        return { ok: false, error: "empty summary" };
+    const candidates = [];
+    // 1) ```json … ``` or ``` … ``` fenced block.
+    const fence = text.match(/```(?:json)?\s*([\s\S]*?)```/i);
+    if (fence?.[1])
+        candidates.push(fence[1].trim());
+    // 2) the whole string.
+    candidates.push(text);
+    // 3) the first balanced {...} or [...] span.
+    const span = firstBalancedSpan(text);
+    if (span)
+        candidates.push(span);
+    for (const candidate of candidates) {
+        try {
+            return { ok: true, value: JSON.parse(candidate) };
+        }
+        catch {
+            // try the next candidate
+        }
+    }
+    return { ok: false, error: "no parseable JSON found in summary" };
+}
+function firstBalancedSpan(text) {
+    const start = text.search(/[[{]/);
+    if (start < 0)
+        return undefined;
+    const open = text[start];
+    const close = open === "{" ? "}" : "]";
+    let depth = 0;
+    let inString = false;
+    let escaped = false;
+    for (let i = start; i < text.length; i++) {
+        const ch = text[i];
+        if (inString) {
+            if (escaped)
+                escaped = false;
+            else if (ch === "\\")
+                escaped = true;
+            else if (ch === '"')
+                inString = false;
+            continue;
+        }
+        if (ch === '"')
+            inString = true;
+        else if (ch === open)
+            depth++;
+        else if (ch === close) {
+            depth--;
+            if (depth === 0)
+                return text.slice(start, i + 1);
+        }
+    }
+    return undefined;
+}
+/** Validates a child summary: extracts JSON then checks it against the schema. */
+export function validateStructuredSummary(summary, schema) {
+    const extracted = extractJson(summary);
+    if (!extracted.ok)
+        return { ok: false, errors: [extracted.error] };
+    const errors = [];
+    validateValue(extracted.value, schema, "$", errors);
+    return errors.length === 0 ? { ok: true, value: extracted.value } : { ok: false, errors };
+}
+function validateValue(value, schema, path, errors) {
+    if (!schema || typeof schema !== "object")
+        return; // permissive: no constraints
+    const s = schema;
+    // enum
+    if (Array.isArray(s.enum)) {
+        if (!s.enum.some((option) => deepEqual(option, value))) {
+            errors.push(`${path}: value not in enum`);
+        }
+    }
+    const declaredType = s.type;
+    const types = Array.isArray(declaredType)
+        ? declaredType.filter((t) => typeof t === "string")
+        : typeof declaredType === "string"
+            ? [declaredType]
+            : [];
+    const nullable = s.nullable === true || types.includes("null");
+    if (value === null) {
+        if (types.length > 0 && !nullable)
+            errors.push(`${path}: null not allowed`);
+        return;
+    }
+    if (types.length > 0 && !types.some((t) => matchesType(value, t))) {
+        errors.push(`${path}: expected ${types.join("|")}, got ${jsonType(value)}`);
+        return; // type mismatch — deeper checks would be noise
+    }
+    // object
+    if (matchesType(value, "object") && typeof value === "object" && !Array.isArray(value)) {
+        const obj = value;
+        if (Array.isArray(s.required)) {
+            for (const key of s.required) {
+                if (typeof key === "string" && !(key in obj))
+                    errors.push(`${path}.${key}: required`);
+            }
+        }
+        if (s.properties && typeof s.properties === "object") {
+            const props = s.properties;
+            for (const [key, sub] of Object.entries(props)) {
+                if (key in obj)
+                    validateValue(obj[key], sub, `${path}.${key}`, errors);
+            }
+        }
+    }
+    // array
+    if (Array.isArray(value) && s.items && typeof s.items === "object") {
+        value.forEach((item, i) => validateValue(item, s.items, `${path}[${i}]`, errors));
+    }
+}
+function matchesType(value, type) {
+    switch (type) {
+        case "object": return typeof value === "object" && value !== null && !Array.isArray(value);
+        case "array": return Array.isArray(value);
+        case "string": return typeof value === "string";
+        case "number": return typeof value === "number" && Number.isFinite(value);
+        case "integer": return typeof value === "number" && Number.isInteger(value);
+        case "boolean": return typeof value === "boolean";
+        case "null": return value === null;
+        default: return true; // unknown type keyword — permissive
+    }
+}
+function jsonType(value) {
+    if (value === null)
+        return "null";
+    if (Array.isArray(value))
+        return "array";
+    return typeof value;
+}
+function deepEqual(a, b) {
+    if (a === b)
+        return true;
+    if (typeof a !== typeof b || a === null || b === null)
+        return false;
+    if (Array.isArray(a) && Array.isArray(b)) {
+        return a.length === b.length && a.every((x, i) => deepEqual(x, b[i]));
+    }
+    if (typeof a === "object" && typeof b === "object") {
+        const ka = Object.keys(a);
+        const kb = Object.keys(b);
+        return ka.length === kb.length && ka.every((k) => deepEqual(a[k], b[k]));
+    }
+    return false;
+}
+/** Appends the "respond with only JSON matching this schema" instruction to a task. */
+export function appendOutputSchemaInstructions(task, schema) {
+    return [
+        task,
+        "",
+        "OUTPUT FORMAT (required): your entire final handoff must be a single JSON value that conforms to this JSON Schema, and nothing else — no prose before or after, no markdown fences.",
+        "JSON Schema:",
+        safeSchemaString(schema),
+    ].join("\n");
+}
+/** Corrective re-prompt sent once when the first summary fails validation. */
+export function buildSchemaCorrectionPrompt(schema, previous) {
+    return [
+        "Your previous response was not valid JSON for the required schema.",
+        "Reply again with ONLY a single JSON value conforming to this schema — no prose, no code fences.",
+        "JSON Schema:",
+        safeSchemaString(schema),
+        "",
+        "Your previous (invalid) response was:",
+        (previous ?? "").slice(0, 2000),
+    ].join("\n");
+}
+function safeSchemaString(schema) {
+    try {
+        return JSON.stringify(schema, null, 2);
+    }
+    catch {
+        return String(schema);
+    }
+}

package/dist/agent/subagent/router.d.ts

@@ -0,0 +1,65 @@
+/**
+ * Subagent model routing (design §3-§7).
+ *
+ * Extracted from Agent so the routing decision chain and the routing prompt
+ * rendering live in one place: before this, the decision side sat next to the
+ * subagent dispatch code while `buildModelRoutingPromptSection` /
+ * `renderModelRoutingPromptFor` sat 2,000 lines away at the top of the class,
+ * with both halves reading the same `agentRouting` / `routingSnapshot` fields.
+ *
+ * The parent route is supplied as a thunk, never a snapshot: `/model` mutates
+ * the parent's provider, model and thinking level mid-session, and children
+ * spawned afterwards must inherit the CURRENT values.
+ */
+import { type AgentCategoriesConfig, type ResolvedSubagentRoute } from "../categories.js";
+import { type AgentRoutingConfig, type RoutableModelEntry, type RoutableModelIndex, type RoutingSnapshot, type RoutingSnapshotAccessor } from "../routing-catalog.js";
+import type { AgentProfile } from "../profiles.js";
+import type { ThinkingLevel } from "../../types.js";
+export interface ParentRoute {
+    providerId: string;
+    /** The API-facing model id — already stripped of any "provider:" prefix. */
+    model: string;
+    thinkingLevel: ThinkingLevel;
+}
+export interface SubagentRouterDeps {
+    /**
+     * Live parent route. MUST read through to the agent on every call — `/model`
+     * reassigns provider/model/thinking mid-session (see slash-commands), and a
+     * captured snapshot would route children to the pre-switch model.
+     */
+    parentRoute(): ParentRoute;
+    categories: AgentCategoriesConfig;
+    routing: AgentRoutingConfig;
+    snapshot?: RoutingSnapshotAccessor;
+    routableModels?: RoutableModelIndex;
+}
+export declare class SubagentRouter {
+    private readonly deps;
+    constructor(deps: SubagentRouterDeps);
+    /** Live snapshot for the CURRENT parent route; undefined when no accessor is wired. */
+    currentSnapshot(): RoutingSnapshot | undefined;
+    resolve(profile: AgentProfile, category: string | undefined, override?: {
+        model?: string;
+        effort?: ThinkingLevel;
+    }): ResolvedSubagentRoute;
+    /**
+     * Early route validation at dispatch time (design §7). Throws with an
+     * actionable message so the model self-corrects in the same turn. The
+     * cross-provider lock (§7.2.1) is snapshot-independent; catalog checks
+     * degrade silently when no snapshot is available (§7.0).
+     */
+    validateForDispatch(route: ResolvedSubagentRoute): string | undefined;
+    /** Routable catalog across runnable providers (design v3.6); undefined when unwired. */
+    listRoutableModels(): RoutableModelEntry[] | undefined;
+    /** Current routing menu (design §4); undefined when no accessor is wired. */
+    promptSection(): string | undefined;
+    /**
+     * Routing menu rendered for a prospective parent route — used by model-
+     * switch transactions to build the NEXT prompt before mutating the agent
+     * (design §1.5).
+     */
+    promptSectionFor(parent: {
+        providerId: string;
+        model: string;
+    }): string | undefined;
+}

package/dist/agent/subagent/router.js

@@ -0,0 +1,203 @@
+/**
+ * Subagent model routing (design §3-§7).
+ *
+ * Extracted from Agent so the routing decision chain and the routing prompt
+ * rendering live in one place: before this, the decision side sat next to the
+ * subagent dispatch code while `buildModelRoutingPromptSection` /
+ * `renderModelRoutingPromptFor` sat 2,000 lines away at the top of the class,
+ * with both halves reading the same `agentRouting` / `routingSnapshot` fields.
+ *
+ * The parent route is supplied as a thunk, never a snapshot: `/model` mutates
+ * the parent's provider, model and thinking level mid-session, and children
+ * spawned afterwards must inherit the CURRENT values.
+ */
+import { mergeAgentCategories, resolveModelRoute, resolveSubagentRoute } from "../categories.js";
+import { nearModelMatches, tierContextFromSnapshot } from "../routing-catalog.js";
+import { buildModelRoutingPrompt } from "../../prompt/routing.js";
+import { getBuiltinModel } from "../../model-catalog.js";
+import { getAvailableThinkingLevels, getDefaultThinkingLevel, normalizeInheritedThinkingLevel, normalizeThinkingLevel } from "../../variant/variant-resolver.js";
+import { providerModelPolicyError } from "../../provider-model-policy.js";
+export class SubagentRouter {
+    deps;
+    constructor(deps) {
+        this.deps = deps;
+    }
+    /** Live snapshot for the CURRENT parent route; undefined when no accessor is wired. */
+    currentSnapshot() {
+        if (!this.deps.snapshot)
+            return undefined;
+        const parent = this.deps.parentRoute();
+        try {
+            return this.deps.snapshot({ providerId: parent.providerId, model: parent.model });
+        }
+        catch {
+            // Catalog data is an enhancement, never a spawn blocker.
+            return undefined;
+        }
+    }
+    resolve(profile, category, override) {
+        const parentRoute = this.deps.parentRoute();
+        const snapshot = this.currentSnapshot();
+        const resolved = resolveSubagentRoute(category ?? profile.category, { ...parentRoute }, this.deps.categories, snapshot ? tierContextFromSnapshot(snapshot, this.deps.routing) : undefined);
+        if ("error" in resolved) {
+            throw new Error(resolved.error);
+        }
+        let route = resolved.route;
+        // modelSource is assigned while applying the chain (design §3.4): an
+        // explicit layer naming the parent's own model is indistinguishable from
+        // inherit by final-value comparison, yet carries different authority.
+        let modelSource = route.categoryModelSource ?? "inherit";
+        if (profile.model && profile.model !== "inherit") {
+            const model = resolveModelRoute(profile.model, parentRoute.providerId);
+            if (model.model !== "inherit") {
+                route = { ...route, providerId: model.providerId, model: model.model, inherited: false };
+                modelSource = "profile";
+            }
+        }
+        // Call-site override beats profile and category. Bare names resolve
+        // against the PARENT provider per the tool contract (design §3.5) — not
+        // against a provider that category/profile may already have switched.
+        if (override?.model) {
+            const model = resolveModelRoute(override.model, parentRoute.providerId);
+            if (model.model !== "inherit") {
+                route = { ...route, providerId: model.providerId, model: model.model, inherited: false };
+                modelSource = "callsite";
+            }
+        }
+        const supportedLevels = getAvailableThinkingLevels(route.providerId, route.model);
+        const modelMetadata = getBuiltinModel(route.providerId, route.model);
+        const hasTrustedEffortMetadata = !!modelMetadata
+            && modelMetadata.reasoningLevels.some((level) => level !== "off");
+        if (override?.effort) {
+            // A call-site effort is explicit user/model intent: preserve the existing
+            // value for legacy/unknown models, and downward-clamp only when the
+            // catalog declares real effort capabilities (for example Luna ultra -> max).
+            route = {
+                ...route,
+                thinkingLevel: hasTrustedEffortMetadata
+                    ? normalizeThinkingLevel(override.effort, supportedLevels)
+                    : override.effort,
+                inherited: false,
+            };
+        }
+        else if (hasTrustedEffortMetadata) {
+            const categoryThinkingLevel = route.category
+                ? mergeAgentCategories(this.deps.categories)[route.category]?.thinkingLevel
+                : undefined;
+            // A category's thinkingLevel is calibrated for the model the CATEGORY
+            // resolved. When a later layer (profile/call-site) replaced the model,
+            // that level is no longer explicit intent for the final model: keep it
+            // only if supported, else use the final model's own default — never
+            // downward-clamp a thinking-default model to "off" (v3.6; live case:
+            // explore's "low" + call-site glm-5.2 [high/max/off] silently landed
+            // on "off").
+            const modelReplacedAfterCategory = modelSource === "profile" || modelSource === "callsite";
+            route = {
+                ...route,
+                thinkingLevel: categoryThinkingLevel
+                    ? (modelReplacedAfterCategory && !supportedLevels.includes(route.thinkingLevel)
+                        ? getDefaultThinkingLevel(route.providerId, route.model)
+                        : normalizeThinkingLevel(route.thinkingLevel, supportedLevels))
+                    : normalizeInheritedThinkingLevel(route.providerId, route.model, route.thinkingLevel),
+            };
+        }
+        return {
+            ...route,
+            modelSource,
+            modelInherited: route.providerId === parentRoute.providerId && route.model === parentRoute.model,
+        };
+    }
+    /**
+     * Early route validation at dispatch time (design §7). Throws with an
+     * actionable message so the model self-corrects in the same turn. The
+     * cross-provider lock (§7.2.1) is snapshot-independent; catalog checks
+     * degrade silently when no snapshot is available (§7.0).
+     */
+    validateForDispatch(route) {
+        const parentProviderId = this.deps.parentRoute().providerId;
+        const resolvedProviderId = route.providerId || parentProviderId;
+        const fixedPolicyError = providerModelPolicyError(resolvedProviderId, route.model);
+        if (fixedPolicyError)
+            throw new Error(fixedPolicyError);
+        const snapshot = this.currentSnapshot();
+        const crossProvider = !!route.providerId && route.providerId !== parentProviderId;
+        if (crossProvider) {
+            // §7.2.1 — the lock. Profile/user-category routes are standing user
+            // authorization and always pass; only call-site routes are lockable.
+            if (!this.deps.routing.allowCrossProvider && route.modelSource === "callsite") {
+                throw new Error("Cross-provider routing is disabled in this session's config (agentRouting.allowCrossProvider). "
+                    + "Use a model from the parent provider, or ask the user to unlock cross-provider routing.");
+            }
+            // §7.2.2 — credentials, when a snapshot is available.
+            if (snapshot && !snapshot.runnableProviderIds.includes(route.providerId)) {
+                throw new Error(`Provider "${route.providerId}" is not configured with active credentials. `
+                    + `Available: ${snapshot.runnableProviderIds.join(", ") || "(none)"}.`);
+            }
+            // §7.2.3 amended (v3.6): the provider stays the authority — no hard
+            // catalog rejection — but a near-match against the target provider's
+            // local catalog is positive evidence of a mistyped id (a Grok parent
+            // invented "openai:gpt-5.6" for gpt-5.6-sol), so soft-reject with the
+            // correction and let the model fix it this turn. Genuinely unknown ids
+            // (no near candidates) still pass through with a note.
+            const targetCatalog = this.deps.routableModels?.()
+                .filter((entry) => entry.providerId === route.providerId) ?? [];
+            if (targetCatalog.length > 0 && !targetCatalog.some((entry) => entry.id === route.model)) {
+                const near = nearModelMatches(route.model, targetCatalog, { mode: "truncation" });
+                if (near.length > 0) {
+                    throw new Error(`Unknown model "${route.model}" for provider "${route.providerId}". Did you mean: ${near.join(", ")}?`);
+                }
+                return `model ${route.providerId}:${route.model} is not in the local catalog; the provider validates it`;
+            }
+            return `model ${route.providerId}:${route.model} is not locally verifiable; the provider validates it`;
+        }
+        // §7.1 — same-provider unknown model, resolved-provider based (never
+        // input-syntax based; qualified same-provider ids land here too).
+        if (snapshot && route.modelSource === "callsite") {
+            const known = snapshot.models.some((model) => model.id === route.model);
+            if (!known) {
+                if (snapshot.authoritative) {
+                    const available = snapshot.models
+                        .map((model) => (model.tier ? `${model.id} (${model.tier})` : model.id))
+                        .join(", ");
+                    throw new Error(`Unknown model "${route.model}" for provider "${parentProviderId}". Available: ${available}.`);
+                }
+                const near = nearModelMatches(route.model, snapshot.models.map((model) => ({ providerId: parentProviderId, id: model.id, name: model.name })));
+                return near.length > 0
+                    ? `model id "${route.model}" is unrecognized locally (did you mean: ${near.join(", ")}?); the provider validates it`
+                    : `model id "${route.model}" is unrecognized locally; the provider validates it`;
+            }
+        }
+        return undefined;
+    }
+    /** Routable catalog across runnable providers (design v3.6); undefined when unwired. */
+    listRoutableModels() {
+        try {
+            return this.deps.routableModels?.();
+        }
+        catch {
+            return undefined;
+        }
+    }
+    /** Current routing menu (design §4); undefined when no accessor is wired. */
+    promptSection() {
+        const snapshot = this.currentSnapshot();
+        if (!snapshot)
+            return undefined;
+        return buildModelRoutingPrompt(snapshot, this.deps.routing);
+    }
+    /**
+     * Routing menu rendered for a prospective parent route — used by model-
+     * switch transactions to build the NEXT prompt before mutating the agent
+     * (design §1.5).
+     */
+    promptSectionFor(parent) {
+        if (!this.deps.snapshot)
+            return undefined;
+        try {
+            return buildModelRoutingPrompt(this.deps.snapshot(parent), this.deps.routing);
+        }
+        catch {
+            return undefined;
+        }
+    }
+}