pulseed 0.1.5 → 0.2.0

package/dist/platform/observation/observation-apply.js.map

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

package/dist/platform/observation/observation-datasource.d.ts

@@ -0,0 +1,21 @@
+import type { ObservationLogEntry } from "../../base/types/state.js";
+import type { IDataSourceAdapter } from "./data-source-adapter.js";
+/**
+ * Find the first DataSource adapter that can serve the given dimension name.
+ * Checks both getSupportedDimensions() and dimension_mapping config keys.
+ * Returns null if no adapter matches.
+ */
+export declare function findDataSourceForDimension(dataSources: IDataSourceAdapter[], dimensionName: string, goalId?: string): IDataSourceAdapter | null;
+/**
+ * Observe a goal dimension by querying a registered data source.
+ *
+ * Steps:
+ *   1. Find the data source by sourceId.
+ *   2. Build a DataSourceQuery, using dimension_mapping if configured.
+ *   3. Call source.query().
+ *   4. Convert result value to numeric if possible.
+ *   5. Create and persist an ObservationLogEntry via applyObservation callback.
+ *   6. Return the entry.
+ */
+export declare function observeFromDataSource(dataSources: IDataSourceAdapter[], goalId: string, dimensionName: string, sourceId: string, applyObservation: (goalId: string, entry: ObservationLogEntry) => void): Promise<ObservationLogEntry>;
+//# sourceMappingURL=observation-datasource.d.ts.map

package/dist/platform/observation/observation-datasource.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"observation-datasource.d.ts","sourceRoot":"","sources":["../../../src/platform/observation/observation-datasource.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,2BAA2B,CAAC;AACrE,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,0BAA0B,CAAC;AAGnE;;;;GAIG;AACH,wBAAgB,0BAA0B,CACxC,WAAW,EAAE,kBAAkB,EAAE,EACjC,aAAa,EAAE,MAAM,EACrB,MAAM,CAAC,EAAE,MAAM,GACd,kBAAkB,GAAG,IAAI,CA4B3B;AAED;;;;;;;;;;GAUG;AACH,wBAAsB,qBAAqB,CACzC,WAAW,EAAE,kBAAkB,EAAE,EACjC,MAAM,EAAE,MAAM,EACd,aAAa,EAAE,MAAM,EACrB,QAAQ,EAAE,MAAM,EAChB,gBAAgB,EAAE,CAAC,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,mBAAmB,KAAK,IAAI,GACrE,OAAO,CAAC,mBAAmB,CAAC,CA8D9B"}

package/dist/platform/observation/observation-datasource.js

@@ -0,0 +1,103 @@
+import { randomUUID } from "node:crypto";
+import { ObservationLogEntrySchema } from "../../base/types/state.js";
+/**
+ * Find the first DataSource adapter that can serve the given dimension name.
+ * Checks both getSupportedDimensions() and dimension_mapping config keys.
+ * Returns null if no adapter matches.
+ */
+export function findDataSourceForDimension(dataSources, dimensionName, goalId) {
+    const matches = (ds) => {
+        const dims = ds.getSupportedDimensions?.() ?? [];
+        if (dims.includes(dimensionName))
+            return true;
+        if (ds.config?.dimension_mapping && dimensionName in ds.config.dimension_mapping)
+            return true;
+        return false;
+    };
+    // First pass: prefer a datasource explicitly scoped to this goalId
+    for (const ds of dataSources) {
+        const scopeGoalId = ds.config?.scope_goal_id;
+        if (scopeGoalId === goalId && goalId !== undefined && matches(ds))
+            return ds;
+    }
+    // Second pass: fall back to an unscoped datasource
+    for (const ds of dataSources) {
+        const scopeGoalId = ds.config?.scope_goal_id;
+        if (scopeGoalId === undefined && matches(ds))
+            return ds;
+    }
+    // Third pass: fall back to a datasource scoped to a different goal.
+    // This handles the case where dedup prevented creating a goal-specific
+    // datasource because an identical one already exists for another goal.
+    for (const ds of dataSources) {
+        if (matches(ds))
+            return ds;
+    }
+    return null;
+}
+/**
+ * Observe a goal dimension by querying a registered data source.
+ *
+ * Steps:
+ *   1. Find the data source by sourceId.
+ *   2. Build a DataSourceQuery, using dimension_mapping if configured.
+ *   3. Call source.query().
+ *   4. Convert result value to numeric if possible.
+ *   5. Create and persist an ObservationLogEntry via applyObservation callback.
+ *   6. Return the entry.
+ */
+export async function observeFromDataSource(dataSources, goalId, dimensionName, sourceId, applyObservation) {
+    const source = dataSources.find((s) => s.sourceId === sourceId);
+    if (!source) {
+        throw new Error(`observeFromDataSource: data source "${sourceId}" not found. ` +
+            `Available: [${dataSources.map((s) => s.sourceId).join(", ")}]`);
+    }
+    const query = {
+        dimension_name: dimensionName,
+        timeout_ms: 10000,
+    };
+    const expression = source.config.dimension_mapping?.[dimensionName];
+    if (expression !== undefined) {
+        query.expression = expression;
+    }
+    const result = await source.query(query);
+    let extractedValue;
+    if (typeof result.value === "number") {
+        extractedValue = result.value;
+    }
+    else if (typeof result.value === "string") {
+        const parsed = parseFloat(result.value);
+        extractedValue = isNaN(parsed) ? result.value : parsed;
+    }
+    else if (typeof result.value === "boolean" || result.value === null) {
+        extractedValue = result.value;
+    }
+    else {
+        extractedValue = 0;
+    }
+    if (extractedValue === null || extractedValue === undefined) {
+        throw new Error(`Data source "${sourceId}" returned null for dimension "${dimensionName}"`);
+    }
+    const entry = ObservationLogEntrySchema.parse({
+        observation_id: randomUUID(),
+        timestamp: result.timestamp,
+        trigger: "periodic",
+        goal_id: goalId,
+        dimension_name: dimensionName,
+        layer: "mechanical",
+        method: {
+            type: "mechanical",
+            source: "data_source",
+            schedule: null,
+            endpoint: sourceId,
+            confidence_tier: "mechanical",
+        },
+        raw_result: result.raw,
+        extracted_value: extractedValue,
+        confidence: 0.90,
+        notes: `Data source: ${sourceId}`,
+    });
+    await applyObservation(goalId, entry);
+    return entry;
+}
+//# sourceMappingURL=observation-datasource.js.map

