principles-disciple 1.6.0 → 1.7.1

package/dist/service/runtime-summary-service.js

@@ -0,0 +1,319 @@
+import * as fs from 'fs';
+import * as path from 'path';
+import { readPainFlagData } from '../core/pain.js';
+import { resolvePdPath } from '../core/paths.js';
+import { listSessions } from '../core/session-tracker.js';
+import { WorkspaceContext } from '../core/workspace-context.js';
+const MAX_SOURCE_EVENTS = 5;
+const LEGACY_TRUST_REWARD_POLICY = 'frozen_all_positive';
+const GFI_PARTIAL_WARNING = 'GFI source attribution remains partial in Phase 2b because only the empathy slice is source-attributed; most non-empathy friction still lacks full per-source attribution.';
+const DAILY_GFI_WARNING = 'daily-stats.gfi is not authoritative in Phase 1 and is used only as a fallback reference.';
+const EVENT_BUFFER_WARNING = 'Live event buffer is unavailable in this context, so status may lag until events.jsonl flushes.';
+function pushWarning(warnings, message) {
+    if (!warnings.includes(message)) {
+        warnings.push(message);
+    }
+}
+export class RuntimeSummaryService {
+    static getSummary(workspaceDir, options) {
+        const generatedAt = new Date().toISOString();
+        const warnings = [];
+        const wctx = WorkspaceContext.fromHookContext({ workspaceDir });
+        const sessions = this.mergeSessionSnapshots(this.readSessions(wctx.resolve('SESSION_DIR'), warnings), workspaceDir);
+        const selectedSession = this.selectSession(sessions, options?.sessionId ?? null);
+        const selectedSessionId = selectedSession.session?.sessionId ?? null;
+        const persistedEvents = this.readEvents(path.join(wctx.stateDir, 'logs', 'events.jsonl'), warnings);
+        const hasBufferedEventAccess = typeof wctx.eventLog.getBufferedEvents === 'function';
+        const bufferedEvents = hasBufferedEventAccess
+            ? wctx.eventLog.getBufferedEvents()
+            : [];
+        const events = [...persistedEvents, ...bufferedEvents];
+        const dailyStats = this.readJsonFile(path.join(wctx.stateDir, 'logs', 'daily-stats.json'), warnings, false);
+        const today = generatedAt.slice(0, 10);
+        const dailyGfiPeak = dailyStats?.[today]?.gfi?.peak;
+        const gfiCurrent = selectedSession.session && Number.isFinite(selectedSession.session.currentGfi)
+            ? Number(selectedSession.session.currentGfi)
+            : null;
+        const sessionPeak = selectedSession.session && Number.isFinite(selectedSession.session.dailyGfiPeak)
+            ? Number(selectedSession.session.dailyGfiPeak)
+            : null;
+        const gfiPeak = sessionPeak ?? (Number.isFinite(dailyGfiPeak) ? Number(dailyGfiPeak) : null);
+        pushWarning(warnings, GFI_PARTIAL_WARNING);
+        if (sessionPeak === null && Number.isFinite(dailyGfiPeak)) {
+            pushWarning(warnings, DAILY_GFI_WARNING);
+        }
+        if (!hasBufferedEventAccess) {
+            pushWarning(warnings, EVENT_BUFFER_WARNING);
+        }
+        if (!selectedSession.session) {
+            pushWarning(warnings, 'No persisted session state was found; current session GFI is unavailable.');
+        }
+        const queue = this.readJsonFile(wctx.resolve('EVOLUTION_QUEUE'), warnings, false);
+        const directive = this.readJsonFile(wctx.resolve('EVOLUTION_DIRECTIVE'), warnings, false);
+        const queueStats = this.buildQueueStats(queue);
+        const directiveSummary = this.buildDirectiveSummary(directive, generatedAt, warnings, queueStats);
+        const painFlag = readPainFlagData(workspaceDir);
+        const painCandidates = this.readJsonFile(wctx.resolve('PAIN_CANDIDATES'), warnings, false);
+        const legacyTrust = this.readLegacyTrust(resolvePdPath(workspaceDir, 'AGENT_SCORECARD'), wctx, warnings);
+        const lastPainSignal = this.findLastPainSignal(events, selectedSessionId);
+        const gfiSources = this.buildGfiSources(events, selectedSessionId);
+        const gateStats = this.buildGateStats(events, selectedSessionId, warnings);
+        return {
+            gfi: {
+                current: gfiCurrent,
+                peak: gfiPeak,
+                sources: gfiSources,
+                dataQuality: 'partial',
+            },
+            legacyTrust,
+            evolution: {
+                queue: queueStats,
+                directive: directiveSummary,
+                dataQuality: queue ? 'authoritative' : 'partial',
+            },
+            pain: {
+                activeFlag: Object.keys(painFlag).length > 0,
+                activeFlagSource: painFlag.source || null,
+                candidates: painCandidates?.candidates && typeof painCandidates.candidates === 'object'
+                    ? Object.keys(painCandidates.candidates).length
+                    : null,
+                lastSignal: lastPainSignal,
+            },
+            gate: gateStats,
+            metadata: {
+                generatedAt,
+                workspaceDir,
+                sessionId: selectedSessionId,
+                selectedSessionReason: selectedSession.reason,
+                warnings,
+            },
+        };
+    }
+    static readSessions(sessionDir, warnings) {
+        if (!fs.existsSync(sessionDir)) {
+            pushWarning(warnings, 'No persisted session directory exists yet; session-scoped runtime state is unavailable.');
+            return [];
+        }
+        const sessions = [];
+        for (const file of fs.readdirSync(sessionDir)) {
+            if (!file.endsWith('.json'))
+                continue;
+            try {
+                const raw = fs.readFileSync(path.join(sessionDir, file), 'utf8');
+                const parsed = JSON.parse(raw);
+                if (parsed?.sessionId) {
+                    sessions.push(parsed);
+                }
+            }
+            catch {
+                pushWarning(warnings, `Failed to parse session snapshot: ${file}`);
+            }
+        }
+        return sessions.sort((a, b) => (b.lastActivityAt ?? 0) - (a.lastActivityAt ?? 0));
+    }
+    static selectSession(sessions, explicitSessionId) {
+        if (explicitSessionId) {
+            const explicit = sessions.find((session) => session.sessionId === explicitSessionId) ?? null;
+            return { session: explicit, reason: explicit ? 'explicit' : 'none' };
+        }
+        if (sessions.length === 0) {
+            return { session: null, reason: 'none' };
+        }
+        return { session: sessions[0], reason: 'latest_active' };
+    }
+    static mergeSessionSnapshots(persistedSessions, workspaceDir) {
+        const merged = new Map();
+        for (const session of persistedSessions) {
+            merged.set(session.sessionId, { ...session });
+        }
+        for (const live of listSessions(workspaceDir)) {
+            const persisted = merged.get(live.sessionId);
+            merged.set(live.sessionId, {
+                sessionId: live.sessionId,
+                currentGfi: Number.isFinite(live.currentGfi) ? Number(live.currentGfi) : persisted?.currentGfi,
+                dailyGfiPeak: Number.isFinite(live.dailyGfiPeak) ? Number(live.dailyGfiPeak) : persisted?.dailyGfiPeak,
+                lastActivityAt: Number.isFinite(live.lastActivityAt) ? Number(live.lastActivityAt) : persisted?.lastActivityAt,
+            });
+        }
+        return [...merged.values()].sort((a, b) => (b.lastActivityAt ?? 0) - (a.lastActivityAt ?? 0));
+    }
+    static buildQueueStats(queue) {
+        const stats = { pending: 0, inProgress: 0, completed: 0 };
+        if (!queue)
+            return stats;
+        for (const item of queue) {
+            if (item?.status === 'completed') {
+                stats.completed++;
+            }
+            else if (item?.status === 'in_progress') {
+                stats.inProgress++;
+            }
+            else {
+                stats.pending++;
+            }
+        }
+        return stats;
+    }
+    static buildDirectiveSummary(directive, generatedAt, warnings, queueStats) {
+        if (!directive) {
+            return {
+                exists: false,
+                active: null,
+                ageSeconds: null,
+                taskPreview: null,
+            };
+        }
+        const timestampMs = directive.timestamp ? new Date(directive.timestamp).getTime() : NaN;
+        const ageSeconds = Number.isFinite(timestampMs)
+            ? Math.max(0, Math.floor((new Date(generatedAt).getTime() - timestampMs) / 1000))
+            : null;
+        if (directive.active && queueStats.pending === 0 && queueStats.inProgress === 0) {
+            warnings.push('Directive is active while the queue has no pending or in-progress task; worker state may be stale.');
+        }
+        return {
+            exists: true,
+            active: typeof directive.active === 'boolean' ? directive.active : null,
+            ageSeconds,
+            taskPreview: directive.task ? directive.task.slice(0, 160) : null,
+        };
+    }
+    static readLegacyTrust(scorecardPath, wctx, warnings) {
+        const scorecard = this.readJsonFile(scorecardPath, warnings, false);
+        const score = Number.isFinite(scorecard?.trust_score) ? Number(scorecard?.trust_score) : null;
+        const settings = wctx.config.get('trust');
+        const stageThresholds = settings?.stages ?? {
+            stage_1_observer: 30,
+            stage_2_editor: 60,
+            stage_3_developer: 80,
+        };
+        let stage = null;
+        if (score !== null) {
+            if (score < (stageThresholds.stage_1_observer ?? 30)) {
+                stage = 1;
+            }
+            else if (score < (stageThresholds.stage_2_editor ?? 60)) {
+                stage = 2;
+            }
+            else if (score < (stageThresholds.stage_3_developer ?? 80)) {
+                stage = 3;
+            }
+            else {
+                stage = 4;
+            }
+        }
+        return {
+            score,
+            stage,
+            frozen: true,
+            lastUpdated: scorecard?.last_updated ?? null,
+            rewardPolicy: LEGACY_TRUST_REWARD_POLICY,
+        };
+    }
+    static readEvents(eventsPath, warnings) {
+        if (!fs.existsSync(eventsPath)) {
+            warnings.push('No events.jsonl file exists yet; recent pain and gate summaries are partial.');
+            return [];
+        }
+        try {
+            const raw = fs.readFileSync(eventsPath, 'utf8').trim();
+            if (!raw)
+                return [];
+            let parseFailures = 0;
+            const entries = raw
+                .split('\n')
+                .map((line) => {
+                try {
+                    return JSON.parse(line);
+                }
+                catch {
+                    parseFailures += 1;
+                    return null;
+                }
+            })
+                .filter((entry) => entry !== null);
+            if (parseFailures > 0) {
+                pushWarning(warnings, `Skipped ${parseFailures} malformed event line${parseFailures === 1 ? '' : 's'} while reading events.jsonl.`);
+            }
+            return entries;
+        }
+        catch {
+            pushWarning(warnings, 'Failed to read events.jsonl; recent pain and gate summaries are partial.');
+            return [];
+        }
+    }
+    static buildGfiSources(events, sessionId) {
+        const filtered = events
+            .filter((entry) => {
+            if (sessionId && entry.sessionId !== sessionId)
+                return false;
+            return (entry.type === 'pain_signal' ||
+                (entry.type === 'tool_call' && entry.category === 'failure'));
+        })
+            .slice(-MAX_SOURCE_EVENTS)
+            .reverse();
+        return filtered.map((entry) => {
+            if (entry.type === 'pain_signal') {
+                return {
+                    source: String(entry.data?.source ?? 'pain_signal'),
+                    score: this.asFiniteNumber(entry.data?.score),
+                    ts: entry.ts,
+                    confidence: this.asFiniteNumber(entry.data?.confidence),
+                    origin: typeof entry.data?.origin === 'string' ? entry.data.origin : undefined,
+                };
+            }
+            return {
+                source: `tool_failure:${String(entry.data?.toolName ?? 'unknown')}`,
+                score: this.asFiniteNumber(entry.data?.gfi),
+                ts: entry.ts,
+            };
+        });
+    }
+    static findLastPainSignal(events, sessionId) {
+        for (let i = events.length - 1; i >= 0; i--) {
+            const entry = events[i];
+            if (entry.type !== 'pain_signal')
+                continue;
+            if (sessionId && entry.sessionId !== sessionId)
+                continue;
+            return {
+                source: String(entry.data?.source ?? 'pain_signal'),
+                ts: entry.ts ?? null,
+                reason: typeof entry.data?.reason === 'string' ? entry.data.reason : null,
+            };
+        }
+        return null;
+    }
+    static buildGateStats(events, sessionId, warnings) {
+        const scoped = events.filter((entry) => {
+            if (sessionId && entry.sessionId !== sessionId)
+                return false;
+            return entry.type === 'gate_block' || entry.type === 'gate_bypass';
+        });
+        if (scoped.length === 0) {
+            pushWarning(warnings, 'Gate block counts before Phase 1 may be incomplete because older block events were not recorded to event-log.');
+        }
+        return {
+            recentBlocks: scoped.filter((entry) => entry.type === 'gate_block').length,
+            recentBypasses: scoped.filter((entry) => entry.type === 'gate_bypass').length,
+            dataQuality: scoped.length > 0 ? 'authoritative' : 'partial',
+        };
+    }
+    static readJsonFile(filePath, warnings, warnOnMissing) {
+        if (!fs.existsSync(filePath)) {
+            if (warnOnMissing) {
+                pushWarning(warnings, `Missing expected file: ${path.basename(filePath)}`);
+            }
+            return null;
+        }
+        try {
+            return JSON.parse(fs.readFileSync(filePath, 'utf8'));
+        }
+        catch {
+            pushWarning(warnings, `Failed to parse ${path.basename(filePath)}.`);
+            return null;
+        }
+    }
+    static asFiniteNumber(value) {
+        return Number.isFinite(value) ? Number(value) : undefined;
+    }
+}

