@owlmeans/llm 0.1.14

package/build/execution/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/execution/index.ts"],"names":[],"mappings":"AACA,mBAAmB,YAAY,CAAA;AAC/B,cAAc,YAAY,CAAA;AAC1B,cAAc,cAAc,CAAA"}

package/build/execution/index.js

@@ -0,0 +1,3 @@
+export * from './utils.js';
+export * from './service.js';
+//# sourceMappingURL=index.js.map

package/build/execution/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/execution/index.ts"],"names":[],"mappings":"AAEA,cAAc,YAAY,CAAA;AAC1B,cAAc,cAAc,CAAA"}

package/build/execution/service.d.ts

@@ -0,0 +1,21 @@
+import type { BasicConfig, BasicContext } from '@owlmeans/context';
+import type { ExecutionService, ExecutionServiceOptions, ExecutionShape, WithExecutionService } from './types.js';
+/**
+ * Build the execution service implementation WITHOUT registering it as a context
+ * service, so a consumer can publish extra methods alongside it (observability
+ * factories, domain-specific refinement). Spread it into your own `createService`:
+ *
+ * ```ts
+ * const api = executionServiceApi<MyShape>({ collaboratorKeys: ['files'] }, () => service)
+ * const service = createService<MyExecutionService>(alias, {
+ *   ...api,
+ *   // delegate to `api`, never to `service`, or you recurse
+ *   forTask: (parent, input) => api.forTask(parent, { ...input, effort: effortOf(input.mode) }),
+ *   spectator: (exec, kind) => makeSpectator(exec, kind),
+ * } as MyExecutionService)
+ * ```
+ */
+export declare const executionServiceApi: <S extends ExecutionShape = ExecutionShape>(options: ExecutionServiceOptions, self: () => ExecutionService<S>) => ExecutionService<S>;
+export declare const makeExecutionService: <S extends ExecutionShape = ExecutionShape>(alias?: string, options?: ExecutionServiceOptions) => ExecutionService<S>;
+export declare const appendExecutionService: <C extends BasicConfig, T extends BasicContext<C>, S extends ExecutionShape = ExecutionShape>(ctx: T, alias?: string, options?: ExecutionServiceOptions) => T & WithExecutionService<S>;
+//# sourceMappingURL=service.d.ts.map

package/build/execution/service.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"service.d.ts","sourceRoot":"","sources":["../../src/execution/service.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,WAAW,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAA;AAKlE,OAAO,KAAK,EACkB,gBAAgB,EAAE,uBAAuB,EAAE,cAAc,EACrD,oBAAoB,EACrD,MAAM,YAAY,CAAA;AAKnB;;;;;;;;;;;;;;GAcG;AACH,eAAO,MAAM,mBAAmB,GAAI,CAAC,SAAS,cAAc,GAAG,cAAc,EAC3E,SAAS,uBAAuB,EAChC,MAAM,MAAM,gBAAgB,CAAC,CAAC,CAAC,KAC9B,gBAAgB,CAAC,CAAC,CA6HpB,CAAA;AAED,eAAO,MAAM,oBAAoB,GAAI,CAAC,SAAS,cAAc,GAAG,cAAc,EAC5E,QAAO,MAA0B,EACjC,UAAS,uBAA4B,KACpC,gBAAgB,CAAC,CAAC,CAMpB,CAAA;AAED,eAAO,MAAM,sBAAsB,GACjC,CAAC,SAAS,WAAW,EAAE,CAAC,SAAS,YAAY,CAAC,CAAC,CAAC,EAAE,CAAC,SAAS,cAAc,GAAG,cAAc,EAE3F,KAAK,CAAC,EACN,QAAO,MAA0B,EACjC,UAAS,uBAA4B,KACpC,CAAC,GAAG,oBAAoB,CAAC,CAAC,CAQ5B,CAAA"}

package/build/execution/service.js

