trellis 3.1.35 → 3.2.2

package/dist/plugins/plan-approval/index.js

@@ -0,0 +1,579 @@
+import "../../chunk-KFQGP6VL.js";
+
+// src/plugins/plan-approval/ontology.ts
+var planApprovalOntology = {
+  id: "trellis:plan-approval",
+  name: "Plan Approval",
+  version: "1.0.0",
+  description: "Multi-turn planning with buffered mutations and user approval",
+  entities: [
+    {
+      name: "PendingPlan",
+      description: "A buffered set of graph mutations awaiting user approval",
+      attributes: [
+        { name: "title", type: "string", required: true },
+        { name: "description", type: "string" },
+        {
+          name: "status",
+          type: "string",
+          required: true,
+          enum: ["drafting", "submitted", "approved", "rejected"],
+          default: "drafting"
+        },
+        { name: "submittedAt", type: "string", description: "ISO 8601 timestamp" },
+        { name: "resolvedAt", type: "string", description: "ISO 8601 timestamp" },
+        { name: "resolvedBy", type: "string", description: "Agent or user who approved/rejected" },
+        { name: "rejectionReason", type: "string" },
+        { name: "operationCount", type: "number", description: "Number of planned operations" }
+      ]
+    },
+    {
+      name: "PlannedOperation",
+      description: "A single buffered graph mutation within a plan",
+      attributes: [
+        {
+          name: "kind",
+          type: "string",
+          required: true,
+          enum: ["createEntity", "updateEntity", "deleteEntity", "addLink", "removeLink"]
+        },
+        { name: "entityId", type: "string", description: "Target entity ID" },
+        { name: "entityType", type: "string", description: "Entity type (for createEntity)" },
+        { name: "attributes", type: "any", description: "JSON-serialized attributes" },
+        { name: "sourceId", type: "string", description: "Source entity (for link operations)" },
+        { name: "targetId", type: "string", description: "Target entity (for link operations)" },
+        { name: "linkAttribute", type: "string", description: "Link attribute name" },
+        { name: "description", type: "string", description: "Human-readable description of this operation" },
+        { name: "sequence", type: "number", description: "Execution order within the plan" }
+      ]
+    }
+  ],
+  relations: [
+    {
+      name: "hasOperation",
+      sourceTypes: ["PendingPlan"],
+      targetTypes: ["PlannedOperation"],
+      cardinality: "many"
+    },
+    {
+      name: "planForRun",
+      sourceTypes: ["PendingPlan"],
+      targetTypes: ["AgentRun"],
+      cardinality: "one",
+      description: "Links a plan to the agent run that produced it"
+    }
+  ]
+};
+
+// src/plugins/plan-approval/plugin.ts
+function createPlanApprovalPlugin() {
+  return {
+    id: "trellis:plan-approval",
+    name: "Plan Approval",
+    version: "1.0.0",
+    description: "Multi-turn planning with buffered mutations and user approval",
+    ontologies: [planApprovalOntology],
+    eventHandlers: [
+      {
+        event: "entity:updated",
+        handler: (data) => {
+          if (!data || typeof data !== "object") return;
+          const d = data;
+          if (d.type !== "PendingPlan") return;
+        }
+      }
+    ],
+    onLoad: async (ctx) => {
+      ctx.log("Plan approval system loaded");
+    },
+    onUnload: async (ctx) => {
+      ctx.log("Plan approval system unloaded");
+    }
+  };
+}
+function createEnterPlanModeTool(ctx) {
+  return {
+    def: {
+      name: "enterPlanMode",
+      description: "Enter plan mode. Subsequent planCreateEntity/planUpdateEntity/planAddLink calls will be buffered for user review instead of executing immediately. Use this before performing bulk operations or significant architectural changes.",
+      schema: JSON.stringify({
+        type: "object",
+        properties: {
+          title: { type: "string", description: "Short title describing the planned changes" },
+          description: { type: "string", description: "Detailed description of what will be changed and why" }
+        },
+        required: ["title"]
+      })
+    },
+    handler: async (input) => {
+      const { title, description } = input;
+      const planId = await ctx.planManager.enterPlanMode(title, description);
+      return {
+        success: true,
+        output: { planId, message: `Plan mode active. Use planCreateEntity/planUpdateEntity/planAddLink to buffer operations, then submitPlan to send for review.` }
+      };
+    }
+  };
+}
+function createPlanCreateEntityTool(ctx) {
+  return {
+    def: {
+      name: "planCreateEntity",
+      description: "Buffer a new entity creation in the active plan. Must be in plan mode.",
+      schema: JSON.stringify({
+        type: "object",
+        properties: {
+          entityId: { type: "string", description: "Unique entity ID" },
+          entityType: { type: "string", description: "Entity type name" },
+          attributes: { type: "object", description: "Entity attributes as key-value pairs" },
+          description: { type: "string", description: "Human-readable description of this operation" }
+        },
+        required: ["entityId", "entityType"]
+      })
+    },
+    handler: async (input) => {
+      const { entityId, entityType, attributes, description } = input;
+      const opId = await ctx.planManager.planCreateEntity(entityId, entityType, attributes, description);
+      return { success: true, output: { operationId: opId } };
+    }
+  };
+}
+function createPlanUpdateEntityTool(ctx) {
+  return {
+    def: {
+      name: "planUpdateEntity",
+      description: "Buffer an entity update in the active plan. Must be in plan mode.",
+      schema: JSON.stringify({
+        type: "object",
+        properties: {
+          entityId: { type: "string", description: "Target entity ID" },
+          attributes: { type: "object", description: "Attributes to update" },
+          description: { type: "string", description: "Human-readable description" }
+        },
+        required: ["entityId", "attributes"]
+      })
+    },
+    handler: async (input) => {
+      const { entityId, attributes, description } = input;
+      const opId = await ctx.planManager.planUpdateEntity(entityId, attributes, description);
+      return { success: true, output: { operationId: opId } };
+    }
+  };
+}
+function createPlanAddLinkTool(ctx) {
+  return {
+    def: {
+      name: "planAddLink",
+      description: "Buffer a link creation in the active plan. Must be in plan mode.",
+      schema: JSON.stringify({
+        type: "object",
+        properties: {
+          sourceId: { type: "string", description: "Source entity ID" },
+          linkAttribute: { type: "string", description: "Relationship attribute name" },
+          targetId: { type: "string", description: "Target entity ID" },
+          description: { type: "string", description: "Human-readable description" }
+        },
+        required: ["sourceId", "linkAttribute", "targetId"]
+      })
+    },
+    handler: async (input) => {
+      const { sourceId, linkAttribute, targetId, description } = input;
+      const opId = await ctx.planManager.planAddLink(sourceId, linkAttribute, targetId, description);
+      return { success: true, output: { operationId: opId } };
+    }
+  };
+}
+function createSubmitPlanTool(ctx) {
+  return {
+    def: {
+      name: "submitPlan",
+      description: "Submit the active plan for user review. The plan will be presented to the user for approval before any operations are executed. The agent loop will pause until the user approves or rejects.",
+      schema: JSON.stringify({
+        type: "object",
+        properties: {}
+      })
+    },
+    handler: async () => {
+      const plan = await ctx.planManager.submitPlan();
+      return {
+        success: true,
+        output: {
+          _planPending: true,
+          planId: plan.id,
+          title: plan.title,
+          description: plan.description,
+          operationCount: plan.operations.length,
+          operations: plan.operations.map((op) => ({
+            kind: op.kind,
+            description: op.description,
+            entityId: op.entityId,
+            entityType: op.entityType
+          }))
+        }
+      };
+    }
+  };
+}
+function createCancelPlanTool(ctx) {
+  return {
+    def: {
+      name: "cancelPlan",
+      description: "Cancel the active plan without submitting. Discards all buffered operations.",
+      schema: JSON.stringify({
+        type: "object",
+        properties: {}
+      })
+    },
+    handler: async () => {
+      await ctx.planManager.cancelPlan();
+      return { success: true, output: { message: "Plan cancelled." } };
+    }
+  };
+}
+function registerPlanTools(harness, ctx) {
+  const tools = [
+    createEnterPlanModeTool(ctx),
+    createPlanCreateEntityTool(ctx),
+    createPlanUpdateEntityTool(ctx),
+    createPlanAddLinkTool(ctx),
+    createSubmitPlanTool(ctx),
+    createCancelPlanTool(ctx)
+  ];
+  return Promise.all(
+    tools.map((t) => harness.registerTool(t.def, t.handler))
+  );
+}
+
+// src/plugins/plan-approval/plan-manager.ts
+var planIdCounter = 0;
+var PlanManager = class {
+  kernel;
+  activePlan = null;
+  constructor(kernel) {
+    this.kernel = kernel;
+  }
+  // -------------------------------------------------------------------------
+  // Plan mode lifecycle
+  // -------------------------------------------------------------------------
+  /**
+   * Enter plan mode. Creates a PendingPlan entity in the graph and sets it
+   * as the active plan. All subsequent `addOperation()` calls buffer into it.
+   */
+  async enterPlanMode(title, description) {
+    if (this.activePlan && this.activePlan.status === "drafting") {
+      throw new Error("PlanManager: Already in plan mode. Submit or cancel the current plan first.");
+    }
+    const id = `plan:${Date.now()}:${++planIdCounter}`;
+    const now = (/* @__PURE__ */ new Date()).toISOString();
+    const plan = {
+      id,
+      status: "drafting",
+      title,
+      description,
+      operations: [],
+      createdAt: now
+    };
+    const attrs = {
+      title,
+      status: "drafting"
+    };
+    if (description) attrs.description = description;
+    attrs.operationCount = 0;
+    await this.kernel.createEntity(id, "PendingPlan", attrs);
+    this.activePlan = plan;
+    return id;
+  }
+  /**
+   * Whether a plan is currently being drafted.
+   */
+  isInPlanMode() {
+    return this.activePlan !== null && this.activePlan.status === "drafting";
+  }
+  /**
+   * Get the active plan (if any).
+   */
+  getActivePlan() {
+    return this.activePlan;
+  }
+  // -------------------------------------------------------------------------
+  // Buffer operations
+  // -------------------------------------------------------------------------
+  /**
+   * Buffer a planned graph operation. Only valid in plan mode.
+   * Returns the operation ID.
+   */
+  async addOperation(op) {
+    if (!this.activePlan || this.activePlan.status !== "drafting") {
+      throw new Error("PlanManager: Not in plan mode. Call enterPlanMode() first.");
+    }
+    const sequence = this.activePlan.operations.length;
+    const opId = `${this.activePlan.id}:op:${sequence}`;
+    const planned = {
+      ...op,
+      id: opId,
+      sequence
+    };
+    this.activePlan.operations.push(planned);
+    const attrs = {
+      kind: op.kind,
+      sequence
+    };
+    if (op.entityId) attrs.entityId = op.entityId;
+    if (op.entityType) attrs.entityType = op.entityType;
+    if (op.attributes) attrs.attributes = JSON.stringify(op.attributes);
+    if (op.sourceId) attrs.sourceId = op.sourceId;
+    if (op.targetId) attrs.targetId = op.targetId;
+    if (op.linkAttribute) attrs.linkAttribute = op.linkAttribute;
+    if (op.description) attrs.description = op.description;
+    await this.kernel.createEntity(opId, "PlannedOperation", attrs);
+    await this.kernel.addLink(this.activePlan.id, "hasOperation", opId);
+    await this.kernel.updateEntity(this.activePlan.id, {
+      operationCount: this.activePlan.operations.length
+    });
+    return opId;
+  }
+  // -------------------------------------------------------------------------
+  // Convenience buffers (mirror the kernel entity API)
+  // -------------------------------------------------------------------------
+  async planCreateEntity(entityId, entityType, attributes, description) {
+    return this.addOperation({
+      kind: "createEntity",
+      entityId,
+      entityType,
+      attributes,
+      description: description ?? `Create ${entityType} "${entityId}"`
+    });
+  }
+  async planUpdateEntity(entityId, attributes, description) {
+    return this.addOperation({
+      kind: "updateEntity",
+      entityId,
+      attributes,
+      description: description ?? `Update "${entityId}"`
+    });
+  }
+  async planDeleteEntity(entityId, description) {
+    return this.addOperation({
+      kind: "deleteEntity",
+      entityId,
+      description: description ?? `Delete "${entityId}"`
+    });
+  }
+  async planAddLink(sourceId, linkAttribute, targetId, description) {
+    return this.addOperation({
+      kind: "addLink",
+      sourceId,
+      targetId,
+      linkAttribute,
+      description: description ?? `Link ${sourceId} -[${linkAttribute}]-> ${targetId}`
+    });
+  }
+  async planRemoveLink(sourceId, linkAttribute, targetId, description) {
+    return this.addOperation({
+      kind: "removeLink",
+      sourceId,
+      targetId,
+      linkAttribute,
+      description: description ?? `Unlink ${sourceId} -[${linkAttribute}]-> ${targetId}`
+    });
+  }
+  // -------------------------------------------------------------------------
+  // Plan resolution
+  // -------------------------------------------------------------------------
+  /**
+   * Submit the active plan for review. Marks it as submitted and returns
+   * the plan for the caller to present to the user.
+   */
+  async submitPlan() {
+    if (!this.activePlan || this.activePlan.status !== "drafting") {
+      throw new Error("PlanManager: No active plan to submit.");
+    }
+    if (this.activePlan.operations.length === 0) {
+      throw new Error("PlanManager: Cannot submit an empty plan.");
+    }
+    const now = (/* @__PURE__ */ new Date()).toISOString();
+    this.activePlan.status = "submitted";
+    this.activePlan.submittedAt = now;
+    await this.kernel.updateEntity(this.activePlan.id, {
+      status: "submitted",
+      submittedAt: now
+    });
+    return { ...this.activePlan };
+  }
+  /**
+   * Approve a submitted plan. Replays all buffered operations against the
+   * real kernel in sequence order. Returns the results of each operation.
+   */
+  async approvePlan(resolvedBy) {
+    if (!this.activePlan || this.activePlan.status !== "submitted") {
+      throw new Error("PlanManager: No submitted plan to approve.");
+    }
+    const plan = this.activePlan;
+    const now = (/* @__PURE__ */ new Date()).toISOString();
+    const results = [];
+    const ops = [...plan.operations].sort((a, b) => a.sequence - b.sequence);
+    for (const op of ops) {
+      const result = await this._executeOperation(op);
+      if (result) results.push(result);
+    }
+    plan.status = "approved";
+    plan.resolvedAt = now;
+    plan.resolvedBy = resolvedBy;
+    await this.kernel.updateEntity(plan.id, {
+      status: "approved",
+      resolvedAt: now,
+      ...resolvedBy ? { resolvedBy } : {}
+    });
+    this.activePlan = null;
+    return {
+      planId: plan.id,
+      operationsExecuted: results.length,
+      results
+    };
+  }
+  /**
+   * Reject a submitted plan. The plan and its operations remain in the graph
+   * as entities, preserving them as substrate for the Idea Garden (Phase 6).
+   */
+  async rejectPlan(reason, resolvedBy) {
+    if (!this.activePlan || this.activePlan.status !== "submitted") {
+      throw new Error("PlanManager: No submitted plan to reject.");
+    }
+    const now = (/* @__PURE__ */ new Date()).toISOString();
+    this.activePlan.status = "rejected";
+    this.activePlan.resolvedAt = now;
+    this.activePlan.resolvedBy = resolvedBy;
+    this.activePlan.rejectionReason = reason;
+    const updates = {
+      status: "rejected",
+      resolvedAt: now
+    };
+    if (reason) updates.rejectionReason = reason;
+    if (resolvedBy) updates.resolvedBy = resolvedBy;
+    await this.kernel.updateEntity(this.activePlan.id, updates);
+    this.activePlan = null;
+  }
+  /**
+   * Cancel a drafting plan without submitting. Like rejection but for
+   * plans that were never submitted.
+   */
+  async cancelPlan() {
+    if (!this.activePlan || this.activePlan.status !== "drafting") {
+      throw new Error("PlanManager: No active plan to cancel.");
+    }
+    await this.kernel.updateEntity(this.activePlan.id, {
+      status: "rejected",
+      resolvedAt: (/* @__PURE__ */ new Date()).toISOString(),
+      rejectionReason: "Cancelled before submission"
+    });
+    this.activePlan = null;
+  }
+  // -------------------------------------------------------------------------
+  // Query helpers
+  // -------------------------------------------------------------------------
+  /**
+   * Load a plan from the graph by ID, including its operations.
+   */
+  loadPlan(planId) {
+    const entity = this.kernel.getEntity(planId);
+    if (!entity || entity.type !== "PendingPlan") return null;
+    const get = (a) => entity.facts.find((f) => f.a === a)?.v;
+    const store = this.kernel.getStore();
+    const opLinks = store.getLinksByEntityAndAttribute(planId, "hasOperation");
+    const operations = [];
+    for (const link of opLinks) {
+      const opEntity = this.kernel.getEntity(link.e2);
+      if (!opEntity || opEntity.type !== "PlannedOperation") continue;
+      const opGet = (a) => opEntity.facts.find((f) => f.a === a)?.v;
+      let attributes;
+      const attrsRaw = opGet("attributes");
+      if (attrsRaw) {
+        try {
+          attributes = JSON.parse(attrsRaw);
+        } catch {
+        }
+      }
+      operations.push({
+        id: opEntity.id,
+        kind: opGet("kind"),
+        entityId: opGet("entityId"),
+        entityType: opGet("entityType"),
+        attributes,
+        sourceId: opGet("sourceId"),
+        targetId: opGet("targetId"),
+        linkAttribute: opGet("linkAttribute"),
+        description: opGet("description"),
+        sequence: opGet("sequence") ?? 0
+      });
+    }
+    operations.sort((a, b) => a.sequence - b.sequence);
+    return {
+      id: planId,
+      status: get("status") ?? "drafting",
+      title: String(get("title") ?? ""),
+      description: get("description"),
+      operations,
+      createdAt: String(get("createdAt") ?? ""),
+      submittedAt: get("submittedAt"),
+      resolvedAt: get("resolvedAt"),
+      resolvedBy: get("resolvedBy"),
+      rejectionReason: get("rejectionReason")
+    };
+  }
+  /**
+   * List all plans, optionally filtered by status.
+   */
+  listPlans(status) {
+    const entities = this.kernel.listEntities("PendingPlan", status ? { status } : void 0);
+    return entities.map((e) => this.loadPlan(e.id)).filter((p) => p !== null);
+  }
+  // -------------------------------------------------------------------------
+  // Internal
+  // -------------------------------------------------------------------------
+  /**
+   * Execute a single planned operation against the real kernel.
+   */
+  async _executeOperation(op) {
+    switch (op.kind) {
+      case "createEntity":
+        if (!op.entityId || !op.entityType) {
+          throw new Error(`PlannedOperation ${op.id}: createEntity requires entityId and entityType`);
+        }
+        return this.kernel.createEntity(op.entityId, op.entityType, op.attributes ?? {});
+      case "updateEntity":
+        if (!op.entityId || !op.attributes) {
+          throw new Error(`PlannedOperation ${op.id}: updateEntity requires entityId and attributes`);
+        }
+        return this.kernel.updateEntity(op.entityId, op.attributes);
+      case "deleteEntity":
+        if (!op.entityId) {
+          throw new Error(`PlannedOperation ${op.id}: deleteEntity requires entityId`);
+        }
+        return this.kernel.deleteEntity(op.entityId);
+      case "addLink":
+        if (!op.sourceId || !op.linkAttribute || !op.targetId) {
+          throw new Error(`PlannedOperation ${op.id}: addLink requires sourceId, linkAttribute, and targetId`);
+        }
+        return this.kernel.addLink(op.sourceId, op.linkAttribute, op.targetId);
+      case "removeLink":
+        if (!op.sourceId || !op.linkAttribute || !op.targetId) {
+          throw new Error(`PlannedOperation ${op.id}: removeLink requires sourceId, linkAttribute, and targetId`);
+        }
+        return this.kernel.removeLink(op.sourceId, op.linkAttribute, op.targetId);
+      default:
+        throw new Error(`PlannedOperation ${op.id}: Unknown operation kind "${op.kind}"`);
+    }
+  }
+};
+export {
+  PlanManager,
+  createCancelPlanTool,
+  createEnterPlanModeTool,
+  createPlanAddLinkTool,
+  createPlanApprovalPlugin,
+  createPlanCreateEntityTool,
+  createPlanUpdateEntityTool,
+  createSubmitPlanTool,
+  planApprovalOntology,
+  registerPlanTools
+};