@soleri/core 9.6.0 → 9.7.1

package/src/planning/goal-ancestry.ts

@@ -0,0 +1,187 @@
+/**
+ * Goal Ancestry — hierarchical goal tracking for plans and tasks.
+ *
+ * Goals form a tree: objective → project → plan → task.
+ * Each plan/task can reference its parent goal, enabling context
+ * to flow from high-level objectives down to individual work items.
+ */
+
+// ─── Types ────────────────────────────────────────────────────────
+
+export type GoalLevel = 'objective' | 'project' | 'plan' | 'task';
+
+export type GoalStatus = 'planned' | 'active' | 'completed' | 'abandoned';
+
+export interface Goal {
+  id: string;
+  title: string;
+  level: GoalLevel;
+  parentId?: string;
+  status: GoalStatus;
+  createdAt?: number;
+  updatedAt?: number;
+}
+
+// ─── Goal Store ───────────────────────────────────────────────────
+
+export interface GoalStore {
+  version: string;
+  goals: Goal[];
+}
+
+/**
+ * Persistent goal repository backed by a JSON file.
+ * Follows the same pattern as PlanStore in planner.ts.
+ */
+export interface GoalRepository {
+  getById(id: string): Goal | null;
+  getByParentId(parentId: string): Goal[];
+  create(goal: Omit<Goal, 'createdAt' | 'updatedAt'>): Goal;
+  updateStatus(id: string, status: GoalStatus): Goal;
+  list(): Goal[];
+}
+
+import { readFileSync, writeFileSync, existsSync, mkdirSync } from 'node:fs';
+import { dirname } from 'node:path';
+
+export class JsonGoalRepository implements GoalRepository {
+  private store: GoalStore;
+
+  constructor(private filePath: string) {
+    this.store = this.load();
+  }
+
+  private load(): GoalStore {
+    if (!existsSync(this.filePath)) return { version: '1.0', goals: [] };
+    try {
+      const data = readFileSync(this.filePath, 'utf-8');
+      return JSON.parse(data) as GoalStore;
+    } catch {
+      return { version: '1.0', goals: [] };
+    }
+  }
+
+  private save(): void {
+    mkdirSync(dirname(this.filePath), { recursive: true });
+    writeFileSync(this.filePath, JSON.stringify(this.store, null, 2), 'utf-8');
+  }
+
+  getById(id: string): Goal | null {
+    return this.store.goals.find((g) => g.id === id) ?? null;
+  }
+
+  getByParentId(parentId: string): Goal[] {
+    return this.store.goals.filter((g) => g.parentId === parentId);
+  }
+
+  create(goal: Omit<Goal, 'createdAt' | 'updatedAt'>): Goal {
+    const now = Date.now();
+    const full: Goal = { ...goal, createdAt: now, updatedAt: now };
+    this.store.goals.push(full);
+    this.save();
+    return full;
+  }
+
+  updateStatus(id: string, status: GoalStatus): Goal {
+    const goal = this.getById(id);
+    if (!goal) throw new Error(`Goal not found: ${id}`);
+    goal.status = status;
+    goal.updatedAt = Date.now();
+    this.save();
+    return goal;
+  }
+
+  list(): Goal[] {
+    return [...this.store.goals];
+  }
+}
+
+// ─── Max ancestor depth ──────────────────────────────────────────
+
+const MAX_ANCESTOR_DEPTH = 10;
+
+// ─── GoalAncestry ────────────────────────────────────────────────
+
+export class GoalAncestry {
+  constructor(private repo: GoalRepository) {}
+
+  /**
+   * Walk the parent chain from a goal up to the root.
+   * Returns ancestors from immediate parent to root (closest first).
+   * Max 10 levels; throws on cycle detection.
+   */
+  getAncestors(goalId: string): Goal[] {
+    const ancestors: Goal[] = [];
+    const visited = new Set<string>();
+    let currentId: string | undefined = goalId;
+
+    // Start by finding the goal itself to get its parentId
+    const start = this.repo.getById(goalId);
+    if (!start) return [];
+    currentId = start.parentId;
+
+    while (currentId && ancestors.length < MAX_ANCESTOR_DEPTH) {
+      if (visited.has(currentId)) {
+        throw new Error(`Cycle detected in goal hierarchy at goal '${currentId}'`);
+      }
+      visited.add(currentId);
+
+      const parent = this.repo.getById(currentId);
+      if (!parent) break;
+
+      ancestors.push(parent);
+      currentId = parent.parentId;
+    }
+
+    return ancestors;
+  }
+
+  /**
+   * Render a markdown summary of the goal hierarchy for a given goal.
+   * Shows the full chain from root objective down to the current goal.
+   */
+  getContext(goalId: string): string {
+    const goal = this.repo.getById(goalId);
+    if (!goal) return '';
+
+    const ancestors = this.getAncestors(goalId);
+    // Build chain from root to current: reverse ancestors then append current
+    const chain = [...ancestors].reverse();
+    chain.push(goal);
+
+    const lines: string[] = ['## Goal Context', ''];
+
+    for (let i = 0; i < chain.length; i++) {
+      const g = chain[i];
+      const indent = '  '.repeat(i);
+      const marker = i === chain.length - 1 ? '**→**' : '-';
+      lines.push(`${indent}${marker} [${g.level}] ${g.title} (${g.status})`);
+    }
+
+    return lines.join('\n');
+  }
+
+  /**
+   * Inject goal ancestry context into an execution context metadata object.
+   * Returns a new context with goalAncestry added to config.
+   */
+  inject<T extends { config?: Record<string, unknown> }>(ctx: T, goalId: string): T {
+    const rendered = this.getContext(goalId);
+    if (!rendered) return ctx;
+
+    return {
+      ...ctx,
+      config: {
+        ...ctx.config,
+        goalAncestry: rendered,
+      },
+    };
+  }
+}
+
+/**
+ * Generate a goal ID with the given level prefix.
+ */
+export function generateGoalId(level: GoalLevel): string {
+  return `goal-${level}-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`;
+}