package/dist/service/trajectory-service.d.ts

@@ -0,0 +1,2 @@
+import type { OpenClawPluginService } from '../openclaw-sdk.js';
+export declare const TrajectoryService: OpenClawPluginService;

package/dist/service/trajectory-service.js

@@ -0,0 +1,15 @@
+import { TrajectoryRegistry } from '../core/trajectory.js';
+import { WorkspaceContext } from '../core/workspace-context.js';
+export const TrajectoryService = {
+    id: 'principles-disciple-trajectory',
+    start(ctx) {
+        if (!ctx.workspaceDir)
+            return;
+        WorkspaceContext.fromHookContext(ctx).trajectory;
+    },
+    stop(ctx) {
+        if (!ctx.workspaceDir)
+            return;
+        TrajectoryRegistry.dispose(ctx.workspaceDir);
+    },
+};

package/dist/tools/agent-spawn.d.ts

@@ -6,22 +6,43 @@
  */
 import type { OpenClawPluginApi } from '../openclaw-sdk.js';
 /**
- * Agent Spawn Tool definition
+ * Create Agent Spawn Tool
+ *
+ * Uses factory pattern to capture `api` in closure, following OpenClaw plugin SDK conventions.
+ * The execute signature must be: async (_toolCallId: string, rawParams: Record<string, unknown>)
  */