@@ -0,0 +1,129 @@
+import { createService } from '@owlmeans/context';
+import { ExecutionLevel } from '@owlmeans/llm-common';
+import { COLLABORATOR_KEYS, EXECUTION_SERVICE } from '../consts.js';
+import { composeExecState, composeTaskState, effortPatch, freeze, mergeOverride, mergePolicy, resolveRole, } from './utils.js';
+/**
+ * Build the execution service implementation WITHOUT registering it as a context
+ * service, so a consumer can publish extra methods alongside it (observability
+ * factories, domain-specific refinement). Spread it into your own `createService`:
+ *
+ * ```ts
+ * const api = executionServiceApi<MyShape>({ collaboratorKeys: ['files'] }, () => service)
+ * const service = createService<MyExecutionService>(alias, {
+ *   ...api,
+ *   // delegate to `api`, never to `service`, or you recurse
+ *   forTask: (parent, input) => api.forTask(parent, { ...input, effort: effortOf(input.mode) }),
+ *   spectator: (exec, kind) => makeSpectator(exec, kind),
+ * } as MyExecutionService)
+ * ```
+ */
+export const executionServiceApi = (options, self) => {
+    const plugins = [];
+    const collaboratorKeys = [...COLLABORATOR_KEYS, ...(options.collaboratorKeys ?? [])];
+    /** Recompose the JSON-safe state of a task execution after any refinement. */
+    const recompose = (exec) => {
+        if (exec.level === ExecutionLevel.Task) {
+            const task = exec;
+            task.state = composeTaskState(task, collaboratorKeys);
+        }
+        return exec;
+    };
+    const api = {
+        root: input => freeze({
+            ...input,
+            level: ExecutionLevel.Project,
+            purpose: { ...input.purpose },
+            policy: { ...input.policy },
+        }),
+        forTask: (parent, input) => {
+            const { effort, phase, data, ...extras } = input;
+            const policy = effort != null
+                ? mergePolicy(parent.policy, { effort })
+                : { ...parent.policy };
+            // Spreading the parent carries every collaborator and domain field forward; the
+            // task's own state is composed afterwards, from the seeded resumable fields.
+            const taskExec = {
+                ...parent, ...extras, level: ExecutionLevel.Task, purpose: { ...parent.purpose }, policy,
+            };
+            taskExec.state = composeTaskState({
+                ...taskExec,
+                state: {
+                    level: ExecutionLevel.Task,
+                    purpose: taskExec.purpose,
+                    policy: taskExec.policy,
+                    phase,
+                    data,
+                },
+            }, collaboratorKeys);
+            return freeze(taskExec);
+        },
+        forHelper: (parent, input) => {
+            const { role, effort, dedication, ...extras } = input;
+            const localPolicy = effort != null ? mergePolicy(parent.policy, { effort }) : parent.policy;
+            const scoped = { ...parent, policy: localPolicy };
+            const helperExec = {
+                ...parent,
+                ...extras,
+                level: ExecutionLevel.Helper,
+                purpose: dedication != null
+                    ? { ...parent.purpose, dedication }
+                    : { ...parent.purpose },
+                policy: localPolicy,
+                role: resolveRole(localPolicy, role),
+                model: self().model(scoped, role),
+                temperatureFactory: self().temperatureFactory(scoped, role),
+            };
+            // A helper is not resumable — drop a parent task's composed state.
+            delete helperExec.state;
+            return freeze(helperExec);
+        },
+        derive: (exec, patch) => freeze(recompose({ ...exec, ...patch })),
+        withPurpose: (exec, patch) => freeze(recompose({ ...exec, purpose: { ...exec.purpose, ...patch } })),
+        escalate: (exec, patch) => freeze(recompose({ ...exec, policy: mergePolicy(exec.policy, patch) })),
+        model: (exec, role, override) => {
+            const effectiveRole = resolveRole(exec.policy, role ?? exec.role);
+            const policyOverride = exec.policy.modelOverrides?.[effectiveRole];
+            const merged = mergeOverride(effortPatch(exec.policy.effort), policyOverride, override);
+            // Strip undefined values so the factory does not see spurious keys.
+            const clean = Object.fromEntries(Object.entries(merged).filter(([, value]) => value !== undefined));
+            return exec.models().getModel(effectiveRole, clean);
+        },
+        temperatureFactory: (exec, role) => temperature => self().model(exec, role, {
+            ...(temperature != null ? { temperature } : {}),
+            ...(temperature != null && temperature > 0.2 ? { topP: 0.8 } : {}),
+        }),
+        use: plugin => {
+            plugins.push(plugin);
+        },
+        checkpoint: async (exec, key) => {
+            if (plugins.length === 0) {
+                return;
+            }
+            const state = self().snapshot(exec);
+            await Promise.all(plugins.map(plugin => plugin.onCheckpoint?.(state, exec, key)));
+        },
+        snapshot: exec => {
+            if (exec.level === ExecutionLevel.Task) {
+                return freeze({ ...exec.state });
+            }
+            return freeze(composeExecState(exec, collaboratorKeys));
+        },
+        restore: (state, collaborators = {}) => freeze({
+            ...state,
+            ...collaborators,
+            ...(state.level === ExecutionLevel.Task ? { state } : {}),
+        }),
+    };
+    return api;
+};
+export const makeExecutionService = (alias = EXECUTION_SERVICE, options = {}) => {
+    const service = createService(alias, executionServiceApi(options, () => service));
+    return service;
+};
+export const appendExecutionService = (ctx, alias = EXECUTION_SERVICE, options = {}) => {
+    const context = ctx;
+    context.registerService(makeExecutionService(alias, options));
+    context.executions = () => context.service(alias);
+    return context;
+};
+//# sourceMappingURL=service.js.map

