@itaila/archetype 0.3.30

package/dist/engine/crud.js

@@ -0,0 +1,260 @@
+import { allowedOperations } from '../core/entity-helpers.js';
+/**
+ * Validate raw CRUD actions against registered entity schemas.
+ * Returns valid + invalid lists.
+ */
+export function validateCrudActions(raw, entities) {
+    const valid = [];
+    const invalid = [];
+    for (const rawAction of raw) {
+        // Parse stringified params (Gemini returns JSON string since the schema uses STRING type)
+        let action = rawAction;
+        if (typeof rawAction.params === 'string') {
+            try {
+                action = { ...rawAction, params: JSON.parse(rawAction.params) };
+            }
+            catch {
+                invalid.push({ action: rawAction, error: `Invalid JSON in params: ${String(rawAction.params).slice(0, 100)}` });
+                continue;
+            }
+        }
+        // Check entity exists
+        const entityConfig = entities[action.entity];
+        if (!entityConfig) {
+            invalid.push({ action, error: `Unknown entity "${action.entity}"` });
+            continue;
+        }
+        // Check the host app implements this operation for this entity
+        const allowed = allowedOperations(entityConfig);
+        if (!allowed.includes(action.operation)) {
+            invalid.push({ action, error: `Entity "${action.entity}" does not support ${action.operation} — supported: ${allowed.join(', ')}` });
+            continue;
+        }
+        // Check id for update/delete
+        if ((action.operation === 'update' || action.operation === 'delete') && !action.id) {
+            invalid.push({ action, error: `${action.operation} requires an id` });
+            continue;
+        }
+        // Validate params for create (full schema) and update (partial)
+        if (action.operation === 'create') {
+            const result = entityConfig.schema.safeParse(action.params ?? {});
+            if (!result.success) {
+                invalid.push({ action, error: result.error.message });
+                continue;
+            }
+            // Ensure every create has an ID (AI-generated temp or SDK fallback)
+            const id = action.id || crypto.randomUUID();
+            valid.push({ ...action, id, params: result.data });
+        }
+        else if (action.operation === 'update') {
+            // Partial validation — use .partial() if available
+            const schema = entityConfig.schema;
+            const partial = 'partial' in schema && typeof schema.partial === 'function'
+                ? schema.partial()
+                : schema;
+            const result = partial.safeParse(action.params ?? {});
+            if (!result.success) {
+                invalid.push({ action, error: result.error.message });
+                continue;
+            }
+            valid.push({ ...action, params: result.data });
+        }
+        else if (action.operation === 'delete') {
+            // delete — no params needed
+            valid.push(action);
+        }
+        else {
+            // Unknown operation — don't silently treat as delete.
+            invalid.push({
+                action,
+                error: `Unknown CRUD operation "${String(action.operation)}" — expected "create", "update", or "delete"`,
+            });
+        }
+    }
+    return { valid, invalid };
+}
+/**
+ * Generate an action annotation string for a CRUD action.
+ * Uses the entity's displayField to create human-readable annotations like:
+ *   created thread: "Roadmap prioritization"
+ */
+export function crudActionToAnnotation(action, entities) {
+    const config = entities[action.entity];
+    const label = config?.label ?? capitalize(action.entity);
+    const displayField = config?.displayField;
+    const displayValue = displayField && action.params?.[displayField]
+        ? String(action.params[displayField])
+        : null;
+    const title = displayValue ? `: "${displayValue}"` : '';
+    switch (action.operation) {
+        case 'create': return `created ${label.toLowerCase()}${title}`;
+        case 'update': return `updated ${label.toLowerCase()} ${action.id ?? ''}${title}`.trim();
+        case 'delete': return `deleted ${label.toLowerCase()} ${action.id ?? ''}`.trim();
+    }
+}
+function capitalize(s) {
+    return s.charAt(0).toUpperCase() + s.slice(1);
+}
+/**
+ * Separate CRUD actions from regular actions in a validated action list.
+ * Handles stringified params (Gemini quirk) and legacy top-level crudActions.
+ */
+export function separateCrudActions(actions, legacyCrud) {
+    const crudActions = [];
+    const nonCrudActions = [];
+    for (const action of actions) {
+        if (action.name === 'crud') {
+            const p = action.params;
+            const innerParams = typeof p.params === 'string' ? p.params : (p.params ? JSON.stringify(p.params) : undefined);
+            crudActions.push({
+                operation: p.operation,
+                entity: p.entity,
+                id: p.id,
+                params: innerParams,
+            });
+        }
+        else {
+            nonCrudActions.push(action);
+        }
+    }
+    if (legacyCrud?.length) {
+        crudActions.push(...legacyCrud);
+    }
+    return { crudActions, nonCrudActions };
+}
+/**
+ * Validate CRUD actions against entity schemas and populate the trace.
+ * Returns the valid subset; invalid actions are logged to trace.errors.
+ */
+export function validateAndTraceCrud(crudActions, entities, trace) {
+    if (crudActions.length === 0)
+        return undefined;
+    // If crud actions were emitted but no entities are declared, that's a
+    // config bug the AI can't recover from. Surface loudly — don't silently
+    // drop the actions (previous behavior was returning undefined, which
+    // hid the whole set from the trace).
+    if (!entities || Object.keys(entities).length === 0) {
+        for (const action of crudActions) {
+            const error = `No entities declared in persona config — cannot route ${action.operation} ${action.entity}`;
+            trace.crudActions.push({
+                operation: action.operation,
+                entity: action.entity,
+                id: action.id,
+                params: (action.params ?? {}),
+                status: 'invalid',
+                error,
+            });
+            trace.errors.push(`CRUD validation failed: ${error}`);
+        }
+        console.warn(`[archetype] ${crudActions.length} CRUD action(s) rejected — no entities declared in persona config`);
+        return undefined;
+    }
+    const validation = validateCrudActions(crudActions, entities);
+    for (const valid of validation.valid) {
+        trace.crudActions.push({ operation: valid.operation, entity: valid.entity, id: valid.id, params: valid.params ?? {}, status: 'valid' });
+    }
+    for (const inv of validation.invalid) {
+        trace.crudActions.push({ operation: inv.action.operation, entity: inv.action.entity, id: inv.action.id, params: inv.action.params ?? {}, status: 'invalid', error: inv.error });
+        trace.errors.push(`CRUD validation failed: ${inv.action.operation} ${inv.action.entity} — ${inv.error}`);
+    }
+    if (validation.invalid.length > 0) {
+        console.warn(`[archetype] ${validation.invalid.length} CRUD action(s) failed validation:`, validation.invalid.map(i => `${i.action.operation} ${i.action.entity}: ${i.error}`).join(' | '));
+    }
+    return validation.valid.length > 0 ? validation.valid : undefined;
+}
+/**
+ * Resolve temp IDs (prefixed with `_`) to real UUIDs.
+ * The AI generates `_w1`, `_ex1` etc. as cross-reference handles within a single response.
+ * This replaces them with permanent UUIDs before handlers see them.
+ *
+ * Resolves both `action.id` on creates and any string param values that match a temp ID.
+ */
+export function resolveTempIds(actions) {
+    const map = new Map();
+    // First pass: generate real IDs for all creates with _ prefix
+    for (const action of actions) {
+        if (action.operation === 'create' && action.id?.startsWith('_')) {
+            map.set(action.id, crypto.randomUUID());
+        }
+    }
+    if (map.size === 0)
+        return actions;
+    // Second pass: resolve all references (action.id + param values)
+    return actions.map(action => {
+        const id = action.id && map.has(action.id) ? map.get(action.id) : action.id;
+        const params = action.params ? resolveParamRefs(action.params, map) : action.params;
+        return { ...action, id, params };
+    });
+}
+function resolveParamRefs(params, map) {
+    const resolved = {};
+    for (const [key, value] of Object.entries(params)) {
+        if (typeof value === 'string' && map.has(value)) {
+            resolved[key] = map.get(value);
+        }
+        else {
+            resolved[key] = value;
+        }
+    }
+    return resolved;
+}
+/**
+ * Execute validated CRUD actions through entity-keyed handlers.
+ * This is the commit gate — the app calls this when ready to persist.
+ *
+ * Actions should be pre-validated (validateCrudActions) and temp-ID-resolved
+ * (resolveTempIds) before calling commitCrud.
+ *
+ * If a trace is provided, populates trace.domainActions with timing and status.
+ */
+export async function commitCrud(actions, handlers, options) {
+    const results = [];
+    for (const action of actions) {
+        const start = Date.now();
+        const label = `${action.operation}_${action.entity}`;
+        const entityHandler = handlers[action.entity];
+        if (!entityHandler) {
+            const result = { success: false, error: `No handler for entity: ${action.entity}` };
+            results.push(result);
+            if (options?.trace) {
+                options.trace.domainActions.push({ name: label, params: action.params ?? {}, status: 'failed', error: result.error, durationMs: Date.now() - start });
+            }
+            continue;
+        }
+        const opHandler = entityHandler[action.operation];
+        if (!opHandler) {
+            const result = { success: false, error: `No ${action.operation} handler for entity: ${action.entity}` };
+            results.push(result);
+            if (options?.trace) {
+                options.trace.domainActions.push({ name: label, params: action.params ?? {}, status: 'failed', error: result.error, durationMs: Date.now() - start });
+            }
+            continue;
+        }
+        try {
+            let result;
+            if (action.operation === 'delete') {
+                result = await opHandler(action.id);
+            }
+            else {
+                result = await opHandler(action.id, action.params ?? {});
+            }
+            results.push(result);
+            if (options?.trace) {
+                options.trace.domainActions.push({
+                    name: label, params: action.params ?? {},
+                    status: result.success ? 'executed' : 'failed',
+                    error: result.error, durationMs: Date.now() - start,
+                });
+            }
+        }
+        catch (err) {
+            const error = err instanceof Error ? err.message : String(err);
+            results.push({ success: false, error });
+            if (options?.trace) {
+                options.trace.domainActions.push({ name: label, params: action.params ?? {}, status: 'failed', error, durationMs: Date.now() - start });
+            }
+        }
+    }
+    return results;
+}
+//# sourceMappingURL=crud.js.map

