@forloop-cc/forloop-opencode-plugin-planner 2.2.24 → 2.2.26

package/package.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://json.schemastore.org/package.json",
   "name": "@forloop-cc/forloop-opencode-plugin-planner",
-  "version": "2.2.24",
+  "version": "2.2.26",
   "description": "ForLoop integration plugin for opencode — Sprint, story, and agent tools for the ForLoop platform",
   "type": "module",
   "license": "MIT",
@@ -68,7 +68,7 @@
     "access": "public"
   },
   "engines": {
-    "node": ">=18.0.0"
+    "node": ">=22.23.4"
   },
   "peerDependencies": {
     "@opencode-ai/plugin": "^1.3.0"

package/plugins/capabilities/api-client.ts

@@ -145,6 +145,7 @@ export class ForLoopAPIClient {
       'organization:write',
       'organization:delete',
       'a2a:read',
+      'a2a:write',
     ];
 
     const name = `lambda-planner-${Date.now()}`;
@@ -270,6 +271,23 @@ export class ForLoopAPIClient {
     return Array.isArray(response) ? response : (response.data || []);
   }
 
+  /**
+   * Read-only APP wallet snapshot for the sprint (the payer for paid core
+   * services). The server scopes it to the sprint publicId and never moves
+   * funds.
+   */
+  async getAppWallet(sprintId: number): Promise<{
+    sprintId: number;
+    appPublicId: string;
+    currency: string;
+    available: number;
+    reserved: number;
+    spent: number;
+    spendCap: number | null;
+  }> {
+    return this.request(`/api/opencode/sprints/${sprintId}/wallet`);
+  }
+
   async getSprint(id: number, options?: SprintOptions): Promise<any> {
     const query = new URLSearchParams({
       includeStories: options?.includeStories !== false ? 'true' : 'false',
@@ -397,6 +415,31 @@ export class ForLoopAPIClient {
     );
   }
 
+  async createConnectionRequest(params: {
+    sprintId: number;
+    targetAgentId: string;
+    scopes: string[];
+    subjectType?: 'user' | 'app';
+    requestedBy?: 'planner' | 'agent';
+    reason?: string;
+  }): Promise<any> {
+    return this.request('/api/opencode/a2a/connection-requests', {
+      method: 'POST',
+      body: JSON.stringify(params),
+    });
+  }
+
+  async getConnectionState(sprintId: number): Promise<any> {
+    return this.request(`/api/opencode/a2a/connection-state?sprintId=${sprintId}`);
+  }
+
+  async openConnectionRequest(requestId: string): Promise<any> {
+    return this.request(
+      `/api/opencode/a2a/connection-requests/${encodeURIComponent(requestId)}/open`,
+      { method: 'POST' }
+    );
+  }
+
   async summarizeConversation(sprintId: number): Promise<any> {
     return this.request(`/api/opencode/sprints/${sprintId}/summarize`, {
       method: 'POST',

package/plugins/forloop-plugin.ts

@@ -73,6 +73,12 @@ import {
   createCoreServiceGetTool,
   createCoreServiceIntegrationRequestTool,
 } from './tools/core-service-tools';
+import { createA2ACheckWalletTool } from './tools/wallet-tools';
+import {
+  createA2ARequestConnectionTool,
+  createA2ACheckConnectionsTool,
+  createA2AOpenConnectionRequestTool,
+} from './tools/a2a-connection-tools';
 import { injectEnvironment } from './hooks/shell-env';
 import { createChatMessageHook, createEventHook } from './hooks/message-recorder';
 
@@ -177,6 +183,14 @@ export default async (ctx: any) => {
       'core_services_search': createCoreServicesSearchTool(client),
       'core_service_get': createCoreServiceGetTool(client),
       'core_service_integration_request': createCoreServiceIntegrationRequestTool(client),
+
+      // Read-only paid-integration pre-flight (balance + price + shortfall)
+      'a2a_check_wallet': createA2ACheckWalletTool(client),
+
+      // Persisted A2A connection requests (planner can request/read, never approve)
+      'a2a_request_connection': createA2ARequestConnectionTool(client),
+      'a2a_check_connections': createA2ACheckConnectionsTool(client),
+      'a2a_open_connection_request': createA2AOpenConnectionRequestTool(client),
     },
     event: createEventHook(client),
     'chat.message': createChatMessageHook(client),

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

@@ -0,0 +1,316 @@
+import { tool } from '@opencode-ai/plugin';
+import { ForLoopAPIClient } from '../capabilities/api-client';
+import { validateToken } from '../capabilities/auth';
+import { resolveSprintId } from '../capabilities/context-resolver';
+
+type RegistryEntry = {
+  agentId: string;
+  name: string;
+  serviceCode?: string | null;
+};
+
+type RequestWire = {
+  id: string;
+  targetAgentId: string;
+  targetSprintId: number;
+  scopes: string[];
+  subjectType: 'user' | 'app';
+  requestedBy: string;
+  reason?: string | null;
+  status: 'pending' | 'approved' | 'denied' | 'expired';
+  connectionId?: string | null;
+  expiresAt?: string | null;
+  link?: string | null;
+};
+
+type ConnectionState = {
+  sprintId: number;
+  callerPublicId: string | null;
+  connections: Array<{
+    connectionId: string;
+    targetSprintId: number;
+    targetAgentId: string | null;
+    subjectType: string;
+    scopes: string[];
+    status: string;
+    autoApprove?: boolean;
+    expiresAt?: string | null;
+  }>;
+  requests: RequestWire[];
+};
+
+const findEntry = async (client: ForLoopAPIClient, agentId: string): Promise<RegistryEntry | undefined> => {
+  const found = await client.searchCoreServices({ query: agentId, limit: 50 });
+  return (found.entries ?? []).find((entry: RegistryEntry) => entry.agentId === agentId);
+};
+
+const resolveWorkingSprint = async (context: any): Promise<number | null> => {
+  const resolution = await resolveSprintId(undefined, context?.directory);
+  return resolution.sprintId ?? null;
+};
+
+const requestLines = (request: RequestWire): string[] => {
+  const lines = [
+    `- requestId: \`${request.id}\``,
+    `- target: \`${request.targetAgentId}\``,
+    `- scopes: ${request.scopes.join(', ') || 'none'}`,
+    `- subject: ${request.subjectType === 'app' ? 'this app' : 'you'}`,
+    `- requestedBy: ${request.requestedBy}`,
+    `- status: **${request.status}**`,
+  ];
+  if (request.connectionId) lines.push(`- connectionId: \`${request.connectionId}\``);
+  // Expiry is an approval deadline for a PENDING request only. An approved
+  // request keeps the row for audit; its old 7-day window must not be read as
+  // the connection's lifetime.
+  if (request.status === 'pending' && request.expiresAt) {
+    lines.push(`- approval window expiresAt: ${request.expiresAt}`);
+  }
+  if (request.reason) lines.push(`- reason: ${request.reason}`);
+  lines.push(`- approval link: ${request.link || '(open App Connections → Connect)'}`);
+  return lines;
+};
+
+// Planner-side write: records a request for the working sprint's app owner.
+// It never creates an A2AConnection and cannot approve.
+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.',
+    args: {
+      agentId: tool.schema.string().describe('Target service/peer agentId (public id)'),
+      scopes: tool.schema
+        .array(tool.schema.string())
+        .describe('Exact scopes the integration needs (clamped to the target manifest)'),
+      reason: tool.schema
+        .string()
+        .optional()
+        .describe('Why the app needs this connection (shown to the approving user)'),
+    },
+    async execute(args, context) {
+      const tokenResult = await validateToken();
+      if (!tokenResult.valid) return tokenResult.error;
+      client.setToken?.(tokenResult.token);
+
+      try {
+        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 sprintId = await resolveWorkingSprint(context);
+        if (!sprintId) {
+          return '❌ Could not resolve the working sprint. Open the planner from an app space, then retry.';
+        }
+        const requested = Array.from(
+          new Set((args.scopes ?? []).map(scope => scope.trim()).filter(Boolean))
+        );
+        if (!requested.length) {
+          return `❌ No scopes requested for \`${args.agentId}\`. Nothing was created.`;
+        }
+
+        const result = await client.createConnectionRequest({
+          sprintId,
+          targetAgentId: args.agentId,
+          scopes: requested,
+          subjectType: 'app',
+          requestedBy: 'planner',
+          ...(args.reason ? { reason: args.reason } : {}),
+        });
+        const request = result.request as RequestWire;
+        const dropped = Array.isArray(result.droppedScopes) ? result.droppedScopes : [];
+
+        return [
+          request.status === 'approved'
+            ? '## Connection already approved'
+            : '## Connection request created — waiting for the app owner',
+          '',
+          `- target: **${target.name}** (\`${target.agentId}\`)`,
+          ...requestLines({ ...request, link: result.link ?? request.link }),
+          ...(dropped.length
+            ? ['', `⚠️ Dropped (not declared by the target manifest): ${dropped.join(', ')}`]
+            : []),
+          '',
+          '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.',
+        ].join('\n');
+      } catch (error: any) {
+        return `❌ Error creating the connection request: ${error.message}`;
+      }
+    },
+  });
+}
+
+// Planner-side read: the working sprint's real connections + request statuses.
+// This is how the planner learns the connection id after the user approves.
+export function createA2ACheckConnectionsTool(client: ForLoopAPIClient) {
+  return tool({
+    description:
+      'Read the current sprint’s active A2A connections (real connection ids + granted scopes) and its connection requests with statuses. Use after the user says they approved, and before writing a brief that references a connection id. Read-only.',
+    args: {
+      sprintId: tool.schema
+        .number()
+        .optional()
+        .describe('Sprint to inspect; defaults to the working sprint'),
+    },
+    async execute(args, context) {
+      const tokenResult = await validateToken();
+      if (!tokenResult.valid) return tokenResult.error;
+      client.setToken?.(tokenResult.token);
+
+      try {
+        const sprintId = args.sprintId ?? (await resolveWorkingSprint(context));
+        if (!sprintId) return '❌ Could not resolve the working sprint.';
+
+        const state = (await client.getConnectionState(sprintId)) as ConnectionState;
+        const connections = state.connections ?? [];
+        const requests = state.requests ?? [];
+        const lines: string[] = [];
+
+        if (!connections.length) {
+          lines.push('## Active connections', '', 'None. No integration can be called yet.');
+        } else {
+          lines.push(`## Active connections (${connections.length})`, '');
+          for (const connection of connections) {
+            lines.push(
+              `- Connection ID: \`${connection.connectionId}\``,
+              `  - target: \`${connection.targetAgentId ?? connection.targetSprintId}\` (sprint ${connection.targetSprintId})`,
+              `  - scopes: ${connection.scopes.join(', ') || 'none'}`,
+              `  - subject: ${connection.subjectType === 'app' ? 'this app' : 'the user'}`,
+              `  - status: ${connection.status}${connection.autoApprove ? ' (always allow)' : ''}`,
+            );
+            const expiresAt = connection.expiresAt ? new Date(connection.expiresAt) : null;
+            if (!expiresAt || Number.isNaN(expiresAt.getTime())) {
+              // Approved grants are permanent by default; only revocation (or a
+              // target disconnect/delete) ends them.
+              lines.push('  - expires: no expiry (until revoked)');
+            } else {
+              const daysLeft = Math.ceil((expiresAt.getTime() - Date.now()) / (24 * 60 * 60 * 1000));
+              const renewHint = daysLeft <= 14
+                ? ' — renews automatically on use; re-request if it lapses'
+                : '';
+              lines.push(`  - expires: ${expiresAt.toISOString()} (${daysLeft} day${daysLeft === 1 ? '' : 's'} left${renewHint})`);
+            }
+          }
+        }
+
+        lines.push('', `## Connection requests (${requests.length})`, '');
+        if (!requests.length) {
+          lines.push('None.');
+        } else {
+          for (const request of requests) {
+            lines.push(...requestLines(request), '');
+          }
+        }
+
+        const pending = requests.filter(request => request.status === 'pending');
+        const approved = requests.filter(request => request.status === 'approved' && request.connectionId);
+        if (pending.length) {
+          lines.push(
+            `${pending.length} request${pending.length === 1 ? ' is' : 's are'} still pending. The user must approve before the integration exists.`,
+          );
+        } else if (approved.length) {
+          lines.push(
+            'Approved request(s) above carry the real connection id — use that id and its granted scopes in the brief. Do not widen the scopes.',
+          );
+        }
+        return lines.join('\n');
+      } catch (error: any) {
+        return `❌ Error reading connections: ${error.message}`;
+      }
+    },
+  });
+}
+
+// Planner-side nudge: ask the user's client to open App Connections focused on
+// the pending request (or create one from target+scopes first). The link is
+// ALWAYS returned so an offline client still gets an actionable fallback.
+export function createA2AOpenConnectionRequestTool(client: ForLoopAPIClient) {
+  return tool({
+    description:
+      'Open the user’s App Connections panel focused on a pending connection request, so they only need to click Approve. Accepts a request id or target+scopes (creates the request if needed). Emits a platform socket action to the live client; when the client is offline the response still contains the request id and the approval link. This never approves.',
+    args: {
+      requestId: tool.schema
+        .string()
+        .optional()
+        .describe('Existing connection request id'),
+      agentId: tool.schema
+        .string()
+        .optional()
+        .describe('Target agentId when the request id is unknown'),
+      scopes: tool.schema
+        .array(tool.schema.string())
+        .optional()
+        .describe('Exact scopes for the request when creating/looking it up'),
+    },
+    async execute(args, context) {
+      const tokenResult = await validateToken();
+      if (!tokenResult.valid) return tokenResult.error;
+      client.setToken?.(tokenResult.token);
+
+      try {
+        const sprintId = await resolveWorkingSprint(context);
+        if (!sprintId) return '❌ Could not resolve the working sprint.';
+
+        let requestId = args.requestId?.trim() || '';
+        let link: string | null = null;
+
+        if (!requestId) {
+          if (!args.agentId) {
+            return '❌ Provide a request id, or a target agentId (and scopes) so the request can be created.';
+          }
+          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.status !== 'pending' && request.status !== 'approved') return false;
+            if (!wanted.size) return true;
+            return (
+              request.scopes.length === wanted.size &&
+              request.scopes.every(scope => wanted.has(scope))
+            );
+          });
+          if (match) {
+            requestId = match.id;
+            link = match.link ?? null;
+          } else {
+            if (!wanted.size) {
+              return `❌ No pending request for \`${args.agentId}\`. Call \`a2a_request_connection\` with scopes first.`;
+            }
+            const created = await client.createConnectionRequest({
+              sprintId,
+              targetAgentId: args.agentId,
+              scopes: [...wanted],
+              subjectType: 'app',
+              requestedBy: 'planner',
+            });
+            requestId = created.request?.id ?? '';
+            link = created.link ?? created.request?.link ?? null;
+          }
+        }
+
+        if (!requestId) return '❌ Could not create or find a connection request.';
+
+        const opened = await client.openConnectionRequest(requestId);
+        const finalLink = opened.link ?? link;
+        const delivered = opened.delivered === true;
+
+        return [
+          delivered
+            ? '## App Connections opened for the user'
+            : '## Link ready — the user’s client was not reachable',
+          '',
+          `- requestId: \`${opened.requestId ?? requestId}\``,
+          `- socket delivered: ${delivered ? 'yes' : 'no'}`,
+          `- approval link: ${finalLink || '(open App Connections → Connect)'}`,
+          '',
+          delivered
+            ? 'The panel should now be focused on this request. The user still has to click **Approve** — the planner cannot approve.'
+            : 'Send the approval link to the user. It opens App Connections focused on this request so they only need to click **Approve**.',
+          'After they approve, call `a2a_check_connections` to resolve the real connection id and scopes.',
+        ].join('\n');
+      } catch (error: any) {
+        return `❌ Error opening the connection request: ${error.message}`;
+      }
+    },
+  });
+}