-export declare const agentSpawnTool: {
+export declare function createAgentSpawnTool(api: OpenClawPluginApi): {
     name: string;
     description: string;
     parameters: import("@sinclair/typebox").TObject<{
         agentType: import("@sinclair/typebox").TString;
         task: import("@sinclair/typebox").TString;
+        runInBackground: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TBoolean>;
     }>;
     /**
      * Execution logic for the agent spawn tool
+     *
+     * OpenClaw tool execute signature:
+     * - First parameter: _toolCallId (string) - the tool call ID
+     * - Second parameter: rawParams (Record<string, unknown>) - the actual parameters
+     * - Third parameter (optional): signal (AbortSignal) - for cancellation
      */
-    execute(params: {
-        agentType: string;
-        task: string;
-    }, api: OpenClawPluginApi, _workspaceDir?: string): Promise<string>;
+    execute(_toolCallId: string, rawParams: Record<string, unknown>): Promise<{
+        content: Array<{
+            type: string;
+            text: string;
+        }>;
+    }>;
+};
+export declare const agentSpawnTool: {
+    name: string;
+    description: string;
+    parameters: import("@sinclair/typebox").TObject<{
+        agentType: import("@sinclair/typebox").TString;
+        task: import("@sinclair/typebox").TString;
+        runInBackground: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TBoolean>;
+    }>;
+    execute: () => never;
 };
 /**
  * Batch spawn multiple agents in sequence