package/build/execution/service.js.map

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

package/build/execution/types.d.ts

@@ -0,0 +1,119 @@
+import type { BaseChatModel } from '@langchain/core/language_models/chat_models';
+import type { InitializedService } from '@owlmeans/context';
+import type { ExecutionEffort, ExecutionLevel, ExecutionState, LlmPurpose, ModelConfigOverride, ModelPolicy, ModelRole, TaskExecutionState } from '@owlmeans/llm-common';
+import type { LlmService, TemperatureFactory } from '../types.js';
+/**
+ * Runtime execution = serializable {@link ExecutionState} + attached collaborators.
+ * A frozen data object with NO behavior of its own — all logic (construct, refine,
+ * resolve a model, snapshot, restore) lives on {@link ExecutionService}. Passing it to
+ * the next performer creates a NEW object; an execution is immutable between layers.
+ *
+ * Extend this interface (and {@link ExecutionState}) to carry domain context; every
+ * field that is not declared a collaborator travels into the snapshot automatically.
+ */
+export interface Execution extends ExecutionState {
+    /** Resolver for the model factory — a function so the service can be swapped/cloned. */
+    models: () => LlmService;
+    outputErrors?: boolean;
+    captureNull?: boolean;
+}
+export interface ProjectExecution extends Execution {
+    level: ExecutionLevel.Project;
+}
+export interface TaskExecution extends Execution {
+    level: ExecutionLevel.Task;
+    /** The composed, JSON-safe state — recomposed on every refinement. */
+    state: TaskExecutionState;
+}
+export interface HelperExecution extends Execution {
+    level: ExecutionLevel.Helper;
+    role: ModelRole;
+    /** A model already resolved against the policy (effort + overrides). */
+    model: BaseChatModel;
+    temperatureFactory: TemperatureFactory;
+}
+export interface ProjectExecutionInput {
+    models: () => LlmService;
+    policy: ModelPolicy;
+    purpose: LlmPurpose;
+    outputErrors?: boolean;
+    captureNull?: boolean;
+}
+export interface TaskExecutionInput {
+    /** Raise (or lower) the effort tier for this task and everything derived from it. */
+    effort?: ExecutionEffort;
+    /** Optional seeds for the resumable task state. */
+    phase?: string;
+    data?: Record<string, unknown>;
+}
+export interface HelperExecutionInput {
+    role: ModelRole;
+    /** Local effort bump without escalating the whole branch. */
+    effort?: ExecutionEffort;
+    /** Refines `purpose.dedication`. */
+    dedication?: string;
+}
+/** Collaborators re-attached to a state that was restored from storage. */
+export interface RestoreCollaborators {
+    models?: () => LlmService;
+}
+/**
+ * Resilience extension seam. A plugin observes flow boundaries (via
+ * {@link ExecutionService.checkpoint}) and can persist/enqueue the JSON-safe
+ * {@link ExecutionState}, or supply one back on resume. This package ships NO concrete
+ * implementation — with no plugin registered, `checkpoint` is a no-op.
+ */
+export interface ExecutionPlugin {
+    /** Fired at a flow boundary with a JSON-safe snapshot; persist/enqueue as desired. */
+    onCheckpoint?: (state: ExecutionState, exec: Execution, key?: string) => Promise<void>;
+    /** Resume hook: return a previously persisted state for `key`, or `null`. */
+    onRestore?: (key: string) => Promise<ExecutionState | null>;
+}
+/**
+ * The set of domain types an {@link ExecutionService} works with. A consumer declares
+ * its own shape (extending each member) and instantiates the service generic with it,
+ * which keeps the method signatures precise without redeclaring — and therefore without
+ * the contravariance problem that narrowing an inherited method signature would cause.
+ */
+export interface ExecutionShape {
+    exec: Execution;
+    project: ProjectExecution;
+    task: TaskExecution;
+    helper: HelperExecution;
+    projectInput: ProjectExecutionInput;
+    taskInput: TaskExecutionInput;
+    helperInput: HelperExecutionInput;
+    purpose: LlmPurpose;
+    collaborators: RestoreCollaborators;
+}
+/**
+ * Standard OwlMeans context service. Every construction/refinement method returns a new,
+ * `Object.freeze`d object — executions are immutable between performers.
+ */
+export interface ExecutionService<S extends ExecutionShape = ExecutionShape> extends InitializedService {
+    root: (input: S['projectInput']) => S['project'];
+    forTask: (parent: S['project'], input: S['taskInput']) => S['task'];
+    forHelper: (parent: S['exec'], input: S['helperInput']) => S['helper'];
+    derive: <E extends S['exec']>(exec: E, patch: Partial<E>) => E;
+    withPurpose: <E extends S['exec']>(exec: E, patch: Partial<S['purpose']>) => E;
+    escalate: <E extends S['exec']>(exec: E, patch: Partial<ModelPolicy>) => E;
+    model: (exec: S['exec'], role?: ModelRole, override?: ModelConfigOverride) => BaseChatModel;
+    temperatureFactory: (exec: S['exec'], role?: ModelRole) => TemperatureFactory;
+    /** Register a resilience plugin (checkpoint/resume). No-op seam until one is provided. */
+    use: (plugin: ExecutionPlugin) => void;
+    /** Snapshot `exec` and dispatch it to every registered plugin. No-op if none. */
+    checkpoint: (exec: S['exec'], key?: string) => Promise<void>;
+    snapshot: (exec: S['exec']) => ExecutionState;
+    restore: (state: ExecutionState, collaborators?: S['collaborators']) => S['exec'];
+}
+export interface ExecutionServiceOptions {
+    /**
+     * Execution fields that are collaborators, not state — excluded from every snapshot.
+     * Merged with the package's own {@link COLLABORATOR_KEYS}.
+     */
+    collaboratorKeys?: string[];
+}
+export interface WithExecutionService<S extends ExecutionShape = ExecutionShape> {
+    executions: () => ExecutionService<S>;
+}
+//# sourceMappingURL=types.d.ts.map

