@useorgx/openclaw-plugin 0.4.5 → 0.4.6

package/dist/contracts/client.js

@@ -6,13 +6,43 @@
  *
  * Uses native fetch — no external dependencies.
  */
-const REQUEST_TIMEOUT_MS = 10_000;
+const DEFAULT_REQUEST_TIMEOUT_MS = 25_000;
+const DEFAULT_LIVE_TIMEOUT_MS = 30_000;
+const DEFAULT_SYNC_TIMEOUT_MS = 45_000;
 const USER_AGENT = "OrgX-Clawdbot-Plugin/1.0";
 const DECISION_MUTATION_CONCURRENCY = 6;
 const DEFAULT_CLIENT_BASE_URL = "https://www.useorgx.com";
 function isUserScopedApiKey(apiKey) {
     return apiKey.trim().toLowerCase().startsWith("oxk_");
 }
+function parseTimeoutMsEnv(name) {
+    const raw = process.env[name];
+    if (!raw)
+        return null;
+    const parsed = Number(raw);
+    if (!Number.isFinite(parsed))
+        return null;
+    // Keep it sane: timeouts below 1s tend to create pathological "offline" loops.
+    return Math.max(1_000, Math.floor(parsed));
+}
+function resolveRequestTimeoutMs(path) {
+    const configured = parseTimeoutMsEnv("ORGX_HTTP_TIMEOUT_MS") ??
+        parseTimeoutMsEnv("ORGX_API_TIMEOUT_MS");
+    const base = configured ?? DEFAULT_REQUEST_TIMEOUT_MS;
+    // Live endpoints frequently return larger payloads (sessions, activity, agents).
+    if (path.startsWith("/api/client/live/")) {
+        return Math.max(base, DEFAULT_LIVE_TIMEOUT_MS);
+    }
+    // Sync can include a full org snapshot and may take longer than typical CRUD.
+    if (path === "/api/client/sync") {
+        return Math.max(base, DEFAULT_SYNC_TIMEOUT_MS);
+    }
+    // Handoffs can require server-side aggregation.
+    if (path === "/api/client/handoffs") {
+        return Math.max(base, DEFAULT_LIVE_TIMEOUT_MS);
+    }
+    return base;
+}
 function normalizeHost(value) {
     return value.trim().toLowerCase().replace(/^\[|\]$/g, "");
 }
