@framers/agentos 0.1.228 → 0.1.230

package/dist/emergent/ForgeShapeValidator.js

@@ -0,0 +1,57 @@
+/**
+ * @fileoverview Pre-judge shape validator for forge requests.
+ * @module @framers/agentos/emergent/ForgeShapeValidator
+ *
+ * Catches the failure modes that dominate cheap-tier forge rejections
+ * (empty schema properties, too-few testCases, empty-input testCases)
+ * BEFORE the judge LLM sees the request. Every shape-check rejection
+ * saves one judge invocation plus the sandbox round-trip that would
+ * have followed it.
+ *
+ * Pure function, no dependencies.
+ */
+/**
+ * Validate a forge request's shape against the rules that dominate
+ * cheap-tier failures. Every violation is reported at once (no
+ * short-circuit) so the caller can build one comprehensive error
+ * message to show the LLM.
+ *
+ * Rules enforced:
+ * - `inputSchema.properties` must declare at least one field.
+ * - `outputSchema.properties` must declare at least one field.
+ * - `testCases` must have at least 2 entries.
+ * - Every testCase must have a non-empty `input` object.
+ *
+ * @param req Request fragment. Only the three fields are inspected;
+ *   other fields on the forge request are ignored.
+ * @returns Array of human-readable error strings. Empty means the
+ *   request's shape is well-formed enough to forward to the judge.
+ */
+export function validateForgeShape(req) {
+    const errors = [];
+    const inputSchema = req.inputSchema;
+    const outputSchema = req.outputSchema;
+    const inputProps = inputSchema && typeof inputSchema.properties === 'object' ? inputSchema.properties : null;
+    const outputProps = outputSchema && typeof outputSchema.properties === 'object' ? outputSchema.properties : null;
+    if (!inputProps || Object.keys(inputProps).length === 0) {
+        errors.push('inputSchema has no declared properties; add at least two typed fields');
+    }
+    if (!outputProps || Object.keys(outputProps).length === 0) {
+        errors.push('outputSchema has no declared properties; add at least one typed output field');
+    }
+    const tcArr = Array.isArray(req.testCases)
+        ? req.testCases
+        : [];
+    if (tcArr.length < 2) {
+        errors.push(`need at least 2 testCases, got ${tcArr.length}`);
+    }
+    const emptyInputs = tcArr.filter(tc => {
+        const inp = tc?.input;
+        return !inp || typeof inp !== 'object' || Object.keys(inp).length === 0;
+    }).length;
+    if (emptyInputs > 0) {
+        errors.push(`${emptyInputs} testCase${emptyInputs === 1 ? '' : 's'} use empty input; every test needs real field values`);
+    }
+    return errors;
+}
+//# sourceMappingURL=ForgeShapeValidator.js.map

package/dist/emergent/ForgeShapeValidator.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ForgeShapeValidator.js","sourceRoot":"","sources":["../../src/emergent/ForgeShapeValidator.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAaH;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,UAAU,kBAAkB,CAAC,GAAsB;IACvD,MAAM,MAAM,GAAa,EAAE,CAAC;IAC5B,MAAM,WAAW,GAAG,GAAG,CAAC,WAA8D,CAAC;IACvF,MAAM,YAAY,GAAG,GAAG,CAAC,YAA+D,CAAC;IACzF,MAAM,UAAU,GACd,WAAW,IAAI,OAAO,WAAW,CAAC,UAAU,KAAK,QAAQ,CAAC,CAAC,CAAC,WAAW,CAAC,UAAU,CAAC,CAAC,CAAC,IAAI,CAAC;IAC5F,MAAM,WAAW,GACf,YAAY,IAAI,OAAO,YAAY,CAAC,UAAU,KAAK,QAAQ,CAAC,CAAC,CAAC,YAAY,CAAC,UAAU,CAAC,CAAC,CAAC,IAAI,CAAC;IAC/F,IAAI,CAAC,UAAU,IAAI,MAAM,CAAC,IAAI,CAAC,UAAU,CAAC,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QACxD,MAAM,CAAC,IAAI,CAAC,uEAAuE,CAAC,CAAC;IACvF,CAAC;IACD,IAAI,CAAC,WAAW,IAAI,MAAM,CAAC,IAAI,CAAC,WAAW,CAAC,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QAC1D,MAAM,CAAC,IAAI,CAAC,8EAA8E,CAAC,CAAC;IAC9F,CAAC;IACD,MAAM,KAAK,GAAG,KAAK,CAAC,OAAO,CAAC,GAAG,CAAC,SAAS,CAAC;QACxC,CAAC,CAAE,GAAG,CAAC,SAAkE;QACzE,CAAC,CAAC,EAAE,CAAC;IACP,IAAI,KAAK,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QACrB,MAAM,CAAC,IAAI,CAAC,kCAAkC,KAAK,CAAC,MAAM,EAAE,CAAC,CAAC;IAChE,CAAC;IACD,MAAM,WAAW,GAAG,KAAK,CAAC,MAAM,CAAC,EAAE,CAAC,EAAE;QACpC,MAAM,GAAG,GAAG,EAAE,EAAE,KAAK,CAAC;QACtB,OAAO,CAAC,GAAG,IAAI,OAAO,GAAG,KAAK,QAAQ,IAAI,MAAM,CAAC,IAAI,CAAC,GAA8B,CAAC,CAAC,MAAM,KAAK,CAAC,CAAC;IACrG,CAAC,CAAC,CAAC,MAAM,CAAC;IACV,IAAI,WAAW,GAAG,CAAC,EAAE,CAAC;QACpB,MAAM,CAAC,IAAI,CACT,GAAG,WAAW,YAAY,WAAW,KAAK,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,GAAG,sDAAsD,CAC7G,CAAC;IACJ,CAAC;IACD,OAAO,MAAM,CAAC;AAChB,CAAC"}

