create-principles-disciple 1.0.0 → 1.74.0

package/plugin/dist/core/pain.js

@@ -0,0 +1,223 @@
+import * as fs from 'fs';
+import { parseKvLines } from '../utils/io.js';
+import { resolvePdPath } from './paths.js';
+import { ConfigService } from './config-service.js';
+import { SystemLogger } from './system-logger.js';
+/**
+ * Builds legacy pain flag data for compatibility tests and historical readers.
+ * Do not use this to create new Runtime V2 diagnosis requests.
+ */
+export function buildPainFlag(input) {
+    // Omit optional fields when not provided — prevents writing empty lines to disk
+    // which causes agent confusion (SKILL.md vs reality drift)
+    return {
+        source: input.source,
+        score: input.score,
+        time: input.time || new Date().toISOString(),
+        reason: input.reason,
+        session_id: input.session_id ?? '',
+        agent_id: input.agent_id ?? '',
+        is_risky: input.is_risky ? 'true' : 'false',
+        trace_id: input.trace_id ?? '',
+        trigger_text_preview: input.trigger_text_preview ?? '',
+        pain_event_id: input.pain_event_id,
+    };
+}
+/**
+ * Validates a pain flag read from disk.
+ * Returns list of missing required fields — empty string means all present.
+ */
+export function validatePainFlag(data) {
+    const missing = [];
+    // Only source/score/time/reason are truly required — session_id/agent_id
+    // may be empty in automated contexts (heartbeat, background workers)
+    const required = ['source', 'score', 'time', 'reason'];
+    for (const field of required) {
+        if (!data[field] || data[field].trim() === '') {
+            missing.push(field);
+        }
+    }
+    return missing;
+}
+export function computePainScore(rc, isSpiral, missingTestCommand, softScore, projectDir) {
+    let score = Math.max(0, softScore || 0);
+    const stateDir = projectDir ? resolvePdPath(projectDir, 'STATE_DIR') : undefined;
+    const config = stateDir ? ConfigService.get(stateDir) : null;
+    const scoreSettings = config ? config.get('scores') : {
+        exit_code_penalty: 70,
+        spiral_penalty: 40,
+        missing_test_command_penalty: 30
+    };
+    if (rc !== 0) {
+        score += scoreSettings.exit_code_penalty;
+    }
+    if (isSpiral) {
+        score += scoreSettings.spiral_penalty;
+    }
+    if (missingTestCommand) {
+        score += scoreSettings.missing_test_command_penalty;
+    }
+    return Math.min(100, score);
+}
+export function painSeverityLabel(painScore, isSpiral = false, projectDir) {
+    if (isSpiral) {
+        return "critical";
+    }
+    const stateDir = projectDir ? resolvePdPath(projectDir, 'STATE_DIR') : undefined;
+    const config = stateDir ? ConfigService.get(stateDir) : null;
+    const thresholds = config ? config.get('severity_thresholds') : {
+        high: 70,
+        medium: 40,
+        low: 20
+    };
+    if (painScore >= thresholds.high) {
+        return "high";
+    }
+    else if (painScore >= thresholds.medium) {
+        return "medium";
+    }
+    else if (painScore >= thresholds.low) {
+        return "low";
+    }
+    else {
+        return "info";
+    }
+}
+/**
+ * Converts a JSON pain flag object to KV format.
+ */
+function convertJsonToKv(json) {
+    const kvData = {};
+    const fieldMap = {
+        source: 'source',
+        score: 'score',
+        time: 'time',
+        timestamp: 'time',
+        reason: 'reason',
+        session_id: 'session_id',
+        sessionId: 'session_id',
+        agent_id: 'agent_id',
+        agentId: 'agent_id',
+        is_risky: 'is_risky',
+        isRisky: 'is_risky',
+        severity: 'severity',
+        painId: 'pain_id',
+    };
+    for (const [jsonKey, kvKey] of Object.entries(fieldMap)) {
+        if (json[jsonKey] !== undefined) {
+            kvData[kvKey] = String(json[jsonKey]);
+        }
+    }
+    for (const [key, value] of Object.entries(json)) {
+        if (fieldMap[key] === undefined && value !== undefined && value !== null) {
+            kvData[key] = String(value);
+        }
+    }
+    return kvData;
+}
+/**
+ * Reads and validates the legacy pain flag file.
+ *
+ * - If file doesn't exist → returns {}
+ * - If file is JSON format → converts to KV in memory only
+ * - If file is KV format → validates required fields, logs warning if missing
+ * - If file has unknown fields → silently ignores them (forward-compatible)
+ */
+export function readPainFlagData(projectDir) {
+    const painFlagPath = resolvePdPath(projectDir, 'PAIN_FLAG');
+    try {
+        if (!fs.existsSync(painFlagPath)) {
+            return {};
+        }
+        const content = fs.readFileSync(painFlagPath, "utf-8").trim();
+        if (!content) {
+            return {};
+        }
+        // Detect JSON format. Legacy compatibility only: parse in memory and do not
+        // rewrite .pain_flag, because Runtime V2 must not create or repair this file.
+        if (content.startsWith('{')) {
+            let json;
+            try {
+                json = JSON.parse(content);
+            }
+            catch {
+                SystemLogger.log(projectDir, 'PAIN_FLAG_CORRUPT', 'Pain flag file contains invalid JSON');
+                return {};
+            }
+            const kvData = convertJsonToKv(json);
+            SystemLogger.log(projectDir, 'PAIN_FLAG_LEGACY_JSON_READ', `Read legacy JSON pain flag in memory (${Object.keys(json).length} fields)`);
+            return kvData;
+        }
+        // KV format — parse and validate
+        const data = parseKvLines(content);
+        const missing = validatePainFlag(data);
+        if (missing.length > 0) {
+            SystemLogger.log(projectDir, 'PAIN_FLAG_INCOMPLETE', `Pain flag missing required fields: ${missing.join(', ')}`);
+        }
+        return data;
+    }
+    catch (e) {
+        SystemLogger.log(projectDir, 'PAIN_FLAG_READ_ERROR', `Failed to read pain flag: ${String(e)}`);
+        return {};
+    }
+}
+export function readPainFlagContract(projectDir) {
+    const data = readPainFlagData(projectDir);
+    if (Object.keys(data).length === 0) {
+        const painFlagPath = resolvePdPath(projectDir, 'PAIN_FLAG');
+        if (!fs.existsSync(painFlagPath)) {
+            return { status: 'missing', format: 'missing', data: {}, missingFields: [] };
+        }
+        const raw = fs.readFileSync(painFlagPath, 'utf-8').trim();
+        if (!raw) {
+            return { status: 'missing', format: 'empty', data: {}, missingFields: [] };
+        }
+        return {
+            status: 'invalid',
+            format: raw.startsWith('{') ? 'invalid_json' : 'kv',
+            data: {},
+            missingFields: ['unparseable'],
+        };
+    }
+    const missing = validatePainFlag(data);
+    return {
+        status: missing.length > 0 ? 'invalid' : 'valid',
+        format: 'kv',
+        data,
+        missingFields: missing,
+    };
+}
+/**
+ * Track principle value metrics when a pain signal is written.
+ * This is observation-only — it does NOT affect the pain flag write flow.
+ * If any principle matches the pain signal, its painPreventedCount is incremented.
+ * Errors are silently ignored to avoid disrupting the pain pipeline.
+ */
+export function trackPrincipleValue(workspaceDir, painData, getActivePrinciples, updatePrincipleMetrics) {
+    try {
+        const activePrinciples = getActivePrinciples();
+        if (!activePrinciples.length)
+            return;
+        const painText = `${painData.reason || ''} ${painData.source || ''}`.toLowerCase();
+        const now = new Date().toISOString();
+        for (const principle of activePrinciples) {
+            const triggerPattern = principle.trigger?.toLowerCase();
+            if (!triggerPattern)
+                continue;
+            // Simple keyword match — if any word from the trigger appears in the pain text
+            const triggerWords = triggerPattern.split(/[\s|\\.+*?()[\]{}^$-]+/).filter((w) => w.length > 2);
+            const matchCount = triggerWords.filter((word) => painText.includes(word)).length;
+            if (matchCount >= 2 || (triggerWords.length <= 3 && matchCount >= 1)) {
+                const currentMetrics = principle.valueMetrics ?? { painPreventedCount: 0, calculatedAt: now };
+                updatePrincipleMetrics(principle.id, {
+                    painPreventedCount: currentMetrics.painPreventedCount + 1,
+                    lastPainPreventedAt: now,
+                    calculatedAt: now,
+                });
+            }
+        }
+    }
+    catch {
+        // Observation only — never disrupt the pain pipeline
+    }
+}

