clinkx 0.3.0 → 1.0.0

package/dist/context-builder/token-estimate.js

@@ -1,15 +1,88 @@
 export const CONTEXT_BUILDER_TOKEN_COUNTING_METHOD = "utf8_bytes_div_3_ceiling";
+// Legacy, model-agnostic divisor. This is the conservative default that the
+// rest of context_builder budgets against and MUST remain unchanged.
+const DEFAULT_BYTES_PER_TOKEN = 3;
+// ADDITIVE / FUTURE-FACING (not yet wired into a budget path). The
+// provider/model-aware divisor table below and its consumers
+// (`TokenEstimateOptions`, `resolveProviderFamily`, `resolveBytesPerToken`,
+// the optional `options` arg, and `estimateContextBuilderTokensDetailed`) are
+// intentionally NOT yet consumed by the context_builder budget pipeline. The
+// active path remains the default ceil(utf8_bytes / 3) math: with no/unknown
+// options every estimate is byte-identical to the legacy behavior. These hooks
+// exist so a later model-aware budget can opt in without a schema change; do
+// not treat them as dead code.
+//
+// Tiny, explicit provider-family -> bytes-per-token table. These are coarse
+// heuristics, NOT real tokenizer output (we deliberately add no BPE library).
+// Modern BPE tokenizers average roughly ~4 UTF-8 bytes/token on English and
+// code; we sit a little below that empirical figure to keep budget headroom,
+// so estimates stay conservative (lean toward over-counting tokens). Anthropic
+// is slightly less byte-efficient than OpenAI/Google in practice, hence 3.5.
+// Anything not listed falls back to DEFAULT_BYTES_PER_TOKEN (today's behavior).
+const BYTES_PER_TOKEN_BY_FAMILY = {
+    anthropic: 3.5,
+    openai: 3.8,
+    google: 3.8,
+};
 export function utf8ByteLength(input) {
     return Buffer.byteLength(input, "utf8");
 }