package/dist/emergent/ForgeStatsAggregator.d.ts

@@ -0,0 +1,94 @@
+/**
+ * @fileoverview Standalone per-run aggregator for forge reliability
+ * telemetry. Composes with any cost/usage tracker the consumer already
+ * has.
+ * @module @framers/agentos/emergent/ForgeStatsAggregator
+ *
+ * Pinned shape: the {@link ForgeStats} snapshot must stay stable. It
+ * ships through consumer telemetry endpoints that downstream dashboards
+ * parse; renaming fields is a breaking change. Fold in new dimensions
+ * by adding fields, not renaming existing ones.
+ */
+import { type ForgeRejectionCategory } from './ForgeRejectionClassifier.js';
+/** Per-run forge reliability rollup snapshot. */
+export interface ForgeStats {
+    /** Total forge attempts (approved + rejected combined). */
+    attempts: number;
+    /** Attempts the judge approved. */
+    approved: number;
+    /** Attempts the judge or shape validator rejected. */
+    rejected: number;
+    /** Sum of confidence across approved attempts. Divide by `approved` for avg. */
+    approvedConfidenceSum: number;
+    /**
+     * Count of unique tool names seen this run (union of approved + rejected).
+     * A tool rejected then re-forged under the same name counts once.
+     */
+    uniqueNames: number;
+    /** Count of unique tool names that landed approved at least once this run. */
+    uniqueApproved: number;
+    /**
+     * Count of unique tool names that were ONLY rejected (never approved)
+     * this run. The retry loop did not recover these. Actionable signal
+     * for "real quality failures" vs retry churn.
+     */
+    uniqueTerminalRejections: number;
+    /**
+     * Histogram of rejection reasons, classified via
+     * {@link classifyForgeRejection}. Keys match {@link ForgeRejectionCategory}.
+     */
+    rejectionReasons: Record<ForgeRejectionCategory, number>;
+}
+/**
+ * Create a fresh, zeroed {@link ForgeStats} snapshot. Exposed for consumers
+ * that want to seed their own state or compare against a baseline.
+ */
+export declare function emptyForgeStats(): ForgeStats;
+/**
+ * Aggregator for forge outcomes across a single run. No dependency on
+ * the cost tracker or any consumer-specific types — consumers compose
+ * it into whatever telemetry layer they already have.
+ *
+ * Typical wiring: the consumer's forge capture callback calls
+ * {@link recordAttempt} with the outcome fields, then embeds
+ * {@link snapshot} under a `forgeStats` key in whatever payload the
+ * consumer ships to clients.
+ */
+export declare class ForgeStatsAggregator {
+    private stats;
+    private readonly approvedNames;
+    private readonly rejectedNames;
+    /**
+     * Record one forge attempt's outcome.
+     *
+     * @param approved `true` when the judge approved; `false` for shape-check
+     *   or judge rejections.
+     * @param confidence Judge's confidence score for approved tools. Summed
+     *   into `approvedConfidenceSum` (skipped for rejections so rejection
+     *   confidence does not dilute the average).
+     * @param toolName Optional tool name. When provided, tracks unique-tool
+     *   metrics (eventually-approved vs terminally-rejected) rather than
+     *   raw attempt counts.
+     * @param errorReason Optional rejection-reason string. On a rejected
+     *   attempt, passed through {@link classifyForgeRejection} and binned
+     *   into `rejectionReasons`.
+     */
+    recordAttempt(approved: boolean, confidence: number, toolName?: string, errorReason?: string): void;
+    /**
+     * Build a plain-object snapshot of current stats. Safe to JSON-serialize
+     * and ship to clients. Returns a shallow copy so callers can mutate
+     * without affecting the aggregator's internal state.
+     */
+    snapshot(): ForgeStats;
+    /**
+     * Clear all accumulated state. Useful when the aggregator is reused
+     * across multiple runs in one process.
+     */
+    reset(): void;
+    /**
+     * Recompute the three unique-tool counters from the name sets. Called
+     * after every attempt so `snapshot()` never has to do the math itself.
+     */
+    private refreshUniqueCounts;
+}
+//# sourceMappingURL=ForgeStatsAggregator.d.ts.map