@@ -85,7 +115,8 @@ export class OrgXClient {
     async request(method, path, body) {
         const url = `${this.baseUrl}${path}`;
         const controller = new AbortController();
-        const timeout = setTimeout(() => controller.abort(), REQUEST_TIMEOUT_MS);
+        const timeoutMs = resolveRequestTimeoutMs(path);
+        const timeout = setTimeout(() => controller.abort(), timeoutMs);
         try {
             const headers = {
                 "Content-Type": "application/json",
@@ -124,7 +155,7 @@ export class OrgXClient {
         }
         catch (err) {
             if (err instanceof DOMException && err.name === "AbortError") {
-                throw new Error(`OrgX API ${method} ${path} timed out after ${REQUEST_TIMEOUT_MS}ms`);
+                throw new Error(`OrgX API ${method} ${path} timed out after ${timeoutMs}ms`);
             }
             throw err;
         }
@@ -194,6 +225,72 @@ export class OrgXClient {
         }
         return response;
     }
+    // ===========================================================================
+    // Kickoff Context
+    // ===========================================================================
+    async getKickoffContext(payload) {
+        return await this.post("/api/client/kickoff-context", payload ?? {});
+    }
+    // ===========================================================================
+    // Skill Packs (ETag-aware)
+    // ===========================================================================
+    async getSkillPack(input) {
+        const name = (input?.name ?? "").trim() || "orgx-agent-suite";
+        const url = `${this.baseUrl}/api/client/skill-pack?name=${encodeURIComponent(name)}`;
+        const controller = new AbortController();
+        const timeoutMs = resolveRequestTimeoutMs("/api/client/skill-pack");
+        const timeout = setTimeout(() => controller.abort(), timeoutMs);
+        try {
+            const headers = {
+                "Content-Type": "application/json",
+                "User-Agent": USER_AGENT,
+                Authorization: `Bearer ${this.apiKey}`,
+            };
+            if (this.userId && !isUserScopedApiKey(this.apiKey)) {
+                headers["X-Orgx-User-Id"] = this.userId;
+            }
+            const ifNoneMatch = (input?.ifNoneMatch ?? "").trim();
+            if (ifNoneMatch) {
+                headers["If-None-Match"] = ifNoneMatch;
+            }
+            const response = await fetch(url, {
+                method: "GET",
+                headers,
+                signal: controller.signal,
+            });
+            const etag = response.headers.get("etag");
+            if (response.status === 304) {
+                return { ok: true, notModified: true, etag, pack: null };
+            }
+            const contentType = response.headers.get("content-type") ?? "";
+            const payload = contentType.includes("application/json")
+                ? (await response.json().catch(() => null))
+                : null;
+            if (!response.ok) {
+                const detail = payload && typeof payload === "object" && "error" in payload && typeof payload.error === "string"
+                    ? payload.error
+                    : `${response.status} ${response.statusText}`;
+                return { ok: false, status: response.status, error: detail };
+            }
+            if (payload && typeof payload === "object" && payload.ok === true && payload.data) {
+                return { ok: true, notModified: false, etag, pack: payload.data };
+            }
+            return { ok: false, status: 502, error: "SkillPack response was invalid" };
+        }
+        catch (err) {
+            if (err instanceof DOMException && err.name === "AbortError") {
+                return {
+                    ok: false,
+                    status: 504,
+                    error: `OrgX API GET /api/client/skill-pack timed out after ${timeoutMs}ms`,
+                };
+            }
+            return { ok: false, status: 502, error: err instanceof Error ? err.message : "SkillPack request failed" };
+        }
+        finally {
+            clearTimeout(timeout);
+        }
+    }
     async delegationPreflight(payload) {
         return this.post("/api/client/delegation/preflight", payload);
     }
@@ -320,6 +417,26 @@ export class OrgXClient {
         }
         return response;
     }
+    async recordRunOutcome(payload) {
+        const response = await this.post("/api/client/live/runs/outcomes/record", payload);
+        if (response &&
+            typeof response === "object" &&
+            "data" in response &&
+            response.data) {
+            return response.data;
+        }
+        return response;
+    }
+    async recordRunRetro(payload) {
+        const response = await this.post("/api/client/live/runs/retro", payload);
+        if (response &&
+            typeof response === "object" &&
+            "data" in response &&
+            response.data) {
+            return response.data;
+        }
+        return response;
+    }
     // ===========================================================================
     // Live Sessions + Activity + Handoffs
     // ===========================================================================

package/dist/contracts/types.d.ts

@@ -15,6 +15,14 @@ export interface OrgXConfig {
     syncIntervalMs: number;
     /** Plugin enabled */
     enabled: boolean;
+    /**
+     * When true (default), provision/update the OrgX agent suite automatically
+     * after a successful connection/sync.
+     *
+     * Safe by default: provisioning uses managed/local overlays and skips files
+     * that appear to have out-of-band edits ("conflict").
+     */
+    autoInstallAgentSuiteOnConnect?: boolean;
 }
 export type OnboardingStatus = 'idle' | 'starting' | 'awaiting_browser_auth' | 'pairing' | 'connected' | 'error' | 'manual_key';
 export type OnboardingNextAction = 'connect' | 'wait_for_browser' | 'open_dashboard' | 'enter_manual_key' | 'retry' | 'reconnect';
@@ -45,6 +53,119 @@ export interface OrgSnapshot {
     /** Last sync timestamp */
     syncedAt: string;
 }
+export type KickoffContextScope = {
+    initiative_id?: string | null;
+    workstream_id?: string | null;
+    task_id?: string | null;
+};
+export type KickoffContextEntityRef = {
+    id: string;
+    title: string;
+    status?: string | null;
+    summary?: string | null;
+    url?: string | null;
+    metadata?: Record<string, unknown> | null;
+};
+export type KickoffContextToolScope = {
+    allow?: string[];
+    deny?: string[];
+    notes?: string | null;
+};
+export interface KickoffContext {
+    /** Deterministic hash of the payload used to render a kickoff message. */
+    context_hash: string;
+    /** Optional schema version for forward/back compat. */
+    schema_version?: string | null;
+    /** Human-friendly overview sentence(s). */
+    overview?: string | null;
+    initiative?: KickoffContextEntityRef | null;
+    workstream?: KickoffContextEntityRef | null;
+    task?: (KickoffContextEntityRef & {
+        description?: string | null;
+        checklist?: string[] | null;
+    }) | null;
+    acceptance_criteria?: string[] | null;
+    constraints?: string[] | null;
+    risks?: string[] | null;
+    decisions?: KickoffContextEntityRef[] | null;
+    artifacts?: KickoffContextEntityRef[] | null;
+    tool_scope?: KickoffContextToolScope | null;
+    reporting_expectations?: string[] | null;
+    /** Server-provided hints for agent tone/behavior; optional. */
+    persona?: {
+        voice?: string | null;
+        collaboration_style?: string | null;
+        defaults?: string[] | null;
+    } | null;
+}
+export type KickoffContextRequest = KickoffContextScope & {
+    agent_id?: string | null;
+    domain?: string | null;
+    required_skills?: string[] | null;
+    message?: string | null;
+};
+export type KickoffContextResponse = {
+    ok: true;
+    data: KickoffContext;
+} | {
+    ok: false;
+    error: string;
+};
+export type OrgxAgentDomain = "engineering" | "product" | "design" | "marketing" | "sales" | "operations" | "orchestration";
+/**
+ * AgentProfile describes the stable agent identity + workspace configuration
+ * needed to instantiate OrgX agents in OpenClaw.
+ *
+ * Note: this is a provisioning contract (what to install/configure), not an
+ * execution record (runs/sessions).
+ */
+export type OrgxAgentProfile = {
+    id: string;
+    name: string;
+    domain: OrgxAgentDomain;
+    workspace: string;
+    required_skills?: string[] | null;
+    tool_scope?: KickoffContextToolScope | null;
+    persona?: KickoffContext["persona"] | null;
+};
+export type OrgxAgentPack = {
+    pack_id: string;
+    pack_version: string;
+    schema_version?: string | null;
+    skill_pack?: {
+        name: string;
+        version: string;
+        checksum: string;
+    } | null;
+    agents: OrgxAgentProfile[];
+    managed_files: string[];
+};
+export type SkillPack = {
+    name: string;
+    version: string;
+    checksum: string;
+    status?: "draft" | "pending_review" | "approved" | "rejected" | string;
+    manifest: Record<string, unknown>;
+    required_scopes?: string[] | null;
+    required_tools?: string[] | null;
+    updated_at?: string | null;
+};
+/**
+ * Canonical manifest shape expected by the OpenClaw plugin.
+ *
+ * Stored in `skill_packs.manifest` on the OrgX server.
+ */
+export type OpenClawSkillPackManifestV1 = {
+    schema_version: string;
+    openclaw_skills: Partial<Record<OrgxAgentDomain, string>>;
+};
+export type SkillPackResponse = {
+    ok: true;
+    data: SkillPack;
+} | {
+    ok: false;
+    error: string;
+};
 export interface Initiative {
     id: string;
     title: string;
@@ -349,13 +470,81 @@ export interface ApplyChangesetResponse {
     event_id: string | null;
     auth_mode?: 'service' | 'api_key';
 }
+export interface RecordRunOutcomeRequest {
+    initiative_id: string;
+    execution_id: string;
+    execution_type: string;
+    agent_id: string;
+    task_type?: string;
+    domain?: string;
+    started_at?: string;
+    completed_at?: string;
+    inputs?: Record<string, unknown>;
+    outputs?: Record<string, unknown>;
+    steps?: Array<Record<string, unknown>>;
+    success: boolean;
+    quality_score?: number;
+    duration_vs_estimate?: number;
+    cost_vs_budget?: number;
+    human_interventions?: number;
+    user_satisfaction?: number;
+    errors?: string[];
+    metadata?: Record<string, unknown>;
+    run_id?: string;
+    correlation_id?: string;
+    source_client?: ReportingSourceClient;
+}
+export interface RecordRunOutcomeResponse {
+    ok: true;
+    run_id: string;
+    reused_run: boolean;
+    execution_id: string;
+    event_id: string | null;
+    auth_mode?: 'service' | 'api_key';
+}
+export type RetroFollowUpPriority = 'p0' | 'p1' | 'p2';
+export interface RetroJson {
+    summary: string;
+    what_went_well?: string[];
+    what_went_wrong?: string[];
+    decisions?: string[];
+    follow_ups?: Array<{
+        title: string;
+        priority?: RetroFollowUpPriority;
+        reason?: string;
+    }>;
+    signals?: Record<string, unknown>;
+}
+export type RetroEntityType = 'initiative' | 'workstream' | 'milestone' | 'task';
+export interface RecordRunRetroRequest {
+    initiative_id: string;
+    entity_type?: RetroEntityType;
+    entity_id?: string;
+    title?: string;
+    idempotency_key?: string;
+    retro: RetroJson;
+    markdown?: string;
+    run_id?: string;
+    correlation_id?: string;
+    source_client?: ReportingSourceClient;
+}
+export interface RecordRunRetroResponse {
+    ok: true;
+    run_id: string;
+    reused_run: boolean;
+    work_artifact_id: string | null;
+    run_step_id: string | null;
+    run_artifact_id: string | null;
+    event_id: string | null;
+    auth_mode?: 'service' | 'api_key';
+}
 export type LiveActivityType = 'run_started' | 'run_completed' | 'run_failed' | 'artifact_created' | 'decision_requested' | 'decision_resolved' | 'handoff_requested' | 'handoff_claimed' | 'handoff_fulfilled' | 'blocker_created' | 'milestone_completed' | 'delegation';
 export type RuntimeInstanceState = 'active' | 'stale' | 'stopped' | 'error';
 export interface RuntimeInstance {
     id: string;
     sourceClient: RuntimeSourceClient;
     displayName: string;
-    providerLogo: 'openai' | 'anthropic' | 'openclaw' | 'orgx' | 'unknown';
+    providerLogo: 'codex' | 'openai' | 'anthropic' | 'openclaw' | 'orgx' | 'unknown';
     state: RuntimeInstanceState;
     runId: string | null;
     correlationId: string | null;

package/dist/entity-comment-store.d.ts

@@ -0,0 +1,29 @@
+export type EntityCommentAuthorType = "human" | "agent" | "system";
+export type EntityCommentRecord = {
+    id: string;
+    parent_comment_id: string | null;
+    author_type: EntityCommentAuthorType;
+    author_id: string;
+    author_name: string | null;
+    body: string;
+    comment_type: string;
+    severity: string;
+    tags: string[] | null;
+    created_at: string;
+};
+export declare function listEntityComments(entityType: string, entityId: string): EntityCommentRecord[];
+export declare function appendEntityComment(input: {
+    entityType: string;
+    entityId: string;
+    body: string;
+    commentType?: string | null;
+    severity?: string | null;
+    tags?: unknown;
+    author?: {
+        author_type?: EntityCommentAuthorType;
+        author_id?: string;
+        author_name?: string | null;
+    };
+}): EntityCommentRecord;
+export declare function mergeEntityComments(remote: unknown, local: EntityCommentRecord[]): EntityCommentRecord[];
+export declare function clearEntityCommentsStore(): void;

package/dist/entity-comment-store.js

@@ -0,0 +1,190 @@
+import { chmodSync, existsSync, mkdirSync, readFileSync, rmSync, } from "node:fs";
+import { randomUUID } from "node:crypto";
+import { getOrgxPluginConfigDir, getOrgxPluginConfigPath } from "./paths.js";
+import { backupCorruptFileSync, writeJsonFileAtomicSync } from "./fs-utils.js";
+const MAX_COMMENTS_PER_ENTITY = 240;
+const MAX_TOTAL_COMMENTS = 1_500;
+function commentsDir() {
+    return getOrgxPluginConfigDir();
+}
+function commentsFile() {
+    return getOrgxPluginConfigPath("entity-comments.json");
+}
+function ensureDir() {
+    const dir = commentsDir();
+    mkdirSync(dir, { recursive: true, mode: 0o700 });
+    try {
+        chmodSync(dir, 0o700);
+    }
+    catch {
+        // best effort
+    }
+}
+function parseJson(value) {
+    try {
+        return JSON.parse(value);
+    }
+    catch {
+        return null;
+    }
+}
+function entityKey(entityType, entityId) {
+    return `${entityType.trim().toLowerCase()}:${entityId.trim()}`;
+}
+function normalizeTags(value) {
+    if (!Array.isArray(value))
+        return null;
+    const tags = value
+        .map((item) => (typeof item === "string" ? item.trim() : ""))
+        .filter((item) => item.length > 0);
+    return tags.length > 0 ? tags.slice(0, 16) : [];
+}
+function normalizeComment(input) {
+    const createdAt = typeof input.created_at === "string" ? input.created_at : new Date().toISOString();
+    return {
+        id: typeof input.id === "string" && input.id.trim().length > 0 ? input.id.trim() : `local_${randomUUID()}`,
+        parent_comment_id: typeof input.parent_comment_id === "string" && input.parent_comment_id.trim().length > 0
+            ? input.parent_comment_id.trim()
+            : null,
+        author_type: input.author_type === "agent" || input.author_type === "system" ? input.author_type : "human",
+        author_id: typeof input.author_id === "string" && input.author_id.trim().length > 0 ? input.author_id.trim() : "local_user",
+        author_name: typeof input.author_name === "string" && input.author_name.trim().length > 0 ? input.author_name.trim() : null,
+        body: typeof input.body === "string" ? input.body : "",
+        comment_type: typeof input.comment_type === "string" && input.comment_type.trim().length > 0 ? input.comment_type.trim() : "note",
+        severity: typeof input.severity === "string" && input.severity.trim().length > 0 ? input.severity.trim() : "info",
+        tags: normalizeTags(input.tags) ?? [],
+        created_at: createdAt,
+    };
+}
+function readStore() {
+    const file = commentsFile();
+    try {
+        if (!existsSync(file)) {
+            return { updatedAt: new Date().toISOString(), commentsByEntity: {} };
+        }
+        const raw = readFileSync(file, "utf8");
+        const parsed = parseJson(raw);
+        if (!parsed || typeof parsed !== "object") {
+            backupCorruptFileSync(file);
+            return { updatedAt: new Date().toISOString(), commentsByEntity: {} };
+        }
+        const commentsByEntity = parsed.commentsByEntity && typeof parsed.commentsByEntity === "object"
+            ? parsed.commentsByEntity
+            : {};
+        return {
+            updatedAt: typeof parsed.updatedAt === "string" ? parsed.updatedAt : new Date().toISOString(),
+            commentsByEntity,
+        };
+    }
+    catch {
+        return { updatedAt: new Date().toISOString(), commentsByEntity: {} };
+    }
+}
+function writeStore(store) {
+    ensureDir();
+    const file = commentsFile();
+    writeJsonFileAtomicSync(file, store, 0o600);
+}
+function trimStore(store) {
+    const next = {
+        updatedAt: store.updatedAt,
+        commentsByEntity: { ...store.commentsByEntity },
+    };
+    for (const [key, comments] of Object.entries(next.commentsByEntity)) {
+        if (!Array.isArray(comments) || comments.length === 0) {
+            delete next.commentsByEntity[key];
+            continue;
+        }
+        const normalized = comments.map((c) => normalizeComment(c));
+        normalized.sort((a, b) => Date.parse(a.created_at) - Date.parse(b.created_at));
+        next.commentsByEntity[key] = normalized.slice(-MAX_COMMENTS_PER_ENTITY);
+    }
+    const all = [];
+    for (const [key, comments] of Object.entries(next.commentsByEntity)) {
+        for (const comment of comments)
+            all.push({ key, comment });
+    }
+    if (all.length <= MAX_TOTAL_COMMENTS)
+        return next;
+    all.sort((a, b) => Date.parse(b.comment.created_at) - Date.parse(a.comment.created_at));
+    const keep = all.slice(0, MAX_TOTAL_COMMENTS);
+    const keepByEntity = new Map();
+    for (const item of keep) {
+        const list = keepByEntity.get(item.key) ?? [];
+        list.push(item.comment);
+        keepByEntity.set(item.key, list);
+    }
+    const rebuilt = {};
+    for (const [key, list] of keepByEntity.entries()) {
+        list.sort((a, b) => Date.parse(a.created_at) - Date.parse(b.created_at));
+        rebuilt[key] = list;
+    }
+    next.commentsByEntity = rebuilt;
+    return next;
+}
+export function listEntityComments(entityType, entityId) {
+    const key = entityKey(entityType, entityId);
+    const store = readStore();
+    const list = store.commentsByEntity[key];
+    if (!Array.isArray(list) || list.length === 0)
+        return [];
+    return list.map((c) => normalizeComment(c));
+}
+export function appendEntityComment(input) {
+    const body = input.body.trim();
+    if (!body) {
+        throw new Error("comment body is required");
+    }
+    const key = entityKey(input.entityType, input.entityId);
+    const now = new Date().toISOString();
+    const record = normalizeComment({
+        id: `local_${randomUUID()}`,
+        parent_comment_id: null,
+        author_type: input.author?.author_type ?? "human",
+        author_id: input.author?.author_id ?? "local_user",
+        author_name: input.author?.author_name ?? null,
+        body,
+        comment_type: (input.commentType ?? "note") || "note",
+        severity: (input.severity ?? "info") || "info",
+        tags: normalizeTags(input.tags) ?? [],
+        created_at: now,
+    });
+    const store = readStore();
+    const existing = Array.isArray(store.commentsByEntity[key]) ? store.commentsByEntity[key] : [];
+    const next = {
+        updatedAt: now,
+        commentsByEntity: {
+            ...store.commentsByEntity,
+            [key]: [...existing, record],
+        },
+    };
+    const trimmed = trimStore(next);
+    writeStore(trimmed);
+    return record;
+}
+export function mergeEntityComments(remote, local) {
+    const remoteList = Array.isArray(remote) ? remote : [];
+    const merged = new Map();
+    for (const comment of remoteList) {
+        if (!comment || typeof comment !== "object")
+            continue;
+        const record = normalizeComment(comment);
+        merged.set(record.id, record);
+    }
+    for (const comment of local) {
+        const record = normalizeComment(comment);
+        merged.set(record.id, record);
+    }
+    const list = Array.from(merged.values());
+    list.sort((a, b) => Date.parse(a.created_at) - Date.parse(b.created_at));
+    return list;
+}
+export function clearEntityCommentsStore() {
+    const file = commentsFile();
+    try {
+        rmSync(file, { force: true });
+    }
+    catch {
+        // best effort
+    }
+}