@forloop-cc/forloop-opencode-plugin-planner 2.2.25 → 2.2.27

package/package.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://json.schemastore.org/package.json",
   "name": "@forloop-cc/forloop-opencode-plugin-planner",
-  "version": "2.2.25",
+  "version": "2.2.27",
   "description": "ForLoop integration plugin for opencode — Sprint, story, and agent tools for the ForLoop platform",
   "type": "module",
   "license": "MIT",

package/plugins/tools/a2a-connection-tools.ts

@@ -7,8 +7,15 @@ type RegistryEntry = {
   agentId: string;
   name: string;
   serviceCode?: string | null;
+  authMode?: 'none' | 'app' | 'user';
 };
 
+// The target manifest is the source of truth for consent: a user-auth service
+// only accepts a user-subject connection, so the planner must never create an
+// app-subject request against it as a workaround.
+const subjectTypeFor = (target: RegistryEntry): 'user' | 'app' =>
+  target.authMode === 'user' ? 'user' : 'app';
+
 type RequestWire = {
   id: string;
   targetAgentId: string;
@@ -75,7 +82,7 @@ const requestLines = (request: RequestWire): string[] => {
 export function createA2ARequestConnectionTool(client: ForLoopAPIClient) {
   return tool({
     description:
-      'Create (or idempotently reuse) a connection request for the current sprint: the app asks a service/peer for an exact scope set. The request is persisted and visible in App Connections, but the planner can never approve it — the signed-in owner must click Approve. Returns the request id and a deep link. Use before writing an integration brief that depends on an external service.',
+      'Create (or idempotently reuse) a connection request for the current sprint: the app asks a service/peer for an exact scope set. The request is persisted and visible in App Connections, but the planner can never approve it — the signed-in owner (or, for user-subject grants, the end user themselves) must click Approve. Returns the request id and a deep link. Use before writing an integration brief that depends on an external service. subjectType defaults to the target manifest authMode: "user" for user-owned data (the user consents), otherwise "app" for app-owned/standing integrations. Never force app for a user-auth target.',
     args: {
       agentId: tool.schema.string().describe('Target service/peer agentId (public id)'),
       scopes: tool.schema
@@ -85,6 +92,10 @@ export function createA2ARequestConnectionTool(client: ForLoopAPIClient) {
         .string()
         .optional()
         .describe('Why the app needs this connection (shown to the approving user)'),
+      subjectType: tool.schema
+        .enum(['user', 'app'])
+        .optional()
+        .describe('Connection subject: "user" for user-owned data (delegated user consent), "app" for an app-owned/standing integration. Defaults to the target authMode; an app subject is refused for a user-auth target.'),
     },
     async execute(args, context) {
       const tokenResult = await validateToken();
@@ -107,23 +118,42 @@ export function createA2ARequestConnectionTool(client: ForLoopAPIClient) {
           return `❌ No scopes requested for \`${args.agentId}\`. Nothing was created.`;
         }
 
+        const targetSubject = subjectTypeFor(target)
+        if (targetSubject === 'user' && args.subjectType === 'app') {
+          return [
+            `❌ Target \`${args.agentId}\` requires user-auth (authMode: "user"); refusing to create an app-subject request.`,
+            'The end user must consent for their own data. Retry without subjectType (it defaults to "user" for this target) or pass subjectType: "user".',
+          ].join('\n');
+        }
+        const subjectType = args.subjectType ?? targetSubject
         const result = await client.createConnectionRequest({
           sprintId,
           targetAgentId: args.agentId,
           scopes: requested,
-          subjectType: 'app',
+          subjectType,
           requestedBy: 'planner',
           ...(args.reason ? { reason: args.reason } : {}),
         });
         const request = result.request as RequestWire;
         const dropped = Array.isArray(result.droppedScopes) ? result.droppedScopes : [];
 
+        if (subjectType === 'user' && request.subjectType !== 'user') {
+          return [
+            '❌ The platform did not create a user-subject connection request; nothing usable was created.',
+            `- returned subject: ${request.subjectType ?? 'unknown'}`,
+            'Do not use an app-subject request for user-owned data. Record `Connection: pending user consent (UI-only)` and stop until the platform delegated-user exchange and user-subject requests are available.',
+          ].join('\n');
+        }
+
         return [
           request.status === 'approved'
             ? '## Connection already approved'
-            : '## Connection request created — waiting for the app owner',
+            : request.subjectType === 'user'
+              ? "## Connection request created — waiting for the user's consent"
+              : '## Connection request created — waiting for the app owner',
           '',
           `- target: **${target.name}** (\`${target.agentId}\`)`,
+          `- request subject: ${request.subjectType === 'user' ? 'user-subject (user consent)' : 'app-subject (app owner)'}`,
           ...requestLines({ ...request, link: result.link ?? request.link }),
           ...(dropped.length
             ? ['', `⚠️ Dropped (not declared by the target manifest): ${dropped.join(', ')}`]
@@ -132,6 +162,7 @@ export function createA2ARequestConnectionTool(client: ForLoopAPIClient) {
           'The planner cannot approve this. Ask the user to click **Approve** in App Connections, or call `a2a_open_connection_request` to bring the panel forward.',
           'Do **not** write the connection id into a brief until `a2a_check_connections` reports an active connection — a pending request is not a grant.',
           'If the user replies that they approved, call `a2a_check_connections` to read the real connection id and scopes.',
+          'For user-owned data the user consents in the platform panel; the app owner cannot consent for them.',
         ].join('\n');
       } catch (error: any) {
         return `❌ Error creating the connection request: ${error.message}`;
@@ -258,10 +289,16 @@ export function createA2AOpenConnectionRequestTool(client: ForLoopAPIClient) {
           if (!args.agentId) {
             return '❌ Provide a request id, or a target agentId (and scopes) so the request can be created.';
           }
+          const target = await findEntry(client, args.agentId);
+          if (!target) {
+            return `❌ Target \`${args.agentId}\` was not found in the registry. Do not invent a connection request.`;
+          }
+          const desiredSubject = subjectTypeFor(target);
           const state = (await client.getConnectionState(sprintId)) as ConnectionState;
           const wanted = new Set((args.scopes ?? []).map(scope => scope.trim()).filter(Boolean));
           const match = (state.requests ?? []).find(request => {
             if (request.targetAgentId !== args.agentId) return false;
+            if (request.subjectType !== desiredSubject) return false;
             if (request.status !== 'pending' && request.status !== 'approved') return false;
             if (!wanted.size) return true;
             return (
@@ -280,9 +317,16 @@ export function createA2AOpenConnectionRequestTool(client: ForLoopAPIClient) {
               sprintId,
               targetAgentId: args.agentId,
               scopes: [...wanted],
-              subjectType: 'app',
+              subjectType: desiredSubject,
               requestedBy: 'planner',
             });
+            if (desiredSubject === 'user' && created.request?.subjectType !== 'user') {
+              return [
+                '❌ The platform did not create a user-subject connection request; nothing usable was created.',
+                `- returned subject: ${created.request?.subjectType ?? 'unknown'}`,
+                'Do not use an app-subject request for user-owned data. Record `Connection: pending user consent (UI-only)` and stop.',
+              ].join('\n');
+            }
             requestId = created.request?.id ?? '';
             link = created.link ?? created.request?.link ?? null;
           }

package/plugins/tools/core-service-tools.ts

@@ -25,6 +25,12 @@ type RegistryEntry = {
   directIntegrable?: boolean;
 };
 
+// The target manifest is the source of truth for consent: a user-auth service
+// only accepts a user-subject connection, so the planner must never create an
+// app-subject request against it as a workaround.
+const subjectTypeFor = (target: RegistryEntry): 'user' | 'app' =>
+  target.authMode === 'user' ? 'user' : 'app';
+
 const formatPrice = (entry: RegistryEntry): string => {
   if (entry.billingPrice == null) return 'price TBD';
   const currency = entry.billingCurrency || 'FLC';
@@ -168,7 +174,8 @@ export function createCoreServiceGetTool(client: ForLoopAPIClient) {
           `# ${args.agentId} — contract ${contract.version}`,
           `- status: ${status}`,
           `${sunset}${deprecated}`,
-          `- checksum: ${contract.checksum ?? 'unknown'}`,
+          `- checksum: ${contract.checksum ?? 'unknown'} (stored raw manifest)`,
+          `- generatedChecksum: ${contract.generatedChecksum ?? 'unknown'} (normalized contract; matches contract-artifact.json)`,
           '',
           '## OpenAPI',
           '```json',
@@ -190,7 +197,7 @@ export function createCoreServiceGetTool(client: ForLoopAPIClient) {
 export function createCoreServiceIntegrationRequestTool(client: ForLoopAPIClient) {
   return tool({
     description:
-      'Prepare the user-approval step for a core-service integration and return a deep link to the app’s App Connections panel plus the app-subject connection payload. Nothing is created or stored until the user clicks Connect. This never creates a connection, never touches credentials, and never constructs API URLs by hand.',
+      'Start the user-approval step for a core-service integration: persist (or idempotently reuse) the pending connection request, then ask the signed-in user’s live client to open App Connections focused on it so they only need to click Approve. Falls back to the approval link when the client is offline. This never approves, never touches credentials, and never constructs API URLs by hand.',
     args: {
       agentId: tool.schema.string().describe('Target core-service agentId'),
       scopes: tool.schema
@@ -232,12 +239,13 @@ export function createCoreServiceIntegrationRequestTool(client: ForLoopAPIClient
           ].join('\n');
         }
 
+        const subjectType = subjectTypeFor(target)
         const resolution = await resolveSprintId(undefined, context?.directory);
         const callerSprintId = resolution.sprintId ?? null;
         const connectionPayload = {
           callerSprintId,
           targetAgentId: args.agentId,
-          subjectType: 'app' as const,
+          subjectType,
           scopes: requested,
         };
 
@@ -261,44 +269,100 @@ export function createCoreServiceIntegrationRequestTool(client: ForLoopAPIClient
         const linkParams = new URLSearchParams();
         linkParams.set('connect', args.agentId);
         linkParams.set('scopes', requested.join(','));
-        linkParams.set('subject', 'app');
-        const connectUrl = spaceUrl ? `${spaceUrl}?${linkParams.toString()}` : null;
+        linkParams.set('subject', subjectType);
+        const fallbackConnectUrl = spaceUrl ? `${spaceUrl}?${linkParams.toString()}` : null;
+
+        // Persist the pending request and nudge the live client to open the
+        // panel. Both steps are best-effort: an offline client (or a backend
+        // without the request routes) must still return an actionable link.
+        let requestId: string | null = null;
+        let delivered = false;
+        let connectUrl: string | null = fallbackConnectUrl;
+        let dropped: string[] = [];
+        if (callerSprintId) {
+          try {
+            const created = await client.createConnectionRequest({
+              sprintId: callerSprintId,
+              targetAgentId: args.agentId,
+              scopes: requested,
+              subjectType,
+              requestedBy: 'planner',
+              reason: args.reason,
+            });
+            const request = created?.request ?? {};
+            if (subjectType === 'user' && request.subjectType !== 'user') {
+              return [
+                '❌ The platform did not create a user-subject connection request; nothing usable was created.',
+                `- returned subject: ${request.subjectType ?? 'unknown'}`,
+                'Do not use an app-subject request for user-owned data. Record `Connection: pending user consent (UI-only)` and stop until the delegated-user exchange is available.',
+              ].join('\n');
+            }
+            requestId = typeof request.id === 'string' ? request.id : null;
+            dropped = Array.isArray(created?.droppedScopes) ? created.droppedScopes : [];
+            connectUrl = created?.link ?? request.link ?? connectUrl;
+
+            if (requestId) {
+              try {
+                const opened = await client.openConnectionRequest(requestId);
+                delivered = opened?.delivered === true;
+                connectUrl = opened?.link ?? opened?.fallback ?? connectUrl;
+              } catch {
+                delivered = false;
+              }
+            }
+          } catch {
+            // Older backend without request persistence: fall back to the link.
+          }
+        }
 
-        const approvalSteps = connectUrl
+        const userSubject = subjectType === 'user';
+        const approver = userSubject ? 'user' : 'app owner';
+        const manualSteps = connectUrl
           ? [
               `1. Open ${connectUrl}`,
-              `   This opens **${target.name}**'s connection panel in this app, with the scopes below and \`This app\` preselected.`,
+              `   This opens **${target.name}**'s connection panel in this app, with the scopes below and ${userSubject ? '`You`' : '`This app`'} preselected.`,
               '2. Review the service, scopes and price shown above.',
-              '3. Click **Connect**.',
-              '4. Copy the **Connection ID** shown under the new connected app into the integration brief.',
+              '3. Click **Approve**.',
             ]
           : [
               `1. Open the app's space${spaceUrl ? `: ${spaceUrl}` : ''}.`,
               '2. Open **Aivy Actions → App Connections (Beta)** and choose the **Connect** tab.',
-              `3. Find **${target.name}**, tick the scopes below, choose **This app**, then click **Connect**.`,
-              '4. Copy the **Connection ID** shown under the new connected app into the integration brief.',
+              `3. Find **${target.name}**, tick the scopes below, choose ${userSubject ? '**You**' : '**This app**'}, then click **Approve**.`,
             ];
+        const pendingLabel = userSubject ? 'pending user consent' : 'pending owner approval';
 
         return [
-          `## Integration approval required — nothing is created yet`,
+          delivered
+            ? `## App Connections opened — waiting for the ${approver} to approve`
+            : `## Approval needed — the ${approver} must approve this request`,
           `- Service: **${target.name}** (\`${target.agentId}\`)`,
           `- serviceCode: ${target.serviceCode ?? 'unknown'}`,
+          `- subject: ${userSubject ? 'user-subject (user consent)' : 'app-subject (app owner)'}`,
           `- reason: ${args.reason}`,
           `- scopes: ${requested.join(', ')}`,
           `- cost: ${formatPrice(target)}`,
+          ...(requestId ? [`- requestId: \`${requestId}\``] : []),
+          ...(dropped.length
+            ? [`⚠️ Dropped (not declared by the target manifest): ${dropped.join(', ')}`]
+            : []),
           '',
-          'The planner cannot create or record connections. The grant exists only after the app owner clicks **Connect**; until then nothing is pending and the Permissions page stays empty.',
+          delivered
+            ? 'The App Connections panel is now open on the user’s screen, focused on this request. They only need to click **Approve** — do not paste a link or repeat manual steps.'
+            : 'The user’s client was not reachable. Send them this link — it opens the same focused panel so they only need to click **Approve**:',
+          ...(delivered ? [] : ['', ...manualSteps]),
           '',
-          '### Approve now (creates the app-subject grant)',
-          ...approvalSteps,
+          'A pending request is not a grant. Do not write a connection id into the integration brief until `a2a_check_connections` reports an active connection.',
+          `After the ${approver} approves, call \`a2a_check_connections\` to read the real connection id and scopes.`,
           '',
-          '### Connection payload (owner handoff)',
+          `### Connection payload (${approver} handoff)`,
           '```json',
           JSON.stringify(connectionPayload, null, 2),
           '```',
           '',
-          'Only the signed-in app owner may submit this payload to `POST /api/a2a/connections` with a Clerk session. Never send credentials or create the connection from the planner.',
-          'If the user cannot or does not complete the approval now, write `Connection: to be created during implementation` in the integration brief and continue — do not block the plan and do not ask again.',
+          'The planner can never approve. Never send credentials or create the connection from the planner.',
+          userSubject
+            ? `If the user cannot or does not consent now, write \`Connection: ${pendingLabel}\` in the integration brief and continue — do not block the plan and do not ask again. The app owner cannot consent for the user.`
+            : `If the user cannot or does not complete the approval now, write \`Connection: ${pendingLabel}\` in the integration brief and continue — do not block the plan and do not ask again.`,
         ].join('\n');
       } catch (error: any) {
         return `❌ Error creating integration request: ${error.message}`;