@lloyal-labs/rig 2.1.0 → 3.0.0

package/dist/tools/keyless-search.js

@@ -0,0 +1,401 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createKeylessSearchProvider = createKeylessSearchProvider;
+const effection_1 = require("effection");
+const lloyal_agents_1 = require("@lloyal-labs/lloyal-agents");
+// ── Endpoints ───────────────────────────────────────────────────
+const DDG_URL = "https://html.duckduckgo.com/html/";
+const MARGINALIA_URL = "https://api2.marginalia-search.com/search";
+const DEFAULT_USER_AGENT = "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/605.1.15 (KHTML, like Gecko) Version/17.0 Safari/605.1.15";
+const TRACKING_PARAMS = new Set([
+    "utm_source",
+    "utm_medium",
+    "utm_campaign",
+    "utm_term",
+    "utm_content",
+    "gclid",
+    "fbclid",
+    "mc_cid",
+    "mc_eid",
+    "ref",
+    "ref_src",
+]);
+function createBreaker(threshold, cooldownMs) {
+    let state = "closed";
+    let failures = 0;
+    let openedAt = 0;
+    return {
+        canProceed() {
+            if (state === "closed" || state === "half-open")
+                return true;
+            if (Date.now() - openedAt >= cooldownMs) {
+                state = "half-open";
+                return true;
+            }
+            return false;
+        },
+        onSuccess() {
+            state = "closed";
+            failures = 0;
+        },
+        onHardFailure() {
+            if (state === "half-open") {
+                state = "open";
+                openedAt = Date.now();
+                failures = threshold;
+                return;
+            }
+            failures++;
+            if (failures >= threshold) {
+                state = "open";
+                openedAt = Date.now();
+            }
+        },
+        get state() {
+            return state;
+        },
+    };
+}
+/**
+ * Scope-owned shared pacer. A single internal `spawn` loop pops one waiter
+ * per jittered interval. Concurrent callers wait their turn via `action()`;
+ * the action's cleanup deregisters a waiter if its caller scope halts before
+ * release, so cancelled callers never resolve into a stale slot.
+ *
+ * No timestamp arithmetic per caller — central loop owns all timing.
+ */
+function useRequestPacer(opts) {
+    return (0, effection_1.resource)(function* (provide) {
+        const waiters = [];
+        yield* (0, effection_1.spawn)(function* () {
+            while (true) {
+                const delay = opts.baseMs + Math.floor(Math.random() * opts.jitterMs);
+                yield* opts.sleepOp(delay);
+                const next = waiters.shift();
+                if (next)
+                    next();
+            }
+        });
+        yield* provide({
+            acquire() {
+                return (0, effection_1.action)((resolve) => {
+                    const fn = () => resolve();
+                    waiters.push(fn);
+                    return () => {
+                        const i = waiters.indexOf(fn);
+                        if (i >= 0)
+                            waiters.splice(i, 1);
+                    };
+                });
+            },
+        });
+    });
+}
+// ── Internal: cancellable HTTP ──────────────────────────────────
+class HardFailure extends Error {
+}
+/**
+ * Effection-native cancellable timeout. `race` halts the loser on win, and
+ * `useAbortSignal` aborts the underlying socket when the http leg is halted.
+ * If the timeout wins, `HardFailure` is thrown and the in-flight fetch is
+ * genuinely cancelled — not abandoned.
+ */
+function* fetchWithTimeout(url, init, timeoutMs, fetchImpl, sleepOp) {
+    const httpLeg = function* () {
+        const signal = yield* (0, effection_1.useAbortSignal)();
+        const res = yield* (0, effection_1.call)(() => fetchImpl(url, { ...init, signal }));
+        const text = yield* (0, effection_1.call)(() => res.text());
+        return { status: res.status, text };
+    };
+    const timeoutLeg = function* () {
+        yield* sleepOp(timeoutMs);
+        throw new HardFailure(`Request timed out after ${timeoutMs}ms`);
+    };
+    return yield* (0, effection_1.race)([httpLeg(), timeoutLeg()]);
+}
+// ── Internal: DDG parsing ───────────────────────────────────────
+const HTML_ENTITY_RE = /&(amp|lt|gt|quot|#x27|#39);/g;
+const HTML_ENTITIES = {
+    amp: "&",
+    lt: "<",
+    gt: ">",
+    quot: '"',
+    "#x27": "'",
+    "#39": "'",
+};
+function decodeHtml(s) {
+    return s.replace(HTML_ENTITY_RE, (_, e) => HTML_ENTITIES[e] ?? "");
+}
+function stripTags(s) {
+    return s.replace(/<[^>]*>/g, "").replace(/\s+/g, " ").trim();
+}
+const ANCHOR_RE = /<a\b([^>]*)>([\s\S]*?)<\/a>/g;
+const HREF_RE = /\bhref="([^"]+)"/;
+const CLASS_RE = /\bclass="([^"]*)"/;
+/**
+ * Extract `result__a` (title + href) and `result__snippet` anchors from a
+ * DuckDuckGo HTML SERP. Returns an empty array on length-too-short or
+ * zero-anchor output (treated as soft-block by the caller).
+ */
+function parseDdgHtml(html) {
+    if (!html || html.length < 200)
+        return [];
+    const titles = [];
+    const snippets = [];
+    for (const m of html.matchAll(ANCHOR_RE)) {
+        const attrs = m[1];
+        const inner = m[2];
+        const clsMatch = CLASS_RE.exec(attrs);
+        if (!clsMatch)
+            continue;
+        const classes = clsMatch[1].split(/\s+/);
+        if (classes.includes("result__a")) {
+            const hrefMatch = HREF_RE.exec(attrs);
+            if (!hrefMatch)
+                continue;
+            titles.push({
+                url: decodeHtml(hrefMatch[1]),
+                title: decodeHtml(stripTags(inner)),
+            });
+        }
+        else if (classes.includes("result__snippet")) {
+            snippets.push(decodeHtml(stripTags(inner)));
+        }
+    }
+    const out = [];
+    for (let i = 0; i < titles.length; i++) {
+        out.push({
+            title: titles[i].title,
+            url: titles[i].url,
+            snippet: snippets[i] ?? "",
+        });
+    }
+    return out;
+}
+function parseMarginaliaJson(text) {
+    let data;
+    try {
+        data = JSON.parse(text);
+    }
+    catch {
+        return [];
+    }
+    if (!Array.isArray(data.results))
+        return [];
+    const out = [];
+    for (const r of data.results) {
+        if (!r.url || !r.title)
+            continue;
+        const snippet = (r.description ?? "").replace(/\s+/g, " ").trim().slice(0, 500);
+        out.push({ title: r.title, url: r.url, snippet });
+    }
+    return out;
+}
+// ── Internal: URL normalization + dedup ─────────────────────────
+/**
+ * Normalize a candidate URL: drop fragment, lowercase host, expand
+ * protocol-relative, strip common tracking params, reject non-http(s) and
+ * `.pdf` paths (which fetch-page hard-rejects downstream — dead slots).
+ */
+function normalizeUrl(raw) {
+    let s = raw.trim();
+    if (!s)
+        return null;
+    if (s.startsWith("//"))
+        s = "https:" + s;
+    let u;
+    try {
+        u = new URL(s);
+    }
+    catch {
+        return null;
+    }
+    if (u.protocol !== "http:" && u.protocol !== "https:")
+        return null;
+    const lowerPath = u.pathname.toLowerCase();
+    if (lowerPath.endsWith(".pdf") ||
+        lowerPath.endsWith(".pdf/") ||
+        lowerPath.includes(".pdf?") ||
+        lowerPath.includes(".pdf#")) {
+        return null;
+    }
+    for (const k of [...u.searchParams.keys()]) {
+        if (TRACKING_PARAMS.has(k.toLowerCase()))
+            u.searchParams.delete(k);
+    }
+    u.hash = "";
+    u.hostname = u.hostname.toLowerCase();
+    return u.toString();
+}
+function dedupResults(results) {
+    const seen = new Set();
+    const out = [];
+    for (const r of results) {
+        if (seen.has(r.url))
+            continue;
+        seen.add(r.url);
+        out.push(r);
+    }
+    return out;
+}
+// ── Factory ─────────────────────────────────────────────────────
+/**
+ * Create the keyless, in-process default {@link SearchProvider}.
+ *
+ * Two engines, primary with circuit-broken fallback:
+ *
+ * - **Primary**: DuckDuckGo HTML (`html.duckduckgo.com/html/`). Static,
+ *   no-JS endpoint. Paced behind a shared FIFO request limiter to avoid
+ *   triggering rate-limit responses on a residential IP. Wrapped in a
+ *   circuit breaker that opens on consecutive hard failures (403/429/
+ *   network/timeout) and recovers via a half-open probe after a cooldown.
+ *
+ * - **Fallback**: Marginalia public JSON API (`api2.marginalia-search.com`,
+ *   shared `public` API key via header). Independent niche index;
+ *   shared-key saturation surfaces as 503/429 and is treated as soft-empty.
+ *
+ * Returned results omit the `score` field by design — the upstream
+ * `WebSearchTool` exploit-mode ranking falls back cleanly to entailment-only
+ * when scores are absent, while a fabricated provider score would corrupt
+ * `min(providerScore, entailment)`.
+ *
+ * The provider is bound to the scope where this factory is yielded — the
+ * pacer's central tick loop is halted when that scope exits.
+ *
+ * @example
+ * ```ts
+ * yield* initAgents(ctx);
+ * const provider = yield* createKeylessSearchProvider();
+ * // Inject into an App factory (e.g. createWebApp) that constructs its
+ * // Source bound to the provider + reranker.
+ * ```
+ *
+ * @category Rig
+ */
+function createKeylessSearchProvider(opts = {}) {
+    return (0, effection_1.resource)(function* (provide) {
+        const paceBaseMs = opts.paceBaseMs ?? 3000;
+        const paceJitterMs = opts.paceJitterMs ?? 2000;
+        if (paceBaseMs <= 0) {
+            throw new Error("createKeylessSearchProvider: paceBaseMs must be > 0. Unpaced egress on a residential IP is unsafe — fail loudly rather than risk being blocked silently.");
+        }
+        if (paceJitterMs < 0) {
+            throw new Error("createKeylessSearchProvider: paceJitterMs must be >= 0.");
+        }
+        const breakerThreshold = opts.breakerThreshold ?? 2;
+        const breakerCooldownMs = opts.breakerCooldownMs ?? 15_000;
+        const requestTimeoutMs = opts.requestTimeoutMs ?? 8000;
+        const sleepOp = opts.sleepOp ?? effection_1.sleep;
+        const fetchImpl = opts.fetchImpl ?? fetch;
+        const userAgent = opts.userAgent ?? DEFAULT_USER_AGENT;
+        const scope = yield* (0, effection_1.useScope)();
+        const pacer = yield* useRequestPacer({
+            baseMs: paceBaseMs,
+            jitterMs: paceJitterMs,
+            sleepOp,
+        });
+        const breaker = createBreaker(breakerThreshold, breakerCooldownMs);
+        /** Park duration handed to the pool when DDG rate-limits and the
+         *  fallback is empty. Tracks DDG's observed quota-refill cadence (~86s
+         *  bought one success in trace-2026-06-11T00-39); must exceed
+         *  breakerCooldownMs (default 15s) so the retry lands on a half-open
+         *  probe, not an open breaker. */
+        const RETRY_AFTER_MS = 90_000;
+        function* doDdg(query, max) {
+            yield* pacer.acquire();
+            let res;
+            try {
+                res = yield* fetchWithTimeout(DDG_URL, {
+                    method: "POST",
+                    headers: {
+                        "User-Agent": userAgent,
+                        "Content-Type": "application/x-www-form-urlencoded",
+                    },
+                    body: new URLSearchParams({ q: query }).toString(),
+                }, requestTimeoutMs, fetchImpl, sleepOp);
+            }
+            catch {
+                return "hard-fail";
+            }
+            // 403/429 are rate-limit semantics, not generic failure. DDG's bot
+            // detection serves 202 + a challenge page (observed live 2026-06-11:
+            // status 202, 47 anomaly/challenge markers, zero result links) — it
+            // passes a naive 2xx check and parses to zero results, which the old
+            // soft-fail classification rendered indistinguishable from "no matches"
+            // and never tripped the breaker.
+            if (res.status === 403 || res.status === 429)
+                return "rate-limited";
+            if (res.status === 202)
+                return "rate-limited";
+            if (res.status < 200 || res.status >= 300)
+                return "hard-fail";
+            const parsed = parseDdgHtml(res.text);
+            if (parsed.length === 0) {
+                return /anomaly|challenge|captcha|detected unusual/i.test(res.text)
+                    ? "rate-limited"
+                    : "soft-fail";
+            }
+            return parsed.slice(0, max);
+        }
+        function* doMarginalia(query, max) {
+            const url = `${MARGINALIA_URL}?query=${encodeURIComponent(query)}&count=${Math.min(Math.max(max, 1), 100)}`;
+            let res;
+            try {
+                res = yield* fetchWithTimeout(url, { headers: { "API-Key": "public" } }, requestTimeoutMs, fetchImpl, sleepOp);
+            }
+            catch {
+                return [];
+            }
+            if (res.status === 503 || res.status === 429)
+                return []; // shared-key saturation = soft-empty
+            if (res.status < 200 || res.status >= 300)
+                return [];
+            return parseMarginaliaJson(res.text);
+        }
+        function postProcess(results, max) {
+            const cleaned = [];
+            for (const r of results) {
+                const url = normalizeUrl(r.url);
+                if (!url)
+                    continue;
+                cleaned.push({ title: r.title, url, snippet: r.snippet });
+            }
+            return dedupResults(cleaned).slice(0, max);
+        }
+        const provider = {
+            returnsFullContentMarkdown: false,
+            search(query, maxResults) {
+                const q = query.trim();
+                if (!q)
+                    return Promise.resolve([]);
+                return scope.run(function* () {
+                    let primary = "hard-fail";
+                    if (breaker.canProceed()) {
+                        primary = yield* doDdg(q, maxResults);
+                        if (primary === "hard-fail" || primary === "rate-limited") {
+                            breaker.onHardFailure();
+                        }
+                        else if (Array.isArray(primary)) {
+                            breaker.onSuccess();
+                        }
+                        // soft-fail: breaker state unchanged (neutral)
+                    }
+                    if (Array.isArray(primary))
+                        return postProcess(primary, maxResults);
+                    const fallback = yield* doMarginalia(q, maxResults);
+                    const processed = postProcess(fallback, maxResults);
+                    // Rate-limited primary + nothing from the fallback: throwing (vs
+                    // returning []) is the difference between the model thrashing on
+                    // "no results" and the pool parking the agent for one quiet retry
+                    // (trace-2026-06-11T00-39: nine zero-result retries in 80s).
+                    if (primary === "rate-limited" && processed.length === 0) {
+                        throw new lloyal_agents_1.ToolRetryError("Search provider rate-limited and fallback returned no results.", RETRY_AFTER_MS);
+                    }
+                    return processed;
+                });
+            },
+        };
+        yield* provide(provider);
+    });
+}
+//# sourceMappingURL=keyless-search.js.map