-export function estimateContextBuilderTokensFromUtf8Bytes(utf8Bytes) {
+// Maps an optional provider/model hint to a known family, or null when the
+// hint is absent/unrecognized (which drives the default-divisor fallback).
+function resolveProviderFamily(options) {
+    const provider = options?.provider?.toLowerCase().trim();
+    if (provider) {
+        if (provider === "anthropic" || provider === "claude")
+            return "anthropic";
+        if (provider === "openai")
+            return "openai";
+        if (provider === "google" || provider === "gemini")
+            return "google";
+    }
+    const model = options?.model?.toLowerCase().trim();
+    if (model) {
+        if (model.includes("claude"))
+            return "anthropic";
+        if (model.includes("gpt") || model.includes("codex") || /\bo[1-4]\b/.test(model)) {
+            return "openai";
+        }
+        if (model.includes("gemini"))
+            return "google";
+    }
+    return null;
+}
+function resolveBytesPerToken(options) {
+    const family = resolveProviderFamily(options);
+    return family ? BYTES_PER_TOKEN_BY_FAMILY[family] : DEFAULT_BYTES_PER_TOKEN;
+}
+export function estimateContextBuilderTokensFromUtf8Bytes(utf8Bytes, options) {
     if (!Number.isSafeInteger(utf8Bytes) || utf8Bytes < 0) {
         throw new RangeError("utf8Bytes must be a non-negative safe integer");
     }
-    return Math.ceil(utf8Bytes / 3);
+    // No options -> exactly ceil(utf8Bytes / 3), byte-identical to before.
+    // Unknown model/provider -> resolveBytesPerToken returns the default too.
+    const bytesPerToken = options
+        ? resolveBytesPerToken(options)
+        : DEFAULT_BYTES_PER_TOKEN;
+    return Math.ceil(utf8Bytes / bytesPerToken);
+}
+export function estimateContextBuilderTokens(input, options) {
+    return estimateContextBuilderTokensFromUtf8Bytes(utf8ByteLength(input), options);
 }
-export function estimateContextBuilderTokens(input) {
-    return estimateContextBuilderTokensFromUtf8Bytes(utf8ByteLength(input));
+// Same math as estimateContextBuilderTokens, but also reports which divisor /
+// method was used. The default (no/unknown options) path returns the frozen
+// manifest method string so callers can record provenance unambiguously.
+export function estimateContextBuilderTokensDetailed(input, options) {
+    const bytes = utf8ByteLength(input);
+    const family = options ? resolveProviderFamily(options) : null;
+    const bytesPerToken = family
+        ? BYTES_PER_TOKEN_BY_FAMILY[family]
+        : DEFAULT_BYTES_PER_TOKEN;
+    const tokens = estimateContextBuilderTokensFromUtf8Bytes(bytes, options);
+    const method = family
+        ? `utf8_bytes_div_${bytesPerToken}_ceiling:${family}`
+        : CONTEXT_BUILDER_TOKEN_COUNTING_METHOD;
+    return { tokens, bytes, bytesPerToken, method };
 }
 export function contextBuilderTokenCountingMethod() {
     return { method: CONTEXT_BUILDER_TOKEN_COUNTING_METHOD };

package/dist/context-builder/token-estimate.js.map

@@ -1 +1 @@
-{"version":3,"file":"token-estimate.js","sourceRoot":"","sources":["../../src/context-builder/token-estimate.ts"],"names":[],"mappings":"AAAA,MAAM,CAAC,MAAM,qCAAqC,GAChD,0BAAmC,CAAC;AAMtC,MAAM,UAAU,cAAc,CAAC,KAAa;IAC1C,OAAO,MAAM,CAAC,UAAU,CAAC,KAAK,EAAE,MAAM,CAAC,CAAC;AAC1C,CAAC;AAED,MAAM,UAAU,yCAAyC,CACvD,SAAiB;IAEjB,IAAI,CAAC,MAAM,CAAC,aAAa,CAAC,SAAS,CAAC,IAAI,SAAS,GAAG,CAAC,EAAE,CAAC;QACtD,MAAM,IAAI,UAAU,CAAC,+CAA+C,CAAC,CAAC;IACxE,CAAC;IAED,OAAO,IAAI,CAAC,IAAI,CAAC,SAAS,GAAG,CAAC,CAAC,CAAC;AAClC,CAAC;AAED,MAAM,UAAU,4BAA4B,CAAC,KAAa;IACxD,OAAO,yCAAyC,CAAC,cAAc,CAAC,KAAK,CAAC,CAAC,CAAC;AAC1E,CAAC;AAED,MAAM,UAAU,iCAAiC;IAC/C,OAAO,EAAE,MAAM,EAAE,qCAAqC,EAAE,CAAC;AAC3D,CAAC"}
+{"version":3,"file":"token-estimate.js","sourceRoot":"","sources":["../../src/context-builder/token-estimate.ts"],"names":[],"mappings":"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"}

package/dist/context-builder/versions.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Explicit cache-identity versions for the workflow context cache (`wfctx-*`).
+ *
+ * These are folded into the workflow context cache key (via the runner options
+ * in `workflow-runner.ts` -> `computeCacheKey` in
+ * `clinkx-workflows/src/context-cache-key.ts`) so that behavior changes in the
+ * root package's context_builder invalidate previously cached bundles instead
+ * of stale-serving output produced by the old behavior.
+ *
+ * Version "1" is the implicit pre-versioning behavior (before the key carried
+ * these components). Callers that supply no version at all fold as the
+ * distinct sentinel `"unversioned"` (see `UNVERSIONED_CACHE_COMPONENT` in
+ * clinkx-workflows), which never collides with a real version.
+ */
+/**
+ * Bump whenever the discovery algorithm changes WHICH content a bundle can
+ * select: search scheduling/ordering, candidate ranking, slicing, or cap/
+ * budget pruning semantics (`src/context-builder/discovery.ts` and the
+ * selection pipeline it feeds). "2" covers the 2026-08 search-scheduler
+ * fairness fixes.
+ */
+export declare const CONTEXT_DISCOVERY_ALGORITHM_VERSION = "2";
+/**
+ * Bump whenever the curator/finalizer delegate prompt content changes in a
+ * way that can alter delegate selection decisions
+ * (`src/context-builder/delegate-packet.ts` prompt assembly and the delegate
+ * role prompts). "2" covers the 2026-08 delegate-prompt revisions.
+ */
+export declare const CONTEXT_DELEGATE_PROMPT_VERSION = "2";

package/dist/context-builder/versions.js

@@ -0,0 +1,30 @@
+/**
+ * Explicit cache-identity versions for the workflow context cache (`wfctx-*`).
+ *
+ * These are folded into the workflow context cache key (via the runner options
+ * in `workflow-runner.ts` -> `computeCacheKey` in
+ * `clinkx-workflows/src/context-cache-key.ts`) so that behavior changes in the
+ * root package's context_builder invalidate previously cached bundles instead
+ * of stale-serving output produced by the old behavior.
+ *
+ * Version "1" is the implicit pre-versioning behavior (before the key carried
+ * these components). Callers that supply no version at all fold as the
+ * distinct sentinel `"unversioned"` (see `UNVERSIONED_CACHE_COMPONENT` in
+ * clinkx-workflows), which never collides with a real version.
+ */
+/**
+ * Bump whenever the discovery algorithm changes WHICH content a bundle can
+ * select: search scheduling/ordering, candidate ranking, slicing, or cap/
+ * budget pruning semantics (`src/context-builder/discovery.ts` and the
+ * selection pipeline it feeds). "2" covers the 2026-08 search-scheduler
+ * fairness fixes.
+ */
+export const CONTEXT_DISCOVERY_ALGORITHM_VERSION = "2";
+/**
+ * Bump whenever the curator/finalizer delegate prompt content changes in a
+ * way that can alter delegate selection decisions
+ * (`src/context-builder/delegate-packet.ts` prompt assembly and the delegate
+ * role prompts). "2" covers the 2026-08 delegate-prompt revisions.
+ */
+export const CONTEXT_DELEGATE_PROMPT_VERSION = "2";
+//# sourceMappingURL=versions.js.map

package/dist/context-builder/versions.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"versions.js","sourceRoot":"","sources":["../../src/context-builder/versions.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,mCAAmC,GAAG,GAAG,CAAC;AAEvD;;;;;GAKG;AACH,MAAM,CAAC,MAAM,+BAA+B,GAAG,GAAG,CAAC"}

package/dist/context-builder/workflow-runner.d.ts

@@ -0,0 +1,69 @@
+import type { ContextBuilderRunner, PreflightContextInput } from "../../clinkx-workflows/dist/context-preflight.js";
+import type { AdapterRegistry } from "../registry.js";
+import { ContextBuilderSemaphore } from "./config.js";
+import { type ContextBuilderHandlerOptions } from "./handler.js";
+import { type ContextBuilderPublicBudgetInput, type ContextBuilderIntentProfile } from "./schema.js";
+import { type ContextBuilderArtifactMap, type ContextBuilderReceipt, type ContextBuilderReceiptTextResponse } from "./receipt.js";
+import { type ContextBuilderLifecycleInjection } from "./lifecycle-observer.js";
+type HandleContextBuilder = (args: unknown, options?: ContextBuilderHandlerOptions) => Promise<ContextBuilderReceiptTextResponse>;
+export type WorkflowContextBuilderRunnerOptions = {
+    handleContextBuilder?: HandleContextBuilder;
+    runsDir?: string;
+    semaphore?: ContextBuilderSemaphore;
+    runIdFactory?: () => string;
+    resolveWorkspaceRoot?: () => string;
+    workspaceSignature?: (roots: readonly string[]) => Promise<string>;
+    getSignatureCoveredPaths?: (roots: readonly string[]) => Promise<Set<string>>;
+    rendererVersion?: string | number;
+    cbSchemaVersion?: string | number;
+    discoveryAlgorithmVersion?: string;
+    delegatePromptVersion?: string;
+    registry?: AdapterRegistry;
+    lifecycleFactory?: (input: PreflightContextInput) => ContextBuilderLifecycleInjection | undefined;
+    lifecycleNow?: () => Date;
+};
+type WorkflowContextBuilderDelegateInput = {
+    readonly enabled?: false;
+} | {
+    readonly enabled: true;
+    readonly curator: {
+        readonly cli_name: string;
+        readonly role: string;
+    };
+    readonly finalizer: {
+        readonly cli_name: string;
+        readonly role: string;
+        readonly enabled?: boolean;
+        readonly min_score?: number;
+    };
+    readonly timeout_seconds?: number;
+    readonly max_response_chars?: number;
+    readonly failure_policy?: "fallback" | "fail";
+};
+type WorkflowContextBuilderInput = {
+    task: string;
+    roots: string[];
+    focus_paths: string[];
+    include_globs: string[];
+    exclude_globs: string[];
+    search_terms: string[];
+    allow_secrets: boolean;
+    budget: ContextBuilderPublicBudgetInput;
+    delegate: WorkflowContextBuilderDelegateInput;
+    run_id?: string;
+    profile?: ContextBuilderIntentProfile;
+};
+export declare function createWorkflowContextBuilderRunner(options?: WorkflowContextBuilderRunnerOptions): ContextBuilderRunner;
+export declare function copyBundleIntoRun(receipt: Pick<ContextBuilderReceipt, "artifacts">, runDir: string, options?: {
+    includeSelectedContext?: boolean;
+    beforeManifestCommit?: () => void | Promise<void>;
+}): Promise<readonly string[]>;
+export declare function copyBundleArtifactsIntoRun(artifacts: ContextBuilderArtifactMap, runDir: string, options?: {
+    includeSelectedContext?: boolean;
+    beforeManifestCommit?: () => void | Promise<void>;
+}): Promise<readonly string[]>;
+export declare function mapPreflightContextInput(input: PreflightContextInput, options: {
+    run_id?: string;
+    resolveWorkspaceRoot?: () => string;
+}): Promise<WorkflowContextBuilderInput>;
+export {};