package/plugins/tools/ai-trigger-tools.ts

@@ -20,13 +20,13 @@ export function createAITriggerTools(client: ForLoopAPIClient) {
  */
 function createDeveloperSprintTool(client: ForLoopAPIClient) {
   return tool({
-    description: 'Trigger forLoopTaskSupervisor agent to execute space work. This sends stories to the developer agent for implementation via EventBridge → Step Functions → ECS Fargate.',
+    description: 'Trigger forLoopTaskSupervisor agent to execute space work. This sends stories to the developer agent for implementation via EventBridge → Step Functions → ECS Fargate. When an approved design preview exists, include `Approved design preview: File #<id> <fileName>` (and its story Design Reference) in the message so the Developer bases the UI on it.',
     args: {
       sprintId: tool.schema.number()
         .describe('Sprint ID to execute'),
       message: tool.schema.string()
         .optional()
-        .describe('Optional instructions for the developer agent')
+        .describe('Instructions for the developer agent — include the approved design File #ID/name and the sprint plan file')
         .default('Start implementing the sprint stories assigned to the developer agent'),
     },
     async execute(args, _context) {

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

@@ -190,7 +190,7 @@ export function createCoreServiceGetTool(client: ForLoopAPIClient) {
 export function createCoreServiceIntegrationRequestTool(client: ForLoopAPIClient) {
   return tool({
     description:
-      'Record an integration request for a core service and return the exact user-approval steps plus the app-subject connection payload. This never creates a connection, never touches credentials, and never constructs 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
@@ -240,31 +240,108 @@ export function createCoreServiceIntegrationRequestTool(client: ForLoopAPIClient
           subjectType: 'app' as const,
           scopes: requested,
         };
-        const connectUrl = `${clientBaseUrl()}/myspace?connect=${encodeURIComponent(args.agentId)}`;
+
+        let callerPublicId: string | null = null;
+        if (callerSprintId && typeof client.getSprint === 'function') {
+          try {
+            const callerSprint = await client.getSprint(callerSprintId, {
+              includeStories: false,
+              includeFiles: false,
+            });
+            callerPublicId = typeof callerSprint?.publicId === 'string' ? callerSprint.publicId : null;
+          } catch {
+            // A missing space lookup must not hide the approval instructions.
+            callerPublicId = null;
+          }
+        }
+
+        const spaceUrl = callerPublicId
+          ? `${clientBaseUrl()}/myspace/${encodeURIComponent(callerPublicId)}`
+          : null;
+        const linkParams = new URLSearchParams();
+        linkParams.set('connect', args.agentId);
+        linkParams.set('scopes', requested.join(','));
+        linkParams.set('subject', 'app');
+        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: 'app',
+              requestedBy: 'planner',
+              reason: args.reason,
+            });
+            const request = created?.request ?? {};
+            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 manualSteps = connectUrl
+          ? [
+              `1. Open ${connectUrl}`,
+              `   This opens **${target.name}**'s connection panel in this app, with the scopes below and \`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**.`,
+            ];
 
         return [
-          `## Integration request — pending user approval`,
+          delivered
+            ? '## App Connections opened — waiting for the app owner to approve'
+            : '## Approval needed — the app owner must approve this request',
           `- Service: **${target.name}** (\`${target.agentId}\`)`,
           `- serviceCode: ${target.serviceCode ?? 'unknown'}`,
           `- 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 does not create connections or handle credentials. Ask the user to approve this request in the UI.',
+          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 in the UI',
-          `1. Open ${connectUrl}`,
-          '2. Review the service, scopes and price shown above.',
-          '3. Approve the app-subject connection.',
-          '4. Copy the resulting connection id into the integration brief.',
+          '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.',
           '',
-          '### Connection payload (owner/developer handoff)',
+          '### Connection payload (owner handoff)',
           '```json',
           JSON.stringify(connectionPayload, null, 2),
           '```',
           '',
-          'Only the owner/developer may submit this payload to `POST /api/a2a/connections` (Clerk session auth). Never send credentials or create the connection from the planner.',
-          'If the UI cannot set `subjectType: "app"`, hand this payload to the user and wait for the connection id before writing the integration brief.',
+          '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.',
         ].join('\n');
       } catch (error: any) {
         return `❌ Error creating integration request: ${error.message}`;

package/plugins/tools/sync-tools.ts

@@ -134,6 +134,9 @@ export function createS3ToLocalSyncTool(client: ForLoopAPIClient) {
       syncTasks: tool.schema.boolean()
         .default(true)
         .describe('Sync task files'),
+      syncDesign: tool.schema.boolean()
+        .default(true)
+        .describe('Sync approved design previews/artifacts (project/design)'),
       overwrite: tool.schema.boolean()
         .default(false)
         .describe('Overwrite local files even if size matches'),
@@ -168,6 +171,9 @@ export function createS3ToLocalSyncTool(client: ForLoopAPIClient) {
       if (args.syncKnowledge) selectedKinds.add('knowledge');
       if (args.syncPlans) selectedKinds.add('plan');
       if (args.syncTasks) selectedKinds.add('task');
+      // Design sync is on unless explicitly disabled, so a caller that only
+      // asks for plans/knowledge still gets the approved preview.
+      if (args.syncDesign !== false) selectedKinds.add('design');
 
       const byRelPath = new Map<string, any>();
       for (const item of candidates) {
@@ -384,6 +390,7 @@ function ensureForloopStructure(forloopRoot: string, sprintId?: number) {
     fs.mkdirSync(path.join(forloopRoot, 'knowledge'), { recursive: true });
     fs.mkdirSync(path.join(forloopRoot, 'plan'), { recursive: true });
     fs.mkdirSync(path.join(forloopRoot, 'task'), { recursive: true });
+    fs.mkdirSync(path.join(forloopRoot, 'design'), { recursive: true });
   }
 
   fs.mkdirSync(path.join(getForloopRootPath(), 'sync'), { recursive: true });
@@ -438,10 +445,13 @@ function inferRemoteFolderFromRelPath(relPath: string): string {
   if (first === 'knowledge') return 'project/knowledge';
   if (first === 'plan') return 'project/plans';
   if (first === 'task') return 'project/tasks';
+  if (first === 'design') return 'project/design';
   return 'project';
 }
 
-function mapRemoteFileToLocalRelPath(file: any): { kind: 'knowledge' | 'plan' | 'task'; folder: string; relPath: string } | null {
+type SyncKind = 'knowledge' | 'plan' | 'task' | 'design';
+
+function mapRemoteFileToLocalRelPath(file: any): { kind: SyncKind; folder: string; relPath: string } | null {
   const storageKey = String(file?.storageKey || file?.s3Url || file?.url || '');
   const name = String(file?.originalName || file?.filename || '').trim();
   const lowerName = name.toLowerCase();
@@ -456,6 +466,9 @@ function mapRemoteFileToLocalRelPath(file: any): { kind: 'knowledge' | 'plan' |
   if (keyLower.includes('/project/tasks/')) {
     return { kind: 'task', folder: 'project/tasks', relPath: path.join('task', path.basename(name || 'remote')) };
   }
+  if (keyLower.includes('/project/design/')) {
+    return { kind: 'design', folder: 'project/design', relPath: path.join('design', path.basename(name || 'remote')) };
+  }
 
   if (lowerName.startsWith('knowledge-')) {
     return { kind: 'knowledge', folder: 'project/knowledge', relPath: path.join('knowledge', path.basename(name)) };
@@ -466,6 +479,9 @@ function mapRemoteFileToLocalRelPath(file: any): { kind: 'knowledge' | 'plan' |
   if (lowerName.startsWith('task-')) {
     return { kind: 'task', folder: 'project/tasks', relPath: path.join('task', path.basename(name)) };
   }
+  if (lowerName.startsWith('design-') || lowerName.endsWith('-preview.html') || lowerName === 'preview.html') {
+    return { kind: 'design', folder: 'project/design', relPath: path.join('design', path.basename(name)) };
+  }
 
   return null;
 }

package/plugins/tools/wallet-tools.ts

@@ -0,0 +1,128 @@
+import { tool } from '@opencode-ai/plugin';
+import { ForLoopAPIClient } from '../capabilities/api-client';
+import { validateToken } from '../capabilities/auth';
+import { resolveSprintId } from '../capabilities/context-resolver';
+
+type RegistryEntry = {
+  agentId: string;
+  name: string;
+  serviceCode?: string | null;
+  kind?: 'system' | 'user';
+  billingPrice?: number | null;
+  billingUnit?: string | null;
+  billingCurrency?: string | null;
+};
+
+const formatAmount = (value: number, currency: string): string => `${value} ${currency}`;
+
+/**
+ * Read-only pre-flight for paid core-service integrations. A paid service
+ * debits the app wallet (APP:<sprint publicId>); discovering a shortfall here
+ * turns a runtime 402 into an explicit "top up" ask before the Developer starts.
+ */
+export function createA2ACheckWalletTool(client: ForLoopAPIClient) {
+  return tool({
+    description:
+      'Read the app wallet balance and, for a target core service, its advertised price and the estimated cost/shortfall. Use after choosing a paid core service and before writing the integration brief or starting the Developer. Read-only: it never moves funds.',
+    args: {
+      agentId: tool.schema
+        .string()
+        .optional()
+        .describe('Target core-service agentId (from core_services_search); omit to read only the balance'),
+      quantity: tool.schema
+        .number()
+        .optional()
+        .describe('Expected billable units for the estimate (default 1; e.g. emails or deliveries)'),
+    },
+    async execute(args, context) {
+      const tokenResult = await validateToken();
+      if (!tokenResult.valid) {
+        return tokenResult.error;
+      }
+      client.setToken?.(tokenResult.token);
+
+      try {
+        const resolution = await resolveSprintId(undefined, context?.directory);
+        if (!resolution.sprintId) {
+          return '❌ Could not resolve the app space, so the app wallet cannot be read. Ask the user which app this is for (or set the sprint context) and try again.';
+        }
+
+        const wallet = await client.getAppWallet(resolution.sprintId);
+        const currency = wallet.currency || 'FLC';
+        const quantity =
+          typeof args.quantity === 'number' && Number.isFinite(args.quantity) && args.quantity > 0
+            ? Math.floor(args.quantity)
+            : 1;
+
+        const lines = [
+          '# App wallet',
+          `- appPublicId: \`${wallet.appPublicId}\``,
+          `- available: ${formatAmount(wallet.available, currency)}`,
+          `- reserved: ${formatAmount(wallet.reserved, currency)}`,
+          `- spent: ${formatAmount(wallet.spent, currency)}`,
+          `- spend cap: ${wallet.spendCap === null ? 'none' : formatAmount(wallet.spendCap, currency)}`,
+        ];
+
+        if (!args.agentId?.trim()) {
+          lines.push(
+            '',
+            'No target service was supplied; only the wallet balance is shown. Pass `agentId` from `core_services_search` to include the price and shortfall.'
+          );
+          return lines.join('\n');
+        }
+
+        const found = await client.searchCoreServices({ query: args.agentId, limit: 50 });
+        const target = (found.entries ?? []).find(
+          (entry: RegistryEntry) => entry.agentId === args.agentId
+        ) as RegistryEntry | undefined;
+
+        if (!target) {
+          lines.push(
+            '',
+            `⚠️ Target \`${args.agentId}\` was not found in the registry. Do not invent a price; re-run \`core_services_search\`.`
+          );
+          return lines.join('\n');
+        }
+
+        const unit = target.billingUnit ? ` per ${target.billingUnit}` : ' per success';
+        lines.push('', `## Target: ${target.name} (\`${target.serviceCode ?? target.agentId}\`)`);
+
+        if (target.billingPrice === null || target.billingPrice === undefined) {
+          lines.push(
+            '- price TBD (not published in the registry yet)',
+            '',
+            'Price is unknown, so no shortfall can be computed. Check again after the service publishes a price, or ask the user to confirm the expected cost. This check is read-only.'
+          );
+          return lines.join('\n');
+        }
+
+        const price = target.billingPrice;
+        const priceCurrency = target.billingCurrency || currency;
+        const estimate = price * quantity;
+        const shortfall = Math.max(0, estimate - wallet.available);
+
+        lines.push(
+          `- unit price: ${formatAmount(price, priceCurrency)}${unit}`,
+          `- estimate (${quantity}): ${formatAmount(estimate, priceCurrency)}`,
+          `- shortfall: ${formatAmount(shortfall, priceCurrency)}`
+        );
+
+        if (shortfall > 0) {
+          lines.push(
+            '',
+            '⚠️ The app wallet is short. Tell the user to top up the app wallet before the Developer starts (App → Credits, or the owner-side `POST /api/ledger/app/:appId/fund`). Starting the Developer now would fail with `402 insufficient_balance`. This check is read-only and does not move funds.'
+          );
+        } else {
+          lines.push(
+            '',
+            'The wallet covers this estimate. Re-run this check before a large batch; prices and balances change. This check is read-only and does not move funds.'
+          );
+        }
+
+        return lines.join('\n');
+      } catch (error: any) {
+        return `❌ Error checking the app wallet: ${error.message}`;
+      }
+    },
+  });
+}