@forloop-cc/forloop-opencode-plugin-planner 2.2.26 → 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.26",
+  "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',
@@ -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,7 +269,7 @@ export function createCoreServiceIntegrationRequestTool(client: ForLoopAPIClient
         const linkParams = new URLSearchParams();
         linkParams.set('connect', args.agentId);
         linkParams.set('scopes', requested.join(','));
-        linkParams.set('subject', 'app');
+        linkParams.set('subject', subjectType);
         const fallbackConnectUrl = spaceUrl ? `${spaceUrl}?${linkParams.toString()}` : null;
 
         // Persist the pending request and nudge the live client to open the
@@ -277,11 +285,18 @@ export function createCoreServiceIntegrationRequestTool(client: ForLoopAPIClient
               sprintId: callerSprintId,
               targetAgentId: args.agentId,
               scopes: requested,
-              subjectType: 'app',
+              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;
@@ -300,25 +315,29 @@ export function createCoreServiceIntegrationRequestTool(client: ForLoopAPIClient
           }
         }
 
+        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 **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 **Approve**.`,
+              `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 [
           delivered
-            ? '## App Connections opened — waiting for the app owner to approve'
-            : '## Approval needed — the app owner must approve this request',
+            ? `## 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)}`,
@@ -333,15 +352,17 @@ export function createCoreServiceIntegrationRequestTool(client: ForLoopAPIClient
           ...(delivered ? [] : ['', ...manualSteps]),
           '',
           '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 user approves, call `a2a_check_connections` to read the real connection id and scopes.',
+          `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),
           '```',
           '',
           'The planner can never approve. Never send credentials or create the connection from the planner.',
-          'If the user cannot or does not complete the approval now, write `Connection: pending owner approval` in the integration brief and continue — do not block the plan and do not ask again.',
+          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}`;