package/plugin/dist/core/path-resolver.d.ts

@@ -0,0 +1,60 @@
+import type { OpenClawPluginApi } from '../openclaw-sdk.js';
+export interface PathResolverOptions {
+    workspaceDir?: string;
+    normalizeWorkspace?: boolean;
+    logger?: {
+        debug?: (_msg: string) => void;
+        info?: (_msg: string) => void;
+        warn?: (_msg: string) => void;
+        error?: (_msg: string) => void;
+    };
+}
+export declare const PD_ENV_VARS: {
+    readonly WORKSPACE_DIR: "PD_WORKSPACE_DIR";
+    readonly STATE_DIR: "PD_STATE_DIR";
+    readonly DEBUG: "DEBUG";
+};
+export declare const PD_ENV_DESCRIPTIONS: Record<keyof typeof PD_ENV_VARS, {
+    desc: string;
+    example: string;
+}>;
+export declare function printEnvVarHelp(): void;
+export interface PDConfig {
+    workspace?: string;
+    state?: string;
+    debug?: boolean;
+}
+export declare class PathResolver {
+    private static extensionRoot;
+    private workspaceDir;
+    private stateDir;
+    private readonly logger?;
+    private readonly normalizeWorkspace;
+    private initialized;
+    static setExtensionRoot(extensionRootPath: string): void;
+    static getExtensionRoot(): string | null;
+    constructor(options?: PathResolverOptions);
+    private log;
+    private detectWorkspaceDir;
+    private normalizePath;
+    normalizeWorkspacePath(inputPath: string): string;
+    getWorkspaceDir(): string;
+    getStateDir(): string;
+    resolve(key: string): string;
+    ensureStateDir(): void;
+    static createFromHookContext(ctx: Record<string, unknown>): PathResolver;
+}
+export declare function createDefaultConfig(targetPath?: string): string;
+/**
+ * Resolve workspace directory via OpenClaw's official API.
+ *
+ * Replaces the removed `api.workspaceDir` field.
+ *
+ * Priority: api.runtime.agent.resolveAgentWorkspaceDir(agentId)
+ *           → PathResolver.getWorkspaceDir() (PD env vars, config file, default)
+ *
+ * @param api - Plugin API instance
+ * @param agentId - Agent ID (defaults to 'main' if not provided)
+ * @returns Resolved workspace directory, or `undefined` if all resolution paths fail
+ */
+export declare function resolveWorkspaceDirFromApi(api: OpenClawPluginApi | undefined, agentId?: string): string | undefined;