package/dist/emergent/ForgeStatsAggregator.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ForgeStatsAggregator.d.ts","sourceRoot":"","sources":["../../src/emergent/ForgeStatsAggregator.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,EAEL,KAAK,sBAAsB,EAC5B,MAAM,+BAA+B,CAAC;AAEvC,iDAAiD;AACjD,MAAM,WAAW,UAAU;IACzB,2DAA2D;IAC3D,QAAQ,EAAE,MAAM,CAAC;IACjB,mCAAmC;IACnC,QAAQ,EAAE,MAAM,CAAC;IACjB,sDAAsD;IACtD,QAAQ,EAAE,MAAM,CAAC;IACjB,gFAAgF;IAChF,qBAAqB,EAAE,MAAM,CAAC;IAC9B;;;OAGG;IACH,WAAW,EAAE,MAAM,CAAC;IACpB,8EAA8E;IAC9E,cAAc,EAAE,MAAM,CAAC;IACvB;;;;OAIG;IACH,wBAAwB,EAAE,MAAM,CAAC;IACjC;;;OAGG;IACH,gBAAgB,EAAE,MAAM,CAAC,sBAAsB,EAAE,MAAM,CAAC,CAAC;CAC1D;AAED;;;GAGG;AACH,wBAAgB,eAAe,IAAI,UAAU,CAiB5C;AAED;;;;;;;;;GASG;AACH,qBAAa,oBAAoB;IAC/B,OAAO,CAAC,KAAK,CAAiC;IAC9C,OAAO,CAAC,QAAQ,CAAC,aAAa,CAAqB;IACnD,OAAO,CAAC,QAAQ,CAAC,aAAa,CAAqB;IAEnD;;;;;;;;;;;;;;OAcG;IACH,aAAa,CACX,QAAQ,EAAE,OAAO,EACjB,UAAU,EAAE,MAAM,EAClB,QAAQ,CAAC,EAAE,MAAM,EACjB,WAAW,CAAC,EAAE,MAAM,GACnB,IAAI;IAeP;;;;OAIG;IACH,QAAQ,IAAI,UAAU;IAOtB;;;OAGG;IACH,KAAK,IAAI,IAAI;IAMb;;;OAGG;IACH,OAAO,CAAC,mBAAmB;CAY5B"}

package/dist/emergent/ForgeStatsAggregator.js

