@useorgx/openclaw-plugin 0.7.0 → 0.7.3

package/dist/contracts/practice-exercise-schema.js

@@ -0,0 +1,314 @@
+export const PRACTICE_EXERCISE_TEMPLATE_SCHEMA_VERSION = "practice-exercise-template.v1";
+function isRecord(value) {
+    return Boolean(value && typeof value === "object" && !Array.isArray(value));
+}
+function readString(source, key, errors, opts = {}) {
+    const { required = true } = opts;
+    const value = source[key];
+    if (typeof value !== "string") {
+        if (required)
+            errors.push(`${key} must be a string`);
+        return "";
+    }
+    const normalized = value.trim();
+    if (!normalized && required) {
+        errors.push(`${key} must not be empty`);
+    }
+    return normalized;
+}
+function readStringArray(source, key, errors, opts = {}) {
+    const { required = true, minItems = 0 } = opts;
+    const value = source[key];
+    if (!Array.isArray(value)) {
+        if (required)
+            errors.push(`${key} must be an array`);
+        return [];
+    }
+    const output = [];
+    value.forEach((entry, index) => {
+        if (typeof entry !== "string" || !entry.trim()) {
+            errors.push(`${key}[${index}] must be a non-empty string`);
+            return;
+        }
+        output.push(entry.trim());
+    });
+    if (output.length < minItems) {
+        errors.push(`${key} must include at least ${minItems} item(s)`);
+    }
+    return output;
+}
+const TASK_TYPE_SET = new Set([
+    "analysis",
+    "implementation",
+    "review",
+    "debugging",
+    "planning",
+]);
+const CONSTRAINT_SEVERITY_SET = new Set(["hard", "soft"]);
+const OUTPUT_FORMAT_SET = new Set(["json_object", "markdown", "text"]);
+function parseScenario(raw, index, errors) {
+    if (!isRecord(raw)) {
+        errors.push(`scenarios[${index}] must be an object`);
+        return null;
+    }
+    const id = readString(raw, "id", errors);
+    const title = readString(raw, "title", errors);
+    const input = raw.input;
+    if (!isRecord(input)) {
+        errors.push(`scenarios[${index}].input must be an object`);
+    }
+    const contextRaw = raw.context;
+    const context = typeof contextRaw === "string" && contextRaw.trim() ? contextRaw.trim() : undefined;
+    const successCriteria = readStringArray(raw, "success_criteria", errors, {
+        minItems: 1,
+    });
+    if (!isRecord(input))
+        return null;
+    return {
+        id,
+        title,
+        input,
+        context,
+        success_criteria: successCriteria,
+    };
+}
+function parseConstraint(raw, index, errors) {
+    if (!isRecord(raw)) {
+        errors.push(`constraints[${index}] must be an object`);
+        return null;
+    }
+    const id = readString(raw, "id", errors);
+    const title = readString(raw, "title", errors);
+    const description = readString(raw, "description", errors);
+    const severityRaw = readString(raw, "severity", errors);
+    if (!CONSTRAINT_SEVERITY_SET.has(severityRaw)) {
+        errors.push(`constraints[${index}].severity must be one of: hard, soft`);
+    }
+    const rationaleRaw = raw.rationale;
+    const rationale = typeof rationaleRaw === "string" && rationaleRaw.trim() ? rationaleRaw.trim() : undefined;
+    return {
+        id,
+        title,
+        description,
+        severity: severityRaw,
+        rationale,
+    };
+}
+function parseExpectedOutputShape(raw, errors) {
+    if (!isRecord(raw)) {
+        errors.push("expected_output_shape must be an object");
+        return null;
+    }
+    const format = readString(raw, "format", errors);
+    if (!OUTPUT_FORMAT_SET.has(format)) {
+        errors.push("expected_output_shape.format must be one of: json_object, markdown, text");
+    }
+    const fieldsRaw = raw.fields;
+    if (!Array.isArray(fieldsRaw)) {
+        errors.push("expected_output_shape.fields must be an array");
+        return null;
+    }
+    const fields = [];
+    fieldsRaw.forEach((entry, index) => {
+        if (!isRecord(entry)) {
+            errors.push(`expected_output_shape.fields[${index}] must be an object`);
+            return;
+        }
+        const path = readString(entry, "path", errors);
+        const type = readString(entry, "type", errors);
+        const required = entry.required;
+        if (typeof required !== "boolean") {
+            errors.push(`expected_output_shape.fields[${index}].required must be boolean`);
+            return;
+        }
+        const description = readString(entry, "description", errors);
+        fields.push({ path, type, required, description });
+    });
+    if (fields.length === 0) {
+        errors.push("expected_output_shape.fields must include at least 1 field");
+    }
+    const exampleRaw = raw.example;
+    const example = typeof exampleRaw === "string"
+        ? exampleRaw
+        : isRecord(exampleRaw)
+            ? exampleRaw
+            : undefined;
+    if (typeof exampleRaw !== "undefined" &&
+        typeof exampleRaw !== "string" &&
+        !isRecord(exampleRaw)) {
+        errors.push("expected_output_shape.example must be a string or object");
+    }
+    return {
+        format: format,
+        fields,
+        example,
+    };
+}
+export function validatePracticeExerciseTemplate(input) {
+    if (!isRecord(input)) {
+        return {
+            ok: false,
+            errors: ["template must be an object"],
+            template: null,
+        };
+    }
+    const errors = [];
+    const schemaVersion = readString(input, "schema_version", errors);
+    if (schemaVersion !== PRACTICE_EXERCISE_TEMPLATE_SCHEMA_VERSION) {
+        errors.push(`schema_version must equal "${PRACTICE_EXERCISE_TEMPLATE_SCHEMA_VERSION}"`);
+    }
+    const id = readString(input, "id", errors);
+    const title = readString(input, "title", errors);
+    const summary = readString(input, "summary", errors);
+    const taskType = readString(input, "task_type", errors);
+    if (!TASK_TYPE_SET.has(taskType)) {
+        errors.push("task_type must be one of: analysis, implementation, review, debugging, planning");
+    }
+    const scenariosRaw = input.scenarios;
+    const scenarios = [];
+    if (!Array.isArray(scenariosRaw)) {
+        errors.push("scenarios must be an array");
+    }
+    else {
+        scenariosRaw.forEach((entry, index) => {
+            const parsed = parseScenario(entry, index, errors);
+            if (parsed)
+                scenarios.push(parsed);
+        });
+    }
+    if (scenarios.length === 0) {
+        errors.push("scenarios must include at least 1 scenario");
+    }
+    const constraintsRaw = input.constraints;
+    const constraints = [];
+    if (!Array.isArray(constraintsRaw)) {
+        errors.push("constraints must be an array");
+    }
+    else {
+        constraintsRaw.forEach((entry, index) => {
+            const parsed = parseConstraint(entry, index, errors);
+            if (parsed)
+                constraints.push(parsed);
+        });
+    }
+    const expectedOutputShape = parseExpectedOutputShape(input.expected_output_shape, errors);
+    const tags = readStringArray(input, "tags", errors, { required: false });
+    const template = errors.length === 0 && expectedOutputShape
+        ? {
+            schema_version: PRACTICE_EXERCISE_TEMPLATE_SCHEMA_VERSION,
+            id,
+            title,
+            summary,
+            task_type: taskType,
+            scenarios,
+            constraints,
+            expected_output_shape: expectedOutputShape,
+            tags: tags.length > 0 ? tags : undefined,
+        }
+        : null;
+    return { ok: errors.length === 0, errors, template };
+}
+export const PRACTICE_EXERCISE_TEMPLATE_JSON_SCHEMA = {
+    $schema: "https://json-schema.org/draft/2020-12/schema",
+    $id: "https://schemas.useorgx.com/practice-exercise-template/v1.json",
+    title: "OrgX Practice Exercise Template v1",
+    description: "Structured exercise template for practice loops with scenarios, constraints, and expected output shape.",
+    type: "object",
+    additionalProperties: false,
+    required: [
+        "schema_version",
+        "id",
+        "title",
+        "summary",
+        "task_type",
+        "scenarios",
+        "constraints",
+        "expected_output_shape",
+    ],
+    properties: {
+        schema_version: {
+            type: "string",
+            const: PRACTICE_EXERCISE_TEMPLATE_SCHEMA_VERSION,
+        },
+        id: { type: "string", minLength: 1, maxLength: 120 },
+        title: { type: "string", minLength: 1, maxLength: 300 },
+        summary: { type: "string", minLength: 1, maxLength: 3000 },
+        task_type: {
+            type: "string",
+            enum: ["analysis", "implementation", "review", "debugging", "planning"],
+        },
+        scenarios: {
+            type: "array",
+            minItems: 1,
+            maxItems: 25,
+            items: {
+                type: "object",
+                additionalProperties: false,
+                required: ["id", "title", "input", "success_criteria"],
+                properties: {
+                    id: { type: "string", minLength: 1, maxLength: 120 },
+                    title: { type: "string", minLength: 1, maxLength: 300 },
+                    input: { type: "object", additionalProperties: true },
+                    context: { type: "string", minLength: 1, maxLength: 4000 },
+                    success_criteria: {
+                        type: "array",
+                        minItems: 1,
+                        maxItems: 20,
+                        items: { type: "string", minLength: 1, maxLength: 1000 },
+                    },
+                },
+            },
+        },
+        constraints: {
+            type: "array",
+            maxItems: 25,
+            items: {
+                type: "object",
+                additionalProperties: false,
+                required: ["id", "title", "description", "severity"],
+                properties: {
+                    id: { type: "string", minLength: 1, maxLength: 120 },
+                    title: { type: "string", minLength: 1, maxLength: 300 },
+                    description: { type: "string", minLength: 1, maxLength: 2000 },
+                    severity: { type: "string", enum: ["hard", "soft"] },
+                    rationale: { type: "string", minLength: 1, maxLength: 2000 },
+                },
+            },
+        },
+        expected_output_shape: {
+            type: "object",
+            additionalProperties: false,
+            required: ["format", "fields"],
+            properties: {
+                format: { type: "string", enum: ["json_object", "markdown", "text"] },
+                fields: {
+                    type: "array",
+                    minItems: 1,
+                    maxItems: 50,
+                    items: {
+                        type: "object",
+                        additionalProperties: false,
+                        required: ["path", "type", "required", "description"],
+                        properties: {
+                            path: { type: "string", minLength: 1, maxLength: 400 },
+                            type: { type: "string", minLength: 1, maxLength: 120 },
+                            required: { type: "boolean" },
+                            description: { type: "string", minLength: 1, maxLength: 2000 },
+                        },
+                    },
+                },
+                example: {
+                    oneOf: [
+                        { type: "string", minLength: 1, maxLength: 20000 },
+                        { type: "object", additionalProperties: true },
+                    ],
+                },
+            },
+        },
+        tags: {
+            type: "array",
+            maxItems: 30,
+            items: { type: "string", minLength: 1, maxLength: 80 },
+        },
+    },
+};