package/src/planning/plan-lifecycle.ts

@@ -372,6 +372,8 @@ export function createPlanObject(params: {
   target_mode?: string;
   alternatives?: import('./planner-types.js').PlanAlternative[];
   initialStatus?: 'brainstorming' | 'draft';
+  /** Optional goal ID to link this plan to the goal hierarchy. */
+  goalId?: string;
 }): Plan {
   const now = Date.now();
   return {
@@ -401,6 +403,7 @@ export function createPlanObject(params: {
     ...(params.flow !== undefined && { flow: params.flow }),
     ...(params.target_mode !== undefined && { target_mode: params.target_mode }),
     ...(params.alternatives !== undefined && { alternatives: params.alternatives }),
+    ...(params.goalId !== undefined && { goalId: params.goalId }),
     checks: [],
     createdAt: now,
     updatedAt: now,

package/src/planning/planner-types.ts

@@ -205,6 +205,8 @@ export interface Plan {
   };
   /** Aggregate execution metrics — populated by reconcile() and complete(). */
   executionSummary?: ExecutionSummary;
+  /** Goal ID linking this plan to the goal hierarchy. */
+  goalId?: string;
   createdAt: number;
   updatedAt: number;
 }

package/src/runtime/context-health.ts

@@ -4,8 +4,18 @@
  *
  * Heuristic: tool calls x average payload size x 1.5 overhead factor.
  * Assumes ~200K token context window for fill estimation.
+ *
+ * Also integrates with CompactionPolicy to trigger session rotation
+ * when policy thresholds are breached.
  */
 
+import type {
+  CompactionPolicy,
+  CompactionResult,
+  SessionState,
+} from '../session/compaction-policy.js';
+import { shouldCompact } from '../session/compaction-evaluator.js';
+
 // =============================================================================
 // TYPES
 // =============================================================================
@@ -18,6 +28,8 @@ export interface ContextHealthStatus {
   toolCallCount: number;
   estimatedTokens: number;
   recommendation: string;
+  /** When a compaction policy is set, this contains the evaluation result. */
+  compaction?: CompactionResult;
 }
 
 export interface TrackEvent {
@@ -47,6 +59,17 @@ const RECOMMENDATIONS: Record<HealthLevel, string> = {
 export class ContextHealthMonitor {
   private toolCallCount = 0;
   private totalPayloadSize = 0;
+  private compactionPolicy: CompactionPolicy | undefined;
+  private sessionStartedAt: string | undefined;
+
+  /**
+   * Set the compaction policy and session start time.
+   * When set, `check()` will evaluate compaction thresholds.
+   */
+  setCompactionPolicy(policy: CompactionPolicy, startedAt?: string): void {
+    this.compactionPolicy = policy;
+    this.sessionStartedAt = startedAt ?? new Date().toISOString();
+  }
 
   /** Track a tool call event. */
   track(event: TrackEvent): void {
@@ -54,19 +77,36 @@ export class ContextHealthMonitor {
     this.totalPayloadSize += event.payloadSize;
   }
 
-  /** Check current context health status. */
+  /** Check current context health status (including compaction policy). */
   check(): ContextHealthStatus {
     const estimatedTokens = Math.round(this.totalPayloadSize * OVERHEAD_FACTOR);
     const estimatedFill = Math.min(estimatedTokens / CONTEXT_WINDOW, 1.0);
     const level = this.classifyLevel(estimatedFill);
 
-    return {
+    const status: ContextHealthStatus = {
       level,
       estimatedFill: Math.round(estimatedFill * 1000) / 1000,
       toolCallCount: this.toolCallCount,
       estimatedTokens,
       recommendation: RECOMMENDATIONS[level],
     };
+
+    // Evaluate compaction policy if configured
+    if (this.compactionPolicy && this.sessionStartedAt) {
+      const session: SessionState = {
+        runCount: this.toolCallCount,
+        inputTokens: estimatedTokens,
+        startedAt: this.sessionStartedAt,
+      };
+      status.compaction = shouldCompact(session, this.compactionPolicy);
+
+      // Escalate recommendation when compaction is triggered
+      if (status.compaction.compact) {
+        status.recommendation = `Compaction triggered: ${status.compaction.reason}`;
+      }
+    }
+
+    return status;
   }
 
   /** Reset all tracking (on session clear). */

package/src/runtime/facades/orchestrate-facade.ts

@@ -9,6 +9,7 @@ import type { AgentRuntime } from '../types.js';
 import { createOrchestrateOps } from '../orchestrate-ops.js';
 import { createProjectOps } from '../project-ops.js';
 import { createPlaybookOps } from '../playbook-ops.js';
+import { checkForUpdate } from '../../update-check.js';
 
 export function createOrchestrateFacadeOps(runtime: AgentRuntime): OpDefinition[] {
   const { vault, governance, projectRegistry } = runtime;
@@ -71,6 +72,19 @@ export function createOrchestrateFacadeOps(runtime: AgentRuntime): OpDefinition[
           // Non-critical — don't fail session start over staging check
         }
 
+        // Fire-and-forget update check — never blocks, never throws
+        try {
+          const enginePkgUrl = new URL('../../../package.json', import.meta.url);
+          const { readFileSync: readFs } = await import('node:fs');
+          const enginePkg = JSON.parse(readFs(enginePkgUrl, 'utf-8'));
+          void checkForUpdate(
+            runtime.config.agentId ?? 'unknown',
+            enginePkg.version ?? '0.0.0',
+          ).catch(() => {});
+        } catch {
+          // package.json not readable — skip update check silently
+        }
+
         return {
           project,
           is_new: isNew,

package/src/session/compaction-evaluator.ts

@@ -0,0 +1,87 @@
+/**
+ * Compaction Evaluator — checks session state against a compaction policy
+ * and determines whether the session should be rotated.
+ */
+
+import type { CompactionPolicy, CompactionResult, SessionState } from './compaction-policy.js';
+
+// =============================================================================
+// DURATION PARSER
+// =============================================================================
+
+const DURATION_RE = /^(\d+)(ms|s|m|h|d)$/;
+
+const MULTIPLIERS: Record<string, number> = {
+  ms: 1,
+  s: 1_000,
+  m: 60_000,
+  h: 3_600_000,
+  d: 86_400_000,
+};
+
+/**
+ * Parse a simple duration string (e.g. '72h', '30m', '7d') into milliseconds.
+ * Returns `undefined` for invalid input.
+ */
+export function parseDuration(duration: string): number | undefined {
+  const match = DURATION_RE.exec(duration.trim());
+  if (!match) return undefined;
+  const [, value, unit] = match;
+  return Number(value) * MULTIPLIERS[unit];
+}
+
+// =============================================================================
+// EVALUATOR
+// =============================================================================
+
+/**
+ * Evaluate whether a session should be compacted based on policy thresholds.
+ *
+ * Returns the first triggered threshold as the reason. Checks in order:
+ * 1. maxRuns
+ * 2. maxInputTokens
+ * 3. maxAge
+ */
+export function shouldCompact(
+  session: SessionState,
+  policy: CompactionPolicy,
+  now: Date = new Date(),
+): CompactionResult {
+  const noCompact: CompactionResult = { compact: false, reason: '', handoff: '' };
+
+  // Check maxRuns
+  if (policy.maxRuns !== undefined && session.runCount >= policy.maxRuns) {
+    return {
+      compact: true,
+      reason: `Run count (${session.runCount}) reached threshold (${policy.maxRuns})`,
+      handoff: '',
+    };
+  }
+
+  // Check maxInputTokens
+  if (policy.maxInputTokens !== undefined && session.inputTokens >= policy.maxInputTokens) {
+    return {
+      compact: true,
+      reason: `Input tokens (${session.inputTokens}) reached threshold (${policy.maxInputTokens})`,
+      handoff: '',
+    };
+  }
+
+  // Check maxAge
+  if (policy.maxAge !== undefined) {
+    const maxMs = parseDuration(policy.maxAge);
+    if (maxMs !== undefined) {
+      const startedAt = new Date(session.startedAt).getTime();
+      const elapsed = now.getTime() - startedAt;
+      if (elapsed >= maxMs) {
+        return {
+          compact: true,
+          reason: `Session age (${Math.round(elapsed / 60_000)}m) reached threshold (${policy.maxAge})`,
+          handoff: '',
+        };
+      }
+    }
+  }
+
+  return noCompact;
+}

package/src/session/compaction-policy.ts

@@ -0,0 +1,66 @@
+/**
+ * Session Compaction Policy — types and defaults for session rotation.
+ *
+ * Three thresholds determine when a session should be compacted:
+ * - maxRuns: tool call / interaction count
+ * - maxInputTokens: cumulative input token count
+ * - maxAge: wall-clock duration (ISO 8601 duration string, e.g. '72h')
+ */
+
+// =============================================================================
+// TYPES
+// =============================================================================
+
+/** Policy thresholds — all optional, merged from three levels. */
+export interface CompactionPolicy {
+  /** Maximum number of runs (tool calls / interactions) before compaction. */
+  maxRuns?: number;
+  /** Maximum cumulative input tokens before compaction. */
+  maxInputTokens?: number;
+  /** Maximum wall-clock age as an ISO 8601-ish duration string (e.g. '72h', '30m', '7d'). */
+  maxAge?: string;
+}
+
+/** Result of evaluating whether compaction is needed. */
+export interface CompactionResult {
+  /** Whether compaction should happen. */
+  compact: boolean;
+  /** Human-readable reason (empty string when compact is false). */
+  reason: string;
+  /** Pre-rendered handoff markdown (empty string when compact is false). */
+  handoff: string;
+}
+
+/** State snapshot of the current session, used for evaluation. */
+export interface SessionState {
+  /** Number of runs (tool calls) so far. */
+  runCount: number;
+  /** Cumulative input tokens consumed. */
+  inputTokens: number;
+  /** ISO 8601 timestamp when the session started. */
+  startedAt: string;
+}
+
+/** Structured handoff note persisted on rotation. */
+export interface HandoffNote {
+  /** ISO 8601 timestamp when the session was rotated. */
+  rotatedAt: string;
+  /** Why the session was rotated. */
+  reason: string;
+  /** Description of work in progress at rotation time. */
+  inProgress: string;
+  /** Key decisions made during the session. */
+  keyDecisions: string[];
+  /** Files modified during the session. */
+  filesModified: string[];
+}
+
+// =============================================================================
+// ENGINE DEFAULTS
+// =============================================================================
+
+export const ENGINE_DEFAULTS: Required<CompactionPolicy> = {
+  maxRuns: 200,
+  maxInputTokens: 2_000_000,
+  maxAge: '72h',
+};