@@ -0,0 +1,123 @@
+/**
+ * @fileoverview Standalone per-run aggregator for forge reliability
+ * telemetry. Composes with any cost/usage tracker the consumer already
+ * has.
+ * @module @framers/agentos/emergent/ForgeStatsAggregator
+ *
+ * Pinned shape: the {@link ForgeStats} snapshot must stay stable. It
+ * ships through consumer telemetry endpoints that downstream dashboards
+ * parse; renaming fields is a breaking change. Fold in new dimensions
+ * by adding fields, not renaming existing ones.
+ */
+import { classifyForgeRejection, } from './ForgeRejectionClassifier.js';
+/**
+ * Create a fresh, zeroed {@link ForgeStats} snapshot. Exposed for consumers
+ * that want to seed their own state or compare against a baseline.
+ */
+export function emptyForgeStats() {
+    return {
+        attempts: 0,
+        approved: 0,
+        rejected: 0,
+        approvedConfidenceSum: 0,
+        uniqueNames: 0,
+        uniqueApproved: 0,
+        uniqueTerminalRejections: 0,
+        rejectionReasons: {
+            schema_extra_field: 0,
+            shape_check: 0,
+            parse_error: 0,
+            judge_correctness: 0,
+            other: 0,
+        },
+    };
+}
+/**
+ * Aggregator for forge outcomes across a single run. No dependency on
+ * the cost tracker or any consumer-specific types — consumers compose
+ * it into whatever telemetry layer they already have.
+ *
+ * Typical wiring: the consumer's forge capture callback calls
+ * {@link recordAttempt} with the outcome fields, then embeds
+ * {@link snapshot} under a `forgeStats` key in whatever payload the
+ * consumer ships to clients.
+ */
+export class ForgeStatsAggregator {
+    constructor() {
+        this.stats = emptyForgeStats();
+        this.approvedNames = new Set();
+        this.rejectedNames = new Set();
+    }
+    /**
+     * Record one forge attempt's outcome.
+     *
+     * @param approved `true` when the judge approved; `false` for shape-check
+     *   or judge rejections.
+     * @param confidence Judge's confidence score for approved tools. Summed
+     *   into `approvedConfidenceSum` (skipped for rejections so rejection
+     *   confidence does not dilute the average).
+     * @param toolName Optional tool name. When provided, tracks unique-tool
+     *   metrics (eventually-approved vs terminally-rejected) rather than
+     *   raw attempt counts.
+     * @param errorReason Optional rejection-reason string. On a rejected
+     *   attempt, passed through {@link classifyForgeRejection} and binned
+     *   into `rejectionReasons`.
+     */
+    recordAttempt(approved, confidence, toolName, errorReason) {
+        this.stats.attempts += 1;
+        if (approved) {
+            this.stats.approved += 1;
+            this.stats.approvedConfidenceSum += confidence;
+            if (toolName)
+                this.approvedNames.add(toolName);
+        }
+        else {
+            this.stats.rejected += 1;
+            if (toolName)
+                this.rejectedNames.add(toolName);
+            const category = classifyForgeRejection(errorReason);
+            this.stats.rejectionReasons[category] += 1;
+        }
+        this.refreshUniqueCounts();
+    }
+    /**
+     * Build a plain-object snapshot of current stats. Safe to JSON-serialize
+     * and ship to clients. Returns a shallow copy so callers can mutate
+     * without affecting the aggregator's internal state.
+     */
+    snapshot() {
+        return {
+            ...this.stats,
+            rejectionReasons: { ...this.stats.rejectionReasons },
+        };
+    }
+    /**
+     * Clear all accumulated state. Useful when the aggregator is reused
+     * across multiple runs in one process.
+     */
+    reset() {
+        this.stats = emptyForgeStats();
+        this.approvedNames.clear();
+        this.rejectedNames.clear();
+    }
+    /**
+     * Recompute the three unique-tool counters from the name sets. Called
+     * after every attempt so `snapshot()` never has to do the math itself.
+     */
+    refreshUniqueCounts() {
+        this.stats.uniqueApproved = this.approvedNames.size;
+        let terminal = 0;
+        for (const n of this.rejectedNames) {
+            if (!this.approvedNames.has(n))
+                terminal += 1;
+        }
+        this.stats.uniqueTerminalRejections = terminal;
+        const union = new Set();
+        for (const n of this.approvedNames)
+            union.add(n);
+        for (const n of this.rejectedNames)
+            union.add(n);
+        this.stats.uniqueNames = union.size;
+    }
+}
+//# sourceMappingURL=ForgeStatsAggregator.js.map

package/dist/emergent/ForgeStatsAggregator.js.map

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

package/dist/emergent/index.d.ts

@@ -33,4 +33,9 @@ export { SelfEvaluateTool } from './SelfEvaluateTool.js';
 export { PersonalityMutationStore } from './PersonalityMutationStore.js';
 export type { PersonalityMutation, RecordMutationInput, DecayResult } from './PersonalityMutationStore.js';
 export type { SelfImprovementToolDeps } from './EmergentCapabilityEngine.js';
