@useorgx/openclaw-plugin 0.4.5 → 0.4.8

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;
@@ -379,6 +568,10 @@ export interface LiveActivityItem {
     description: string | null;
     agentId: string | null;
     agentName: string | null;
+    requesterAgentId: string | null;
+    requesterAgentName: string | null;
+    executorAgentId: string | null;
+    executorAgentName: string | null;
     runId: string | null;
     initiativeId: string | null;
     timestamp: string;

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
+    }
+}