package/plugin/dist/core/path-resolver.js

@@ -0,0 +1,359 @@
+import * as path from 'path';
+import * as os from 'os';
+import * as fs from 'fs';
+import { PathResolutionError } from '../config/index.js';
+import { atomicWriteFileSync } from '../utils/io.js';
+const DEFAULT_WORKSPACE_SUBPATH = '.openclaw/workspace';
+export const PD_ENV_VARS = {
+    WORKSPACE_DIR: 'PD_WORKSPACE_DIR',
+    STATE_DIR: 'PD_STATE_DIR',
+    DEBUG: 'DEBUG',
+};
+export const PD_ENV_DESCRIPTIONS = {
+    WORKSPACE_DIR: {
+        desc: 'Override the default workspace directory',
+        example: 'PD_WORKSPACE_DIR=/home/user/my-workspace',
+    },
+    STATE_DIR: {
+        desc: 'Override the default state directory (.state)',
+        example: 'PD_STATE_DIR=/home/user/my-workspace/.state',
+    },
+    DEBUG: {
+        desc: 'Enable debug logging for path resolution',
+        example: 'DEBUG=true',
+    },
+};
+export function printEnvVarHelp() {
+    console.log('\n📁 Principles Disciple - Environment Variables\n');
+    console.log('You can customize directory paths using environment variables:\n');
+    for (const [key, varName] of Object.entries(PD_ENV_VARS)) {
+        const info = PD_ENV_DESCRIPTIONS[key];
+        console.log(`  ${varName}`);
+        console.log(`    Description: ${info.desc}`);
+        console.log(`    Example: ${info.example}`);
+        console.log();
+    }
+    console.log('💡 Tips:');
+    console.log('  - These can be set in your shell profile (~/.bashrc, ~/.zshrc)');
+    console.log('  - Or passed when starting OpenClaw gateway');
+    console.log('  - Example: PD_WORKSPACE_DIR=/custom/path openclaw-gateway start\n');
+}
+const PD_CONFIG_FILE = 'principles-disciple.json';
+const PD_CONFIG_LOCATIONS = [
+    path.join(process.cwd(), PD_CONFIG_FILE),
+    path.join(os.homedir(), '.openclaw', PD_CONFIG_FILE),
+    path.join(os.homedir(), '.principles', PD_CONFIG_FILE),
+];
+function isWindowsPath(inputPath) {
+    return /^[A-Za-z]:[\\/]/.test(inputPath) || inputPath.startsWith('\\\\');
+}
+function isPosixAbsolutePath(inputPath) {
+    return inputPath.startsWith('/');
+}
+function getPathApi(inputPath) {
+    if (isWindowsPath(inputPath)) {
+        return path.win32;
+    }
+    if (isPosixAbsolutePath(inputPath)) {
+        return path.posix;
+    }
+    return path;
+}
+function findConfigFile() {
+    for (const loc of PD_CONFIG_LOCATIONS) {
+        if (fs.existsSync(loc)) {
+            return loc;
+        }
+    }
+    return null;
+}
+function loadConfigFromFile() {
+    const configPath = findConfigFile();
+    if (!configPath) {
+        return null;
+    }
+    try {
+        const content = fs.readFileSync(configPath, 'utf8');
+        const config = JSON.parse(content);
+        console.log(`[PD:PathResolver] Loaded config from: ${configPath}`);
+        return config;
+    }
+    catch (e) {
+        console.warn(`[PD:PathResolver] Failed to load config from ${configPath}: ${String(e)}`);
+        return null;
+    }
+}
+export class PathResolver {
+    static extensionRoot = null;
+    workspaceDir = null;
+    stateDir = null;
+    logger;
+    normalizeWorkspace;
+    initialized = false;
+    static setExtensionRoot(extensionRootPath) {
+        if (!extensionRootPath || !extensionRootPath.trim()) {
+            return;
+        }
+        const trimmed = extensionRootPath.trim();
+        const pathApi = getPathApi(trimmed);
+        PathResolver.extensionRoot = pathApi.normalize(trimmed);
+    }
+    static getExtensionRoot() {
+        return PathResolver.extensionRoot;
+    }
+    constructor(options = {}) {
+        this.logger = options.logger;
+        this.normalizeWorkspace = options.normalizeWorkspace ?? true;
+        if (options.workspaceDir) {
+            const original = options.workspaceDir;
+            const normalized = this.normalizeWorkspace ? this.normalizePath(original) : original;
+            if (original !== normalized) {
+                this.log('info', `Workspace path normalized: ${original} -> ${normalized}`);
+            }
+            this.workspaceDir = normalized;
+            this.initialized = true;
+        }
+    }
+    log(level, msg) {
+        const prefix = '[PD:PathResolver]';
+        const fullMsg = `${prefix} ${msg}`;
+        if (process.env.DEBUG === 'true') {
+            this.logger?.debug?.(fullMsg);
+        }
+        switch (level) {
+            case 'debug':
+                this.logger?.debug?.(fullMsg);
+                break;
+            case 'info':
+                this.logger?.info?.(fullMsg);
+                break;
+            case 'warn':
+                this.logger?.warn?.(fullMsg);
+                break;
+            case 'error':
+                this.logger?.error?.(fullMsg);
+                break;
+        }
+    }
+    detectWorkspaceDir() {
+        const envWorkspace = process.env.PD_WORKSPACE_DIR;
+        if (envWorkspace && envWorkspace.trim()) {
+            this.log('info', `Using workspace from PD_WORKSPACE_DIR: ${envWorkspace}`);
+            return envWorkspace.trim();
+        }
+        const envOpenclaw = process.env.OPENCLAW_WORKSPACE;
+        if (envOpenclaw && envOpenclaw.trim()) {
+            this.log('info', `Using workspace from OPENCLAW_WORKSPACE: ${envOpenclaw}`);
+            return envOpenclaw.trim();
+        }
+        const fileConfig = loadConfigFromFile();
+        if (fileConfig?.workspace) {
+            this.log('info', `Using workspace from config file: ${fileConfig.workspace}`);
+            return fileConfig.workspace;
+        }
+        const homeDir = os.homedir();
+        const defaultWorkspace = path.join(homeDir, DEFAULT_WORKSPACE_SUBPATH);
+        this.log('info', `Using default workspace: ${defaultWorkspace}`);
+        return defaultWorkspace;
+    }
+    normalizePath(inputPath) {
+        const pathApi = getPathApi(inputPath);
+        let normalized = pathApi === path ? path.resolve(inputPath) : pathApi.normalize(inputPath);
+        if (this.normalizeWorkspace) {
+            const problematicSuffixes = ['/memory', '/docs', '\\memory', '\\docs'];
+            for (const suffix of problematicSuffixes) {
+                if (normalized.endsWith(suffix)) {
+                    const parent = pathApi.dirname(normalized);
+                    this.log('warn', `Detected subdirectory suffix '${suffix}' in path. Normalized to parent: ${parent}`);
+                    normalized = parent;
+                    break;
+                }
+            }
+        }
+        return normalized;
+    }
+    normalizeWorkspacePath(inputPath) {
+        return this.normalizePath(inputPath);
+    }
+    getWorkspaceDir() {
+        if (this.initialized && this.workspaceDir) {
+            return this.workspaceDir;
+        }
+        let dir = this.detectWorkspaceDir();
+        if (this.normalizeWorkspace) {
+            const originalDir = dir;
+            dir = this.normalizePath(dir);
+            if (originalDir !== dir) {
+                this.log('info', `Workspace path normalized: ${originalDir} -> ${dir}`);
+            }
+        }
+        this.workspaceDir = dir;
+        this.initialized = true;
+        this.log('debug', `Final workspace directory: ${this.workspaceDir}`);
+        return this.workspaceDir;
+    }
+    getStateDir() {
+        if (this.stateDir) {
+            return this.stateDir;
+        }
+        const envStateDir = process.env.PD_STATE_DIR;
+        if (envStateDir && envStateDir.trim()) {
+            this.stateDir = envStateDir.trim();
+            this.log('info', `Using state directory from PD_STATE_DIR: ${this.stateDir}`);
+            return this.stateDir;
+        }
+        // If workspaceDir was explicitly provided via constructor, use workspace-based state dir
+        // This ensures tests and programmatic usage don't get polluted by global config
+        if (this.initialized && this.workspaceDir) {
+            const pathApi = getPathApi(this.workspaceDir);
+            this.stateDir = pathApi.join(this.workspaceDir, '.state');
+            this.log('debug', `Using workspace-based state directory: ${this.stateDir}`);
+            return this.stateDir;
+        }
+        const fileConfig = loadConfigFromFile();
+        if (fileConfig?.state) {
+            this.stateDir = fileConfig.state;
+            this.log('info', `Using state directory from config file: ${this.stateDir}`);
+            return this.stateDir;
+        }
+        const workspaceDir = this.getWorkspaceDir();
+        const pathApi = getPathApi(workspaceDir);
+        this.stateDir = pathApi.join(workspaceDir, '.state');
+        this.log('debug', `Computed state directory: ${this.stateDir}`);
+        return this.stateDir;
+    }
+    resolve(key) {
+        const workspace = this.getWorkspaceDir();
+        const state = this.getStateDir();
+        const workspacePath = getPathApi(workspace);
+        const extensionRoot = PathResolver.extensionRoot || path.resolve(process.cwd(), 'packages', 'openclaw-plugin');
+        const extensionPath = getPathApi(extensionRoot);
+        const memory = workspacePath.join(workspace, 'memory');
+        const extensionSrc = extensionPath.join(extensionRoot, 'src');
+        const extensionDist = extensionPath.join(extensionRoot, 'dist');
+        const evolutionWorker = fs.existsSync(extensionSrc)
+            ? extensionPath.join(extensionSrc, 'service', 'evolution-worker.ts')
+            : extensionPath.join(extensionDist, 'service', 'evolution-worker.js');
+        const pathMap = {
+            'PROFILE': workspacePath.join(workspace, '.principles', 'PROFILE.json'),
+            'PRINCIPLES': workspacePath.join(workspace, '.principles', 'PRINCIPLES.md'),
+            'THINKING_OS': workspacePath.join(workspace, '.principles', 'THINKING_OS.md'),
+            'DECISION_POLICY': workspacePath.join(workspace, '.principles', 'DECISION_POLICY.json'),
+            'MODELS_DIR': workspacePath.join(workspace, '.principles', 'models'),
+            'PLAN': workspacePath.join(workspace, 'PLAN.md'),
+            'AGENT_SCORECARD': workspacePath.join(state, 'AGENT_SCORECARD.json'),
+            'PAIN_FLAG': workspacePath.join(state, '.pain_flag'),
+            'EVOLUTION_QUEUE': workspacePath.join(state, 'evolution_queue.json'),
+            'EVOLUTION_DIRECTIVE': workspacePath.join(state, 'evolution_directive.json'),
+            'WORKBOARD': workspacePath.join(state, 'WORKBOARD.json'),
+            'SYSTEM_CAPABILITIES': workspacePath.join(state, 'SYSTEM_CAPABILITIES.json'),
+            'PAIN_SETTINGS': workspacePath.join(state, 'pain_settings.json'),
+            'PAIN_CANDIDATES': workspacePath.join(state, 'pain_candidates.json'),
+            'THINKING_OS_USAGE': workspacePath.join(state, 'thinking_os_usage.json'),
+            'DICTIONARY': workspacePath.join(state, 'pain_dictionary.json'),
+            'STATE_DIR': state,
+            'EXTENSION_ROOT': extensionRoot,
+            'EXTENSION_SRC': extensionSrc,
+            'EXTENSION_DIST': extensionDist,
+            'EVOLUTION_WORKER': evolutionWorker,
+            'LOGS': workspacePath.join(memory, 'logs'),
+            'SYSTEM_LOG': workspacePath.join(memory, 'logs', 'SYSTEM.log'),
+            'REFLECTION_LOG': workspacePath.join(memory, 'reflection-log.md'),
+            'USER_CONTEXT': workspacePath.join(memory, 'USER_CONTEXT.md'),
+            'OKR_DIR': workspacePath.join(memory, 'okr'),
+            'CURRENT_FOCUS': workspacePath.join(memory, 'okr', 'CURRENT_FOCUS.md'),
+            'WEEK_STATE': workspacePath.join(memory, 'okr', 'WEEK_STATE.json'),
+            'THINKING_OS_CANDIDATES': workspacePath.join(memory, 'THINKING_OS_CANDIDATES.md'),
+            'EVOLUTION_STREAM': workspacePath.join(memory, 'evolution.jsonl'),
+            'EVOLUTION_LOCK': workspacePath.join(memory, '.locks', 'evolution'),
+            'PRINCIPLE_BLACKLIST': workspacePath.join(state, 'principle_blacklist.json'),
+            'MEMORY': memory,
+        };
+        const resolved = pathMap[key];
+        if (!resolved) {
+            this.log('warn', `Unknown path key: ${key}`);
+            throw new PathResolutionError(key);
+        }
+        this.log('debug', `Resolved path for '${key}': ${resolved}`);
+        return resolved;
+    }
+    ensureStateDir() {
+        const stateDir = this.getStateDir();
+        if (!fs.existsSync(stateDir)) {
+            this.log('info', `Creating state directory: ${stateDir}`);
+            fs.mkdirSync(stateDir, { recursive: true });
+        }
+    }
+    static createFromHookContext(ctx) {
+        const resolver = new PathResolver();
+        if (ctx?.workspaceDir) {
+            let workspaceDir = String(ctx.workspaceDir);
+            if (resolver.normalizeWorkspace) {
+                workspaceDir = resolver.normalizePath(workspaceDir);
+            }
+            resolver.workspaceDir = workspaceDir;
+            resolver.initialized = true;
+            resolver.log('info', `Created from hook context with workspace: ${workspaceDir}`);
+        }
+        if (ctx?.stateDir) {
+            resolver.stateDir = String(ctx.stateDir);
+        }
+        return resolver;
+    }
+}
+export function createDefaultConfig(targetPath) {
+    const defaultConfig = {
+        workspace: path.join(os.homedir(), '.openclaw', 'workspace'),
+        state: path.join(os.homedir(), '.openclaw', 'workspace', '.state'),
+        debug: false,
+    };
+    const target = targetPath || path.join(os.homedir(), '.openclaw', PD_CONFIG_FILE);
+    const dir = path.dirname(target);
+    if (!fs.existsSync(dir)) {
+        fs.mkdirSync(dir, { recursive: true });
+    }
+    atomicWriteFileSync(target, JSON.stringify(defaultConfig, null, 2));
+    console.log(`✅ Created default config at: ${target}`);
+    console.log(`   You can edit this file to customize paths.`);
+    return target;
+}
+// ── OpenClaw API Workspace Resolution ────────────────────────────
+/**
+ * Resolve workspace directory via OpenClaw's official API.
+ *
+ * Replaces the removed `api.workspaceDir` field.
+ *
+ * Priority: api.runtime.agent.resolveAgentWorkspaceDir(agentId)
+ *           → PathResolver.getWorkspaceDir() (PD env vars, config file, default)
+ *
+ * @param api - Plugin API instance
+ * @param agentId - Agent ID (defaults to 'main' if not provided)
+ * @returns Resolved workspace directory, or `undefined` if all resolution paths fail
+ */
+export function resolveWorkspaceDirFromApi(api, agentId) {
+    if (!api)
+        return undefined;
+    // 1. Official API: api.runtime.agent.resolveAgentWorkspaceDir
+    const officialAgent = api.runtime.agent;
+    if (officialAgent?.resolveAgentWorkspaceDir) {
+        try {
+            return officialAgent.resolveAgentWorkspaceDir(api.config, agentId ?? 'main');
+        }
+        catch {
+            // Fall through to config check
+        }
+    }
+    // 2. Direct config workspaceDir (for tests and programmatic usage)
+    const cfgWorkspaceDir = api.config?.workspaceDir;
+    if (cfgWorkspaceDir && cfgWorkspaceDir.trim()) {
+        return cfgWorkspaceDir.trim();
+    }
+    // 3. Fallback: PathResolver (PD_WORKSPACE_DIR env, config file, default)
+    try {
+        const pr = new PathResolver();
+        return pr.getWorkspaceDir();
+    }
+    catch {
+        return undefined;
+    }
+}