+export { classifyForgeRejection, type ForgeRejectionCategory, } from './ForgeRejectionClassifier.js';
+export { validateForgeShape, type ForgeShapeRequest, } from './ForgeShapeValidator.js';
+export { inferSchemaFromTestCases, type ForgeSchemaInferenceRequest, } from './ForgeSchemaInference.js';
+export { wrapForgeTool, type CapturedForge, type ForgeLogEvent, type WrapForgeToolOptions, } from './wrapForgeTool.js';
+export { ForgeStatsAggregator, emptyForgeStats, type ForgeStats, } from './ForgeStatsAggregator.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/emergent/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/emergent/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,cAAc,YAAY,CAAC;AAC3B,OAAO,EAAE,KAAK,qBAAqB,EAAE,+BAA+B,EAAE,MAAM,4BAA4B,CAAC;AACzG,OAAO,EAAE,qBAAqB,EAAE,MAAM,4BAA4B,CAAC;AACnE,OAAO,EAAE,kBAAkB,EAAE,MAAM,yBAAyB,CAAC;AAC7D,YAAY,EAAE,wBAAwB,EAAE,MAAM,yBAAyB,CAAC;AACxE,OAAO,EAAE,oBAAoB,EAAE,MAAM,2BAA2B,CAAC;AACjE,YAAY,EACV,eAAe,IAAI,8BAA8B,EACjD,UAAU,GACX,MAAM,2BAA2B,CAAC;AACnC,OAAO,EACL,oCAAoC,EACpC,wBAAwB,EACxB,4BAA4B,EAC5B,wBAAwB,EACxB,kCAAkC,GACnC,MAAM,kBAAkB,CAAC;AAC1B,YAAY,EACV,6BAA6B,EAC7B,0BAA0B,EAC1B,2BAA2B,EAC3B,+BAA+B,EAC/B,yCAAyC,GAC1C,MAAM,kBAAkB,CAAC;AAC1B,OAAO,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC;AACnD,YAAY,EAAE,aAAa,EAAE,mBAAmB,EAAE,MAAM,oBAAoB,CAAC;AAC7E,OAAO,EAAE,wBAAwB,EAAE,MAAM,+BAA+B,CAAC;AACzE,YAAY,EAAE,4BAA4B,EAAE,MAAM,+BAA+B,CAAC;AAClF,OAAO,EAAE,iBAAiB,EAAE,MAAM,wBAAwB,CAAC;AAC3D,YAAY,EAAE,cAAc,EAAE,MAAM,wBAAwB,CAAC;AAC7D,OAAO,EACL,iBAAiB,EACjB,mBAAmB,EACnB,cAAc,EACd,qBAAqB,GACtB,MAAM,oBAAoB,CAAC;AAC5B,OAAO,EAAE,oBAAoB,EAAE,MAAM,2BAA2B,CAAC;AACjE,OAAO,EAAE,gBAAgB,EAAE,MAAM,uBAAuB,CAAC;AACzD,OAAO,EAAE,kBAAkB,EAAE,MAAM,yBAAyB,CAAC;AAC7D,OAAO,EAAE,gBAAgB,EAAE,MAAM,uBAAuB,CAAC;AACzD,OAAO,EAAE,wBAAwB,EAAE,MAAM,+BAA+B,CAAC;AACzE,YAAY,EAAE,mBAAmB,EAAE,mBAAmB,EAAE,WAAW,EAAE,MAAM,+BAA+B,CAAC;AAC3G,YAAY,EAAE,uBAAuB,EAAE,MAAM,+BAA+B,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/emergent/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,cAAc,YAAY,CAAC;AAC3B,OAAO,EAAE,KAAK,qBAAqB,EAAE,+BAA+B,EAAE,MAAM,4BAA4B,CAAC;AACzG,OAAO,EAAE,qBAAqB,EAAE,MAAM,4BAA4B,CAAC;AACnE,OAAO,EAAE,kBAAkB,EAAE,MAAM,yBAAyB,CAAC;AAC7D,YAAY,EAAE,wBAAwB,EAAE,MAAM,yBAAyB,CAAC;AACxE,OAAO,EAAE,oBAAoB,EAAE,MAAM,2BAA2B,CAAC;AACjE,YAAY,EACV,eAAe,IAAI,8BAA8B,EACjD,UAAU,GACX,MAAM,2BAA2B,CAAC;AACnC,OAAO,EACL,oCAAoC,EACpC,wBAAwB,EACxB,4BAA4B,EAC5B,wBAAwB,EACxB,kCAAkC,GACnC,MAAM,kBAAkB,CAAC;AAC1B,YAAY,EACV,6BAA6B,EAC7B,0BAA0B,EAC1B,2BAA2B,EAC3B,+BAA+B,EAC/B,yCAAyC,GAC1C,MAAM,kBAAkB,CAAC;AAC1B,OAAO,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC;AACnD,YAAY,EAAE,aAAa,EAAE,mBAAmB,EAAE,MAAM,oBAAoB,CAAC;AAC7E,OAAO,EAAE,wBAAwB,EAAE,MAAM,+BAA+B,CAAC;AACzE,YAAY,EAAE,4BAA4B,EAAE,MAAM,+BAA+B,CAAC;AAClF,OAAO,EAAE,iBAAiB,EAAE,MAAM,wBAAwB,CAAC;AAC3D,YAAY,EAAE,cAAc,EAAE,MAAM,wBAAwB,CAAC;AAC7D,OAAO,EACL,iBAAiB,EACjB,mBAAmB,EACnB,cAAc,EACd,qBAAqB,GACtB,MAAM,oBAAoB,CAAC;AAC5B,OAAO,EAAE,oBAAoB,EAAE,MAAM,2BAA2B,CAAC;AACjE,OAAO,EAAE,gBAAgB,EAAE,MAAM,uBAAuB,CAAC;AACzD,OAAO,EAAE,kBAAkB,EAAE,MAAM,yBAAyB,CAAC;AAC7D,OAAO,EAAE,gBAAgB,EAAE,MAAM,uBAAuB,CAAC;AACzD,OAAO,EAAE,wBAAwB,EAAE,MAAM,+BAA+B,CAAC;AACzE,YAAY,EAAE,mBAAmB,EAAE,mBAAmB,EAAE,WAAW,EAAE,MAAM,+BAA+B,CAAC;AAC3G,YAAY,EAAE,uBAAuB,EAAE,MAAM,+BAA+B,CAAC;AAM7E,OAAO,EACL,sBAAsB,EACtB,KAAK,sBAAsB,GAC5B,MAAM,+BAA+B,CAAC;AACvC,OAAO,EACL,kBAAkB,EAClB,KAAK,iBAAiB,GACvB,MAAM,0BAA0B,CAAC;AAClC,OAAO,EACL,wBAAwB,EACxB,KAAK,2BAA2B,GACjC,MAAM,2BAA2B,CAAC;AACnC,OAAO,EACL,aAAa,EACb,KAAK,aAAa,EAClB,KAAK,aAAa,EAClB,KAAK,oBAAoB,GAC1B,MAAM,oBAAoB,CAAC;AAC5B,OAAO,EACL,oBAAoB,EACpB,eAAe,EACf,KAAK,UAAU,GAChB,MAAM,2BAA2B,CAAC"}