package/dist/platform/observation/observation-datasource.js.map

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

package/dist/platform/observation/observation-engine.d.ts

@@ -0,0 +1,171 @@
+import type { ObservationLogEntry, ObservationLog } from "../../base/types/state.js";
+import type { ObservationLayer, ObservationMethod } from "../../base/types/core.js";
+import type { StateManager } from "../../base/state/state-manager.js";
+import type { KnowledgeGapSignal } from "../../base/types/knowledge.js";
+import type { IDataSourceAdapter } from "./data-source-adapter.js";
+import type { ILLMClient } from "../../base/llm/llm-client.js";
+import type { Logger } from "../../runtime/logger.js";
+import type { IDimensionPreChecker } from "./dimension-pre-checker.js";
+import type { HookManager } from "../../runtime/hook-manager.js";
+import type { TaskDomain } from "../../base/types/pipeline.js";
+import type { AgentTask } from "../../orchestrator/execution/adapter-layer.js";
+import type { TaskObservationContext } from "./observation-task.js";
+export type { TaskObservationContext } from "./observation-task.js";
+import { getConfidenceTier, createObservationEntry } from "./observation-helpers.js";
+import type { ObservationEngineOptions } from "./observation-helpers.js";
+import type { ToolExecutor } from "../../tools/executor.js";
+import type { ToolCallContext } from "../../tools/types.js";
+import type { Dimension } from "../../orchestrator/goal/types/goal.js";
+import type { ToolObservationResult } from "./observation-tools.js";
+export type { ObservationEngineOptions, CrossValidationResult } from "./observation-helpers.js";
+export { applyProgressCeiling, getConfidenceTier, createObservationEntry, needsVerificationTask, resolveContradiction, detectKnowledgeGap, } from "./observation-helpers.js";
+export { observeWithTools, registerObservationAllowRules, type ToolObservationResult, } from "./observation-tools.js";
+/**
+ * ObservationEngine handles the 3-layer observation architecture.
+ *
+ * Layers (in descending trust order):
+ *   mechanical         — confidence [0.85, 1.0],  progress ceiling 1.00
+ *   independent_review — confidence [0.50, 0.84], progress ceiling 0.90
+ *   self_report        — confidence [0.10, 0.49], progress ceiling 0.70
+ *
+ * Observation logs are persisted via StateManager.appendObservation.
+ * Goal state updates are persisted via StateManager.saveGoal.
+ */
+export declare class ObservationEngine {
+    private readonly stateManager;
+    private dataSources;
+    private readonly llmClient?;
+    private readonly contextProvider?;
+    private readonly options;
+    private readonly logger?;
+    private readonly preChecker?;
+    private readonly hookManager?;
+    private toolExecutor?;
+    constructor(stateManager: StateManager, dataSources?: IDataSourceAdapter[], llmClient?: ILLMClient, contextProvider?: (goalId: string, dimensionName: string) => Promise<string>, options?: ObservationEngineOptions, logger?: Logger, preChecker?: IDimensionPreChecker, hookManager?: HookManager, toolExecutor?: ToolExecutor);
+    /**
+     * Compare a mechanical observation value against an LLM-produced value.
+     * Logs a warning when the two diverge beyond the configured threshold.
+     * The mechanical value always wins — LLM is used for diagnostics only.
+     */
+    private crossValidate;
+    /**
+     * Apply progress ceiling based on observation layer.
+     * Returns min(progress, ceiling).
+     */
+    applyProgressCeiling(progress: number, layer: ObservationLayer): number;
+    /**
+     * Return the ConfidenceTier and valid confidence range for a given layer.
+     */
+    getConfidenceTier(layer: ObservationLayer): ReturnType<typeof getConfidenceTier>;
+    /**
+     * Construct a new ObservationLogEntry.
+     * Confidence is clamped to the layer's valid range.
+     */
+    createObservationEntry(params: Parameters<typeof createObservationEntry>[0]): ObservationLogEntry;
+    /**
+     * Returns true when effective progress meets the threshold but confidence
+     * is below 0.85, meaning a mechanical verification task should be generated.
+     */
+    needsVerificationTask(effectiveProgress: number, confidence: number, threshold: number): boolean;
+    /**
+     * Resolve contradictions among multiple observation entries.
+     */
+    resolveContradiction(entries: ObservationLogEntry[]): ObservationLogEntry;
+    /**
+     * Strip trailing _2, _3, ... _N suffixes that LLMs sometimes append to
+     * deduplicate JSON keys.  Only applied to names from external (LLM) input.
+     */
+    normalizeDimensionName(name: string): string;
+    applyObservation(goalId: string, entry: ObservationLogEntry): Promise<void>;
+    /**
+     * Load the observation log for a goal.
+     * Returns an empty log if none exists.
+     */
+    getObservationLog(goalId: string): Promise<ObservationLog>;
+    /**
+     * Persist the observation log for a goal.
+     */
+    saveObservationLog(goalId: string, log: ObservationLog): Promise<void>;
+    /**
+     * Perform an observation pass for all dimensions of a goal.
+     *
+     * For each dimension, the following priority order is used:
+     *   1. DataSource — if a registered data source covers this dimension,
+     *      call observeFromDataSource() (mechanical, confidence 0.90).
+     *   2. LLM — if an LLM client is available, call observeWithLLM()
+     *      (independent_review, confidence 0.70).
+     *   3. self_report — fall back to re-recording the existing stored value.
+     *
+     * @param goalId   The goal to observe.
+     * @param methods  Array of ObservationMethod descriptors (one per dimension,
+     *                 in the same order as goal.dimensions).  Extra entries are
+     *                 ignored; missing entries fall back to the dimension's own
+     *                 observation_method.
+     */
+    observe(goalId: string, methods: ObservationMethod[]): Promise<void>;
+    /**
+     * Observe a goal dimension by querying a registered data source.
+     */
+    observeFromDataSource(goalId: string, dimensionName: string, sourceId: string): Promise<ObservationLogEntry>;
+    /**
+     * Find the first DataSource adapter that can serve the given dimension name.
+     */
+    private findDataSourceForDimension;
+    /**
+     * Observe a goal dimension using the LLM client.
+     *
+     * @param goalId             The goal being observed.
+     * @param dimensionName      The dimension name (snake_case).
+     * @param goalDescription    Human-readable goal description.
+     * @param dimensionLabel     Human-readable dimension label.
+     * @param thresholdDescription  JSON-stringified threshold for context.
+     * @param workspaceContext   Optional pre-fetched workspace context.
+     * @param previousScore      Previous observed score for trend context.
+     * @param dryRun             If true, do not write to state.
+     */
+    observeWithLLM(goalId: string, dimensionName: string, goalDescription: string, dimensionLabel: string, thresholdDescription: string, workspaceContext?: string, previousScore?: number | null, dryRun?: boolean, currentValue?: number | null, sourceAvailable?: boolean, workspacePath?: string): Promise<ObservationLogEntry>;
+    /**
+     * Return the registered data source adapters.
+     */
+    getDataSources(): IDataSourceAdapter[];
+    /**
+     * Dynamically add a data source adapter at runtime.
+     */
+    addDataSource(adapter: IDataSourceAdapter): void;
+    /**
+     * Dynamically remove a data source adapter at runtime.
+     * Returns true if the adapter was found and removed, false otherwise.
+     */
+    removeDataSource(sourceId: string): boolean;
+    /**
+     * Return dimension info for all registered data sources that expose
+     * getSupportedDimensions().
+     */
+    getAvailableDimensionInfo(): Array<{
+        name: string;
+        dimensions: string[];
+    }>;
+    /**
+     * Detect whether a set of observation entries indicates a knowledge gap.
+     */
+    detectKnowledgeGap(entries: ObservationLogEntry[], dimensionName?: string): KnowledgeGapSignal | null;
+    /**
+     * Collect domain-specific pre-execution context for a task.
+     *
+     * Delegates to the standalone `_observeForTask` function from
+     * `observation-task.ts`. The `contextProvider` on this class returns
+     * `Promise<string>` while `ObserveForTaskDeps` expects
+     * `Promise<string | null>`, so we adapt inline (both are compatible at
+     * runtime since `string` satisfies `string | null`).
+     *
+     * @param task    The agent task requiring pre-execution context.
+     * @param domain  The task domain that governs the collection strategy.
+     */
+    observeForTask(task: AgentTask, domain: TaskDomain): Promise<TaskObservationContext>;
+    /**
+     * Observe a dimension using the tool executor.
+     * Thin wrapper around the standalone observeWithTools function.
+     */
+    observeWithTools(dimension: Dimension, context: ToolCallContext): Promise<ToolObservationResult | null>;
+}
+//# sourceMappingURL=observation-engine.d.ts.map

package/dist/platform/observation/observation-engine.d.ts.map

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