package/dist/engine/crud.js.map

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

package/dist/engine/side-effects.d.ts

@@ -0,0 +1,93 @@
+import type { ParsedAction, ActionDefinition, ApprovalConfig } from '../types.js';
+export interface SideEffectHandlerResult {
+    success: boolean;
+    /** Did the handler actually mutate state? Defaults to `success` when omitted. */
+    changed?: boolean;
+    error?: string;
+}
+export interface SideEffectHandler {
+    (params: Record<string, unknown>): Promise<SideEffectHandlerResult>;
+}
+export interface SideEffectResult {
+    action: ParsedAction;
+    status: 'executed' | 'proposed' | 'failed' | 'no_op';
+    success: boolean;
+    /** Whether the handler actually mutated state (only set when status is 'executed' or 'no_op'). */
+    changed?: boolean;
+    error?: string;
+    annotation?: string;
+}
+/** A proposed action that passed validation but wasn't executed (propose mode). */
+export interface ProposedAction {
+    action: ParsedAction;
+    validatedParams: Record<string, unknown>;
+    annotation: string;
+}
+export interface ExecuteSideEffectsOptions {
+    /** Approval configuration. Defaults to yolo (execute immediately). */
+    approval?: ApprovalConfig;
+}
+/**
+ * Execute side effects for parsed actions.
+ * Validates action names, calls handlers, builds annotations.
+ *
+ * In 'yolo' mode (default): validates + executes immediately.
+ * In 'propose' mode: validates + returns proposals without executing.
+ *
+ * ActionConfidence interacts with mode:
+ * - 'low' always auto-executes (even in propose mode)
+ * - 'medium' follows the mode setting
+ * - 'high' always proposes (even in yolo mode)
+ */
+export declare function executeSideEffects(actions: ParsedAction[], handlers: Record<string, SideEffectHandler>, actionDefs: Record<string, ActionDefinition>, options?: ExecuteSideEffectsOptions): Promise<SideEffectResult[]>;
+/** Extended result type when propose mode generates proposals. */
+export interface SideEffectResultWithProposals extends Array<SideEffectResult> {
+    __proposed?: ProposedAction[];
+}
+/**
+ * Extract proposed actions from a side-effects result.
+ */
+export declare function getProposedActions(results: SideEffectResult[]): ProposedAction[];
+/**
+ * Return annotations for actions that actually executed successfully.
+ * Proposed or failed actions are intentionally excluded from stored history.
+ */
+export declare function getExecutedAnnotations(results: SideEffectResult[]): string[];
+/**
+ * Build the assistant message that should be stored in history.
+ * Uses the shared continuity builder so future turns see factual outcomes,
+ * while raw action annotations remain debug/display-only and are stripped
+ * before the model sees history.
+ */
+export declare function buildAssistantHistoryMessage(message: string, results: SideEffectResult[]): string;
+/**
+ * Execute previously proposed actions after user confirmation.
+ * Takes the ProposedAction[] from `getProposedActions()` and runs the handlers.
+ */
+export declare function confirmActions(proposed: ProposedAction[], handlers: Record<string, SideEffectHandler>): Promise<SideEffectResult[]>;
+export type SideEffectOutcomeStatus = 'none' | 'succeeded' | 'partial' | 'failed' | 'no_op';
+export interface SideEffectOutcome {
+    /** Aggregate status across all executed actions */
+    status: SideEffectOutcomeStatus;
+    /** Human-readable summary of what happened */
+    summary: string;
+    /** Action names that were attempted */
+    attemptedActions: string[];
+    /** Action names that actually mutated state */
+    appliedActions: string[];
+    /** Error messages from failed or partial actions */
+    errors: string[];
+}
+/**
+ * Summarize side-effect execution results into an aggregate outcome.
+ * Useful for communicating "what actually happened" to the user.
+ *
+ * Status logic:
+ * - 'none': no actions attempted (empty input or all proposed)
+ * - 'succeeded': all executed actions changed state
+ * - 'partial': some changed, some failed or didn't change
+ * - 'failed': nothing changed and there were errors
+ * - 'no_op': handlers ran successfully but nothing changed
+ */
+export declare function summarizeSideEffects(results: SideEffectResult[]): SideEffectOutcome;
+//# sourceMappingURL=side-effects.d.ts.map