package/dist/emergent/index.js

@@ -25,4 +25,13 @@ export { ManageSkillsTool } from './ManageSkillsTool.js';
 export { CreateWorkflowTool } from './CreateWorkflowTool.js';
 export { SelfEvaluateTool } from './SelfEvaluateTool.js';
 export { PersonalityMutationStore } from './PersonalityMutationStore.js';
+// Forge observability — instrumentation for consumers that want live
+// visibility into forge health (rejection-reason histogram, shape-check
+// pre-validator, schema inference from testCases, capture wrapper,
+// aggregator).
+export { classifyForgeRejection, } from './ForgeRejectionClassifier.js';
+export { validateForgeShape, } from './ForgeShapeValidator.js';
+export { inferSchemaFromTestCases, } from './ForgeSchemaInference.js';
+export { wrapForgeTool, } from './wrapForgeTool.js';
+export { ForgeStatsAggregator, emptyForgeStats, } from './ForgeStatsAggregator.js';
 //# sourceMappingURL=index.js.map

package/dist/emergent/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/emergent/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,cAAc,YAAY,CAAC;AAC3B,OAAO,EAA8B,+BAA+B,EAAE,MAAM,4BAA4B,CAAC;AACzG,OAAO,EAAE,qBAAqB,EAAE,MAAM,4BAA4B,CAAC;AACnE,OAAO,EAAE,kBAAkB,EAAE,MAAM,yBAAyB,CAAC;AAE7D,OAAO,EAAE,oBAAoB,EAAE,MAAM,2BAA2B,CAAC;AAKjE,OAAO,EACL,oCAAoC,EACpC,wBAAwB,EACxB,4BAA4B,EAC5B,wBAAwB,EACxB,kCAAkC,GACnC,MAAM,kBAAkB,CAAC;AAQ1B,OAAO,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC;AAEnD,OAAO,EAAE,wBAAwB,EAAE,MAAM,+BAA+B,CAAC;AAEzE,OAAO,EAAE,iBAAiB,EAAE,MAAM,wBAAwB,CAAC;AAE3D,OAAO,EACL,iBAAiB,EACjB,mBAAmB,EACnB,cAAc,EACd,qBAAqB,GACtB,MAAM,oBAAoB,CAAC;AAC5B,OAAO,EAAE,oBAAoB,EAAE,MAAM,2BAA2B,CAAC;AACjE,OAAO,EAAE,gBAAgB,EAAE,MAAM,uBAAuB,CAAC;AACzD,OAAO,EAAE,kBAAkB,EAAE,MAAM,yBAAyB,CAAC;AAC7D,OAAO,EAAE,gBAAgB,EAAE,MAAM,uBAAuB,CAAC;AACzD,OAAO,EAAE,wBAAwB,EAAE,MAAM,+BAA+B,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/emergent/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,cAAc,YAAY,CAAC;AAC3B,OAAO,EAA8B,+BAA+B,EAAE,MAAM,4BAA4B,CAAC;AACzG,OAAO,EAAE,qBAAqB,EAAE,MAAM,4BAA4B,CAAC;AACnE,OAAO,EAAE,kBAAkB,EAAE,MAAM,yBAAyB,CAAC;AAE7D,OAAO,EAAE,oBAAoB,EAAE,MAAM,2BAA2B,CAAC;AAKjE,OAAO,EACL,oCAAoC,EACpC,wBAAwB,EACxB,4BAA4B,EAC5B,wBAAwB,EACxB,kCAAkC,GACnC,MAAM,kBAAkB,CAAC;AAQ1B,OAAO,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC;AAEnD,OAAO,EAAE,wBAAwB,EAAE,MAAM,+BAA+B,CAAC;AAEzE,OAAO,EAAE,iBAAiB,EAAE,MAAM,wBAAwB,CAAC;AAE3D,OAAO,EACL,iBAAiB,EACjB,mBAAmB,EACnB,cAAc,EACd,qBAAqB,GACtB,MAAM,oBAAoB,CAAC;AAC5B,OAAO,EAAE,oBAAoB,EAAE,MAAM,2BAA2B,CAAC;AACjE,OAAO,EAAE,gBAAgB,EAAE,MAAM,uBAAuB,CAAC;AACzD,OAAO,EAAE,kBAAkB,EAAE,MAAM,yBAAyB,CAAC;AAC7D,OAAO,EAAE,gBAAgB,EAAE,MAAM,uBAAuB,CAAC;AACzD,OAAO,EAAE,wBAAwB,EAAE,MAAM,+BAA+B,CAAC;AAIzE,qEAAqE;AACrE,wEAAwE;AACxE,mEAAmE;AACnE,eAAe;AACf,OAAO,EACL,sBAAsB,GAEvB,MAAM,+BAA+B,CAAC;AACvC,OAAO,EACL,kBAAkB,GAEnB,MAAM,0BAA0B,CAAC;AAClC,OAAO,EACL,wBAAwB,GAEzB,MAAM,2BAA2B,CAAC;AACnC,OAAO,EACL,aAAa,GAId,MAAM,oBAAoB,CAAC;AAC5B,OAAO,EACL,oBAAoB,EACpB,eAAe,GAEhB,MAAM,2BAA2B,CAAC"}