package/build/execution/types.d.ts.map

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

package/build/execution/types.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=types.js.map

package/build/execution/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/execution/types.ts"],"names":[],"mappings":""}

package/build/execution/utils.d.ts

@@ -0,0 +1,28 @@
+import type { ExecutionEffort, ExecutionState, ModelConfigOverride, ModelConfigPatch, ModelPolicy, ModelRole, TaskExecutionState } from '@owlmeans/llm-common';
+import type { Execution, TaskExecution } from './types.js';
+export declare const freeze: <T extends object>(o: T) => Readonly<T>;
+/** Overlay a partial policy onto a base one. Override maps are merged, not replaced. */
+export declare const mergePolicy: (base: ModelPolicy, patch: Partial<ModelPolicy>) => ModelPolicy;
+/** Apply the policy's role→role remap. */
+export declare const resolveRole: (policy: ModelPolicy, role: ModelRole) => ModelRole;
+export declare const effortPatch: (effort: ExecutionEffort) => ModelConfigPatch;
+/** Normalize a {@link ModelConfigOverride} (alias or patch) to a patch. */
+export declare const resolveModelConfig: (override: ModelConfigOverride) => ModelConfigPatch;
+/**
+ * Merge effort < policy.modelOverride < call-site override into a single patch.
+ * Any field present in a higher-precedence source wins.
+ */
+export declare const mergeOverride: (effortBase: ModelConfigPatch, policyOverride: ModelConfigOverride | undefined, callOverride: ModelConfigOverride | undefined) => ModelConfigPatch;
+/**
+ * Project an execution down to its JSON-safe state: every own field except the declared
+ * collaborators. Domain fields added by a consumer are carried through automatically,
+ * which is what lets an extended execution be persisted without extra wiring.
+ */
+export declare const composeExecState: (exec: Execution, collaboratorKeys: string[]) => ExecutionState;
+/**
+ * Same as {@link composeExecState}, plus the resumable task fields carried over from the
+ * execution's PRIOR state (they live only there — `phase`/`cursor`/`completed`/`data` are
+ * advanced by the workflow, not by refinement).
+ */
+export declare const composeTaskState: (exec: TaskExecution, collaboratorKeys: string[]) => TaskExecutionState;
+//# sourceMappingURL=utils.d.ts.map