package/dist/contracts/shared-types.d.ts

@@ -47,7 +47,7 @@ export type LiveActivityType = 'run_started' | 'run_completed' | 'run_failed' |
  * Keep in sync with emitters in auto-continue-engine.ts, autopilot-operations.ts,
  * dispatch-lifecycle.ts, and http/index.ts.
  */
-export type ActivityEventName = 'autopilot_slice_dispatched' | 'autopilot_slice_started' | 'autopilot_slice_heartbeat' | 'autopilot_slice_finished' | 'autopilot_slice_result' | 'autopilot_slice_handoff' | 'autopilot_slice_mcp_handshake_failed' | 'autopilot_slice_timeout' | 'autopilot_slice_log_stall' | 'autopilot_slice_artifact_buffered' | 'autopilot_slice_status_updates_buffered' | 'auto_continue_started' | 'auto_continue_stopped' | 'auto_continue_spawn_guard_blocked' | 'auto_continue_spawn_guard_rate_limited' | 'auto_continue_spawn_guard_rate_limit_overridden' | 'auto_continue_behavior_config_drift_detected' | 'auto_continue_behavior_config_approval_required' | 'auto_continue_behavior_automation_manual_blocked' | 'auto_continue_behavior_automation_supervised_one_shot' | 'autopilot_autofix_scheduled' | 'autopilot_autofix_executed' | 'autopilot_autofix_skipped' | 'orchestrator_dispatch' | 'autopilot_transition' | 'next_up_manual_dispatch_started' | 'scope_completed' | 'session_start' | 'session_stop' | 'heartbeat' | 'decision_buffered' | 'decision_resolved' | 'spawn_guard_degraded' | 'dashboard_run_mark_completed' | 'proof_gate_warning' | 'artifact_registered';
+export type ActivityEventName = 'autopilot_slice_dispatched' | 'autopilot_slice_started' | 'autopilot_slice_heartbeat' | 'autopilot_slice_finished' | 'autopilot_slice_result' | 'autopilot_slice_handoff' | 'autopilot_slice_mcp_handshake_failed' | 'autopilot_slice_timeout' | 'autopilot_slice_log_stall' | 'autopilot_slice_artifact_buffered' | 'autopilot_slice_status_updates_buffered' | 'auto_continue_started' | 'auto_continue_stopped' | 'auto_continue_spawn_guard_blocked' | 'auto_continue_spawn_guard_rate_limited' | 'auto_continue_spawn_guard_rate_limit_overridden' | 'auto_continue_behavior_config_drift_detected' | 'auto_continue_behavior_config_approval_required' | 'auto_continue_behavior_automation_manual_blocked' | 'auto_continue_behavior_automation_supervised_one_shot' | 'autopilot_autofix_scheduled' | 'autopilot_autofix_executed' | 'autopilot_autofix_skipped' | 'orchestrator_dispatch' | 'autopilot_transition' | 'next_up_manual_dispatch_started' | 'scope_completed' | 'session_start' | 'session_stop' | 'heartbeat' | 'decision_buffered' | 'decision_resolved' | 'question_asked' | 'question_timeout_started' | 'question_auto_answered' | 'question_answer_applied' | 'question_answer_failed' | 'review_item_created' | 'review_item_resolved' | 'decision_auto_answer_scheduled' | 'decision_auto_answer_timeout' | 'decision_auto_answer_applied' | 'decision_auto_answer_skipped' | 'spawn_guard_degraded' | 'dashboard_run_mark_completed' | 'proof_gate_warning' | 'artifact_registered';
 export interface LiveActivityItem {
     id: string;
     type: LiveActivityType;
@@ -75,7 +75,7 @@ export interface LiveActivityItem {
     lastHeartbeatAt?: string | null;
     metadata?: Record<string, unknown>;
 }
-export declare const KNOWN_ACTIVITY_ACTION_TYPES: readonly ["orchestrator_dispatch", "dispatch_slice", "spawn_worker", "run_heartbeat", "run_state_transition", "run_started", "run_completed", "run_failed", "slice_handoff", "decision_requested", "decision_resolved", "status_updates_applied", "status_updates_buffered", "artifact_registered", "spawn_guard_blocked", "spawn_guard_rate_limited", "behavior_config_review", "auto_fix", "auto_continue_started", "auto_continue_stopped", "milestone_completed", "workflow_error"];
+export declare const KNOWN_ACTIVITY_ACTION_TYPES: readonly ["orchestrator_dispatch", "dispatch_slice", "spawn_worker", "run_heartbeat", "run_state_transition", "run_started", "run_completed", "run_failed", "slice_handoff", "question_asked", "question_timeout_started", "question_auto_answered", "question_answer_applied", "question_answer_failed", "decision_requested", "decision_resolved", "review_item_created", "review_item_resolved", "status_updates_applied", "status_updates_buffered", "artifact_registered", "spawn_guard_blocked", "spawn_guard_rate_limited", "behavior_config_review", "auto_fix", "auto_continue_started", "auto_continue_stopped", "autopilot_resumed", "autopilot_paused", "autopilot_blocked", "milestone_completed", "workflow_error"];
 export type KnownActivityActionType = (typeof KNOWN_ACTIVITY_ACTION_TYPES)[number];
 export type ActivityActionType = KnownActivityActionType | (string & {});
 export declare const KNOWN_ACTIVITY_ACTION_PHASES: readonly ["intent", "dispatch", "execution", "handoff", "review", "completed", "blocked", "error"];

package/dist/contracts/shared-types.js

@@ -10,8 +10,15 @@ export const KNOWN_ACTIVITY_ACTION_TYPES = [
     "run_completed",
     "run_failed",
     "slice_handoff",
+    "question_asked",
+    "question_timeout_started",
+    "question_auto_answered",
+    "question_answer_applied",
+    "question_answer_failed",
     "decision_requested",
     "decision_resolved",
+    "review_item_created",
+    "review_item_resolved",
     "status_updates_applied",
     "status_updates_buffered",
     "artifact_registered",
@@ -21,6 +28,9 @@ export const KNOWN_ACTIVITY_ACTION_TYPES = [
     "auto_fix",
     "auto_continue_started",
     "auto_continue_stopped",
+    "autopilot_resumed",
+    "autopilot_paused",
+    "autopilot_blocked",
     "milestone_completed",
     "workflow_error",
 ];
@@ -38,10 +48,22 @@ const ACTIVITY_ACTION_TYPE_ALIASES = {
     orchestrator: "orchestrator_dispatch",
     dispatch: "dispatch_slice",
     dispatched: "dispatch_slice",
+    question: "question_asked",
+    question_timeout: "question_timeout_started",
+    question_auto_answer: "question_auto_answered",
+    decision_auto_answer: "question_auto_answered",
+    decision_auto_answer_applied: "question_answer_applied",
+    decision_auto_answer_failed: "question_answer_failed",
+    decision_auto_answer_skipped: "review_item_created",
     start: "run_started",
     started: "run_started",
     stop: "auto_continue_stopped",
     stopped: "auto_continue_stopped",
+    pause: "autopilot_paused",
+    paused: "autopilot_paused",
+    resume: "autopilot_resumed",
+    resumed: "autopilot_resumed",
+    blocked: "autopilot_blocked",
     complete: "run_completed",
     completed: "run_completed",
     fail: "run_failed",

package/dist/contracts/types.d.ts

@@ -88,6 +88,19 @@ export interface KickoffContext {
         decision_dedupe_enabled?: boolean;
         decision_evidence_required_for_blocking?: boolean;
         decision_auto_resolve_guarded_enabled?: boolean;
+        question_auto_answer_enabled?: boolean;
+        question_auto_answer_timeout_sec?: number;
+        question_auto_answer_policy?: "contextual" | "approve_non_blocking" | "defer_non_blocking";
+        question_blocking_behavior?: "require_human" | "guarded_auto_resolve_then_human";
+        question_policy_version?: number;
+        question_auto_answer_delay_seconds?: number;
+        question_auto_answer_action?: "approve" | "reject";
+        workspace_question_defaults?: {
+            question_auto_answer_enabled?: boolean;
+            question_auto_answer_timeout_sec?: number;
+            question_auto_answer_policy?: "contextual" | "approve_non_blocking" | "defer_non_blocking";
+            question_blocking_behavior?: "require_human" | "guarded_auto_resolve_then_human";
+        } | null;
         custom_run_instructions?: string | null;
     } | null;
     /** Recent team activity for cross-agent awareness. */
@@ -154,6 +167,13 @@ export interface AgentRuntimeSettingsPayload {
     decision_dedupe_enabled?: boolean;
     decision_evidence_required_for_blocking?: boolean;
     decision_auto_resolve_guarded_enabled?: boolean;
+    question_auto_answer_enabled?: boolean;
+    question_auto_answer_timeout_sec?: number;
+    question_auto_answer_policy?: "contextual" | "approve_non_blocking" | "defer_non_blocking";
+    question_blocking_behavior?: "require_human" | "guarded_auto_resolve_then_human";
+    question_policy_version?: number;
+    question_auto_answer_delay_seconds?: number;
+    question_auto_answer_action?: "approve" | "reject";
     custom_run_instructions?: string | null;
 }
 export interface ClientRuntimeSettingsAgent {

package/dist/fs-utils.js

@@ -1,14 +1,5 @@
 import { chmodSync, renameSync, unlinkSync, writeFileSync } from "node:fs";
 import { randomUUID } from "node:crypto";
-function isSafeFilePath(path) {
-    if (!path)
-        return false;
-    if (/[\u0000-\u001f\u007f]/.test(path))
-        return false;
-    if (/\\0|\\x00|\\u0000|%00/i.test(path))
-        return false;
-    return true;
-}
 function hardenPath(path, mode) {
     try {
         chmodSync(path, mode);
@@ -18,7 +9,7 @@ function hardenPath(path, mode) {
     }
 }
 export function backupCorruptFileSync(targetPath) {
-    if (!isSafeFilePath(targetPath))
+    if (!targetPath || targetPath.includes("\0"))
         return null;
     const suffix = `${Date.now()}-${randomUUID().slice(0, 8)}`;
     const backupPath = `${targetPath}.corrupt.${suffix}`;
@@ -32,9 +23,6 @@ export function backupCorruptFileSync(targetPath) {
     }
 }
 export function writeFileAtomicSync(targetPath, content, options) {
-    if (!isSafeFilePath(targetPath)) {
-        throw new TypeError("targetPath must be a safe, non-empty file path");
-    }
     const mode = options?.mode ?? 0o600;
     const encoding = options?.encoding ?? "utf8";
     const tmpPath = `${targetPath}.tmp.${process.pid}.${randomUUID().slice(0, 8)}`;