package/dist/tools/keyless-search.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"keyless-search.js","sourceRoot":"","sources":["../../src/tools/keyless-search.ts"],"names":[],"mappings":"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"}

package/dist/tools/plan.d.ts

@@ -1,6 +1,6 @@
 import type { Operation } from 'effection';
 import { Tool } from '@lloyal-labs/lloyal-agents';
-import type { JsonSchema } from '@lloyal-labs/lloyal-agents';
+import type { JsonSchema, App } from '@lloyal-labs/lloyal-agents';
 import { Session } from '@lloyal-labs/sdk';
 /**
  * Configuration for {@link PlanTool}.
@@ -15,10 +15,27 @@ export interface PlanToolOpts {
     };
     /** Active session whose trunk is used as the parent branch for generation. */
     session: Session;
-    /** Maximum number of tasks the planner may produce. */
-    maxQuestions: number;
+    /** Maximum number of research tasks the planner may produce. Caps the
+     *  `tasks` array via grammar `maxItems` and renders into the planner
+     *  prompt as `it.count` so the model sees the limit. Does NOT bound
+     *  `clarifyQuestions` (the planner prompt limits those by instruction only;
+     *  add a separate cap if grammar-enforced bound is needed). */
+    maxTasks: number;
     /** Sampling temperature for plan generation. @default 0.3 */
     temperature?: number;