package/dist/emergent/wrapForgeTool.d.ts

@@ -0,0 +1,114 @@
+/**
+ * @fileoverview Wrapper around ForgeToolMetaTool that normalizes LLM
+ * output, runs a pre-judge shape check, captures every attempt, and
+ * surfaces outcomes as structured log events.
+ * @module @framers/agentos/emergent/wrapForgeTool
+ *
+ * LLMs emit wide variety in forge_tool args (stringified JSON, wrong
+ * mode spellings, missing allowlists, no code body). This wrapper fixes
+ * them up so the engine never crashes deep in sandbox validation, and
+ * every attempt gets recorded to the caller's capture sink regardless
+ * of outcome. That gives consumers an attempt-level ground truth that
+ * does not depend on the LLM self-reporting its forge calls.
+ *
+ * Pure wrapper over ForgeToolMetaTool + ForgeShapeValidator +
+ * ForgeSchemaInference. No stdout dependency — log events route
+ * through the optional `log` callback.
+ */
+import type { ITool } from '../core/tools/ITool.js';
+import { ForgeToolMetaTool } from './ForgeToolMetaTool.js';
+/**
+ * Captured forge event — ground-truth record of an actual forge call,
+ * independent of whether the LLM self-reported it.
+ */
+export interface CapturedForge {
+    /** Tool name (`fixed.name || 'unnamed'`). */
+    name: string;
+    /** Tool description (`fixed.description || name`). */
+    description: string;
+    /** `'sandbox'` or `'compose'` after normalization. */
+    mode: string;
+    /** Forge request's declared input schema post-normalization. */
+    inputSchema: unknown;
+    /** Forge request's declared output schema post-normalization. */
+    outputSchema: unknown;
+    /** Did the judge approve? */
+    approved: boolean;
+    /** Judge confidence for approved tools; 0 on rejection. */
+    confidence: number;
+    /** Judge verdict payload or shape-check context. */
+    output: unknown;
+    /** Populated on rejection or error. Truncated to 240 chars. */
+    errorReason?: string;
+    /**
+     * Optional free-form scope label (e.g. a department name, a chat
+     * agent id, or any grouping the caller wants propagated onto every
+     * capture record). Left undefined when the caller does not group.
+     */
+    scope?: string;
+    /** Wall-clock ms so captures can be attributed to surrounding events. */
+    timestamp: number;
+}
+/**
+ * Structured log event emitted at each forge lifecycle step. Consumers
+ * who care about stdout visibility can pass a `log` callback that
+ * renders this into console.log / pm2 / whatever. AgentOS emits
+ * nothing by default so the wrapper is safe to use in quiet contexts.
+ */
+export type ForgeLogEvent = {
+    kind: 'start';
+    scope?: string;
+    toolName: string;
+    mode: string;
+} | {
+    kind: 'approved';
+    scope?: string;
+    toolName: string;
+    confidence: number;
+} | {
+    kind: 'rejected';
+    scope?: string;
+    toolName: string;
+    reason: string;
+} | {
+    kind: 'error';
+    scope?: string;
+    toolName: string;
+    error: string;
+};
+/** Options for {@link wrapForgeTool}. */
+export interface WrapForgeToolOptions {
+    /** The raw ForgeToolMetaTool instance from EmergentCapabilityEngine. */
+    raw: ForgeToolMetaTool;
+    /** GMI / agent id patched onto the tool execution context. */
+    agentId: string;
+    /** Session id patched onto the tool execution context under sessionData. */
+    sessionId: string;
+    /** Required capture sink. Every attempt (valid or not) is recorded. */
+    capture: (record: CapturedForge) => void;
+    /**
+     * Optional scope label propagated onto every CapturedForge. Use for
+     * semantic grouping when multiple callers share a wrapper (dept
+     * name, channel id, agent role, etc.).
+     */
+    scope?: string;
+    /**
+     * Optional log callback for lifecycle visibility. When undefined,
+     * no log events are emitted (quiet mode).
+     */
+    log?: (event: ForgeLogEvent) => void;
+}
+/**
+ * Wrap the raw ForgeToolMetaTool so each forge attempt gets normalized,
+ * pre-validated, captured, and logged.
+ *
+ * Normalization fixes: stringified-JSON fields, mode synonyms (`code`,
+ * `javascript`, `js` → `sandbox`; `composed`, `composition`, `chain`,
+ * `pipeline` → `compose`), missing allowlist / code body / steps /
+ * schemas / testCases. After normalization, the shape validator runs;
+ * on failure the judge is skipped and a rejection record is captured
+ * immediately. On success, the raw meta-tool executes and the result's
+ * verdict is folded into a capture record.
+ */
+export declare function wrapForgeTool(options: WrapForgeToolOptions): ITool;
+//# sourceMappingURL=wrapForgeTool.d.ts.map