package/build/execution/utils.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"utils.d.ts","sourceRoot":"","sources":["../../src/execution/utils.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EACV,eAAe,EAAE,cAAc,EAAE,mBAAmB,EAAE,gBAAgB,EACtE,WAAW,EAAE,SAAS,EAAE,kBAAkB,EAC3C,MAAM,sBAAsB,CAAA;AAE7B,OAAO,KAAK,EAAE,SAAS,EAAE,aAAa,EAAE,MAAM,YAAY,CAAA;AAE1D,eAAO,MAAM,MAAM,GAAI,CAAC,SAAS,MAAM,EAAE,GAAG,CAAC,KAAG,QAAQ,CAAC,CAAC,CAAqB,CAAA;AAE/E,wFAAwF;AACxF,eAAO,MAAM,WAAW,GAAI,MAAM,WAAW,EAAE,OAAO,OAAO,CAAC,WAAW,CAAC,KAAG,WAQ3E,CAAA;AAEF,0CAA0C;AAC1C,eAAO,MAAM,WAAW,GAAI,QAAQ,WAAW,EAAE,MAAM,SAAS,KAAG,SACF,CAAA;AAEjE,eAAO,MAAM,WAAW,GAAI,QAAQ,eAAe,KAAG,gBAAwC,CAAA;AAE9F,2EAA2E;AAC3E,eAAO,MAAM,kBAAkB,GAAI,UAAU,mBAAmB,KAAG,gBACH,CAAA;AAEhE;;;GAGG;AACH,eAAO,MAAM,aAAa,GACxB,YAAY,gBAAgB,EAC5B,gBAAgB,mBAAmB,GAAG,SAAS,EAC/C,cAAc,mBAAmB,GAAG,SAAS,KAC5C,gBAIF,CAAA;AAID;;;;GAIG;AACH,eAAO,MAAM,gBAAgB,GAAI,MAAM,SAAS,EAAE,kBAAkB,MAAM,EAAE,KAAG,cAQ9E,CAAA;AAED;;;;GAIG;AACH,eAAO,MAAM,gBAAgB,GAAI,MAAM,aAAa,EAAE,kBAAkB,MAAM,EAAE,KAAG,kBAWlF,CAAA"}

package/build/execution/utils.js