package/dist/engine/side-effects.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"side-effects.d.ts","sourceRoot":"","sources":["../../src/engine/side-effects.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,gBAAgB,EAAE,cAAc,EAAE,MAAM,aAAa,CAAA;AAIjF,MAAM,WAAW,uBAAuB;IACtC,OAAO,EAAE,OAAO,CAAA;IAChB,iFAAiF;IACjF,OAAO,CAAC,EAAE,OAAO,CAAA;IACjB,KAAK,CAAC,EAAE,MAAM,CAAA;CACf;AAED,MAAM,WAAW,iBAAiB;IAChC,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,OAAO,CAAC,uBAAuB,CAAC,CAAA;CACpE;AAED,MAAM,WAAW,gBAAgB;IAC/B,MAAM,EAAE,YAAY,CAAA;IACpB,MAAM,EAAE,UAAU,GAAG,UAAU,GAAG,QAAQ,GAAG,OAAO,CAAA;IACpD,OAAO,EAAE,OAAO,CAAA;IAChB,kGAAkG;IAClG,OAAO,CAAC,EAAE,OAAO,CAAA;IACjB,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,UAAU,CAAC,EAAE,MAAM,CAAA;CACpB;AAED,mFAAmF;AACnF,MAAM,WAAW,cAAc;IAC7B,MAAM,EAAE,YAAY,CAAA;IACpB,eAAe,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;IACxC,UAAU,EAAE,MAAM,CAAA;CACnB;AAED,MAAM,WAAW,yBAAyB;IACxC,sEAAsE;IACtE,QAAQ,CAAC,EAAE,cAAc,CAAA;CAC1B;AAED;;;;;;;;;;;GAWG;AACH,wBAAsB,kBAAkB,CACtC,OAAO,EAAE,YAAY,EAAE,EACvB,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,iBAAiB,CAAC,EAC3C,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,gBAAgB,CAAC,EAC5C,OAAO,CAAC,EAAE,yBAAyB,GAClC,OAAO,CAAC,gBAAgB,EAAE,CAAC,CAuG7B;AAED,kEAAkE;AAClE,MAAM,WAAW,6BAA8B,SAAQ,KAAK,CAAC,gBAAgB,CAAC;IAC5E,UAAU,CAAC,EAAE,cAAc,EAAE,CAAA;CAC9B;AAED;;GAEG;AACH,wBAAgB,kBAAkB,CAAC,OAAO,EAAE,gBAAgB,EAAE,GAAG,cAAc,EAAE,CAEhF;AAED;;;GAGG;AACH,wBAAgB,sBAAsB,CAAC,OAAO,EAAE,gBAAgB,EAAE,GAAG,MAAM,EAAE,CAI5E;AAED;;;;;GAKG;AACH,wBAAgB,4BAA4B,CAC1C,OAAO,EAAE,MAAM,EACf,OAAO,EAAE,gBAAgB,EAAE,GAC1B,MAAM,CAaR;AAED;;;GAGG;AACH,wBAAsB,cAAc,CAClC,QAAQ,EAAE,cAAc,EAAE,EAC1B,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,iBAAiB,CAAC,GAC1C,OAAO,CAAC,gBAAgB,EAAE,CAAC,CAmD7B;AAkBD,MAAM,MAAM,uBAAuB,GAAG,MAAM,GAAG,WAAW,GAAG,SAAS,GAAG,QAAQ,GAAG,OAAO,CAAA;AAE3F,MAAM,WAAW,iBAAiB;IAChC,mDAAmD;IACnD,MAAM,EAAE,uBAAuB,CAAA;IAC/B,8CAA8C;IAC9C,OAAO,EAAE,MAAM,CAAA;IACf,uCAAuC;IACvC,gBAAgB,EAAE,MAAM,EAAE,CAAA;IAC1B,+CAA+C;IAC/C,cAAc,EAAE,MAAM,EAAE,CAAA;IACxB,oDAAoD;IACpD,MAAM,EAAE,MAAM,EAAE,CAAA;CACjB;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,oBAAoB,CAAC,OAAO,EAAE,gBAAgB,EAAE,GAAG,iBAAiB,CAyCnF"}