package/dist/emergent/wrapForgeTool.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"wrapForgeTool.d.ts","sourceRoot":"","sources":["../../src/emergent/wrapForgeTool.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAEH,OAAO,KAAK,EAAE,KAAK,EAAwB,MAAM,wBAAwB,CAAC;AAC1E,OAAO,EAAE,iBAAiB,EAAuB,MAAM,wBAAwB,CAAC;AAIhF;;;GAGG;AACH,MAAM,WAAW,aAAa;IAC5B,6CAA6C;IAC7C,IAAI,EAAE,MAAM,CAAC;IACb,sDAAsD;IACtD,WAAW,EAAE,MAAM,CAAC;IACpB,sDAAsD;IACtD,IAAI,EAAE,MAAM,CAAC;IACb,gEAAgE;IAChE,WAAW,EAAE,OAAO,CAAC;IACrB,iEAAiE;IACjE,YAAY,EAAE,OAAO,CAAC;IACtB,6BAA6B;IAC7B,QAAQ,EAAE,OAAO,CAAC;IAClB,2DAA2D;IAC3D,UAAU,EAAE,MAAM,CAAC;IACnB,oDAAoD;IACpD,MAAM,EAAE,OAAO,CAAC;IAChB,+DAA+D;IAC/D,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB;;;;OAIG;IACH,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,yEAAyE;IACzE,SAAS,EAAE,MAAM,CAAC;CACnB;AAED;;;;;GAKG;AACH,MAAM,MAAM,aAAa,GACrB;IAAE,IAAI,EAAE,OAAO,CAAC;IAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,GACjE;IAAE,IAAI,EAAE,UAAU,CAAC;IAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAC;IAAC,UAAU,EAAE,MAAM,CAAA;CAAE,GAC1E;IAAE,IAAI,EAAE,UAAU,CAAC;IAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,GACtE;IAAE,IAAI,EAAE,OAAO,CAAC;IAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,CAAC;AAEvE,yCAAyC;AACzC,MAAM,WAAW,oBAAoB;IACnC,wEAAwE;IACxE,GAAG,EAAE,iBAAiB,CAAC;IACvB,8DAA8D;IAC9D,OAAO,EAAE,MAAM,CAAC;IAChB,4EAA4E;IAC5E,SAAS,EAAE,MAAM,CAAC;IAClB,uEAAuE;IACvE,OAAO,EAAE,CAAC,MAAM,EAAE,aAAa,KAAK,IAAI,CAAC;IACzC;;;;OAIG;IACH,KAAK,CAAC,EAAE,MAAM,CAAC;IACf;;;OAGG;IACH,GAAG,CAAC,EAAE,CAAC,KAAK,EAAE,aAAa,KAAK,IAAI,CAAC;CACtC;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,aAAa,CAAC,OAAO,EAAE,oBAAoB,GAAG,KAAK,CA2LlE"}