@@ -0,0 +1,60 @@
+import { ExecutionLevel } from '@owlmeans/llm-common';
+import { EFFORT_TABLE } from '../consts.js';
+export const freeze = (o) => Object.freeze(o);
+/** Overlay a partial policy onto a base one. Override maps are merged, not replaced. */
+export const mergePolicy = (base, patch) => ({
+    effort: patch.effort ?? base.effort,
+    roleOverrides: patch.roleOverrides != null || base.roleOverrides != null
+        ? { ...base.roleOverrides, ...patch.roleOverrides }
+        : undefined,
+    modelOverrides: patch.modelOverrides != null || base.modelOverrides != null
+        ? { ...base.modelOverrides, ...patch.modelOverrides }
+        : undefined,
+});
+/** Apply the policy's role→role remap. */
+export const resolveRole = (policy, role) => policy.roleOverrides?.[role] ?? role;
+export const effortPatch = (effort) => EFFORT_TABLE[effort];
+/** Normalize a {@link ModelConfigOverride} (alias or patch) to a patch. */
+export const resolveModelConfig = (override) => typeof override === 'string' ? { preset: override } : override;
+/**
+ * Merge effort < policy.modelOverride < call-site override into a single patch.
+ * Any field present in a higher-precedence source wins.
+ */
+export const mergeOverride = (effortBase, policyOverride, callOverride) => {
+    const policy = policyOverride != null ? resolveModelConfig(policyOverride) : {};
+    const call = callOverride != null ? resolveModelConfig(callOverride) : {};
+    return { ...effortBase, ...policy, ...call };
+};
+// --- Serialization ---
+/**
+ * Project an execution down to its JSON-safe state: every own field except the declared
+ * collaborators. Domain fields added by a consumer are carried through automatically,
+ * which is what lets an extended execution be persisted without extra wiring.
+ */
+export const composeExecState = (exec, collaboratorKeys) => {
+    const state = {};
+    for (const [key, value] of Object.entries(exec)) {
+        if (!collaboratorKeys.includes(key)) {
+            state[key] = value;
+        }
+    }
+    return state;
+};
+/**
+ * Same as {@link composeExecState}, plus the resumable task fields carried over from the
+ * execution's PRIOR state (they live only there — `phase`/`cursor`/`completed`/`data` are
+ * advanced by the workflow, not by refinement).
+ */
+export const composeTaskState = (exec, collaboratorKeys) => {
+    const base = composeExecState(exec, collaboratorKeys);
+    const prior = exec.state ?? {};
+    return {
+        ...base,
+        level: ExecutionLevel.Task,
+        phase: prior.phase,
+        completed: prior.completed,
+        cursor: prior.cursor,
+        data: prior.data,
+    };
+};
+//# sourceMappingURL=utils.js.map

package/build/execution/utils.js.map

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

package/build/helpers/index.d.ts

@@ -0,0 +1,5 @@
+export * from './retry.js';
+export * from './json.js';
+export * from './messages.js';
+export * from './spectate.js';
+//# sourceMappingURL=index.d.ts.map

package/build/helpers/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/helpers/index.ts"],"names":[],"mappings":"AACA,cAAc,YAAY,CAAA;AAC1B,cAAc,WAAW,CAAA;AACzB,cAAc,eAAe,CAAA;AAC7B,cAAc,eAAe,CAAA"}

package/build/helpers/index.js

@@ -0,0 +1,5 @@
+export * from './retry.js';
+export * from './json.js';
+export * from './messages.js';
+export * from './spectate.js';
+//# sourceMappingURL=index.js.map

package/build/helpers/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/helpers/index.ts"],"names":[],"mappings":"AACA,cAAc,YAAY,CAAA;AAC1B,cAAc,WAAW,CAAA;AACzB,cAAc,eAAe,CAAA;AAC7B,cAAc,eAAe,CAAA"}