+    /**
+     * Apps available to route research tasks to. When provided
+     * and non-empty, the plan grammar constrains each task's `app` field to
+     * an enum of these apps' `manifest.protocol.name` values — the names
+     * the planner sees in the spine catalog — so the planner must assign
+     * every task to a real protocol. The harness maps each emitted
+     * `task.app` (a protocol name) back to its `manifest.name` to set
+     * `SpawnSpec.assignedApp` when spawning research agents.
+     *
+     * Omit for single-app or app-agnostic pipelines: the grammar drops the
+     * `app` field entirely and {@link ResearchTask.app} stays undefined.
+     */
+    availableApps?: readonly App[];
 }
 /**
  * A structured research task produced by the planner.
@@ -31,6 +48,15 @@ export interface PlanToolOpts {
 export interface ResearchTask {
     /** What to find out — a specific, actionable research assignment. */
     description: string;
+    /**
+     * Contract name of the app this task is routed to (matches one of the
+     * planner's `availableApps`' `manifest.protocol.name`). Present only
+     * when the planner ran with {@link PlanToolOpts.availableApps}; the
+     * harness maps it to the App's `manifest.name` for
+     * `SpawnSpec.assignedApp`. Undefined for single-app / app-agnostic
+     * pipelines.
+     */
+    app?: string;
 }
 /**
  * Convert a ResearchTask to agent content string.
@@ -88,8 +114,9 @@ export declare class PlanTool extends Tool<{
     readonly parameters: JsonSchema;
     private _prompt;
     private _session;
-    private _maxQuestions;
+    private _maxTasks;
     private _temperature;
+    private _appProtocolNames;
     constructor(opts: PlanToolOpts);
     execute(args: {
         query: string;

package/dist/tools/plan.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"plan.d.ts","sourceRoot":"","sources":["../../src/tools/plan.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,WAAW,CAAC;AAC3C,OAAO,EAAE,IAAI,EAAyB,MAAM,4BAA4B,CAAC;AACzE,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,4BAA4B,CAAC;AAC7D,OAAO,EAAE,OAAO,EAAE,MAAM,kBAAkB,CAAC;AAE3C;;;;GAIG;AACH,MAAM,WAAW,YAAY;IAC3B,0GAA0G;IAC1G,MAAM,EAAE;QAAE,MAAM,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAE,CAAC;IACzC,8EAA8E;IAC9E,OAAO,EAAE,OAAO,CAAC;IACjB,uDAAuD;IACvD,YAAY,EAAE,MAAM,CAAC;IACrB,6DAA6D;IAC7D,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAED;;;;;;;GAOG;AACH,MAAM,WAAW,YAAY;IAC3B,qEAAqE;IACrE,WAAW,EAAE,MAAM,CAAC;CACrB;AAED;;;;GAIG;AACH,wBAAgB,aAAa,CAAC,IAAI,EAAE,YAAY,GAAG,MAAM,CAExD;AAED;;;;;;;;;;;GAWG;AACH,MAAM,MAAM,UAAU,GAAG,SAAS,GAAG,aAAa,GAAG,UAAU,CAAC;AAEhE;;;;GAIG;AACH,MAAM,WAAW,UAAU;IACzB,uEAAuE;IACvE,MAAM,EAAE,UAAU,CAAC;IACnB,8EAA8E;IAC9E,KAAK,EAAE,YAAY,EAAE,CAAC;IACtB,mGAAmG;IACnG,gBAAgB,EAAE,MAAM,EAAE,CAAC;IAC3B,kDAAkD;IAClD,UAAU,EAAE,MAAM,CAAC;IACnB,6DAA6D;IAC7D,MAAM,EAAE,MAAM,CAAC;CAChB;AAED;;;;;;;;;;GAUG;AACH,qBAAa,QAAS,SAAQ,IAAI,CAAC;IAAE,KAAK,EAAE,MAAM,CAAC;IAAC,OAAO,CAAC,EAAE,MAAM,CAAA;CAAE,CAAC;IACrE,QAAQ,CAAC,IAAI,UAAU;IACvB,QAAQ,CAAC,WAAW,0KAA0K;IAC9L,QAAQ,CAAC,UAAU,EAAE,UAAU,CAO7B;IAEF,OAAO,CAAC,OAAO,CAAmC;IAClD,OAAO,CAAC,QAAQ,CAAU;IAC1B,OAAO,CAAC,aAAa,CAAS;IAC9B,OAAO,CAAC,YAAY,CAAS;gBAEjB,IAAI,EAAE,YAAY;IAQ7B,OAAO,CAAC,IAAI,EAAE;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,OAAO,CAAC,EAAE,MAAM,CAAA;KAAE,GAAG,SAAS,CAAC,OAAO,CAAC;CA4ExE"}
+{"version":3,"file":"plan.d.ts","sourceRoot":"","sources":["../../src/tools/plan.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,WAAW,CAAC;AAC3C,OAAO,EAAE,IAAI,EAAyB,MAAM,4BAA4B,CAAC;AACzE,OAAO,KAAK,EAAE,UAAU,EAAE,GAAG,EAAE,MAAM,4BAA4B,CAAC;AAClE,OAAO,EAAE,OAAO,EAAE,MAAM,kBAAkB,CAAC;AAE3C;;;;GAIG;AACH,MAAM,WAAW,YAAY;IAC3B,0GAA0G;IAC1G,MAAM,EAAE;QAAE,MAAM,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAE,CAAC;IACzC,8EAA8E;IAC9E,OAAO,EAAE,OAAO,CAAC;IACjB;;;;mEAI+D;IAC/D,QAAQ,EAAE,MAAM,CAAC;IACjB,6DAA6D;IAC7D,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB;;;;;;;;;;;OAWG;IACH,aAAa,CAAC,EAAE,SAAS,GAAG,EAAE,CAAC;CAChC;AAED;;;;;;;GAOG;AACH,MAAM,WAAW,YAAY;IAC3B,qEAAqE;IACrE,WAAW,EAAE,MAAM,CAAC;IACpB;;;;;;;OAOG;IACH,GAAG,CAAC,EAAE,MAAM,CAAC;CACd;AAED;;;;GAIG;AACH,wBAAgB,aAAa,CAAC,IAAI,EAAE,YAAY,GAAG,MAAM,CAExD;AAuBD;;;;;;;;;;;GAWG;AACH,MAAM,MAAM,UAAU,GAAG,SAAS,GAAG,aAAa,GAAG,UAAU,CAAC;AAEhE;;;;GAIG;AACH,MAAM,WAAW,UAAU;IACzB,uEAAuE;IACvE,MAAM,EAAE,UAAU,CAAC;IACnB,8EAA8E;IAC9E,KAAK,EAAE,YAAY,EAAE,CAAC;IACtB,mGAAmG;IACnG,gBAAgB,EAAE,MAAM,EAAE,CAAC;IAC3B,kDAAkD;IAClD,UAAU,EAAE,MAAM,CAAC;IACnB,6DAA6D;IAC7D,MAAM,EAAE,MAAM,CAAC;CAChB;AAED;;;;;;;;;;GAUG;AACH,qBAAa,QAAS,SAAQ,IAAI,CAAC;IAAE,KAAK,EAAE,MAAM,CAAC;IAAC,OAAO,CAAC,EAAE,MAAM,CAAA;CAAE,CAAC;IACrE,QAAQ,CAAC,IAAI,UAAU;IACvB,QAAQ,CAAC,WAAW,0KAA0K;IAC9L,QAAQ,CAAC,UAAU,EAAE,UAAU,CAO7B;IAEF,OAAO,CAAC,OAAO,CAAmC;IAClD,OAAO,CAAC,QAAQ,CAAU;IAC1B,OAAO,CAAC,SAAS,CAAS;IAC1B,OAAO,CAAC,YAAY,CAAS;IAC7B,OAAO,CAAC,iBAAiB,CAAW;gBAExB,IAAI,EAAE,YAAY;IAS7B,OAAO,CAAC,IAAI,EAAE;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,OAAO,CAAC,EAAE,MAAM,CAAA;KAAE,GAAG,SAAS,CAAC,OAAO,CAAC;CAyFxE"}

package/dist/tools/plan.js

@@ -11,6 +11,27 @@ const lloyal_agents_1 = require("@lloyal-labs/lloyal-agents");
 function taskToContent(task) {
     return task.description;
 }
+/**
+ * Parse the planner's JSON, tolerant of a markdown code fence or surrounding
+ * prose. Grammar-constrained generation *should* emit bare JSON, but instruct
+ * models routinely wrap it in ```json … ``` — the few-shot examples in the plan
+ * prompt prime exactly that. A bare `JSON.parse` throws on the fence, which used
+ * to silently demote a real research plan to passthrough (no plan presented for
+ * approval), so extract the outermost `{…}` object before parsing.
+ */
+function parsePlanJson(raw) {
+    try {
+        return JSON.parse(raw);
+    }
+    catch {
+        const start = raw.indexOf('{');
+        const end = raw.lastIndexOf('}');
+        if (start === -1 || end <= start) {
+            throw new Error('planner output contained no JSON object');
+        }
+        return JSON.parse(raw.slice(start, end + 1));
+    }
+}
 /**
  * Grammar-constrained query planner.
  *
@@ -35,17 +56,31 @@ class PlanTool extends lloyal_agents_1.Tool {
     };
     _prompt;
     _session;
-    _maxQuestions;
+    _maxTasks;
     _temperature;
+    _appProtocolNames;
     constructor(opts) {
         super();
         this._prompt = opts.prompt;
         this._temperature = opts.temperature ?? 0.3;
         this._session = opts.session;
-        this._maxQuestions = opts.maxQuestions;
+        this._maxTasks = opts.maxTasks;
+        this._appProtocolNames = (opts.availableApps ?? []).map(a => a.manifest.protocol.name);
     }
     *execute(args) {
         const t = performance.now();
+        // When apps are available, force the planner to route every task to
+        // one of their protocol names via a grammar enum. With no
+        // apps the task carries only a description.
+        const hasApps = this._appProtocolNames.length > 0;
+        const taskProperties = {
+            description: { type: 'string' },
+        };
+        const taskRequired = ['description'];
+        if (hasApps) {
+            taskProperties.app = { type: 'string', enum: this._appProtocolNames };
+            taskRequired.push('app');
+        }
         const schema = {
             type: 'object',
             properties: {
@@ -54,12 +89,10 @@ class PlanTool extends lloyal_agents_1.Tool {
                     type: 'array',
                     items: {
                         type: 'object',
-                        properties: {
-                            description: { type: 'string' },
-                        },
-                        required: ['description'],
+                        properties: taskProperties,
+                        required: taskRequired,
                     },
-                    maxItems: this._maxQuestions,
+                    maxItems: this._maxTasks,
                 },
                 clarifyQuestions: {
                     type: 'array',
@@ -70,7 +103,7 @@ class PlanTool extends lloyal_agents_1.Tool {
         };
         const userContent = (0, lloyal_agents_1.renderTemplate)(this._prompt.user, {
             query: args.query,
-            count: this._maxQuestions,
+            count: this._maxTasks,
             context: args.context || null,
         });
         const planAgent = yield* (0, lloyal_agents_1.agent)({
@@ -83,14 +116,16 @@ class PlanTool extends lloyal_agents_1.Tool {
         const timeMs = performance.now() - t;
         const tokenCount = planAgent.tokenCount;
         try {
-            const parsed = JSON.parse(planAgent.rawOutput);
+            const parsed = parsePlanJson(planAgent.rawOutput);
             const intent = parsed.intent === 'clarify' || parsed.intent === 'passthrough' || parsed.intent === 'research'
                 ? parsed.intent
                 : 'research';
             const tasks = (parsed.tasks ?? [])
-                .slice(0, this._maxQuestions)
+                .slice(0, this._maxTasks)
                 .filter(t => typeof t.description === 'string')
-                .map(t => ({ description: t.description }));
+                .map(t => (typeof t.app === 'string'
+                ? { description: t.description, app: t.app }
+                : { description: t.description }));
             const clarifyQuestions = (parsed.clarifyQuestions ?? []).filter(q => typeof q === 'string');
             return { intent, tasks, clarifyQuestions, tokenCount, timeMs };
         }

package/dist/tools/plan.js.map

@@ -1 +1 @@
-{"version":3,"file":"plan.js","sourceRoot":"","sources":["../../src/tools/plan.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"plan.js","sourceRoot":"","sources":["../../src/tools/plan.ts"],"names":[],"mappings":"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"}