package/dist/engine/side-effects.js

@@ -0,0 +1,271 @@
+import { buildAnnotations } from '../core/actions.js';
+import { buildAssistantContinuityMessage } from './continuity.js';
+/**
+ * Execute side effects for parsed actions.
+ * Validates action names, calls handlers, builds annotations.
+ *
+ * In 'yolo' mode (default): validates + executes immediately.
+ * In 'propose' mode: validates + returns proposals without executing.
+ *
+ * ActionConfidence interacts with mode:
+ * - 'low' always auto-executes (even in propose mode)
+ * - 'medium' follows the mode setting
+ * - 'high' always proposes (even in yolo mode)
+ */
+export async function executeSideEffects(actions, handlers, actionDefs, options) {
+    const mode = options?.approval?.mode ?? 'yolo';
+    const results = [];
+    const proposed = [];
+    for (const action of actions) {
+        // Validate action exists
+        if (!(action.name in actionDefs)) {
+            results.push({
+                action,
+                status: 'failed',
+                success: false,
+                error: `Unknown action: ${action.name}`,
+            });
+            continue;
+        }
+        // Validate handler exists
+        const handler = handlers[action.name];
+        if (!handler) {
+            results.push({
+                action,
+                status: 'failed',
+                success: false,
+                error: `No handler registered for action: ${action.name}`,
+            });
+            continue;
+        }
+        // Validate params against Zod schema
+        const schema = actionDefs[action.name].schema;
+        const parseResult = schema.safeParse(action.params);
+        if (!parseResult.success) {
+            results.push({
+                action,
+                status: 'failed',
+                success: false,
+                error: `Invalid params for ${action.name}: ${parseResult.error.message}`,
+            });
+            continue;
+        }
+        // Determine whether to execute or propose
+        const shouldExecute = shouldAutoExecute(action.confidence, mode);
+        if (shouldExecute) {
+            // Execute handler immediately
+            try {
+                const result = await handler(parseResult.data);
+                const changed = result.changed ?? result.success;
+                const annotations = buildAnnotations([{ name: action.name, params: action.params }]);
+                if (result.success && !changed) {
+                    results.push({
+                        action,
+                        status: 'no_op',
+                        success: true,
+                        changed: false,
+                        error: result.error,
+                        annotation: annotations[0],
+                    });
+                }
+                else {
+                    results.push({
+                        action,
+                        status: result.success ? 'executed' : 'failed',
+                        success: result.success,
+                        changed,
+                        error: result.error,
+                        annotation: annotations[0],
+                    });
+                }
+            }
+            catch (err) {
+                results.push({
+                    action,
+                    status: 'failed',
+                    success: false,
+                    changed: false,
+                    error: `Handler error for ${action.name}: ${err instanceof Error ? err.message : String(err)}`,
+                });
+            }
+        }
+        else {
+            // Propose without executing
+            const annotations = buildAnnotations([{ name: action.name, params: action.params }]);
+            proposed.push({
+                action,
+                validatedParams: parseResult.data,
+                annotation: annotations[0],
+            });
+            results.push({
+                action,
+                status: 'proposed',
+                success: true, // validation passed, just not executed yet
+                annotation: annotations[0],
+            });
+        }
+    }
+    // Attach proposed actions to the result for the app to render
+    if (proposed.length > 0) {
+        ;
+        results.__proposed = proposed;
+    }
+    return results;
+}
+/**
+ * Extract proposed actions from a side-effects result.
+ */
+export function getProposedActions(results) {
+    return results.__proposed ?? [];
+}
+/**
+ * Return annotations for actions that actually executed successfully.
+ * Proposed or failed actions are intentionally excluded from stored history.
+ */
+export function getExecutedAnnotations(results) {
+    return results
+        .filter(result => result.status === 'executed' && result.success && result.annotation)
+        .map(result => result.annotation);
+}
+/**
+ * Build the assistant message that should be stored in history.
+ * Uses the shared continuity builder so future turns see factual outcomes,
+ * while raw action annotations remain debug/display-only and are stripped
+ * before the model sees history.
+ */
+export function buildAssistantHistoryMessage(message, results) {
+    const annotations = getExecutedAnnotations(results);
+    return buildAssistantContinuityMessage({
+        message,
+        actionAnnotations: annotations,
+        actionOutcomes: results.map(result => ({
+            action: result.action,
+            status: result.status,
+            success: result.success,
+            error: result.error,
+            annotation: result.annotation,
+        })),
+    });
+}
+/**
+ * Execute previously proposed actions after user confirmation.
+ * Takes the ProposedAction[] from `getProposedActions()` and runs the handlers.
+ */
+export async function confirmActions(proposed, handlers) {
+    const results = [];
+    for (const { action, validatedParams } of proposed) {
+        const handler = handlers[action.name];
+        if (!handler) {
+            results.push({
+                action,
+                status: 'failed',
+                success: false,
+                error: `No handler registered for action: ${action.name}`,
+            });
+            continue;
+        }
+        try {
+            const result = await handler(validatedParams);
+            const changed = result.changed ?? result.success;
+            const annotations = buildAnnotations([{ name: action.name, params: action.params }]);
+            if (result.success && !changed) {
+                results.push({
+                    action,
+                    status: 'no_op',
+                    success: true,
+                    changed: false,
+                    error: result.error,
+                    annotation: annotations[0],
+                });
+            }
+            else {
+                results.push({
+                    action,
+                    status: result.success ? 'executed' : 'failed',
+                    success: result.success,
+                    changed,
+                    error: result.error,
+                    annotation: annotations[0],
+                });
+            }
+        }
+        catch (err) {
+            results.push({
+                action,
+                status: 'failed',
+                success: false,
+                changed: false,
+                error: `Handler error for ${action.name}: ${err instanceof Error ? err.message : String(err)}`,
+            });
+        }
+    }
+    return results;
+}
+/**
+ * Determine if an action should auto-execute based on confidence + approval mode.
+ *
+ * - 'low' always executes (memory saves, logging)
+ * - 'medium' follows mode ('yolo' = execute, 'propose' = propose)
+ * - 'high' always proposes (destructive operations)
+ */
+function shouldAutoExecute(confidence, mode) {
+    if (confidence === 'low')
+        return true;
+    if (confidence === 'high')
+        return false;
+    // medium: follows mode
+    return mode === 'yolo';
+}
+/**
+ * Summarize side-effect execution results into an aggregate outcome.
+ * Useful for communicating "what actually happened" to the user.
+ *
+ * Status logic:
+ * - 'none': no actions attempted (empty input or all proposed)
+ * - 'succeeded': all executed actions changed state
+ * - 'partial': some changed, some failed or didn't change
+ * - 'failed': nothing changed and there were errors
+ * - 'no_op': handlers ran successfully but nothing changed
+ */
+export function summarizeSideEffects(results) {
+    const executed = results.filter(r => r.status !== 'proposed');
+    if (executed.length === 0) {
+        return {
+            status: 'none',
+            summary: 'No actions executed.',
+            attemptedActions: [],
+            appliedActions: [],
+            errors: [],
+        };
+    }
+    const attemptedActions = executed.map(r => r.action.name);
+    const appliedActions = executed.filter(r => r.changed === true).map(r => r.action.name);
+    const errors = executed.filter(r => r.error).map(r => r.error);
+    const anyChanged = appliedActions.length > 0;
+    const anyFailed = executed.some(r => r.status === 'failed');
+    const anyNoOp = executed.some(r => r.status === 'no_op');
+    let status;
+    if (anyChanged && (anyFailed || anyNoOp)) {
+        status = 'partial';
+    }
+    else if (anyChanged) {
+        status = 'succeeded';
+    }
+    else if (anyFailed) {
+        status = 'failed';
+    }
+    else {
+        status = 'no_op';
+    }
+    const summary = status === 'succeeded'
+        ? `${appliedActions.length} action${appliedActions.length === 1 ? '' : 's'} applied.`
+        : status === 'partial'
+            ? `${appliedActions.length} of ${attemptedActions.length} actions applied.${errors.length > 0 ? ` Errors: ${errors.join('; ')}` : ''}`
+            : status === 'failed'
+                ? `No actions applied.${errors.length > 0 ? ` ${errors.join('; ')}` : ''}`
+                : status === 'no_op'
+                    ? 'Actions ran but nothing changed.'
+                    : 'No actions executed.';
+    return { status, summary, attemptedActions, appliedActions, errors };
+}
+//# sourceMappingURL=side-effects.js.map

package/dist/engine/side-effects.js.map

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