package/build/helpers/json.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Recover a JSON value from message content. Some models ignore the tool they were
+ * pinned to and emit the schema-shaped JSON directly as plain message content, so the
+ * tool-call parse yields nothing while the content is still valid JSON. Tolerates
+ * markdown fences and leading/trailing prose by falling back to the outermost
+ * `{...}` / `[...]` span. Returns `null` when nothing parseable is found.
+ */
+export declare const parseJsonContent: (content: unknown) => unknown;
+/**
+ * Reconcile a model's answer with the schema it was given, for the two mistakes models
+ * make most often with tool-call arguments:
+ *
+ * 1. **Stringified structures** — an `array` field filled with the string `"[]"`, an
+ *    `integer` field with `"7"`, a `boolean` with `"true"`. Parsed back to the declared
+ *    type; on a parse failure the original value is kept so validation reports the real error.
+ * 2. **Over-wrapped scalars** — a `string` field filled with `{ path: "…" }` instead of
+ *    `"…"`. Unwrapped via the likely key, or via the single string property if there is
+ *    exactly one.
+ *
+ * Walks objects and arrays, so nested occurrences are fixed too. Purely defensive: a
+ * value that already matches its schema is returned untouched.
+ */
+export declare const coerceToSchema: (value: unknown, schema: unknown) => unknown;
+//# sourceMappingURL=json.d.ts.map

package/build/helpers/json.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"json.d.ts","sourceRoot":"","sources":["../../src/helpers/json.ts"],"names":[],"mappings":"AAWA;;;;;;GAMG;AACH,eAAO,MAAM,gBAAgB,GAAI,SAAS,OAAO,KAAG,OAmCnD,CAAA;AAED;;;;;;;;;;;;;GAaG;AACH,eAAO,MAAM,cAAc,GAAI,OAAO,OAAO,EAAE,QAAQ,OAAO,KAAG,OA+ChE,CAAA"}

package/build/helpers/json.js

@@ -0,0 +1,119 @@
+/** Property names checked when a model wraps a scalar string in an object. */
+const SCALAR_KEYS = ['path', 'file', 'filename', 'name', 'value', 'source'];
+const tryParse = (text) => {
+    try {
+        return JSON.parse(text);
+    }
+    catch {
+        return undefined;
+    }
+};
+/**
+ * Recover a JSON value from message content. Some models ignore the tool they were
+ * pinned to and emit the schema-shaped JSON directly as plain message content, so the
+ * tool-call parse yields nothing while the content is still valid JSON. Tolerates
+ * markdown fences and leading/trailing prose by falling back to the outermost
+ * `{...}` / `[...]` span. Returns `null` when nothing parseable is found.
+ */
+export const parseJsonContent = (content) => {
+    let text;
+    if (typeof content === 'string') {
+        text = content;
+    }
+    else if (Array.isArray(content)) {
+        text = content.map(part => typeof part === 'object' && part !== null && 'text' in part
+            ? String(part.text) : '').join('');
+    }
+    else {
+        return null;
+    }
+    text = text.trim();
+    if (text === '')
+        return null;
+    const fence = text.match(/```(?:json)?\s*([\s\S]*?)```/i);
+    if (fence != null)
+        text = fence[1].trim();
+    const whole = tryParse(text);
+    if (whole !== undefined)
+        return whole;
+    const firstObj = text.indexOf('{');
+    const lastObj = text.lastIndexOf('}');
+    if (firstObj >= 0 && lastObj > firstObj) {
+        const parsed = tryParse(text.slice(firstObj, lastObj + 1));
+        if (parsed !== undefined)
+            return parsed;
+    }
+    const firstArr = text.indexOf('[');
+    const lastArr = text.lastIndexOf(']');
+    if (firstArr >= 0 && lastArr > firstArr) {
+        const parsed = tryParse(text.slice(firstArr, lastArr + 1));
+        if (parsed !== undefined)
+            return parsed;
+    }
+    return null;
+};
+/**
+ * Reconcile a model's answer with the schema it was given, for the two mistakes models
+ * make most often with tool-call arguments:
+ *
+ * 1. **Stringified structures** — an `array` field filled with the string `"[]"`, an
+ *    `integer` field with `"7"`, a `boolean` with `"true"`. Parsed back to the declared
+ *    type; on a parse failure the original value is kept so validation reports the real error.
+ * 2. **Over-wrapped scalars** — a `string` field filled with `{ path: "…" }` instead of
+ *    `"…"`. Unwrapped via the likely key, or via the single string property if there is
+ *    exactly one.
+ *
+ * Walks objects and arrays, so nested occurrences are fixed too. Purely defensive: a
+ * value that already matches its schema is returned untouched.
+ */
+export const coerceToSchema = (value, schema) => {
+    if (schema == null || typeof schema !== 'object')
+        return value;
+    const s = schema;
+    const type = s.type;
+    if (typeof value === 'string' && type != null && type !== 'string') {
+        if (type === 'array' || type === 'object') {
+            try {
+                return coerceToSchema(JSON.parse(value), schema);
+            }
+            catch {
+                return value;
+            }
+        }
+        if (type === 'integer' || type === 'number') {
+            const n = Number(value);
+            return Number.isNaN(n) ? value : n;
+        }
+        if (type === 'boolean') {
+            if (value === 'true')
+                return true;
+            if (value === 'false')
+                return false;
+            return value;
+        }
+    }
+    if (type === 'string' && value != null && typeof value === 'object' && !Array.isArray(value)) {
+        const obj = value;
+        for (const key of SCALAR_KEYS) {
+            if (typeof obj[key] === 'string')
+                return obj[key];
+        }
+        const strings = Object.values(obj).filter((v) => typeof v === 'string');
+        if (strings.length === 1)
+            return strings[0];
+    }
+    if (type === 'object' && s.properties != null && value != null
+        && typeof value === 'object' && !Array.isArray(value)) {
+        const obj = value;
+        for (const [key, propSchema] of Object.entries(s.properties)) {
+            if (key in obj)
+                obj[key] = coerceToSchema(obj[key], propSchema);
+        }
+        return obj;
+    }
+    if (type === 'array' && Array.isArray(value) && s.items != null) {
+        return value.map(item => coerceToSchema(item, s.items));
+    }
+    return value;
+};
+//# sourceMappingURL=json.js.map

