@com55/node-red-ai-access 0.2.0-beta.7 → 0.2.0-beta.8

package/dist/plugin.d.cts

@@ -218,7 +218,7 @@ declare class AuditLog {
  */
 
 type ProposalStatus = 'pending' | 'conflict' | 'approved' | 'rejected' | 'failed' | 'withdrawn' | 'expired' | 'superseded';
-/** One stored rebase conflict (field names only — never values). */
+/** One stored rebase conflict (field paths only, including env names / credential keys; never values). */
 interface StoredRebaseConflict {
     kind: string;
     nodeId?: string;
@@ -228,6 +228,11 @@ interface StoredRebaseConflict {
     message: string;
     choices: ('live' | 'proposed')[];
 }
+/** Paths where an AI conflict choice replaced a live editor change. */
+interface AiConflictOverride {
+    nodeId: string;
+    fields: string[];
+}
 /** Result of the last auto-rebase check against the live flows. */
 interface ProposalRebaseInfo {
     /** Live rev the check ran against. */
@@ -303,6 +308,20 @@ interface Proposal {
     };
     /** Last auto-rebase result (pending / conflict proposals). */
     rebase?: ProposalRebaseInfo;
+    /** AI resolutions that replace editor changes and still require reviewer acknowledgement. */
+    aiConflictOverrides?: AiConflictOverride[];
+    /** Latest manual resolution, retained for admin undo until the next body edit. */
+    conflictChoice?: {
+        nodeId: string;
+        choice: 'live' | 'proposed';
+        chooser?: 'ai' | 'human';
+        undo?: {
+            baseFlow: Partial<FlowTab>;
+            flow: Partial<FlowTab>;
+            warnings: ProposalWarning[];
+            aiConflictOverrides?: AiConflictOverride[];
+        };
+    };
     /**
      * Short human title (≤80 chars). Set at submit (AI-supplied or auto-generated).
      * Optional on legacy proposals; API responses always resolve a title.
@@ -388,6 +407,8 @@ declare class ProposalStore {
             property: string;
         }[];
         warnings?: ProposalWarning[];
+        conflictChoice?: Proposal['conflictChoice'];
+        aiConflictOverrides?: AiConflictOverride[];
     }): Proposal;
     /** True while an approve holds this proposal's lock. */
     isApproving(id: string): boolean;

package/docs/api/openapi.yaml

@@ -2,7 +2,7 @@ openapi: 3.1.0
 
 info:
   title: Node-RED AI Access Plugin API
-  version: 0.1.1
+  version: 0.2.0-beta.8
   summary: Temporary, owner-approved Node-RED access for AI clients
   description: |
     REST surface exposed by the `@com55/node-red-ai-access` Node-RED plugin
@@ -10,8 +10,8 @@ info:
 
     **Git mental model:** a proposal is like a pull request. Human approve =
     merge; reject = close; withdraw = the author closes their own PR. If `rev` /
-    `expectedRev` does not match, treat it as a conflict: re-read the flow,
-    rebase the edit, and resubmit. Every access link can see all proposals
+    `expectedRev` does not match, open proposals auto-rebase; only overlapping
+    field changes block approval. Read `rebase.state` to assess readiness. Every access link can see all proposals
     (`mine: true|false`).
 
     ## Base path
@@ -185,6 +185,10 @@ info:
     full tab or batch return `duplicate_node_id`.
 
     Open proposals (`pending` or `conflict`) auto-rebase when live revisions change.
+    Disjoint node and tab fields merge automatically. Only fields changed on both
+    sides conflict (even identical edits); x/y never conflict and proposed positions
+    win ties. Env merges by unique name and entry field, credentials by key.
+    Duplicate env names fall back to atomic comparison with ambiguity warnings.
     Conflicts block approval until resolved. Proposals expire only after the
     configured `proposalTtlDays` (default 7). Approval rebases other open proposals;
     legacy expired, rejected and superseded proposals stay closed.
@@ -194,7 +198,11 @@ info:
     The creating access link may withdraw its own pending proposal
     (`POST /proposals/{id}/withdraw`, GET `…/proposals/{id}/withdraw?confirm=1`,
     or MCP `withdraw_proposal`). GET withdraw requires `confirm=1` so prefetchers
-    cannot trigger it. Status becomes `withdrawn` (separate from admin
+    cannot trigger it. If the token is lost, a full (`*`) admin session may use
+    POST `/proposals/{id}/withdraw`. Other tokens remain blocked. Recovery is logged
+    as `proposal.withdrawn` with the admin identity, originalOwnerId, reason and
+    withdrawalAuthority=`admin-recovery` (owner-token withdrawals use `owner-token`).
+    Status becomes `withdrawn` (separate from admin
     `rejected`).
 
     ## Known issues
@@ -1054,9 +1062,13 @@ paths:
         (long text fields listed for expandable UI). Modified nodes include
         line-level diffs for text fields such as `func` and `template`.
 
-        `baseRevStale` is true only for **open** proposals when
+        `baseRev` aliases `expectedRev`, the stored proposal base revision.
+        `baseRevChanged` is true only for **open** proposals when
         `expectedRev` does not match the live revision (informational).
-        Closed proposals never set `baseRevStale`. Open proposals include
+        This is informational after a successful rebase, not an approval error.
+        `rebase.state` (`clean`, `merged`, `conflict`) reports merge readiness and
+        `rebase.rev` identifies the checked live rev. Closed proposals never set
+        `baseRevChanged` as true. Open proposals include
         `rebase` and `liveChanges` (editor changes since the stored base).
         Without conflicts, `vsCurrent` compares the merged deployment to live.
         Merges use raw stored proposals and live flows; AI diff sections are redacted.
@@ -1087,7 +1099,7 @@ paths:
   /proposals/{id}/resolve-conflict:
     post:
       tags: [Proposals]
-      summary: Choose live or proposed for one current conflict
+      summary: Choose live or proposed for one current conflict, or undo the latest choice
       operationId: resolveProposalConflict
       security:
         - AdminSession: []
@@ -1145,7 +1157,12 @@ paths:
   /proposals/{id}/resolve:
     post:
       tags: [Proposals]
-      summary: Resolve your own open proposal with a fresh payload
+      summary: Resolve your own open proposal with a choice or replacement payload
+      description: |
+        Use nodeId + choice for one current conflict (overlapping fields only;
+        independent live and proposed edits survive). Or use expectedRev + payload:
+        operations apply to the flow snapshot at expectedRev, not the stored
+        proposal or merged result. Include every intended edit. Do not mix modes.
       operationId: resolveProposal
       security:
         - AccessLinkBearer: []
@@ -1272,14 +1289,16 @@ paths:
   /proposals/{id}/withdraw:
     post:
       tags: [Proposals]
-      summary: Withdraw own pending proposal
+      summary: Withdraw an open proposal (owner token or full admin recovery)
       description: |
-        Access-link Bearer only. Withdraws an **open** (pending or conflict) proposal created by
-        this token. Status becomes `withdrawn` (not `rejected`). Optional
+        Accepts the creating access-link Bearer, or a full (`*`) admin session
+        for lost-token recovery. Other tokens and read-only admins are forbidden.
+        Withdraws an **open** (pending or conflict) proposal. Status becomes `withdrawn` (not `rejected`). Optional
         JSON body `{ "reason": "…" }`.
       operationId: withdrawProposal
       security:
         - AccessLinkBearer: []
+        - AdminSession: []
       parameters:
         - $ref: '#/components/parameters/ProposalId'
       requestBody:
@@ -1301,7 +1320,7 @@ paths:
         '401':
           $ref: '#/components/responses/Unauthorized'
         '403':
-          description: Not owned by this access link
+          description: Not owned by this access link or admin lacks full permission
           content:
             application/json:
               schema:
@@ -1585,7 +1604,7 @@ components:
         - `version_mismatch` (409): Unknown or unavailable `rev` / `expectedRev` snapshot
         - `proposal_not_found` (404): Unknown proposal id
         - `proposal_not_pending` (409): Action needs an open proposal
-        - `proposal_not_owned` (403): Withdraw of another token’s proposal
+        - `proposal_not_owned` (403): Resolve or withdraw another token’s proposal
         - `validation_failed` (400): Several validation errors at once (message `N validation errors`)
         - `duplicate_node_id` (400): The same node id appears more than once in a full tab or batch
         - `missing_node_id` (400): Node / op without an id
@@ -2346,6 +2365,7 @@ components:
         - type
         - status
         - expectedRev
+        - baseRev
         - payload
         - createdBy
         - createdAt
@@ -2355,6 +2375,16 @@ components:
         - reviewUrl
         - reviewPath
       properties:
+        conflictChoice:
+          type: object
+          description: Latest manual resolution; admins can undo it until the next body edit or choice. Undo snapshots are never returned.
+          required: [nodeId, choice]
+          properties:
+            nodeId:
+              type: string
+            choice:
+              type: string
+              enum: [live, proposed]
         deployPending:
           type: object
           description: Timed-out deployment has an unknown outcome; approvals wait until settlement or the hard cap. Check live flows before approving again.
@@ -2378,6 +2408,12 @@ components:
           $ref: '#/components/schemas/ProposalStatus'
         expectedRev:
           type: string
+        baseRev:
+          type: string
+          description: Revision of the stored base snapshot; alias of expectedRev.
+        baseRevChanged:
+          type: boolean
+          description: Informational revision difference for open proposals; use rebase.state for merge readiness.
         payload:
           $ref: '#/components/schemas/ReplaceFlowPayload'
         baseFlow:
@@ -2536,7 +2572,7 @@ components:
       type: object
       required: [kind]
       description: |
-        Admin for approve/reject/fail; access-link for withdraw.
+        Admin for approve/reject/fail and recovery withdrawal; access-link for owner withdrawal.
       properties:
         kind:
           type: string
@@ -2596,24 +2632,44 @@ components:
           type: string
         choice:
           type: string
-          enum: [live, proposed]
+          enum: [live, proposed, undo]
+          description: Undo restores the proposal before the latest choice for nodeId and rechecks against live. Available until the next body edit or choice; admin only. Nothing is deployed.
 
     ResolveProposalRequest:
-      type: object
-      required: [expectedRev]
-      properties:
-        expectedRev:
-          type: string
-        title:
-          type: string
-          maxLength: 80
-        payload:
-          $ref: '#/components/schemas/ReplaceFlowPayload'
-        nodes:
-          type: array
-          items:
-            type: object
-            additionalProperties: true
+      oneOf:
+        - type: object
+          additionalProperties: false
+          required: [nodeId, choice]
+          properties:
+            nodeId:
+              type: string
+              description: Current conflict node id; flow id for tab/env conflicts.
+            choice:
+              type: string
+              enum: [live, proposed]
+              description: Keep this side for overlapping fields only; preserve independent changes and live secrets.
+        - type: object
+          required: [expectedRev]
+          properties:
+            expectedRev:
+              type: string
+              description: Flow snapshot revision to which replacement operations apply.
+            title:
+              type: string
+              maxLength: 80
+            payload:
+              $ref: '#/components/schemas/ReplaceFlowPayload'
+              description: Complete intended edits based on expectedRev; not applied to the stored proposal or merged result.
+            nodes:
+              type: array
+              description: Legacy alias for replacement payload nodes, applied to expectedRev.
+              items:
+                type: object
+                additionalProperties: true
+          not:
+            anyOf:
+              - required: [nodeId]
+              - required: [choice]
 
     ApproveProposalRequest:
       type: object
@@ -2730,6 +2786,11 @@ components:
       type: object
       required: [summary, added, removed, modified]
       properties:
+        tabProperties:
+          type: array
+          description: Before and after values of changed flow settings, including env. Uses the caller's redacted view.
+          items:
+            $ref: '#/components/schemas/ProposalDiffPropertyChange'
         summary:
           type: object
           required: [added, removed, modified, tabChanges]
@@ -2766,7 +2827,8 @@ components:
             - flowId
             - expectedRev
             - currentRev
-            - baseRevStale
+            - baseRevChanged
+            - baseRev
             - compareAgainst
           properties:
             proposalId:
@@ -2775,9 +2837,12 @@ components:
               type: string
             expectedRev:
               type: string
+            baseRev:
+              type: string
+              description: Alias of expectedRev, the stored base revision.
             currentRev:
               type: string
-            baseRevStale:
+            baseRevChanged:
               type: boolean
               description: |
                 Informational: true for open proposals when expectedRev ≠ live rev.
@@ -2790,6 +2855,26 @@ components:
               description: True for legacy proposals without a stored baseFlow
             rebase:
               $ref: '#/components/schemas/ProposalRebase'
+            conflictValues:
+              type: array
+              description: Base, live and proposed values for each conflicting path. AI callers receive redacted values.
+              items:
+                type: object
+                required: [nodeId, fields]
+                properties:
+                  nodeId:
+                    type: string
+                  fields:
+                    type: array
+                    items:
+                      type: object
+                      required: [field]
+                      properties:
+                        field:
+                          type: string
+                        base: {}
+                        live: {}
+                        proposed: {}
             liveChanges:
               $ref: '#/components/schemas/ProposalDiffSections'
             vsCurrent:

package/docs/errors.md

@@ -18,8 +18,8 @@ GET-link `401` responses include a `WWW-Authenticate: Bearer …` header.
 | `proposal_conflict` | 409 | Editor and proposal changes conflict (conflicts contains field names only) | Read the current flow and resolve the proposal before approval | GET, REST, MCP, admin |
 | `rebase_ack_required` | 409 | The merged result needs review (mergedHash included) | Review the diff and approve with its mergedHash | admin |
 | `rebase_race` | 409 | Flows kept changing during approval | Recheck the proposal and retry approval | admin |
-| `conflict_not_found` | 409 | The requested conflict no longer exists | Reload the proposal and its conflicts | admin |
-| `invalid_choice` | 400 | Invalid manual conflict choice | Use an available live or proposed choice | admin |
+| `conflict_not_found` | 409 | The requested conflict no longer exists | Reload the proposal and its conflicts | REST, MCP, admin |
+| `invalid_choice` | 400 | Invalid manual conflict choice | Use nodeId plus an available live or proposed choice, without replacement payload or revision | REST, MCP, admin |
 | `flow_id_mismatch` | 400 | Resolution tried to change the proposal flow id | Keep the same flowId or submit a new proposal | REST, MCP |
 | `access_link_missing` | 401 | No Bearer / path token | Ask the user for a new access link of the right kind | GET, REST, MCP |
 | `bearer_scheme_required` | 401 | Auth used Basic (or non-Bearer) | Send `Authorization: Bearer <token>` | REST, MCP |
@@ -49,7 +49,7 @@ GET-link `401` responses include a `WWW-Authenticate: Bearer …` header.
 | `version_mismatch` | 409 | Unknown or unavailable `rev` / `expectedRev` snapshot | Re-read flows and resubmit | GET, REST, MCP |
 | `proposal_not_found` | 404 | Unknown proposal id | List proposals and use an existing id | GET, REST, MCP |
 | `proposal_not_pending` | 409 | Action needs an open proposal | Only pending or conflict proposals can withdraw / decide | GET, REST, MCP |
-| `proposal_not_owned` | 403 | Withdraw of another token’s proposal | Only the creating token can withdraw | GET, REST, MCP |
+| `proposal_not_owned` | 403 | Resolve or withdraw another token’s proposal | Use the creating token; lost-token withdrawal requires a full admin session | GET, REST, MCP |
 | `validation_failed` | 400 | Several validation errors at once (message `N validation errors`) | Fix every entry in errors[] and resubmit. | GET, REST, MCP |
 | `duplicate_node_id` | 400 | The same node id appears more than once in a full tab or batch | Give every node a unique id | GET, REST, MCP |
 | `missing_node_id` | 400 | Node / op without an id | Include a non-empty string id | GET, REST, MCP |

package/docs/mcp-tools.md

@@ -45,7 +45,7 @@ Get detail for one installed node type: defaults (JSON), inputs/outputs (always
 
 ## `get_proposal`
 
-Get any proposal by id (all tokens can read). Response includes mine:true|false and, for open proposals (pending or conflict), conflictingProposals when other open work touches the same flow. Lean by default (no payload/baseFlow); pass include_payload=true for full bodies. Cite displayName + reviewUrl when talking to the user.
+Get any proposal by id (all tokens can read). Response includes mine:true|false and, for open proposals (pending or conflict), conflictingProposals when other open work touches the same flow. baseRev aliases expectedRev; baseRevChanged is informational. rebase.state=clean|merged means mergeable; conflict blocks approval. Lean by default (no payload/baseFlow); pass include_payload=true for full bodies. Cite displayName + reviewUrl when talking to the user.
 
 | Parameter | Required | Type | Description |
 | --- | --- | --- | --- |
@@ -109,14 +109,16 @@ List proposals visible to this access link (all proposals by default). Each item
 
 ## `resolve_proposal_conflict`
 
-Replace your own open proposal with a resolution based on expectedRev. Revision changes auto-rebase; conflict blocks approval until resolved. Open proposals expire after the configured TTL (default 7 days). Read the current flow first; payload accepts a full flow or nodes ops as in submit_proposal.
+Resolve your own open proposal. Different node/tab fields auto-merge; only fields changed on both sides conflict (x/y never conflict). Choose one current conflict using nodeId + choice, preserving all non-conflicting fields. Alternatively replace the proposal using expectedRev + payload: nodes ops apply to the flow snapshot at expectedRev, NOT the stored proposal or merged result; include every intended proposal edit. Read get_proposal_diff for conflicts and get_flow for a fresh rev. These two modes cannot be mixed.
 
 | Parameter | Required | Type | Description |
 | --- | --- | --- | --- |
-| `expectedRev` | yes | string | — |
-| `id` | yes | string | — |
-| `payload` | yes | object | — |
-| `title` | no | string | — |
+| `choice` | no | "live" \| "proposed" | For this conflict, keep live or proposed values of overlapping fields only. Disjoint edits survive. Use with nodeId, without expectedRev/title/payload. |
+| `expectedRev` | no | string | Revision of the flow snapshot on which replacement payload ops run. Required with payload; normally the current get_flow rev. |
+| `id` | yes | string | Your open proposal id (prop-…) |
+| `nodeId` | no | string | Conflict nodeId from rebase.conflicts; use the flow id for tab/env conflicts. Required with choice. |
+| `payload` | no | object | Replacement body; required with expectedRev, omitted with nodeId + choice |
+| `title` | no | string | Optional replacement title (body replacement mode only) |
 
 ## `search_flows`
 
@@ -151,7 +153,7 @@ Submit a replace_flow proposal for owner approval (does not deploy). Preferred f
 
 ## `withdraw_proposal`
 
-Withdraw one of YOUR open (pending or conflict) proposals (status becomes withdrawn, not rejected). Optional reason. Only the creating access link can withdraw; other tokens get 403. Cite displayName + reviewUrl when telling the user.
+Withdraw one of YOUR open (pending or conflict) proposals (status becomes withdrawn, not rejected). Optional reason. Only the creating access link can withdraw via MCP; other tokens get 403. If it is lost, a full admin session can recover via POST /proposals/{id}/withdraw. Cite displayName + reviewUrl when telling the user.
 
 | Parameter | Required | Type | Description |
 | --- | --- | --- | --- |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@com55/node-red-ai-access",
-  "version": "0.2.0-beta.7",
+  "version": "0.2.0-beta.8",
   "description": "Node-RED plugin that gives AI agents temporary, owner-approved access via REST and MCP",
   "main": "dist/plugin.cjs",
   "types": "dist/plugin.d.cts",