package/build/helpers/json.js.map

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

package/build/helpers/messages.d.ts

@@ -0,0 +1,10 @@
+import type { MessageFieldWithRole } from '@langchain/core/messages';
+import type { ModelInput } from '../types.js';
+/**
+ * Normalize whatever a caller passed as input into an array of role-tagged messages:
+ * a bare string becomes a `user` message, a single message becomes a one-element array.
+ * The result is a fresh array the model is free to mutate (JSON directive, `/no_think`,
+ * cache markers) without touching the caller's data.
+ */
+export declare const normalizeInput: (input: ModelInput) => MessageFieldWithRole[];
+//# sourceMappingURL=messages.d.ts.map

package/build/helpers/messages.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"messages.d.ts","sourceRoot":"","sources":["../../src/helpers/messages.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,0BAA0B,CAAA;AACpE,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,aAAa,CAAA;AAE7C;;;;;GAKG;AACH,eAAO,MAAM,cAAc,GAAI,OAAO,UAAU,KAAG,oBAAoB,EAE2D,CAAA"}

package/build/helpers/messages.js

@@ -0,0 +1,9 @@
+/**
+ * Normalize whatever a caller passed as input into an array of role-tagged messages:
+ * a bare string becomes a `user` message, a single message becomes a one-element array.
+ * The result is a fresh array the model is free to mutate (JSON directive, `/no_think`,
+ * cache markers) without touching the caller's data.
+ */
+export const normalizeInput = (input) => (Array.isArray(input) ? input : [input])
+    .map(message => typeof message === 'string' ? { role: 'user', content: message } : message);
+//# sourceMappingURL=messages.js.map

package/build/helpers/messages.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"messages.js","sourceRoot":"","sources":["../../src/helpers/messages.ts"],"names":[],"mappings":"AAGA;;;;;GAKG;AACH,MAAM,CAAC,MAAM,cAAc,GAAG,CAAC,KAAiB,EAA0B,EAAE,CAC1E,CAAC,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC;KACrC,GAAG,CAAC,OAAO,CAAC,EAAE,CAAC,OAAO,OAAO,KAAK,QAAQ,CAAC,CAAC,CAAC,EAAE,IAAI,EAAE,MAAe,EAAE,OAAO,EAAE,OAAO,EAAE,CAAC,CAAC,CAAC,OAAO,CAA2B,CAAA"}